Chargement des résultats d'analyse de CodeQL sur GitHub

À propos de la sortie SARIF

GitHub crée des alertes d'code scanning dans un dépôt en utilisant des informations provenant de fichiers SARIF (Static Analysis Results Interchange Format). Le format SARIF est conçu pour représenter la sortie d'un large éventail d'outils d'analyse statique et il existe de nombreuses fonctionnalités dans la spécification SARIF considérées comme « facultatives ». Les résultats doivent utiliser SARIF version 2.1.0. Pour plus d'informations, consultez « Prise en charge de SARIF pour l’analyse du code ».

Après avoir analysé une base de données CodeQL à l'aide de CodeQL CLI, vous disposerez d'un fichier SARIF qui contient les résultats. Pour plus d'informations, consultez « Analyse de votre code avec des requêtes CodeQL ». Vous pouvez ensuite utiliser CodeQL CLI pour charger les résultats sur GitHub.

Si vous avez utilisé une méthode autre que CodeQL CLI pour générer les résultats, vous pouvez utiliser d'autres méthodes de chargement. Pour plus d'informations, consultez « Chargement d’un fichier SARIF sur GitHub ».

Remarque : le chargement de données SARIF à afficher comme résultats code scanning dans GitHub Enterprise Server est pris en charge pour des dépôts appartenant à l’organisation avec GitHub Advanced Security activé. Pour plus d’informations, consultez « Gestion des paramètres de sécurité et d’analyse pour votre dépôt ».

Génération d'un jeton pour l'authentification auprès de GitHub Enterprise Server

Avant de pouvoir télécharger vos résultats sur GitHub Enterprise Server, vous devez d'abord générer un personal access token.

Personal access token (classic) nécessite l’accès en lecture et en écriture aux référentiels requis pour « Code scanning ».
Fine-grained personal access token nécessite un accès security_events « référentiel ».

Pour plus d’informations, consultez « Gestion de vos jetons d'accès personnels ».

Si vous avez installé CodeQL CLI dans un système CI de tiers pour créer des résultats à afficher dans GitHub en tant qu'alertes d'analyse du code, vous pouvez utiliser une GitHub App ou un personal access token pour charger les résultats dans GitHub Enterprise Server. Pour plus d'informations, consultez « Utilisation de l'analyse du code avec votre système CI existant ».

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 télécharger les résultats sur GitHub Enterprise Server, vous devez déterminer la meilleure façon de passer GitHub App ou personal access token que vous avez créé dans la section précédente à CodeQL CLI. 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 décidé de la méthode la plus sûre et la plus fiable pour votre configuration, 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-url=<URL> \
    --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> --github-url=<URL> \

Option	Obligatoire	Usage
`--repository`		Spécifiez le PROPRIÉTAIRE/NOM du dépôt sur lequel charger les données. Le propriétaire doit être une organisation au sein d'une entreprise qui dispose d'une licence pour GitHub Advanced Security et GitHub Advanced Security doit être activé pour le dépôt. Pour plus d'informations, consultez « Gestion des paramètres de sécurité et d’analyse pour votre dépôt ».
`--ref`		Spécifiez le nom de la référence (`ref`) 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 de tête d'une demande de tirage, utilisez : `refs/pull/NUMBER/head`. Pour le commit de fusion généré par GitHub d'une demande de tirage, utilisez : `refs/pull/NUMBER/merge`.
`--commit`		Spécifiez l'algorithme SHA complet du commit que vous avez analysé.
`--sarif`		Spécifiez le fichier SARIF à charger.
`--github-url`		Spécifiez l’URL pour GitHub Enterprise Server.
`--github-auth-stdin`		Passer à l'interface CLI la GitHub App ou le personal access token créé pour l'authentification avec l'API REST de GitHub depuis le magasin de secrets via une entrée standard. Cette option n'est pas nécessaire si la commande a accès à une variable d'environnement `GITHUB_TOKEN` définie avec ce jeton.

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

Remarque : si vous avez analysé plusieurs bases de données CodeQL pour un seul commit, vous devez avoir spécifié 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. Pour plus d'informations, consultez « Analyse de votre code avec des requêtes CodeQL ».

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

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 --github-url=https://HOSTNAME \

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 « Évaluation des alertes d’analyse du code pour votre référentiel ».

Chargement des informations de diagnostic dans GitHub Enterprise Server 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. Quand vous chargez le fichier SARIF sur GitHub, les informations de diagnostic s'affichent sur la page d’état de l’outil de code scanning pour le dépôt, ce qui permet de voir facilement comment CodeQL fonctionne et 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 ».

Cependant, en cas d'échec de codeql database analyze pour une raison quelconque, il n'y a pas de fichier SARIF à charger sur GitHub et aucune information de diagnostic à afficher sur la page d’état de l’outil de code scanning pour le dépôt. 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 Enterprise Server 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-typescript --format=sarifv2.1.0 \
    --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 sur GitHub Enterprise Server en utilisant « 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 --github-url=https://HOSTNAME \

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