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 finden Sie unterVerwenden 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 finden Sie unterSARIF-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 von code scanning auf deinem CI-System verwendest, kannst du die Ergebnisse mithilfe der CLI auf GitHub hochladen (weitere Informationen unterVerwenden 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 unterREST-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 finden Sie unterSchreiben von Workflows.

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

• Mitsarif_file wird die Datei oder das Verzeichnis der SARIF-Dateien zum Hochladen konfiguriert. Das Verzeichnis oder der Dateipfad ist relativ zum Stammverzeichnis des Repositorys.
• Mitcategory (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 findest du im Artikel über dieAktionupload-sarif.

Die Aktionupload-sarif kann so konfiguriert werden, dass sie ausgeführt wird, wenn das Ereignispush und das Ereignisscheduled auftreten. Weitere Informationen zu GitHub Actions-Ereignissen findest du unterEreignisse zum Auslösen von Workflows.

Wenn deine SARIF-Datei keinepartialFingerprints enthält, berechnet dieupload-sarif-Aktion daspartialFingerprints-Feld für dich und versucht, doppelte Warnungen zu verhindern. Von GitHub könnenpartialFingerprints 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 unterSARIF-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 finden Sie 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 diepartialFingerprints-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 finden Sie unterEreignisse zum Auslösen von Workflows.

Dieser Workflow lädt dieresults.sarif-Datei hoch, die sich im Stammverzeichnis des Repositorys befindet. Weitere Informationen zum Erstellen einer Workflowdatei findest du unterSchreiben 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 Namensarif-output platzieren und den Eingabeparametersarif_file der Aktion aufsarif-output festlegen. Wenn du ein Verzeichnis hochlädst, muss jede SARIF-Datei eine eindeutigerunAutomationDetails.id zum Definieren der Kategorie für die Ergebnisse enthalten. Weitere Informationen finden Sie unterSARIF-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@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

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 dieupload-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 unterSchnellstart für GitHub Actions.

Dieser Beispielworkflow wird jedes Mal ausgeführt, wenn Commits in das Repository gepusht werden. Die Aktion verwendet diepartialFingerprints-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 finden Sie unterEreignisse 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. DerRun ESLint-Schritt führt das ESLint-Tool aus und gibt dieresults.sarif-Datei aus. Anschließend wird in dem Workflow die Dateiresults.sarif mithilfe der Aktionupload-sarif in GitHub hochgeladen. Weitere Informationen zum Erstellen einer Workflowdatei findest du unterGrundlegendes 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@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

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