Hochladen einer SARIF-Datei in GitHub

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

Wenn Sie beispielsweise Folgendes verwenden:

• 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.
• GitHub Actions um ein SARIF-kompatibles Analysetool auszuführen, können Sie den Workflow aktualisieren, um einen letzten Schritt einzufügen, der die Ergebnisse hochlädt. Siehe Hochladen einer code scanning-Analyse mit GitHub Actions.
• Um CodeQL CLI in Ihrem CI-System auszuführen, können Sie die CLI verwenden, um Ergebnisse nach GitHub hochzuladen. Weitere Informationen findest du unter Verwenden der Codeüberprüfung mit deinem vorhandenen CI-System.
• Ein Tool, das Ergebnisse als Artefakt außerhalb Ihres Repositorys erzeugt, können Sie über die code scanning API hochladen. Weitere Informationen findest du unter 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

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 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 findest du im Artikel über die 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.

Ü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 finden Sie 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 finden Sie 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 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 finden Sie 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@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:

• Wenn du direkt die CodeQL CLI verwendest, übergib beim Generieren von SARIF-Dateien das --sarif-category-Argument an den codeql database analyze-Befehl. Weitere Informationen finden Sie unter Informationen zur CodeQL-CLI.
• Wenn du GitHub Actions mit codeql-action/analyze verwendest, wird die Kategorie automatisch über den Workflownamen und beliebige Matrixvariablen (in der Regel language) festgelegt. 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.
• Bei Verwendung von GitHub Actions zum Hochladen von Ergebnissen aus anderen Tools für die statische Analyse musst du eine category-Eingabe angeben, wenn du mehr als eine Ergebnisdatei für dasselbe Tool in einem Workflow hochlädst. Weitere Informationen finden Sie 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. Sollten du jedoch versuchen, mehrere SARIF-Dateien für dasselbe Tool und dieselbe Kategorie in einer einzelnen GitHub Actions-Workflowausführung hochzuladen, wird die Fehlkonfiguration erkannt, und bei der Ausführung tritt ein Fehler auf.

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)