Chargement des résultats d’analyse CodeQL dans GitHub

Après avoir analysé une CodeQL base de données à l’aide du CodeQL CLI, vous aurez un fichier SARIF qui contient les résultats. Vous pouvez ensuite utiliser le CodeQL CLI fichier pour charger les résultats vers GitHub.

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

Génération d’un jeton pour l’authentification avec GitHub

Avant de pouvoir charger vos résultats sur GitHub, vous devez d'abord générer un personal access token. Consultez « Gestion de vos jetons d’accès personnels ».

•         **
          Personal access token (classic)
          ** nécessite l’accèsCode scanning en **lecture-écriture** aux référentiels requis.
  

•         **
          Fine-grained personal access token
          ** nécessite un accès au dépôt **security_events**.
  

Si vous avez installé le CodeQL CLI système CI tiers, vous pouvez également utiliser un GitHub App pour charger les résultats vers GitHub. Consultez « Utilisation de l’analyse du code avec votre système CI existant ».

Chargement des résultats vers GitHub

1. Vérifiez 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 ».

2. Déterminez la meilleure façon de passer le GitHub App ou personal access token vous avez créé dans la section précédente à l’objet 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. Les CodeQL CLI supports :

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

3. 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> \
       
   

Choix	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 avec GitHub Advanced Security activé pour le référentiel. 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 utiliser une branche : refs/heads/BRANCH-NAME, pour la validation principale d'une demande de tirage, utilisez refs/pull/NUMBER/head, ou pour la validation de fusion générée 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 votre instance GitHub Enterprise Server.
--github-auth-stdin		Transmettez au CLI le GitHub App ou personal access token créé pour l'authentification avec l’API REST de GitHub depuis votre 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 ».

Exemple de base du chargement des résultats vers 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 code scanning que les résultats concernent la validation deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 sur la branche main. L’exemple suppose que l’authentification GitHub App ou personal access token créée avec GitHubl’API REST utilise la GITHUB_TOKEN variable d’environnement.

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 bases de code plus petites, vous devriez être en mesure d’explorer les code scanning alertes dans GitHub peu de temps après. Vous pouvez voir les alertes directement dans la pull request ou sous l’onglet Security pour les branches, en fonction du code que vous avez extrait.

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

Une fois que CodeQL CLI a terminé l'analyse réussie 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 le code scanningpage d’état de l’outil du référentiel, ce qui permet de voir facilement comment CodeQL fonctionne et de déboguer d’éventuels problèmes. Pour plus d’informations, consultez « Utiliser la page d’état de l’outil pour l’analyse du code ».

Toutefois, si codeql database analyze échoue pour une raison quelconque, il n’existe aucun fichier SARIF à charger vers GitHub et aucune information de diagnostic à afficher sur le référentiel code scanningpage d’état de l’outil. 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 flux de travail CI pour exporter et charger des informations GitHub de diagnostic lorsqu’une analyse échoue. Pour ce faire, vous pouvez utiliser les commandes simples suivantes pour exporter les informations de diagnostic et les charger .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 diagnostics d'exportation de base de données, 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 sur le page d’état de l’outil en chargeant le fichier SARIF vers GitHub 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.