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 qui peuvent être chargés vers GitHub Enterprise Server pour générer des alertes d'analyse de codes.

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.

La méthode la plus simple d'exécuter codeql database analyze consiste à utiliser les requêtes standard incluses dans l'offre groupée CodeQL CLI.

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

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 « Chargement des résultats d'analyse de CodeQL sur GitHub » ou « Points de terminaison d’API REST pour l’analyse de codes ».

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

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

Pour en savoir plus sur les résultats au format CSV, reportez-vous à « Production CSV de l'interface 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

Quand vous analysez une base de données CodeQL avec une suite de requêtes d'code scanning, 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 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. Dans le cas des dépôts avec peu d'alertes, ces informations peuvent s'avérer utiles pour déterminer s'il y a vraiment peu de problèmes dans le code ou s'il y a eu des erreurs lors de la génération de la base de données CodeQL. 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 « Affichage des journaux d’analyse du code ».

Vous pouvez choisir d'exporter et de télécharger des informations de diagnostic vers GitHub Enterprise Server même en cas d'échec d'une analyse CodeQL. Pour plus d'informations, consultez « Chargement des résultats d'analyse de CodeQL sur GitHub ».

Étapes suivantes

• Pour savoir comment télécharger vos résultats d'analyse CodeQL sur GitHub Enterprise Server, reportez-vous à « Chargement des résultats d'analyse de CodeQL sur GitHub ».