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 CodeQL » et « Création de bases de données 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 « Création de bases de données 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 bases de données avec CodeQL CLI ».

Exemple simple d’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.

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 :

• Le passage du jeton à l’interface CLI par le biais d’une entrée standard à l’aide de 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.

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.

echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
      --ref=<ref> --commit=<commit> --sarif=<file> \
      --github-auth-stdin

Pour plus d’informations, consultez github upload-results dans la documentation relative à l’CodeQL CLI.

Exemple simple de chargement de résultats sur GitHub

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

$ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

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

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

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif --github-auth-stdin

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

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif --github-auth-stdin

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éprécions la prise en charge de Python 2 pour CodeQL CLI, plus spécifiquement pour la phase de génération de 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

• Création de bases de données CodeQL
• Analyse des bases de données avec l’interface CLI de CodeQL
• Publication et utilisation de packs CodeQL