À 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 :
- Télécharge éventuellement tous les packages CodeQL référencés qui ne sont pas disponibles localement.
- Exécute un ou plusieurs fichiers de requête en les exécutant sur une base de données CodeQL.
- 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.
- 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>...
Remarque : Si vous analysez plusieurs bases de données CodeQLL pour un seul commit, vous devez spécifier une catégorie SARIF pour chaque ensemble de résultats généré par cette commande. Quand vous chargez les résultats sur GitHub, l’code scanning utilise cette catégorie pour stocker les résultats de chaque langage séparément. Si vous oubliez de spécifier une catégorie, chaque chargement remplace les résultats précédents.
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.
Option | Obligatoire | Usage |
---|---|---|
<database> | Spécifiez le chemin du répertoire qui contient la base de données CodeQL à analyser. | |
<packs,queries> | Spécifiez les requêtes ou packs CodeQL à exécuter. Pour exécuter les requêtes standard utilisées pour l’code scanning, omettez ce paramètre. Pour voir les autres suites de requêtes incluses dans le bundle de l’CodeQL CLI, regardez dans /<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites . Pour plus d’informations sur la création de votre propre suite de requêtes, consultez Création de suites de requêtes CodeQL dans la documentation du CodeQL CLI. | |
--format | Spécifiez le format du fichier de résultats généré lors de l’analyse. Un certain nombre de formats différents sont pris en charge, notamment les formats CSV, SARIF et graphique. Pour le chargement sur GitHub, ce doit être : sarif-latest . Pour plus d’informations, consultez « Prise en charge de SARIF pour l’analyse du code ». | |
--output | Spécifiez l’emplacement d’enregistrement du fichier de résultats SARIF. | |
--sarif-category | Facultatif pour une analyse de base de données unique. Obligatoire pour définir le langage quand vous analysez plusieurs bases de données pour un seul commit dans un dépôt. Spécifiez une catégorie à inclure dans le fichier de résultats SARIF pour cette analyse. Une catégorie est utilisée pour distinguer plusieurs analyses pour le même outil et le même commit, mais effectuées dans différents langages ou différentes parties du code. | |
--sarif-add-baseline-file-info | Recommandé. À utiliser pour envoyer des informations de couverture des fichiers à la page d’état de l’outil. Pour plus d’informations, consultez « À propos de la page d’état de l’outil pour l’analyse du code ». | |
--sarif-add-query-help | Utilisez cette option pour inclure toute aide disponible sur les requêtes rendue en Markdown pour les requêtes personnalisées utilisées dans votre analyse. Toute aide sur les requêtes incluses dans la sortie SARIF pour des requêtes personnalisées va s’afficher dans l’interface utilisateur de l’analyse du code si la requête appropriée génère une alerte. Pour plus d’informations, consultez « Inclusion d’une aide aux requêtes pour les requêtes CodeQL personnalisées dans des fichiers SARIF ». | |
<packs> | À utiliser si vous souhaitez inclure des packs de requêtes CodeQL dans votre analyse. Pour plus d’informations, consultez « Téléchargement et utilisation de packs CodeQL ». | |
--download | À utiliser si certains de vos packs de requêtes CodeQL ne sont pas encore sur le disque et doivent être téléchargés avant d’exécuter des requêtes. | |
--threads | Utilisez cette option si vous voulez utiliser plusieurs threads pour exécuter des requêtes. La valeur par défaut est 1 . Vous pouvez spécifier d’autres threads pour accélérer l’exécution des requêtes. Pour définir le nombre de threads sur le nombre de processeurs logiques, spécifiez 0 . | |
--verbose | Utilisez cette option pour obtenir des informations détaillées sur le processus d’analyse et les données diagnostiques issues du processus de création de la base de données. |
Mise à niveau des bases de données
Pour les bases de données créées par CodeQL CLI version 2.3.3 ou antérieure, vous devez les mettre à niveau explicitement avant de pouvoir exécuter une analyse avec une version plus récente de CodeQL CLI. Si cette étape est nécessaire, vous verrez un message vous indiquant que votre base de données doit être mise à niveau lorsque vous exécutez database analyze
.
Pour les bases de données créées par CodeQL CLI version 2.3.4 ou ultérieure, l’interface CLI exécute implicitement les mises à niveau requises. L’exécution explicite de la commande de mise à niveau n’est pas nécessaire.
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
Remarque
La fonctionnalité de gestion de packages CodeQL, y compris des packs CodeQL, est actuellement disponible en version bêta et peut faire l’objet de modifications. Dans la version bêta, les packs CodeQL sont seulement disponibles avec GitHub Packages - GitHub Container registry. Pour utiliser cette fonctionnalité bêta, installez la dernière version du bundle CodeQL CLI à partir de : https://github.com/github/codeql-action/releases.
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.
Important
Vous devez éviter de spécifier la racine d’un pack de requêtes CodeQL principales lors de l’exécution de database analyze
, car il risque de contenir des requêtes spéciales qui ne sont pas conçues pour être utilisées avec la commande. Au lieu de cela, exécutez le pack de requêtes pour inclure les requêtes par défaut du pack dans l’analyse, ou exécutez l’une des suites de requêtes d’analyse du code.
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.
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 '\\\\'. |
Chemin d’accès | 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.