Skip to main content

Cette version de GitHub Enterprise Server ne sera plus disponible le 2024-06-29. Aucune publication de correctifs n’est effectuée, même pour les problèmes de sécurité critiques. Pour de meilleures performances, une sécurité améliorée et de nouvelles fonctionnalités, effectuez une mise à niveau vers la dernière version de GitHub Enterprise. Pour obtenir de l’aide sur la mise à niveau, contactez le support GitHub Enterprise.

Analyse de votre code avec des requêtes CodeQL

Vous pouvez exécuter des requêtes sur une base de données CodeQL extraite d'un codebase.

Qui peut utiliser cette fonctionnalité ?

GitHub CodeQL est concédé sous licence par utilisateur lors de l’installation. Vous pouvez utiliser CodeQL uniquement pour certaines tâches soumises aux restrictions de licence. Pour plus d’informations, consultez « À propos de CodeQL CLI ».

Si vous disposez d’une licence GitHub Advanced Security, vous pouvez utiliser CodeQL pour l’analyse automatisée, l’intégration continue et la livraison continue. Pour plus d’informations, consultez « À propos de GitHub Advanced Security ».

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

Remarque : cet article décrit les fonctionnalités disponibles avec l’offre groupée CodeQL CLI 2.12.7 incluse dans la mise en production initiale de GitHub Enterprise Server 3.9.

Si votre administrateur de site a mis à jour votre versionCodeQL CLI vers une version plus récente, consultez la version GitHub Enterprise Cloud de cet article pour obtenir plus d’informations sur les dernières fonctionnalités.

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 :

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

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 Enterprise Server, 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.

OptionObligatoireUsage
<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.
--formatSpé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 : sarifv2.1.0. Pour plus d'informations, consultez « Prise en charge de SARIF pour l’analyse du code ».
--outputIndiquez l'emplacement où vous souhaitez enregistrer le fichier de résultats SARIF, y compris le nom de fichier souhaité avec l'extension .sarif.
--sarif-categoryFacultatif 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-infoRecommandé. À 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-helpUtilisez 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 « Utilisation de requêtes personnalisées avec CodeQL CLI ».
<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.
--threadsUtilisez 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.
--verboseUtilisez 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(Beta) Permet d'ajouter des modèles de risque pour configurer des sources supplémentaires dans votre analyse CodeQL. Pendant la version bêta, les modèles de risque ne sont pris en charge que par l'analyse Java. Pour plus d'informations, consultez « database analyze ».

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=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 en option envoyer les informations de couverture des fichiers à GitHub Enterprise Server 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=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 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 « 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