Hochladen einer SARIF-Datei in GitHub

Informationen zu SARIF-Dateiuploads für code scanning

GitHub erstellt code scanning-Warnungen in einem Repository mithilfe von Informationen aus den SARIF-Dateien (Static Analysis Results Interchange Format). SARIF-Dateien können mithilfe der API oder GitHub Actions in ein Repository hochgeladen werden. Weitere Informationen findest du unter Verwenden der Codeüberprüfung mit deinem vorhandenen CI-System.

Du kannst SARIF-Dateien mit vielen Sicherheitstesttools für statische Analysen generieren, einschließlich CodeQL. Für die Ergebnisse muss SARIF Version 2.1.0 verwendet werden. Weitere Informationen findest du unter SARIF-Unterstützung für die Codeüberprüfung.

Du kannst die Ergebnisse mit GitHub Actions, der API für die code scanning oder mithilfe der CodeQL CLI hochladen. Die beste Uploadmethode hängt davon ab, wie du die SARIF-Datei generierst, z. B. ob du Folgendes verwendest:

• Wenn du GitHub Actions zum Ausführen der CodeQL-Aktion verwendest, ist keine weitere Aktion erforderlich. Durch die CodeQL-Aktion wird die SARIF-Datei automatisch hochgeladen, wenn die Analyse abgeschlossen ist.
• Wenn du GitHub Actions verwendest, um ein mit SARIF kompatibles Analysetool auszuführen, kannst du den Workflow aktualisieren, um mit einem finalen Schritt die Ergebnisse hochzuladen (siehe unten).
• Wenn du die CodeQL CLI zum Ausführen einer code scanning auf deinem CI-System verwendest, kannst du die Ergebnisse mithilfe der CLI auf GitHub hochladen (weitere Informationen findest du unter Verwenden der Codeüberprüfung mit deinem vorhandenen CI-System).
• Wenn du ein Tool verwendest, das Ergebnisse als Artefakte außerhalb deines Repositorys generiert, kannst du die Datei mithilfe der code scanning-API hochladen (weitere Informationen findest du unter REST-API-Endpunkte für die Codeüberprüfung).

Hochladen einer code scanning-Analyse mit GitHub Actions

du benötigst einen Workflow, wenn du GitHub Actions verwenden möchtest, um eine SARIF-Datei eines Drittanbieters in ein Repository hochzuladen. Weitere Informationen findest du unter Schreiben von Workflows.

In deinem Workflow muss die Aktion upload-sarif verwendet werden, die Teil des Repositorys github/codeql-action ist. Sie enthält Eingabeparameter, die du zum Konfigurieren des Uploads verwenden kannst. Die wichtigsten Eingabeparameter, die du verwendest, sind folgende:

• Mit sarif-file wird die Datei oder das Verzeichnis der SARIF-Dateien zum Hochladen konfiguriert. Das Verzeichnis oder der Dateipfad ist relativ zum Stammverzeichnis des Repositorys.
• Mit category (optional) wird eine Kategorie für Ergebnisse in der SARIF-Datei zugewiesen. So kannst du denselben Commit auf mehrere Arten analysieren und die Ergebnisse mithilfe der code scanning-Ansichten in GitHub überprüfen. Du kannst z. B. eine Analyse mithilfe mehrerer Tools durchführen. In Monorepos kannst du verschiedene Slices des Repositorys basierend auf der Teilmenge geänderter Dateien analysieren.

Weitere Informationen finden Sie unter upload-sarif-Aktion.

Die Aktion upload-sarif kann so konfiguriert werden, dass sie ausgeführt wird, wenn das Ereignis push und das Ereignis scheduled auftreten. Weitere Informationen zu GitHub Actions-Ereignissen findest du unter Ereignisse zum Auslösen von Workflows.

Wenn deine SARIF-Datei keine partialFingerprints enthält, berechnet die upload-sarif-Aktion das partialFingerprints-Feld für dich und versucht, doppelte Warnungen zu verhindern. Von GitHub können partialFingerprints nur erstellt werden, wenn das Repository sowohl die SARIF-Datei als auch den Quellcode enthält, der in der statischen Analyse verwendet wird. Weitere Informationen zum Verhindern doppelter Warnungen findest du unter SARIF-Unterstützung für die Codeüberprüfung.

Du kannst überprüfen, ob die SARIF-Eigenschaften die unterstützte Größe für den Upload aufweisen und ob die Datei mit der Codeüberprüfung kompatibel ist. Weitere Informationen findest du unter SARIF-Unterstützung für die Codeüberprüfung.

Beispielworkflow für SARIF-Dateien, die außerhalb eines Repositorys generiert wurden

Du kannst einen neuen Workflow erstellen, der SARIF-Dateien hochlädt, nachdem du sie in dein Repository committet hast. Dies ist nützlich, wenn die SARIF-Datei als Artefakt außerhalb deines Repositorys generiert wird.

Dieser Beispielworkflow wird jedes Mal ausgeführt, wenn Commits in das Repository gepusht werden. Die Aktion verwendet die partialFingerprints-Eigenschaft, um zu bestimmen, ob Änderungen aufgetreten sind. Zusätzlich zur Ausführung beim Pushen von Commits wird die Ausführung des Workflows ein Mal pro Woche geplant. Weitere Informationen findest du unter Ereignisse zum Auslösen von Workflows.

Dieser Workflow lädt die results.sarif-Datei hoch, die sich im Stammverzeichnis des Repositorys befindet. Weitere Informationen zum Erstellen einer Workflowdatei findest du unter Schreiben von Workflows.

Alternativ dazu kannst du diesen Workflow auch ändern, um ein Verzeichnis mit SARIF-Dateien hochzuladen. Beispielsweise kannst du alle SARIF-Dateien in einem Verzeichnis im Stammverzeichnis deines Repositorys mit dem Namen sarif-output platzieren und den Eingabeparameter sarif_file der Aktion auf sarif-output festlegen. Wenn du ein Verzeichnis hochlädst, muss jede SARIF-Datei eine eindeutige runAutomationDetails.id zum Definieren der Kategorie für die Ergebnisse enthalten. Weitere Informationen findest du unter SARIF-Unterstützung für die Codeüberprüfung.

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

Beispielworkflow, mit dem das ESLint-Analysetool ausgeführt wird

Wenn du die SARIF-Datei eines Drittanbieters als Teil eines CI-Workflows (Continuous Integration) generierst, kannst du die upload-sarif-Aktion als Schritt nach dem Ausführen der CI-Tests hinzufügen. Wenn du noch keinen CI-Workflow hast, kannst du einen mit einer GitHub Actions-Vorlage erstellen. Weitere Informationen findest du unter Schnellstart für GitHub Actions.

Dieser Beispielworkflow wird jedes Mal ausgeführt, wenn Commits in das Repository gepusht werden. Die Aktion verwendet die partialFingerprints-Eigenschaft, um zu bestimmen, ob Änderungen aufgetreten sind. Zusätzlich zur Ausführung beim Pushen von Commits wird die Ausführung des Workflows ein Mal pro Woche geplant. Weitere Informationen findest du unter Ereignisse zum Auslösen von Workflows.

Der Workflow zeigt ein Beispiel für das Ausführen des Analysetools ESLint für statische Analysen als Schritt in einem Workflow. Der Run ESLint-Schritt führt das ESLint-Tool aus und gibt die results.sarif-Datei aus. Anschließend wird in dem Workflow die Datei results.sarif mithilfe der Aktion upload-sarif in GitHub hochgeladen. Weitere Informationen zum Erstellen einer Workflowdatei findest du unter Grundlegendes zu 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

Weiterführende Themen

• Problembehandlung bei SARIF-Uploads
• Workflowsyntax für GitHub Actions
• Anzeigen des Ausführungsverlaufs eines Workflows
• Verwenden der Codeüberprüfung mit deinem vorhandenen CI-System
• REST-API-Endpunkte für die Codeüberprüfung