Chargement d’un fichier SARIF sur GitHub

À propos des chargements de fichiers SARIF pour l’code scanning

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). Les fichiers SARIF peuvent être chargés sur un dépôt avec l’API ou GitHub Actions. Pour plus d’informations, consultez « Utilisation de l'analyse du code avec votre système CI existant ».

Vous pouvez générer des fichiers SARIF avec de nombreux outils de test de sécurité d’analyse statique, y compris CodeQL. 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 ».

Vous pouvez charger les résultats à l’aide de GitHub Actions, de l’API code scanning ou de CodeQL CLI. La meilleure méthode de chargement dépend de la façon dont vous générez le fichier SARIF. Par exemple, si vous utilisez :

• GitHub Actions pour exécuter l’action CodeQL, aucune action supplémentaire n’est requise. L’action CodeQL charge automatiquement le fichier SARIF quand il termine l’analyse.
• GitHub Actions pour exécuter un outil d’analyse compatible SARIF, vous pouvez mettre à jour le workflow pour inclure une étape finale qui charge les résultats (voir ci-dessous).
• L’interface CodeQL CLI pour exécuter code scanning dans votre système CI, vous pouvez utiliser l’interface CLI pour charger les résultats sur GitHub (pour plus d’informations, consultez « Utilisation de l'analyse du code avec votre système CI existant »).
• Un outil qui génère les résultats en tant qu’artefact en dehors de votre dépôt, vous pouvez utiliser l’API d’code scanning pour charger le fichier (pour plus d’informations, consultez « Points de terminaison d’API REST pour l’analyse de codes »).

Chargement d’une code scanning avec GitHub Actions

Pour utiliser GitHub Actions afin de charger un fichier SARIF tiers sur un dépôt, vous avez besoin d’un workflow. Pour plus d’informations, consultez « Écriture de workflows ».

Votre workflow doit utiliser l’action upload-sarif, qui fait partie du dépôt github/codeql-action. Il a des paramètres d’entrée que vous pouvez utiliser pour configurer le chargement. Les principaux paramètres d’entrée sont les suivants :

• sarif-file, qui configure le fichier ou le répertoire des fichiers SARIF à charger. Le chemin du répertoire ou du chemin est relatif à la racine du référentiel.
• category (facultatif), qui affecte une catégorie pour les résultats dans le fichier SARIF. Cela vous permet d’analyser le même commit de plusieurs façons et de passer en revue les résultats avec les affichages d’code scanning dans GitHub. Par exemple, vous pouvez effectuer une analyse avec plusieurs outils et, dans un monodépôt, vous pouvez analyser différentes tranches du dépôt en fonction du sous-ensemble de fichiers modifiés.

Pour plus d'informations, consultez upload-sarifaction.

L’action upload-sarif peut être configurée pour s’exécuter quand les événements push et scheduled se produisent. Pour plus d’informations sur les événements GitHub Actions, consultez « Événements qui déclenchent des flux de travail ».

Si votre fichier SARIF n’inclut pas partialFingerprints, l’action upload-sarif calcule le champ partialFingerprints pour vous et tente d’empêcher les alertes en double. GitHub ne peut créer partialFingerprints que quand le dépôt contient à la fois le fichier SARIF et le code source utilisé dans l’analyse statique. Pour plus d’informations sur la prévention des alertes en double, consultez « Prise en charge de SARIF pour l’analyse du code ».

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

Exemple de workflow pour les fichiers SARIF générés en dehors d’un dépôt

Vous pouvez créer un workflow qui charge les fichiers SARIF après leur commit dans votre dépôt. Cela est utile lorsque le fichier SARIF est généré en tant qu’artefact en dehors de votre référentiel.

Cet exemple de workflow s’exécute chaque fois que des commits sont poussés (push) vers le dépôt. L’action utilise la propriété partialFingerprints pour déterminer si des modifications ont eu lieu. En plus de s’exécuter lorsque des validations sont envoyées, le flux de travail est planifié pour s’exécuter une fois par semaine. Pour plus d’informations, consultez « Événements qui déclenchent des flux de travail ».

Ce flux de travail charge le fichier results.sarif situé à la racine du référentiel. Pour plus d’informations sur la création d’un fichier de workflow, consultez « Écriture de workflows ».

Vous pouvez également modifier ce workflow pour charger un répertoire de fichiers SARIF. Par exemple, vous pouvez placer tous les fichiers SARIF dans un répertoire à la racine de votre référentiel appelé sarif-output et définir le paramètre d’entrée de l’action sarif_file sur sarif-output. Notez que si vous chargez un répertoire, chaque fichier SARIF doit inclure un runAutomationDetails.id unique pour définir la catégorie des résultats. Pour plus d’informations, consultez « Prise en charge de SARIF pour l’analyse du code ».

name: "Upload SARIF"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Thursday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 4'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      # This step checks out a copy of your repository.
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v3
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif
          # Optional category for the results
          # Used to differentiate multiple results for one commit
          category: my-analysis-tool

Exemple de workflow qui exécute l’outil d’analyse ESLint

Si vous générez votre fichier SARIF tiers dans le cadre d’un flux de travail d’intégration continue (CI), vous pouvez ajouter l’action upload-sarif en tant qu’étape après avoir exécuté vos tests CI. Si vous n’avez pas encore de workflow CI, vous pouvez en créer un avec un modèle GitHub Actions. Pour plus d’informations, consultez « Démarrage rapide pour GitHub Actions ».

Cet exemple de workflow s’exécute chaque fois que des commits sont poussés (push) vers le dépôt. L’action utilise la propriété partialFingerprints pour déterminer si des modifications ont eu lieu. En plus de s’exécuter lorsque des validations sont envoyées, le flux de travail est planifié pour s’exécuter une fois par semaine. Pour plus d’informations, consultez « Événements qui déclenchent des flux de travail ».

Le workflow montre un exemple d’exécution de l’outil d’analyse statique ESLint en tant qu’étape de workflow. L’étape Run ESLint exécute l’outil ESLint et génère le fichier results.sarif. Le workflow charge ensuite le fichier results.sarif sur GitHub en utilisant l’action upload-sarif. Pour plus d’informations sur la création d’un fichier de workflow, consultez « Comprendre GitHub Actions ».

name: "ESLint analysis"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Wednesday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 3'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Run npm install
        run: npm install
      # Runs the ESlint code analysis
      - name: Run ESLint
        # eslint exits 1 if it finds anything to report
        run: node_modules/.bin/eslint build docs lib script spec-main -f node_modules/@microsoft/eslint-formatter-sarif/sarif.js -o results.sarif || true
      # Uploads results.sarif to GitHub repository using the upload-sarif action
      - uses: github/codeql-action/upload-sarif@v3
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

Pour aller plus loin

• « Résolution des problèmes de chargements SARIF »
• « Workflow syntax for GitHub Actions »
• « Affichage de l’historique des exécutions de workflows »
• « Utilisation de l'analyse du code avec votre système CI existant »
• « Points de terminaison d’API REST pour l’analyse de codes »