Configuration de l’interface CLI de CodeQL dans votre système CI

À propos de la génération de résultats d’analyse du code avec l’CodeQL CLI

Une fois que vous avez rendu l’CodeQL CLI disponible pour les serveurs de votre système CI et que vous avez vérifié qu’ils peuvent s’authentifier auprès de GitHub, vous êtes prêt à générer des données.

Vous utilisez trois commandes différentes pour générer des résultats et les charger sur GitHub :

1. database create pour créer une base de données CodeQL afin de représenter la structure hiérarchique de chaque langage de programmation pris en charge dans le dépôt.
2. database analyze pour exécuter des requêtes afin d’analyser chaque base de données CodeQL et de synthétiser les résultats dans un fichier SARIF.
3. github upload-results pour charger les fichiers SARIF résultants sur GitHub où les résultats sont mis en correspondance avec une branche ou une demande de tirage (pull request) et affichés sous la forme d’alertes d’code scanning.

Vous pouvez afficher l’aide de ligne de commande pour toute commande en utilisant l’option --help.

Création de bases de données CodeQL à analyser

1. Extrayez le code à analyser :

   • Pour une branche, extrayez la tête (début) de la branche à analyser.
   • Pour une demande de tirage, extrayez son commit de tête ou un commit de fusion généré par GitHub.

2. Configurez l’environnement pour le codebase, en vérifiant que toutes les dépendances sont disponibles. Pour plus d’informations, consultez « Création de bases de données pour les langages non compilés » et « Création de bases de données pour les langages compilés » dans « Préparation de votre code pour l’analyse CodeQL ».

3. Recherchez la commande de génération, le cas échéant, pour le codebase. En général, celle-ci est disponible dans un fichier de configuration dans le système CI.

4. Exécutez codeql database create à partir de la racine d’extraction de votre dépôt et générez le codebase.

   # Single supported language - create one CodeQL database
   codeql database create <database> --command <build> \
         --language=<language-identifier>
   
   # Multiple supported languages - create one CodeQL database per language
   codeql database create <database> --command <build> \
         --db-cluster --language=<language-identifier>,<language-identifier>
   

   Remarque : Si vous utilisez une build conteneurisée, vous avez besoin d’exécuter l’CodeQL CLI à l’intérieur du conteneur dans lequel votre tâche de génération se produit.

Pour plus d’informations, consultez « Préparation de votre code pour l’analyse CodeQL ».

Exemple avec un langage unique

Cet exemple crée une base de données CodeQL pour le dépôt extrait à l’emplacement /checkouts/example-repo. Il utilise l’extracteur JavaScript pour créer une représentation hiérarchique du code JavaScript et TypeScript dans le dépôt. La base de données obtenue est stockée dans /codeql-dbs/example-repo.

$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

Exemple avec plusieurs langages

Cet exemple crée deux bases de données CodeQL pour le dépôt extrait à l’emplacement /checkouts/example-repo-multi. Il utilise :

• --db-cluster pour demander l’analyse de plusieurs langages.
• --language pour spécifier les langages pour lesquels créer des bases de données.
• --command pour indiquer à l’outil la commande de génération pour le codebase, ici make.
• --no-run-unnecessary-builds pour indiquer à l’outil d’ignorer la commande de génération pour les langages où elle n’est pas nécessaire (comme Python).

Les bases de données obtenues sont stockées dans les sous-répertoires python et cpp de /codeql-dbs/example-repo-multi.

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

Analyse d’une base de données CodeQL

1. Créez une base de données CodeQL (voir ci-dessus).

2. Exécutez codeql database analyze sur la base de données et spécifiez les packs et/ou les requêtes à utiliser.

   codeql database analyze <database> --format=<format> \
       --output=<output>  --download <packs,queries>
   

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

Pour plus d’informations, consultez « Analyse de votre code avec des requêtes CodeQL ».

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 éventuellement 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

Chargement de résultats dans GitHub

Vous pouvez vérifier que les propriétés SARIF ont la taille prise en charge pour le chargement et que le fichier est compatible avec l’analyse du code. Pour plus d’informations, consultez « Prise en charge de SARIF pour l’analyse du code ».

Pour pouvoir charger des résultats dans GitHub, vous devez déterminer la meilleure façon de passer l’GitHub App ou le personal access token que vous avez créé précédemment à CodeQL CLI (consultez Installation de CodeQL CLI dans votre système CI). Nous vous recommandons de consulter les instructions de votre système CI sur l’utilisation sécurisée d’un magasin de secrets. L’CodeQL CLI prend en charge :

• Interfaçage avec un magasin de secrets en utilisant l’option --github-auth-stdin (recommandé).
• L’enregistrement du secret dans la variable d’environnement GITHUB_TOKEN et l’exécution de l’interface CLI sans inclure l’option --github-auth-stdin.
• À des fins de test, vous pouvez passer l’option de ligne de commande --github-auth-stdin et fournir un jeton temporaire via une entrée standard.

Quand vous avez choisi la méthode la plus sûre et la plus fiable pour votre serveur CI, exécutez codeql github upload-results sur chaque fichier de résultats SARIF et incluez --github-auth-stdin, sauf si le jeton est disponible dans la variable d’environnement GITHUB_TOKEN.

# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-auth-stdin

# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> 

Pour plus d’informations, consultez « github upload-results ».

Exemple simple de chargement de résultats sur GitHub

L’exemple suivant charge les résultats depuis le fichier SARIF temp/example-repo-js.sarif sur le dépôt my-org/example-repo. Il indique à l’API d’code scanning que les résultats sont destinés au commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 sur la branche main. L’exemple suppose que la GitHub App ou le personal access token créé pour l’authentification avec l’API REST de GitHub utilise la variable d’environnement GITHUB_TOKEN.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif 

Cette commande ne génère aucune sortie, sauf si le chargement a échoué. L’invite de commandes réapparaît une fois que le chargement est terminé et que le traitement des données a commencé. Sur les codebases plus petits, vous devez être en mesure d’explorer les alertes d’code scanning dans GitHub peu de temps après. Vous pouvez voir les alertes directement dans la demande de tirage ou sous l’onglet Sécurité des branches, en fonction du code que vous avez extrait. Pour plus d’informations, consultez « Triage des alertes d’analyse du code dans les demandes de tirage (pull request) » et « Gestion des alertes d’analyse du code pour votre référentiel ».

Chargement des informations de diagnostic dans GitHub si l’analyse échoue

Lorsque CodeQL CLI termine avec succès l’analyse d’une base de données, il collecte des informations de diagnostic telles que la couverture des fichiers, les avertissements et les erreurs et les inclut dans le fichier SARIF avec les résultats. Lorsque vous chargez le fichier SARIF dans GitHub, les informations de diagnostic s’affichent sur la page d’état de l’outil code scanning pour permettre au référentiel de consulter facilement le fonctionnement de CodeQL et de déboguer les problèmes éventuels. Pour plus d’informations, consultez « À propos de la page d’état de l’outil pour l’analyse du code ».

Toutefois, en cas d’échec de codeql database analyze pour une raison quelconque, il n’y a pas de fichier SARIF à charger dans GitHub et aucune information de diagnostic à afficher sur la page d’état de l’outil code scanning pour le référentiel. Les utilisateurs rencontrent alors des difficultés pour résoudre les problèmes d’analyse, sauf s’ils ont accès aux fichiers journaux dans votre système CI.

Nous vous recommandons de configurer votre workflow CI pour exporter et charger les informations de diagnostic vers GitHub en cas d’échec d’une analyse. Pour ce faire, utilisez les commandes simples suivantes pour exporter les informations de diagnostic et les charger dans GitHub.

Exportation des informations de diagnostic en cas d’échec de l’analyse

Vous pouvez créer un fichier SARIF pour l’analyse ayant échoué à l’aide de « database export-diagnostics », par exemple :

$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

Ce fichier SARIF contient des informations de diagnostic pour l’analyse ayant échoué, y compris les informations de couverture des fichiers, les avertissements et les erreurs générés pendant l’analyse.

Chargement des informations de diagnostic en cas d’échec de l’analyse

Vous pouvez rendre ces informations de diagnostic disponibles dans la page d’état de l’outil en chargeant le fichier SARIF dans GitHub à l’aide de « github upload-results », par exemple :

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif 

Il s’agit du processus de chargement des fichiers SARIF à partir d’analyses réussies.

Téléchargement et utilisation de packs de requêtes CodeQL

Le bundle de l’CodeQL CLI inclut des requêtes gérées par les experts GitHub, les chercheurs en sécurité et les contributeurs de la communauté. Si vous souhaitez exécuter des requêtes développées par d’autres organisations, les packs de requêtes CodeQL fournissent un moyen efficace et fiable de télécharger et d’exécuter des requêtes. Pour plus d’informations, consultez « À propos de l’analyse du code avec CodeQL ».

Avant de pouvoir utiliser un pack CodeQL pour analyser une base de données, vous devez télécharger tous les packages dont vous avez besoin à partir du Container registry GitHub. Cela peut être fait en utilisant l’indicateur --download dans la commande codeql database analyze. Si un package n’est pas disponible publiquement, vous devez utiliser une GitHub App ou un personal access token pour vous authentifier. Pour plus d’informations et un exemple, consultez « Chargement de résultats dans GitHub » plus haut.

Exemple simple de téléchargement et d’utilisation de packs de requêtes

Cet exemple exécute la commande codeql database analyze avec l’option --download pour :

1. Télécharger la dernière version du pack octo-org/security-queries.
2. Télécharger une version du pack octo-org/optional-security-queries compatible avec la version 1.0.1 (dans ce cas, la version 1.0.2). Pour plus d’informations sur la compatibilité avec semver, consultez la documentation sur la plage de versions sémantiques de npm.
3. Exécuter toutes les requêtes par défaut dans octo-org/security-queries.
4. Exécuter uniquement la requête queries/csrf.ql à partir de octo-org/optional-security-queries

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

Téléchargement direct de packs CodeQL

Si vous souhaitez télécharger un pack CodeQL sans l’exécuter immédiatement, vous pouvez utiliser la commande codeql pack download. Cela est utile si vous souhaitez éviter d’accéder à Internet lors de l’exécution de requêtes CodeQL. Lorsque vous exécutez l’analyse CodeQL, vous pouvez spécifier des packs, des versions et des chemins d’accès de la même façon que dans l’exemple précédent :

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

Téléchargement des packs CodeQL à partir de plusieurs registres de conteneurs GitHub

Si vos packs CodeQL se trouvent sur plusieurs registres de conteneurs, vous devez indiquer à CodeQL CLI où trouver chaque pack. Pour plus d’informations, consultez « Personnalisation de votre configuration avancée pour l’analyse du code ».

Exemple de configuration CI pour l’analyse CodeQL

Il s’agit d’un exemple de la série de commandes que vous pouvez utiliser pour analyser un codebase avec deux langages pris en charge, puis pour charger les résultats dans GitHub.

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'
# The GitHub App or personal access token created for authentication
# with GitHub's REST API is available in the `GITHUB_TOKEN` environment variable.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif

# Upload the SARIF file with the Python results: 'python-results.sarif'

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif

Résolution des problèmes liés à l’CodeQL CLI dans votre système CI

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

L’Code scanning affiche uniquement les résultats d’analyse de l’un des langages analysés

Par défaut, l’code scanning attend un fichier de résultats SARIF par analyse pour un dépôt. Ainsi, quand vous chargez un deuxième fichier de résultats SARIF pour un commit, il est traité comme un remplacement du jeu de données d’origine.

Si vous souhaitez charger plusieurs jeux de résultats sur l’API d’code scanning pour un commit dans un dépôt, vous devez identifier chaque jeu de résultats en tant que jeu unique. Pour les dépôts où vous créez plusieurs bases de données CodeQL pour analyser chaque commit, utilisez l’option --sarif-category afin de spécifier un langage ou une autre catégorie unique pour chaque fichier SARIF que vous générez pour ce dépôt.

Problèmes liés à l’extraction Python

Nous déconseillons le support de Python 2 pour CodeQL CLI, plus spécifiquement pour la phase de génération de la base de données CodeQL (extraction de code).

Si vous utilisez CodeQL CLI pour exécuter l’code scanning CodeQL sur du code écrit en Python, vous devez vérifier que Python 3 est installé sur votre système CI.

Pour aller plus loin

• « Préparation de votre code pour l’analyse CodeQL »
• « Analyse de votre code avec des requêtes CodeQL ».
• Publication et utilisation de packs CodeQL