Chargement d’un fichier SARIF sur GitHub

Si vous utilisez un outil d’analyse tiers ou un système CI/CD pour analyser le code des vulnérabilités, vous pouvez générer un fichier SARIF et le charger sur GitHub. 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 flux de travail pour inclure une étape finale qui charge les résultats. Consultez Chargement d’une code scanning avec GitHub Actions.
• La CodeQL CLI pour exécuter l'code scanning dans votre système CI, vous pouvez utiliser l’interface CLI pour charger les résultats sur GitHub. 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. Consultez Points de terminaison d’API REST pour l’analyse de codes.

Par défaut, l’code scanning attend un fichier de résultats SARIF par analyse pour un dépôt. Si vous souhaitez télécharger plusieurs jeux de résultats pour un commit dans un référentiel, vous devez identifier chaque jeu de résultats en tant que jeu unique.

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 l’action upload-sarif.

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@v5
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v4
        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@v5
      - 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@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

Chargement de plusieurs fichiers SARIF pour un commit

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. Vous pouvez télécharger deux fichiers SARIF différents pour une même analyse si, par exemple, votre outil d'analyse génère un fichier SARIF différent pour chaque langue qu'il analyse ou chaque ensemble de règles qu'il utilise. Si vous souhaitez télécharger plusieurs jeux de résultats pour un commit dans un référentiel, vous devez identifier chaque jeu de résultats en tant que jeu unique.

Quand vous chargez plusieurs fichiers SARIF pour un commit, vous devez indiquer une « catégorie » pour chaque analyse. La façon de spécifier une catégorie varie selon la méthode d’analyse :

• Si vous utilisez l’CodeQL CLI directement, transmettez l’argument --sarif-category à la commande codeql database analyze quand vous générez des fichiers SARIF. Pour plus d’informations, consultez « À propos de CodeQL CLI ».
• Si vous utilisez GitHub Actions avec codeql-action/analyze, la catégorie est définie automatiquement à partir du nom du workflow et de toutes les variables de matrice (généralement, language). Vous pouvez à la place spécifier une entrée category pour l’action, ce qui est utile lorsque vous analysez différentes sections d’un monodépôt dans un seul flux de travail.
• Si vous utilisez GitHub Actions pour charger des résultats à partir d’autres outils d’analyse statique, vous devez spécifier une entrée category si vous chargez plusieurs fichiers de résultats pour le même outil dans un workflow. Pour plus d’informations, consultez « Chargement d’un fichier SARIF sur GitHub ».
• Si vous n’utilisez pas l’une de ces approches, vous devez spécifier un runAutomationDetails.id unique dans chaque fichier SARIF à charger. Pour plus d’informations sur cette propriété, consultez l’objet runAutomationDetails.

Si vous chargez un deuxième fichier SARIF pour un commit avec la même catégorie et à partir du même outil, les résultats précédents sont remplacés. Toutefois, si vous essayez de charger plusieurs fichiers SARIF pour le même outil et la même catégorie dans une seule exécution de workflow GitHub Actions, la configuration incorrecte est détectée et l’exécution échoue.

Lectures complémentaires

•         [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/troubleshooting/troubleshooting-sarif-uploads)
  

•         [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions)
  

•         [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history)
  

•         [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)
  

•         [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data)