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

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 Enterprise Server 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 à utiliser.

   codeql database analyze <database> --format=<format> \
       --output=<output>  <queries>

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <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=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.

Chargement de résultats dans GitHub Enterprise Server

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 Enterprise Server, 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-url=<URL> \
      --github-auth-stdin

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

Exemple simple de chargement de résultats sur GitHub Enterprise Server

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-url=https://github.example.com \
    --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 Enterprise Server 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 ».

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

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

Pour aller plus loin

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