Configuration avancée de l’interface CLI CodeQL

À propos de la configuration avancée de CodeQL CLI

Si vous prévoyez d’utiliser CodeQL pour effectuer d’autres tâches que la simple analyse de codes, vous préférerez peut-être une configuration avancée de CodeQL CLI.

• Si vous souhaitez envoyer des requêtes partagées en open source CodeQL, vous pouvez choisir de travailler directement avec le code source de CodeQL.
• Si vous souhaitez utiliser les dernières fonctionnalités de CodeQL pour générer des alertes d’analyse de code pour un codebase, mais que vous souhaitez également analyser un autre codebase qui n’est compatible qu’avec une version spécifique de CodeQL CLI, vous pouvez installer plusieurs versions de CodeQL CLI.
• Si vous effectuez des recherches ou élaborez des requêtes, vous pouvez télécharger des bases de données intéressantes ou uniques à partir de GitHub.com.

Pour en savoir plus sur la configuration la plus simple de CodeQL CLI, consultez Configuration de CodeQL CLI.

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.

1. Télécharger l’archive tar de CodeQL CLI

Le package de téléchargement CodeQL CLI est une archive tar 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. Cela garantit la compatibilité et offre de meilleures performances qu’un téléchargement de CodeQL CLI et une extraction des requêtes CodeQL. Si vous envisagez d’exécuter l’interface CLI sur une seule plateforme, téléchargez le fichier codeql-bundle-PLATFORM.tar.zst approprié. Vous pouvez également télécharger codeql-bundle.tar.zst qui contient l’interface CLI pour toutes les plateformes prises en charge.

Il existe également des variantes tar.gz du bundle, qui sont identiques aux variantes tar.zst, sauf qu’elles sont compressées à l’aide de l’algorithme gzip moins efficace. La seule raison de télécharger les variantes tar.gz est si vous utilisez des outils de décompression plus anciens qui ne prennent pas en charge l’algorithme de compression Zstandard.

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 « Création et utilisation de packs CodeQL ».

4. Extraire l’archive tar de CodeQL CLI

Extrayez l’archive tar 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

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.

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. Vous pouvez télécharger les versions de CodeQL CLI souhaitées et décompresser les deux archives CLI dans le même répertoire parent.

Téléchargement des bases de données à partir de GitHub.com

GitHub stocke les bases de données CodeQL pour plus de 200 000 référentiels sur GitHub.com, que vous pouvez télécharger à l’aide de l’API REST. La liste des référentiels s’allonge et évolue constamment pour s’assurer qu’elle inclut les codebases les plus intéressants pour la recherche sur la sécurité.

Vous pouvez également analyser des bases de données à partir de GitHub.com en utilisant CodeQL pour l’extension VS Code. Pour plus d’informations, consultez « Exécuter des requêtes CodeQL ».

Vous pouvez vérifier si un dépôt a des bases de données CodeQL disponibles en téléchargement à l’aide du point de terminaison /repos/<owner>/<repo>/code-scanning/codeql/databases. Par exemple, pour rechercher des bases de données CodeQL avec GitHub CLI, vous devez exécuter :

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases

Cette commande retourne des informations sur toutes les bases de données CodeQL disponibles dans un dépôt, y compris le langage que représente la base de données et la date de la dernière mise à jour de la base de données. Si aucune base de données CodeQL n’est disponible, la réponse est vide.

Une fois que vous avez confirmé qu’une base de données CodeQL existe pour le langage qui vous intéresse, vous pouvez la télécharger en utilisant la commande suivante :

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip

Pour plus d’informations, consultez la documentation pour Obtenir un point de terminaison de base de données CodeQL.

Avant d’exécuter une analyse avec CodeQL CLI, vous devez décompresser les bases de données.