Configuration de CodeQL CLI

Configuration de 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.

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 l’interface CLI de CodeQL 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.

Vous devez télécharger le bundle CodeQL à partir de https://github.com/github/codeql-action/releases. Le bundle contient :

• L’CodeQL CLI
• Une version compatible des requêtes et des bibliothèques de https://github.com/github/codeql
• Versions précompilées de toutes les requêtes incluses dans le bundle

Vous devez toujours utiliser le bundle CodeQL, car cela garantit la compatibilité et offre de meilleures performances qu’un téléchargement de l’CodeQL CLI et une extraction des requêtes CodeQL à part. Si vous envisagez d’exécuter l’interface CLI sur une seule plateforme, téléchargez le fichier codeql-bundle-PLATFORM.tar.gz approprié. Vous pouvez également télécharger codeql-bundle.tar.gz 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)

À partir de la version 10.15 (« Catalina ») de macOS, vous devez vérifier 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... ou Paramètres... (version 13 « Ventura » et ultérieures).
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 », « Monterey » ou « Ventura »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 « Manuel des commandes de l’interface CLI CodeQL ».

Test de la configuration de l’CodeQL CLI

Après avoir extrait le bundle de CodeQL CLI, vous pouvez exécuter la commande suivante pour vérifier que l’interface CLI est correctement configurée pour créer et analyser des bases de données :

• codeql resolve qlpacks si /<extraction-root>/codeql est dans le PATH.
• Sinon, /<extraction-root>/codeql/codeql resolve qlpacks.

Extrait de la sortie réussie :

codeql/cpp-all (/<extraction-root>/qlpacks/codeql/cpp-all/<version>)
codeql/cpp-examples (/<extraction-root>/qlpacks/codeql/cpp-examples/<version>)
codeql/cpp-queries (/<extraction-root>/qlpacks/codeql/cpp-queries/<version>)
codeql/csharp-all (/<extraction-root>/qlpacks/codeql/charp-all/<version>)
codeql/csharp-examples (/<extraction-root>/qlpacks/codeql/charp-examples/<version>)
codeql/csharp-queries (/<extraction-root>/qlpacks/codeql/charp-queries/<version>)
codeql/java-all (/<extraction-root>/qlpacks/codeql/java-all/<version>)
codeql/java-examples (/<extraction-root>/qlpacks/codeql/java-examples/<version>)
codeql/java-queries (/<extraction-root>/qlpacks/codeql/java-queries/<version>)
codeql/javascript-all (/<extraction-root>/qlpacks/codeql/javascript-all/<version>)
codeql/javascript-examples (/<extraction-root>/qlpacks/codeql/javascript-examples/<version>)
codeql/javascript-queries (/<extraction-root>/qlpacks/codeql/javascript-queries/<version>)
codeql/python-all (/<extraction-root>/qlpacks/codeql/python-all/<version>)
codeql/python-examples (/<extraction-root>/qlpacks/codeql/python-examples/<version>)
codeql/python-queries (/<extraction-root>/qlpacks/codeql/python-queries/<version>)
codeql/ruby-all (/<extraction-root>/qlpacks/codeql/ruby-all/<version>)
codeql/ruby-examples (/<extraction-root>/qlpacks/codeql/ruby-examples/<version>)
codeql/ruby-queries (/<extraction-root>/qlpacks/codeql/ruby-queries/<version>)
...

Vous devez vérifier que la sortie contient les langages attendus et que l’emplacement du répertoire des fichiers qlpack est correct. L’emplacement doit se trouver dans le bundle de CodeQL CLI extrait, qui est montré dans l’exemple précédent en tant que <extraction root>, sauf si vous utilisez une extraction de github/codeql. Si l’CodeQL CLI ne peut pas localiser les qlpacks pour les langages attendus, vérifiez que vous avez téléchargé le bundle CodeQL et non une copie autonome de l’CodeQL CLI.

Vous pouvez aussi exécuter codeql resolve languages pour montrer 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.

(Facultatif) Vous pouvez télécharger des « Personnalisation de l’analyse avec des packs CodeQL » contenant des requêtes précompilées que vous voulez exécuter. Pour ce faire, exécutez codeql pack download <pack-name> [...pack-name], où pack-name est le nom du pack que vous voulez télécharger. Les packs de requêtes de base sont des bons points de départ. Il s'agit des éléments suivants :

• codeql/cpp-queries
• codeql/csharp-queries
• codeql/go-queries
• codeql/java-queries
• codeql/javascript-queries
• codeql/python-queries
• codeql/ruby-queries

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.

Génération d’un jeton pour l’authentification auprès de GitHub

Si vous voulez charger vos résultats sur GitHub pour les afficher en tant qu’alertes d’analyse du code, vous devez générer un personal access token avec l’autorisation d’écriture security_events. Pour plus d’informations, consultez « Gestion de vos jetons d’accès personnels ».

Si vous avez installé CodeQL CLI dans un système CI de tiers pour créer des résultats à afficher dans GitHub en tant qu’alertes d’analyse du code, vous pouvez utiliser une GitHub App ou un personal access token pour charger les résultats dans GitHub. Pour plus d’informations, consultez « Installation de l’interface CLI de CodeQL dans votre système CI ».

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 1. 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.

Dans ce dépôt, les requêtes et les bibliothèques sont organisées en packs CodeQL. Avec les requêtes elles-mêmes, les packs CodeQL contiennent des métadonnées importantes qui indiquent à CodeQL CLI comment traiter les fichiers de requête. Pour plus d’informations, consultez « Personnalisation de l’analyse avec des packs CodeQL ».

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.