Bien démarrer avec CodeQL CLI

Bien démarrer avec CodeQL CLI

Pour exécuter les commandes CodeQL, vous devez configurer l’interface CLI afin qu’elle puisse accéder aux outils, aux requêtes et aux bibliothèques nécessaires à la création et à l’analyse des bases de données.

Configuration de CodeQL CLI

CodeQL CLI peut être configuré pour prendre en charge de nombreux cas d’usage et structures de répertoires différents. Pour commencer rapidement, nous vous recommandons d’adopter une configuration relativement simple, comme indiqué dans les étapes ci-dessous.

Si vous utilisez Linux, Windows ou macOS version 10.14 (« Mojave ») ou antérieure, suivez simplement les étapes ci-dessous. Pour macOS version 10.15 (« Catalina ») ou plus récente, vous trouverez des notes supplémentaires pour certaines étapes. Si vous utilisez macOS sur Apple Silicon (par exemple, Apple M1), assurez-vous que les outils de développement en ligne de commande Xcode et Rosetta 2 sont installés.

Pour plus d’informations sur l’installation de CodeQL CLI dans un système CI pour créer des résultats à afficher dans GitHub en tant qu’alertes d’analyse du code, consultez Installation de CodeQL CLI dans votre système CI.

1. Télécharger le package zip de CodeQL CLI

Le package de téléchargement CodeQL CLI est une archive zip contenant des outils, des scripts et divers fichiers spécifiques à CodeQL. Si vous n’avez pas de licence GitHub Enterprise, en téléchargeant cette archive, vous acceptez les conditions générales de GitHub CodeQL.

Si vous utilisez Linux, Windows ou macOS version 10.14 (« Mojave ») ou antérieure, il vous suffit de télécharger l’archive zip de la version dont vous avez besoin.

Si vous souhaitez utiliser l’interface CLI pour une plateforme spécifique, téléchargez le fichier codeql-PLATFORM.zip approprié. Vous pouvez également télécharger codeql.zip qui contient l’interface CLI pour toutes les plateformes prises en charge.

Télécharger les informations pour les utilisateurs de macOS « Catalina » (ou plus récent)

Si vous utilisez macOS version 10.15 (« Catalina »), version 11 (« Big Sur ») ou la version 12 à venir (« Monterey »), vous devez vous assurer que votre navigateur web n’extrait pas automatiquement les fichiers zip. Si vous utilisez Safari, effectuez les étapes suivantes avant de télécharger l’archive zip de CodeQL CLI :

1. Ouvrez Safari.
2. Dans le menu Safari, sélectionnez Préférences... .
3. Cliquez sur l’onglet Général.
4. Vérifiez que la case intitulée Ouvrir automatiquement les fichiers « fiables » est décochée.

2. Extraire l’archive zip

Pour les utilisateurs Linux, Windows et macOS (version 10.14 « Mojave » et antérieure) extrayez simplement l’archive zip.

Extraction des informations pour les utilisateurs de macOS « Catalina » (ou plus récent)

Les utilisateurs de macOS « Catalina », « Big Sur » ou « Monterey » doivent exécuter les commandes suivantes dans le Terminal, où ${extraction-root} est le chemin du répertoire où vous allez extraire l’archive zip de CodeQL CLI :

1. mv ~/Downloads/codeql\*.zip ${extraction-root}
2. cd ${extraction-root}
3. /usr/bin/xattr -c codeql\*.zip
4. unzip codeql\*.zip

3. Lancer codeql

Une fois extrait, vous pouvez exécuter des processus CodeQL en exécutant le fichier exécutable codeql de deux façons :

• En exécutant <extraction-root>/codeql/codeql, où <extraction-root> est le dossier dans lequel vous avez extrait le package de CodeQL CLI.
• En ajoutant <extraction-root>/codeql à votre PATH, afin de pouvoir exécuter le fichier exécutable uniquement comme codeql.

À ce stade, vous pouvez exécuter des commandes CodeQL. Pour obtenir la liste complète des commandes CodeQL CLI, consultez le « Manuel de CodeQL CLI ».

4. Vérifier votre configuration de CodeQL CLI

CodeQL CLI a des sous-commandes que vous pouvez exécuter pour vérifier que vous êtes correctement configuré pour créer et analyser des bases de données :

• Exécutez codeql resolve languages pour afficher les langages disponibles pour la création de base de données. Cette opération liste les langages pris en charge par défaut dans votre package CodeQL CLI.

Vous pouvez également télécharger des packs de requêtes pendant l’analyse à l’aide de l’indicateur --download de la commande codeql database analyze.

Extraction directe du code source CodeQL

Certains utilisateurs préfèrent utiliser des sources de requêtes CodeQL directement afin de travailler sur les requêtes partagées open source ou d’y contribuer. Pour ce faire, les étapes suivantes sont recommandées. Notez que les instructions suivantes constituent une alternative légèrement plus compliquée à l’utilisation des packages CodeQL comme expliqué ci-dessus.

1. Télécharger le zip de CodeQL CLI

Suivez l’étape 1 de la section précédente.

2. Créer un répertoire CodeQL

Créez un répertoire dans lequel vous pouvez placer l’interface CLI et toutes les requêtes et bibliothèques que vous souhaitez utiliser. Par exemple : $HOME/codeql-home.

Les opérations de recherche intégrées de l’interface CLI recherchent automatiquement dans tous ses répertoires frères les fichiers utilisés lors de la création et de l’analyse de la base de données. Le fait de garder ces composants dans leur propre répertoire empêche l’interface CLI de rechercher dans des répertoires frères non concernés tout en s’assurant que tous les fichiers sont disponibles sans spécifier d’autres options sur la ligne de commande.

3. Obtenir une copie locale des requêtes CodeQL

Le dépôt CodeQL contient les requêtes et bibliothèques nécessaires pour l’analyse CodeQL de tous les langages pris en charge. Clonez une copie de ce dépôt dans codeql-home.

Par défaut, la racine du dépôt cloné est nommée codeql. Renommez ce dossier codeql-repo pour éviter tout conflit avec l’interface CodeQL CLI que vous allez extraire à l’étape 4. Si vous utilisez git sur la ligne de commande, vous pouvez cloner et renommer le dépôt en une seule étape en exécutant git clone git@github.com:github/codeql.git codeql-repo dans le dossier codeql-home.

4. Extraire l’archive zip

Pour les utilisateurs de Linux, Windows et macOS (version 10.14 « Mojave » et antérieure), extrayez simplement l’archive zip dans le répertoire que vous avez créé à l’étape 2.

Par exemple, si le chemin de votre copie du dépôt CodeQL est $HOME/codeql-home/codeql-repo, extrayez l’interface CLI dans $HOME/codeql-home/.

5. Lancer codeql

Consultez l’étape 3 de la section précédente.

6. Vérifier votre configuration de CodeQL CLI

CodeQL CLI a des sous-commandes que vous pouvez exécuter pour vérifier que vous êtes correctement configuré pour créer et analyser des bases de données :

• Exécutez codeql resolve languages pour afficher les langages disponibles pour la création de base de données. Cette opération liste les langages pris en charge par défaut dans votre package CodeQL CLI.
• Exécutez codeql resolve qlpacks pour montrer les packs CodeQL que l’interface CLI peut trouver. Cela affiche les noms de tous les packs CodeQL directement disponibles pour CodeQL CLI. Cela devrait inclure :
• Les packs de requêtes pour chaque langage pris en charge, par exemple codeql/{language}-queries. Ces packs contiennent les requêtes standard qui seront exécutées pour chaque analyse.
• Les packs de bibliothèques pour chaque langage pris en charge, par exemple codeql/{language}-all. Ces packs contiennent des bibliothèques de requêtes, telles que les bibliothèques de flux de contrôle et de flux de données, qui peuvent être utiles aux auteurs de requêtes.
• Les packs d’exemples pour chaque langage pris en charge, par exemple codeql/{language}-examples. Ces packs contiennent des extraits de code utiles de CodeQL que les auteurs de requêtes peuvent trouver utiles.
• Les packs hérités qui garantissent que les bibliothèques et les requêtes personnalisées créées à l’aide de produits plus anciens sont compatibles avec votre version de CodeQL.

Utilisation de deux versions de CodeQL CLI

Si vous souhaitez utiliser les dernières fonctionnalités de CodeQL pour exécuter des requêtes ou des tests CodeQL, mais que vous souhaitez également préparer des bases de données compatibles avec une version spécifique de l’analyse du code CodeQL sur GitHub Enterprise Server, vous devrez peut-être installer deux versions de l’interface CLI. La configuration de répertoire recommandée dépend des versions que vous souhaitez installer :

• Si les deux versions sont 2.0.2 (ou plus récentes), vous pouvez décompresser les deux archives CLI dans le même répertoire parent.
• Si au moins une des versions est 2.0.1 (ou plus ancienne), les archives CLI décompressées ne peuvent pas se trouver dans le même répertoire parent, mais elles peuvent partager le même répertoire grand-parent. Par exemple, si vous décompressez la version 2.0.2 dans $HOME/codeql-home/codeql-cli, la version plus ancienne doit être décompressée dans $HOME/codeql-older-version/old-codeql-cli. Ici, le grand-parent commun est le répertoire $HOME.