Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Hochladen einer SARIF-Datei in GitHub

Du kannst SARIF-Dateien von statischen Analysewerkzeugen von Drittanbietern in GitHub hochladen und code scanning-Warnungen von diesen Werkzeugen in Deinem Repository sehen.

Who can use this feature

People with write permissions to a repository can upload code scanning data generated outside GitHub.

Code scanning ist für organisationseigene Repositorys in GitHub Enterprise Server verfügbar. Dieses Feature erfordert eine Lizenz für GitHub Advanced Security. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

Hinweis: Dein Websiteadministrator muss code scanning für your GitHub Enterprise Server instance aktivieren, damit du dieses Feature verwenden kannst. Weitere Informationen findest du unter Konfigurieren von code scanning für deine Appliance.

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 Verwalten von code scanning-Warnungen für dein Repository.

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 code scanning.

Du kannst die Ergebnisse mit GitHub Actions, der code scanning-API, oder 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 CLI verwenden, um Ergebnisse in GitHub hochzuladen (weitere Informationen unter Installieren der CodeQL CLI auf deinem CI-System).
  • Wenn du ein Tool verwendest, das Ergebnisse als Artefakte außerhalb deines Repositorys generiert, kannst du die code scanning-API verwenden, um die Datei hochzuladen (weitere Informationen findest du unter Hochladen einer Analyse als SARIF-Daten).

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 Informationen zu GitHub Actions.

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 findest du 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, die Workflows auslösen.

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 Informationen zur 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 Überprüfen deiner SARIF-Datei.

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, die Workflows auslösen.

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 Informationen zu GitHub Actions.

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: runAutomationDetails-Objekt.

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@v3
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v2
        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 in der Schnellstartanleitung 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, die Workflows auslösen.

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 Einführung in 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@v3
      - 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@v2
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

Weiterführende Themen