Hochladen einer SARIF-Datei in GitHub

Wenn Sie ein Analysetool eines Drittanbieters oder ein CI/CD-System verwenden, um Code auf Sicherheitsrisiken zu überprüfen, können Sie eine SARIF-Datei generieren und sie in GitHub hochladen. Die beste Uploadmethode hängt davon ab, wie Sie die SARIF-Datei generieren.

Wenn Sie beispielsweise Folgendes verwenden:

•         GitHub Actions um die CodeQL Aktion auszuführen, ist keine weitere Aktion erforderlich. Die CodeQL Aktion lädt die SARIF-Datei automatisch hoch, wenn sie die Analyse abgeschlossen hat.
  

•         GitHub Actions um ein SARIF-kompatibles Analysetool auszuführen, können Sie den Workflow so aktualisieren, dass er einen letzten Schritt enthält, der die Ergebnisse hochlädt. Siehe [Hochladen einer code scanning Analyse mit GitHub Actions](#uploading-a-code-scanning-analysis-with-github-actions).
  

• Um CodeQL CLI in Ihrem CI-System auszuführen, können Sie die CLI verwenden, um Ergebnisse zu GitHub hochzuladen. Siehe Verwenden der Codeüberprüfung mit deinem vorhandenen CI-System.
• Sie können mit einem Tool, das Ergebnisse als Artefakt außerhalb Ihres Repositorys generiert, die code scanning API verwenden, um die Datei hochzuladen. Siehe REST-API-Endpunkte für die Codeüberprüfung.

Standardmäßig erwartet code scanning eine SARIF-Ergebnisdatei pro Analyse für ein Repository. Wenn du mehrere Ergebnisse für einen Commit in einem Repository hochladen möchtest, musst du jede Gruppe von Ergebnissen als eindeutige Gruppe identifizieren.

Hochladen einer code scanning Analyse mit GitHub Actions

          GitHub Actions Um eine SARIF-Datei eines Drittanbieters in ein Repository hochzuladen, benötigen Sie einen Workflow. Weitere Informationen findest du unter [AUTOTITLE](/actions/learn-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. Auf diese Weise können Sie denselben Commit in mehreren Weisen 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 der 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. GitHub kann nur partialFingerprints erstellt werden, wenn das Repository sowohl die SARIF-Datei als auch den in der statischen Analyse verwendeten Quellcode enthält. Weitere Informationen zum Verhindern doppelter Warnungen findest du unter SARIF-Unterstützung für die Codeüberprüfung.

Überprüfen Sie, ob die SARIF-Eigenschaften die unterstützte Größe für den Upload haben und dass 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 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@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) generieren, kannst du die upload-sarif-Aktion als Schritt nach dem Ausführen der CI-Tests hinzufügen. Wenn Sie noch keinen CI-Workflow haben, können Sie 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. Der Workflow lädt dann die results.sarif Datei mithilfe der upload-sarif Aktion in GitHub hoch. 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@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

Hochladen von mehr als einer SARIF-Datei für einen Commit

Standardmäßig erwartet code scanning eine SARIF-Ergebnisdatei pro Analyse für ein Repository. Wenn du daher eine zweite SARIF-Ergebnisdatei für einen Commit hochlädst, wird sie als Ersatz für den ursprünglichen Datensatz behandelt. Möglicherweise möchtest du zwei verschiedene SARIF-Dateien für eine Analyse hochladen, wenn dein Analysetool beispielsweise eine andere SARIF-Datei für jede Sprache generiert, die analysiert wird, oder für jeden Regelsatz, den sie verwendet. Wenn du mehrere Ergebnisse für einen Commit in einem Repository hochladen möchtest, musst du jede Gruppe von Ergebnissen als eindeutige Gruppe identifizieren.

Wenn du mehrere SARIF-Dateien für einen Commit hochlädst, musst du eine „Kategorie“ für jede Analyse angeben. Das Angeben einer Kategorie variiert je nach Analysemethode:

• Übergeben Sie das CodeQL CLI--sarif-category Argument direkt an den codeql database analyze Befehl, wenn Sie SARIF-Dateien generieren. Weitere Informationen findest du unter Informationen zur CodeQL-CLI.
• Bei der Verwendung von GitHub Actions mit codeql-action/analyze wird die Kategorie automatisch anhand des Workflownamens und aller Matrixvariablen festgelegt (in der Regel language). Du kannst dieses Verhalten überschreiben, indem du eine category-Eingabe für die Aktion angibst, was beim Analysieren verschiedener Abschnitte eines Monorepositorys in einem einzelnen Workflow nützlich ist.
• Verwenden Sie GitHub Actions, um Ergebnisse von anderen statischen Analysetools hochzuladen, müssen Sie eine category Eingabe angeben, wenn Sie mehr als eine Datei mit Ergebnissen für dasselbe Tool in einem Workflow hochladen. Weitere Informationen findest du unter Hochladen einer SARIF-Datei in GitHub.
• Wenn du keinen dieser beiden Ansätze verwendest, musst du in jeder SARIF-Datei, die hochgeladen werden soll, eine eindeutige runAutomationDetails.id-Eigenschaft angeben. Weitere Informationen zu dieser Eigenschaft finden Sie unter runAutomationDetails-Objekt.

Wenn du eine zweite SARIF-Datei für einen Commit mit derselben Kategorie und aus demselben Tool hochlädst, werden die früheren Ergebnisse überschrieben. Wenn Sie jedoch versuchen, mehrere SARIF-Dateien für dasselbe Tool und dieselbe Kategorie in einer einzigen GitHub Actions Workflowausführung hochzuladen, wird die Fehlkonfiguration erkannt, und die Ausführung schlägt fehl.

Weiterführende Lektüre

•         [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)