Analyse des bases de données avec l’interface CLI de CodeQL

À propos de l’analyse des bases de données avec CodeQL CLI

Pour analyser un codebase, vous exécutez des requêtes sur une base de données CodeQL extraite du code.

Les analyses CodeQL produisent des résultats interprétés qui peuvent être affichés sous forme d’alertes ou de chemins dans le code source. Pour plus d’informations sur l’écriture de requêtes à exécuter avec database analyze, consultez « Utilisation de requêtes personnalisées avec CodeQL CLI ».

Avant de commencer une analyse, vous devez :

• Configurer CodeQL CLI pour exécuter des commandes localement.
• Créer une base de données CodeQL pour le code source que vous souhaitez analyser.

Le moyen le plus simple d’exécuter codeql database analyze consiste à utiliser des packs CodeQL. Vous pouvez également exécuter la commande à l’aide de requêtes à partir d’une extraction locale du dépôt CodeQL, ce que vous voudrez peut-être faire si vous souhaitez personnaliser les principales requêtes CodeQL.

En cours d’exécution codeql database analyze

Lorsque la commande database analyze est exécutée, elle :

1. Télécharge éventuellement tous les packages CodeQL référencés qui ne sont pas disponibles localement.
2. Exécute un ou plusieurs fichiers de requête en les exécutant sur une base de données CodeQL.
3. Interprète les résultats, sur la base de certaines métadonnées de requête, afin que les alertes puissent être affichées au bon endroit dans le code source.
4. Signale les résultats de toutes les requêtes de diagnostic et de synthèse à la sortie standard.

Vous pouvez analyser une base de données en exécutant la commande suivante :

codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>...

Vous devez spécifier :

• <database> : chemin de la base de données CodeQL que vous souhaitez analyser.
• --format : format du fichier de résultats généré pendant l’analyse. Un certain nombre de formats différents sont pris en charge, notamment les formats CSV, SARIF et graphique. Pour plus d’informations sur CSV et SARIF, consultez Résultats. Pour savoir quels autres formats de résultats sont pris en charge, consultez les informations de référence sur l’analyse de bases de données.
• --output : chemin de sortie du fichier de résultats généré pendant l’analyse.

Vous pouvez également spécifier :

• <query-specifiers>... : liste séparée par un espace des requêtes à exécuter sur votre base de données. Il s’agit d’une liste d’arguments, où chaque argument peut être :

  • un chemin vers un fichier de requête
  • un chemin vers un répertoire contenant des fichiers de requête
  • un chemin vers un fichier de suite de requêtes
  • le nom d’un pack de requêtes CodeQL
    • avec une plage de versions facultative
    • avec un chemin facultatif vers une requête, un répertoire ou une suite de requêtes à l’intérieur du pack

  En cas d’omission, la suite de requêtes par défaut pour le langage de la base de données analysée est utilisée. Pour obtenir la syntaxe complète des spécificateurs de requêtes, consultez « Spécification des requêtes à exécuter dans un pack CodeQL ».

• --sarif-category : catégorie d’identification pour les résultats. Utilisée lorsque vous souhaitez charger plusieurs jeux de résultats pour un commit. Par exemple, lorsque vous utilisez github upload-results pour envoyer des résultats pour plusieurs langages à l’API d’analyse du code GitHub. Pour plus d’informations sur ce cas d’usage, consultez Configuration de CodeQL CLI dans votre système CI.

• --sarif-add-query-help : (pris en charge dans les versions 2.7.1 et ultérieures) ajoute toute aide aux requêtes personnalisées écrite au format Markdown dans les fichiers SARIF (v2.1.0 ou ultérieur) générés par l’analyse. L’aide aux requêtes stockée dans les fichiers .qhelp doit être convertie au format .md avant d’exécuter l’analyse. Pour plus d’informations, consultez « Inclusion d’une aide aux requêtes pour les requêtes CodeQL personnalisées dans les fichiers SARIF ».

• --download : indicateur booléen qui permet à l’interface CLI de télécharger tous les packages CodeQL référencés qui ne sont pas disponibles localement. Si cet indicateur n’est pas présent et qu’un package CodeQL référencé n’est pas disponible localement, la commande échoue.

Pour des détails complets sur toutes les options que vous pouvez utiliser lors de l’analyse des bases de données, consultez la documentation de référence sur database analyze.

Spécification des requêtes à exécuter dans un pack CodeQL

Les spécificateurs de requêtes sont utilisés par codeql database analyze et d’autres commandes qui opèrent sur un ensemble de requêtes. La forme complète d’un spécificateur de requête est scope/name@range:path, où :

• scope/name est le nom qualifié d’un pack CodeQL.

• range est une plage semver.

• path est un chemin de système de fichiers vers une requête unique, un répertoire contenant des requêtes ou un fichier de suite de requêtes.

Lorsque vous spécifiez un scope/name, range et path sont facultatifs. Si vous omettez une range, la dernière version du pack spécifié est utilisée. Si vous omettez un path, la suite de requêtes par défaut du pack spécifié est utilisée.

path peut être au choix : un fichier de requête .ql, un répertoire contenant une ou plusieurs requêtes ou un fichier de suite de requêtes .qls. Si vous omettez un nom de pack, vous devez fournir un path, qui sera interprété en fonction du répertoire de travail du processus en cours. Les modèles glob ne sont pas pris en charge.

Si vous spécifiez à la fois un scope/name et un path, le path ne peut pas être absolu. Il est considéré comme relatif à la racine du pack CodeQL.

Exemples de spécificateurs de requêtes

• codeql/python-queries - Toutes les requêtes de la suite de requêtes par défaut de la dernière version du pack codeql/python-queries.

• codeql/python-queries@1.2.3 - Toutes les requêtes de la suite de requêtes par défaut de la version 1.2.3 du pack codeql/python-queries.

• codeql/python-queries@~1.2.3 - Toutes les requêtes de la suite de requêtes par défaut de la dernière version du pack codeql/python-queries qui est >= 1.2.3 et < 1.3.0.

• codeql/python-queries:Functions - Toutes les requêtes du répertoire Functions dans la dernière version du pack codeql/python-queries.

• codeql/python-queries@1.2.3:Functions - Toutes les requêtes du répertoire Functions dans la version 1.2.3 du pack codeql/python-queries.

• codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls - Toutes les requêtes du répertoire codeql-suites/python-code-scanning.qls dans la version 1.2.3 du pack codeql/python-queries.

• suites/my-suite.qls - Toutes les requêtes du fichier suites/my-suite.qls relatives au répertoire de travail actuel.

Exemples d’exécution d’analyses de bases de données

Les exemples suivants montrent comment exécuter database analyze avec les packs CodeQL et comment utiliser une extraction locale du dépôt CodeQL. Ces exemples supposent que vos bases de données CodeQL ont été créées dans un répertoire qui est un frère de vos copies locales du dépôt CodeQL.

Exécution d’un pack de requêtes CodeQL

Pour exécuter un pack de requêtes CodeQL existant à partir de GitHub Container registry, vous pouvez spécifier un ou plusieurs noms de pack :

codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

Cette commande exécute la suite de requêtes par défaut de deux packs de requêtes CodeQL : microsoft/coding-standards version 1.0.0 et la dernière version de github/security-queries sur la base de données spécifiée. Pour plus d’informations sur les suites par défaut, consultez « Publication et utilisation de packs CodeQL ».

L'indicateur --download est facultatif. Son utilisation garantit que le pack de requêtes est téléchargé s’il n’est pas encore disponible en local.

Exécution d’une requête unique

Pour exécuter une requête unique sur une base de données CodeQL pour un codebase JavaScript, vous pouvez utiliser la commande suivante à partir du répertoire contenant votre base de données :

codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

Cette commande exécute une requête simple qui trouve les bogues potentiels relatifs à des variables, importations, fonctions ou classes inutilisées. Il s’agit de l’une des requêtes JavaScript incluses dans le dépôt CodeQL. Vous pouvez exécuter plusieurs requêtes en spécifiant une liste de chemins similaires séparés par des espaces.

L’analyse génère un fichier CSV (js-results.csv) dans un nouveau répertoire (js-analysis).

Sinon, si vous avez extrait le dépôt CodeQL, vous pouvez exécuter les mêmes requêtes en spécifiant directement le chemin de la requête :

codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

Vous pouvez également exécuter vos propres requêtes personnalisées avec la commande database analyze. Pour plus d’informations sur la préparation de vos requêtes à utiliser avec CodeQL CLI, consultez « Utilisation de requêtes personnalisées avec CodeQL CLI ».

Exécution de toutes les requêtes dans un répertoire

Vous pouvez exécuter toutes les requêtes d’un répertoire en fournissant le chemin du répertoire, au lieu de lister tous les fichiers de requêtes individuels. Les chemins étant recherchés de manière récursive, toutes les requêtes contenues dans les sous-dossiers seront également exécutées.

Par exemple, pour exécuter toutes les requêtes Python contenues dans le répertoire Functions du pack de requêtes codeql/python-queries, vous devez exécuter :

codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download

Sinon, si vous avez extrait le dépôt CodeQL, vous pouvez exécuter les mêmes requêtes en spécifiant directement le chemin du répertoire :

codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif

Une fois l’analyse terminée, un fichier de résultats SARIF est généré. Spécifier --format=sarif-latest garantit que les résultats sont mis en forme selon la spécification SARIF la plus récente prise en charge par CodeQL.

Exécution d’une partie des requêtes d’un pack CodeQL

Si vous utilisez CodeQL CLI version 2.8.1 ou ultérieure, vous pouvez inclure un chemin à la fin de la spécification d’un pack pour exécuter une partie des requêtes dans le pack. Cela s’applique à toute commande qui localise ou exécute des requêtes dans un pack.

La spécification complète d’un ensemble de requêtes se présente sous la forme scope/name@range:path, où :

• scope/name est le nom qualifié d’un pack CodeQL.

• range est une plage semver.

• path est un chemin de système de fichiers vers une requête unique, un répertoire contenant des requêtes ou un fichier de suite de requêtes.

Lorsque vous spécifiez un scope/name, range et path sont facultatifs. Si vous omettez une range, la dernière version du pack spécifié est utilisée. Si vous omettez un path, la suite de requêtes par défaut du pack spécifié est utilisée.

path peut être, au choix, un fichier de requête \*.ql, un répertoire contenant une ou plusieurs requêtes ou un fichier de suite de requêtes .qls. Si vous omettez un nom de pack, vous devez fournir un path, qui sera interprété en fonction du répertoire de travail du processus en cours.

Si vous spécifiez un scope/name et un path, le path ne peut pas être absolu. Il est considéré comme relatif à la racine du pack CodeQL.

Pour analyser une base de données avec toutes les requêtes du dossier experimental/Security dans le pack codeql/cpp-queries CodeQL, vous pouvez utiliser :

codeql database analyze --format=sarif-latest --output=results <db> \
    codeql/cpp-queries:experimental/Security

Pour exécuter la requête RedundantNullCheckParam.ql dans le pack codeql/cpp-queries CodeQL, utilisez :

codeql database analyze --format=sarif-latest --output=results <db> \
    'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql'

Pour analyser votre base de données avec la suite de requêtes cpp-security-and-quality.qls depuis une version du pack codeql/cpp-queries CodeQL qui est >= 0.0.3 et < 0.1.0 (la version compatible la plus haute sera choisie), vous pouvez utiliser :

codeql database analyze --format=sarif-latest --output=results <db> \
   'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls'

Si vous devez référencer un fichier de requête, un répertoire ou une suite dont le chemin contient un littéral @ ou :, vous pouvez préfixer la spécification de la requête avec path: comme suit :

codeql database analyze --format=sarif-latest --output=results <db> \
    path:C:/Users/ci/workspace@2/security/query.ql

Pour plus d’informations sur les packs CodeQL, consultez À propose des packs CodeQL.

Exécution de suites de requêtes

Pour exécuter une suite de requêtes sur une base de données CodeQL pour un codebase C/C++, vous pouvez utiliser la commande suivante à partir du répertoire contenant votre base de données :

codeql database analyze <cpp-database> codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download

Cette commande télécharge le pack de requêtes codeql/cpp-queries CodeQL, exécute l’analyse et génère un fichier au format SARIF version 2.1.0 qui est pris en charge par toutes les versions de GitHub. Ce fichier peut être chargé dans GitHub en exécutant codeql github upload-results ou l’API d’analyse du code. Pour plus d’informations, consultez « Configuration de l’interface CLI de CodeQL dans votre système CI » ou « Analyse du code ».

Les suites de requêtes CodeQL sont des fichiers .qls qui utilisent des directives pour sélectionner des requêtes à exécuter selon certaines propriétés de métadonnées. Les packs CodeQL standard ont des métadonnées qui spécifient l’emplacement des suites de requêtes utilisées par l’analyse du code. Ainsi, CodeQL CLI sait où trouver ces fichiers de suite automatiquement, et vous n’avez pas à spécifier le chemin complet sur la ligne de commande. Pour plus d’informations, consultez « Création de suites de requêtes CodeQL ».

Pour des informations sur la création de suites de requêtes personnalisées, consultez « Création de suites de requêtes CodeQL ».

Informations de diagnostic et de synthèse

Lorsque vous créez une base de données CodeQL, l’extracteur stocke les données de diagnostic dans la base de données. Les suites de requêtes d’analyse du code incluent des requêtes supplémentaires pour reporter sur ces données de diagnostic et calculer des métriques récapitulatives. Une fois la commande database analyze terminée, l’interface CLI génère le fichier de résultats et reporte toute donnée de diagnostic et de synthèse dans la sortie standard. Si vous choisissez de générer une sortie SARIF, les données supplémentaires sont également incluses dans le fichier SARIF.

Si l’analyse a trouvé moins de résultats pour les requêtes standard que prévu, passez en revue les résultats des requêtes de diagnostic et de synthèse pour vérifier si la base de données CodeQL est susceptible d’être une bonne représentation du codebase que vous souhaitez analyser.

Intégration d’un pack CodeQL dans un workflow d’analyse du code dans GitHub

Vous pouvez utiliser des packs de requêtes CodeQL dans votre configuration d’analyse du code. Cela vous permet de sélectionner des packs de requêtes publiés par différentes sources et de les utiliser pour analyser votre code. Pour plus d’informations, consultez « Utilisation des packs de requêtes CodeQL dans l’action CodeQL » ou « Téléchargement et utilisation de packs de requêtes CodeQL dans votre système CI ».

Inclusion d’une aide aux requêtes pour les requêtes CodeQL personnalisées dans les fichiers SARIF

Si vous utilisez CodeQL CLI pour exécuter des analyses de code sur des systèmes CI/CD tiers, vous pouvez inclure l’aide aux requêtes pour vos requêtes personnalisées dans les fichiers SARIF générés lors d’une analyse. Après avoir chargé le fichier SARIF dans GitHub, l’aide aux requêtes s’affiche dans l’interface utilisateur de l’analyse du code pour toutes les alertes générées par les requêtes personnalisées.

À partir de CodeQL CLI version 2.7.1 et ultérieure, vous pouvez inclure l’aide aux requêtes restituée au format Markdown dans les fichiers SARIF en fournissant l’option --sarif-add-query-help lors de l’exécution de codeql database analyze. Pour plus d’informations, consultez Configuration de CodeQL CLI dans votre système CI.

Vous pouvez écrire une aide aux requêtes pour les requêtes personnalisées directement dans un fichier Markdown et l’enregistrer en même temps que la requête correspondante. Par souci de cohérence avec les requêtes CodeQL standard, vous pouvez aussi écrire une aide aux requêtes au format .qhelp. L’aide aux requêtes écrite dans les fichiers .qhelp ne peut pas être incluse dans les fichiers SARIF et ne peut pas être traitée par l’analyse du code, elle doit par conséquent être convertie au format Markdown avant d’exécuter l’analyse. Pour plus d’informations, consultez « Fichiers d’aide aux requêtes » et « Test des fichiers d’aide aux requêtes ».

Résultats

Vous pouvez enregistrer les résultats d’analyse dans différents formats, notamment SARIF et CSV.

Le format SARIF est conçu pour représenter la sortie d’un large éventail d’outils d’analyse statique. Pour plus d’informations, consultez Sortie SARIF.

Si vous choisissez de générer des résultats au format CSV, chaque ligne du fichier de sortie correspond à une alerte. Chaque ligne est une liste séparée par des virgules avec les informations suivantes.

Propriété	Description	Exemple
Nom	Nom de la requête qui a identifié le résultat.	Inefficient regular expression
Description	Description de la requête.	A regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks.
severity	Gravité de la requête.	error
Message	Message d’alerte.	This part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'.
Path	Chemin du fichier contenant l’alerte.	/vendor/codemirror/markdown.js
Ligne de début	Ligne du fichier où commence le code qui a déclenché l’alerte.	617
Colonne de début	Colonne de la ligne de début qui marque le début du code d’alerte. Non incluse si égal à 1.	32
Ligne de fin	Ligne du fichier où finit le code qui a déclenché l’alerte. Non incluse lorsqu’elle a la même valeur que la ligne de début.	64
Colonne de fin	Lorsqu’elle est disponible, colonne de la ligne de fin qui marque la fin du code d’alerte. Sinon, la ligne de fin est répétée.	617

Les fichiers de résultats peuvent être intégrés à votre propre infrastructure de revue ou de débogage du code. Par exemple, la sortie du fichier SARIF peut être utilisée pour mettre en évidence des alertes au bon endroit dans votre code source à l’aide d’un plug-in de visionneuse SARIF pour votre IDE.

Pour aller plus loin

• « Analyse de vos projets dans CodeQL pour VS Code »