Utiliser l’interface CLI de CodeQL

8 minutes

En plus de l’interface utilisateur graphique sur GitHub.com, vous pouvez accéder à la plupart des fonctionnalités principales de CodeQL via une interface de ligne de commande.

Cette unité couvre l’utilisation de l’interface CLI CodeQL pour créer des bases de données, les analyser et charger les résultats sur GitHub.

Commandes CLI CodeQL

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

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

database create pour créer une base de données CodeQL pour représenter la structure hiérarchique de chaque langage de programmation pris en charge dans le dépôt.
database analyze pour exécuter des requêtes pour analyser chaque base de données CodeQL et résumer les résultats dans un fichier SARIF.
github upload-results pour charger les fichiers SARIF obtenus dans GitHub, là où les résultats sont associés à une branche ou un pull request et affichés sous forme d’alertes d’analyse du code.

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

Le chargement de données SARIF pour les afficher comme résultats d’analyse du code dans GitHub est pris en charge pour les dépôts qui appartiennent à une organisation et pour lesquels GitHub Advanced Security est activé, et pour les dépôts publics sur GitHub.com.

Créer des bases de données CodeQL à analyser

Suivez ces étapes pour créer des bases de données CodeQL à analyser.

Examinez le code que vous souhaitez analyser.
- Pour une branche, consultez la pointe de la branche que vous souhaitez analyser.
- Pour une demande de tirage, consultez la validation principale de la demande de tirage ou vérifiez une validation de fusion générée par GitHub de la demande de tirage.
Configurez l’environnement pour le codebase, en vérifiant que toutes les dépendances sont disponibles.
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.
Exécutez codeql database create à partir de la racine d’extraction de votre dépôt et générez le codebase :
- Pour créer une base de données CodeQL pour un seul langage pris en charge, utilisez la commande suivante :
```
codeql database create <database> --command <build> --language=<language-identifier>
```
- Pour créer une seule base de données CodeQL par langage quand plusieurs langages sont pris en charge, utilisez la commande suivante :
```
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’interface CLI de CodeQL à l’intérieur du conteneur dans lequel votre tâche de génération se produit.

La liste complète des paramètres de la commande database create figure dans le tableau suivant :

Option	Utilisation requise
`<database>`	Spécifiez le nom et l’emplacement d’un répertoire à créer pour la base de données CodeQL. La commande échoue si vous essayez de remplacer un répertoire existant. Si vous spécifiez aussi `--db-cluster`, il s’agit du répertoire parent et un sous-répertoire est créé pour chaque langage analysé.
`--language`	Spécifiez l’identifiant pour la langue pour créer une base de données pour l'une de `cpp`, `csharp`, `go`, `java`, `javascript`, `python`, et `ruby` (utilisez JavaScript pour analyser le code TypeScript). Utilisée avec `--db-cluster`, l’option accepte une liste séparée par des virgules ou peut être spécifiée plusieurs fois.
`--command`	Recommandé. Utilisez cette option pour spécifier la commande de génération ou le script qui appelle le processus de génération pour le codebase. Les commandes sont exécutées à partir du dossier actif ou, où elles sont définies, à partir de `--source-root`. Non nécessaire pour une analyse Python et JavaScript/TypeScript.
`--db-cluster`	Optionnel. Utilisez cette option dans les codebases en plusieurs langages pour générer une seule base de données pour chaque langage spécifié par `--language`.
`--no-run-unnecessary-builds`	Recommandé. Permet de supprimer la commande de build pour les langages où l’interface CLI CodeQL n’a pas besoin de surveiller la build (par exemple, Python et JavaScript/TypeScript).
`--source-root`	Optionnel. Utilisez cette option si vous exécutez l’interface CLI en dehors de la racine d’extraction du dépôt. Par défaut, la commande database create suppose que le répertoire actuel est le répertoire racine des fichiers sources. Utilisez cette option pour spécifier un autre emplacement.

Exemple avec un langage unique

Cet exemple crée une base de données CodeQL pour le dépôt extrait dans /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 dans /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 la base de code, ici make.
--no-run-unnecessary-builds pour indiquer à l’outil d’ignorer la commande de build pour les langages où il 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.
$

Analyser une base de données CodeQL

Après avoir créé votre base de données CodeQL, suivez ces étapes pour l’analyser :

Exécutez éventuellement codeql pack download <packs> pour télécharger tous les packs CodeQL (bêta) à exécuter pendant l’analyse.
Exécutez codeql database analyze sur la base de données et spécifiez les packs et/ou requêtes à utiliser.

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

Remarque

Si vous analysez plusieurs bases de données CodeQL pour un même commit, vous devez spécifier une catégorie SARIF pour chaque ensemble de résultats générés par cette commande. Quand vous chargez les résultats dans GitHub, l’analyse du code utilise cette catégorie pour stocker les résultats pour chaque langage séparément. Si vous oubliez de le faire, chaque téléversement écrase les résultats précédents.

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

La liste complète des paramètres de la commande database analyze figure dans le tableau suivant :

Option	Utilisation requise
`<database>`	Spécifiez le chemin du répertoire qui contient la base de données CodeQL à analyser.
`<packs,queries>`	Spécifiez les packs ou requêtes CodeQL à exécuter. Pour exécuter les requêtes standard utilisées pour l’analyse du code, omettez ce paramètre. Vous pouvez trouver les autres suites de requêtes incluses dans le bundle CodeQL CLI dans `/<extraction-root>/codeql/qlpacks/codeql-<language>/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^[5] dans la documentation l’interface de ligne de commande CodeQL.
`--format`	Spécifiez le format du fichier de résultats généré par la commande. Pour un chargement sur GitHub, ce doit être `sarif-latest`.
`--output`	Spécifiez l’emplacement d’enregistrement du fichier de résultats SARIF.
`--sarif-category`	Facultatif 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-query-help`	Optionnel. Utilisez 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.
`<packs>`	Optionnel. Utilisez cette option si vous avez téléchargé des packs de requêtes CodeQL et souhaitez exécuter les requêtes ou suites de requêtes par défaut spécifiées dans les packs.
`--threads`	Optionnel. Utilisez 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.
`--verbose`	Optionnel. Utilisez 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.

Exemple de base

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 lorsque vous avez plusieurs bases de données CodeQL à analyser pour un seul commit dans un dépôt.

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

Charger les résultats dans GitHub

Le chargement SARIF prend en charge un maximum de 25 000 résultats par chargement. Toutefois, seuls les 5 000 premiers résultats sont affichés, classés par priorité par gravité. Si un outil génère trop de résultats, vous devez mettre à jour la configuration pour vous concentrer sur les résultats des règles ou requêtes les plus importantes.

Pour chaque chargement, un chargement SARIF prend en charge une taille maximale de 10 Mo pour le fichier SARIF compressé au format gzip. Tous les chargements au-delà de cette limite sont rejetés. Si votre fichier SARIF est trop volumineux parce qu’il contient trop de résultats, vous devez mettre à jour la configuration pour vous concentrer sur les résultats des règles ou requêtes les plus importantes. Pour plus d’informations sur les limitations et la validation des fichiers SARIF, consultez la documentation^[6]..

Avant de pouvoir charger des résultats dans GitHub, vous devez déterminer la meilleure façon de passer l’application GitHub ou le jeton d’accès personnel que vous avez créé précédemment à l’interface CLI de CodeQL. Nous vous recommandons de consulter les recommandations de votre système CI sur l’utilisation sécurisée d’un espace de stockage sécurisé. L’interface CLI de CodeQL prend en charge :

Créer une interface avec un magasin des secrets en utilisant l’option --github-auth-stdin. Il s’agit de la méthode recommandée pour l’authentification.
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.
Transmettez l’option de ligne de commande --github-auth-stdin et fournissez un jeton temporaire via une entrée standard. Cette manipulation est recommandée à des fins de test.

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>

La liste complète des paramètres de la github upload-results commande est affichée dans le tableau comme suit.

Option	Utilisation requise
`--repository`	Spécifiez le PROPRIÉTAIRE/NOM du dépôt où charger les données. Le propriétaire doit être une organisation au sein d’une entreprise disposant d’une licence pour GitHub Advanced Security et GitHub Advanced Security doit être activé pour le dépôt, sauf si celui-ci est public.
`--ref`	Spécifiez le nom de la référence que vous avez extraite et analysée afin que les résultats puissent être mis en correspondance avec le code correct. Pour une branche, utilisez : `refs/heads/BRANCH-NAME`. Pour le commit principal d’une demande de tirage, utilisez : `refs/pulls/NUMBER/head`. Pour le commit de fusion généré par GitHub d’une demande de tirage, utilisez : `refs/pulls/NUMBER/merge`.
`--commit`	Spécifiez l’algorithme SHA complet du commit que vous avez analysé.
`--sarif`	Spécifiez le fichier SARIF à charger.
`--github-auth-stdin`	Optionnel. Utilisez pour transférer à l'interface CLI l'application GitHub ou le jeton d'accès personnel créé pour l'authentification avec l'API REST de GitHub, via une entrée standard. Ceci n’est pas nécessaire si la commande a accès à une variable d’environnement `GITHUB_TOKEN` définie avec ce jeton.

Commentaires

Cette page a-t-elle été utile ?