Analyse de votre code avec des requêtes CodeQL

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

Pour analyser une base de code, vous exécutez des requêtes sur une CodeQL base de données extraite du code. CodeQL les analyses produisent des résultats qui peuvent être chargés sur GitHub afin de générer des alertes d’analyse du code.

Prerequisites

Avant de commencer une analyse, vous devez :

•         [Configurer le CodeQL CLI](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli) pour exécuter des commandes localement.
  

•         [Créez une CodeQL base de données](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis) pour le code source à analyser.
  

La façon la plus simple d’exécuter codeql database analyze consiste à utiliser les requêtes standard incluses dans le CodeQL CLI bundle.

En cours d’exécution codeql database analyze

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

1. Télécharge éventuellement les packages référencés CodeQL qui ne sont pas disponibles localement.
2. Exécute un ou plusieurs fichiers de requête, en les exécutant sur une CodeQL base de données.
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.

          **Recommandé.** Permet d’envoyer des informations de couverture de fichier au page d’état de l’outil. Pour plus d’informations, consultez « [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page#how-codeql-defines-scanned-files) ». |

| --sarif-include-query-help | | Indiquez si vous souhaitez inclure l’aide des requêtes dans la sortie SARIF. L'un des éléments suivants : always : Inclure l’aide des requêtes pour toutes les requêtes. custom_queries_only (par défaut) : inclure l’aide des requêtes uniquement pour les requêtes personnalisées, c’est-à-dire les requêtes appartenant à des packs de requêtes qui ne sont pas de la forme codeql/<lang>-queries. never : N’inclut aucune aide pour les requêtes. Toute aide associée aux requêtes personnalisées incluse dans la sortie SARIF sera affichée dans les alertes d’analyse du code pour la requête. Pour plus d’informations, consultez « Écriture de requêtes personnalisées pour l’interface CLI CodeQL ». | | <packs> | | Utilisez si vous souhaitez inclure CodeQL des packs de requêtes dans votre analyse. Pour plus d’informations, consultez Téléchargement et utilisation de CodeQL packs. | | --download | | Utilisez si certains de vos CodeQL packs de requêtes 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. | | --threat-model | | (Préversion publique) Utilisez cet outil pour ajouter des modèles de menace et configurer des sources supplémentaires dans votre analyse CodeQL. Pendant le préversion publique, seuls les modèles de menace sont pris en charge par l'analyse Java. Pour plus d’informations, consultez « analyse de base de données ». |

          **Mise à niveau des bases de données**

Pour les bases de données créées par CodeQL CLI la version 2.3.3 ou antérieure, vous devez mettre à niveau explicitement la base de données avant de pouvoir exécuter une analyse avec une version plus récente du 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 la version 2.3.4 ou ultérieure, l’interface CLI exécute implicitement toutes 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 analyse de base de données.

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

Cet exemple analyse une base de données stockée à CodeQL et enregistre les résultats sous forme de 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. Cela est essentiel lorsque vous avez plusieurs CodeQL bases de données à analyser pour une validation unique dans un référentiel.

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --format=sarifv2.1.0 --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 éventuellement soumettre des informations de couverture de fichier à GitHub pour affichage sur le page d’état de l’outil pour code scanning. Pour plus d’informations sur la page de couverture des fichiers, consultez Utiliser la page d’état de l’outil pour l’analyse du code.

Pour inclure des informations de couverture de fichiers avec vos code scanning résultats, 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-typescript \
    --sarif-add-baseline-file-info \ --format=sarifv2.1.0 \
    --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 à l’aide CodeQL de packs et comment utiliser une extraction locale du CodeQL référentiel. Ces exemples supposent que vos CodeQL bases de données ont été créées dans un répertoire qui est un frère de vos copies locales du CodeQL référentiel.

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

Pour exécuter un pack de requêtes existant CodeQL à partir du GitHubContainer 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 l'ensemble de requêtes par défaut de deux packs de requêtes : la version 1.0.0 de microsoft/coding-standards 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 CodeQL base de données pour une base de code 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 recherche des bogues potentiels liés à des variables inutilisées, des importations, des fonctions ou des classes , il s’agit de l’une des requêtes JavaScript incluses dans le CodeQL référentiel. 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 CodeQL référentiel, vous pouvez exécuter les mêmes requêtes en spécifiant directement le chemin d’accès à 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 Écriture de requêtes personnalisées pour l’interface CLI CodeQL.

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 dans le pack de requêtes codeql/python-queries, vous exécutez :

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 CodeQL référentiel, vous pouvez exécuter les mêmes requêtes en spécifiant directement le chemin d’accès au 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é. La spécification --format=sarif-latest garantit que les résultats sont mis en forme en fonction de la spécification SARIF la plus récente prise en charge par CodeQL.

Exécution d’un sous-ensemble de requêtes dans un CodeQL pack

Si vous utilisez CodeQL CLI v2.8.1 ou une version ultérieure, vous pouvez inclure un chemin à la fin d’une spécification de pack pour exécuter un sous-ensemble de requêtes à l’intérieur du 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 CodeQL pack.
  

•         `range` est une [plage semver](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges).
  

•         `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. Elle est considérée par rapport à la racine du CodeQL paquet.

Pour analyser une base de données en utilisant toutes les requêtes du dossier experimental/Security dans le package codeql/cpp-queriesCodeQL, vous pouvez utiliser :

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

Pour exécuter la RedundantNullCheckParam.ql requête dans le codeql/cpp-queriesCodeQL pack, 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 à l’aide de la cpp-security-and-quality.qls``codeql/cpp-queriesCodeQL suite de requêtes à partir d’une version du pack >= 0.0.3 et < 0.1.0 (la version compatible la plus élevée 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 CodeQL packs, 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 CodeQL base de données pour une base de code 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 codeql/cpp-queriesCodeQL pack de requêtes, exécute l’analyse et génère un fichier au format SARIF version 2.1.0 pris en charge par toutes les versions de GitHub. Ce fichier peut être chargé sur GitHub en exécutant codeql github upload-results ou l’API d’analyse du code. Pour plus d’informations, consultez Chargement des résultats d’analyse CodeQL dans GitHub ou Points de terminaison d’API REST pour l’analyse de codes.

          CodeQL les suites de requêtes sont des `.qls` fichiers qui utilisent des directives pour sélectionner des requêtes à exécuter en fonction de certaines propriétés de métadonnées. Les packs standard CodeQL ont des métadonnées qui spécifient l’emplacement des suites de requêtes utilisées par l’analyse du code. Par conséquent, vous CodeQL CLI savez où rechercher ces fichiers de suite automatiquement et vous n’avez pas besoin de 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.

Inclusion de packs de modèles afin d’ajouter des sources potentielles de données contaminées

Vous pouvez configurer des modèles de menace dans une code scanning analyse. Pour plus d’informations, consultez les modèles de menace pour Java et Kotlin et les modèles de menace pour C# dans la CodeQL documentation.

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --threat-model=local \
  --output=/temp/my-company.sarif codeql/java-queries

Dans cet exemple, les requêtes pertinentes du pack de requêtes standard codeql/java-queries utiliseront le modèle de menace local, ainsi que le modèle de menace par défaut pour les sources de flux de données remote. Vous devez utiliser le modèle de menace local si vous considérez que les données provenant de sources locales (par exemple les systèmes de fichiers, les arguments de ligne de commande, les bases de données et les variables d’environnement) constituent des sources potentielles de données contaminées pour votre base de code.

Results

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

Pour en savoir plus sur les résultats au format CSV, consultez Sortie CSV de l'outil CLI CodeQL.

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.

Affichage des informations de journal et de diagnostic

Lorsque vous analysez une CodeQL base de données à l’aide d’une code scanning suite de requêtes, en plus de générer des informations détaillées sur les alertes, l’interface CLI signale les données de diagnostic à partir de l’étape de génération de la base de données et des métriques récapitulatives. Si vous choisissez de générer une sortie SARIF, les données supplémentaires sont également incluses dans le fichier SARIF. Pour les référentiels avec quelques alertes, vous trouverez peut-être ces informations utiles pour déterminer s’il existe réellement peu de problèmes dans le code ou s’il y a eu des erreurs qui génèrent la CodeQL base de données. Pour obtenir une sortie plus détaillée de codeql database analyze, utilisez l’option --verbose.

Pour plus d’informations sur le type d’informations de diagnostic disponibles, consultez Journaux d’analyse du code.

Vous pouvez choisir d’exporter et de charger des informations de diagnostic, GitHub même si une CodeQL analyse échoue. Pour plus d’informations, consultez « Chargement des résultats d’analyse CodeQL dans GitHub ».

Étapes suivantes

• Pour savoir comment télécharger les résultats de votre CodeQL analyse vers GitHub, veuillez consulter Chargement des résultats d’analyse CodeQL dans GitHub.