Analyse de votre code avec des requêtes CodeQL

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

Pour analyser un codebase, vous pouvez exécuter 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 ».

Autres commandes d’exécution de requête

Les requêtes exécutées avec database analyze ont des exigences de métadonnées strictes. Vous pouvez également exécuter des requêtes à l’aide des sous-commandes de niveau plomberie suivantes :

• database run-queries, qui génère des résultats non interprétés dans un format binaire intermédiaire appelé BQRS.

• query run, qui génère des fichiers BQRS ou affiche les tables de résultats directement dans la ligne de commande. L’affichage des résultats directement dans la ligne de commande peut être utile pour le développement de requêtes itératives à l’aide de l’interface CLI.

Les requêtes exécutées avec ces commandes n’ont pas les mêmes exigences de métadonnées. Toutefois, pour enregistrer des données lisibles par l’homme, vous devez traiter chaque fichier de résultats BQRS avec la sous-commande de plomberie bqrs decode. C’est pourquoi, dans la plupart des cas d’usage, il est plus simple d’utiliser database analyze pour générer directement des résultats interprétés.

Prérequis

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

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

Vous devez spécifier <database>, --format et --output. Vous pouvez spécifier des options supplémentaires en fonction de l’analyse que vous voulez effectuer.

Pour des détails complets sur toutes les options que vous pouvez utiliser lors de l’analyse des bases de données, consultez « database analyze ».

Exemple de base d’une analyse d’une base de données CodeQL

Cet exemple analyse une base de données CodeQL stockée dans /codeql-dbs/example-repo et enregistre les résultats sous la forme d’un fichier SARIF : /temp/example-repo-js.sarif. Il utilise --sarif-category pour inclure des informations supplémentaires dans le fichier SARIF qui identifient les résultats comme du code JavaScript. Cette option est primordiale quand vous avez plusieurs bases de données CodeQL à analyser pour une seule évaluation dans un référentiel.

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

Ajout d’informations de couverture des fichiers à vos résultats pour le monitoring

Vous pouvez en option envoyer les informations de couverture des fichiers à GitHub pour les afficher sur la page d’état de l’outil pour code scanning. Pour plus d’informations sur la page de couverture des fichiers, consultez « À propos de la page d’état de l’outil pour l’analyse du code ».

Pour inclure les informations de couverture des fichiers avec vos résultats code scanning, ajoutez l’indicateur --sarif-add-baseline-file-info à l’appel codeql database analyze dans votre système CI, par exemple :

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript \
    --sarif-add-baseline-file-info \ --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

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 pour les 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, un répertoire ou une suite de requêtes dont le chemin contient un littéral @ ou :, vous pouvez préfixer la spécification des requêtes 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 Personnalisation de l’analyse avec 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 l’interface CLI de CodeQL 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 dans l’interface CLI de CodeQL ».

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.

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 »