SARIF-Export und Integration in GitHub Code Scanning

Exportieren Sie ein abgeschlossenes vetkit-Audit über dessen Report-Endpunkt mit format=sarif und laden Sie die SARIF-2.1.0-Datei dann aus Ihrem GitHub-Actions-Workflow hoch. Ordnen Sie das Audit vor dem Upload dem analysierten Repository und Commit zu. Das Herunterladen des Berichts veröffentlicht selbst noch keine Warnungen auf GitHub; der Upload ist ein separater Schritt, den Sie konfigurieren.

1. Voraussetzungen prüfen

• Halten Sie die Organisations-ID, die Audit-ID und einen vetkit-API-Schlüssel mit reports:read bereit. Ein automatisierter Workflow, der Audits auch startet und deren Status abfragt, braucht audits:write und audits:read.
• Prüfen Sie Repository und Commit-SHA des Audits. Fordern Sie in der CI ein Audit für genau den Commit des Workflows an oder verwenden Sie ein vorhandenes wieder, und warten Sie vor dem Export, bis es abgeschlossen ist.
• Prüfen Sie den JSON-Bericht auf Teilergebnisse und den tatsächlichen Scan-Umfang. Auch ein gültiges SARIF-Dokument kann eine unvollständige Analyse darstellen.

GitHub unterstützt Code Scanning für öffentliche Repositorys und für berechtigte Organisations-Repositorys mit aktiviertem GitHub Code Security. Prüfen Sie Berechtigung und Schreibzugriff Ihres Repositorys in GitHubs Dokumentation zum SARIF-Upload.

2. Das Audit exportieren

Setzen Sie die folgenden Variablen in Ihrer lokalen Shell oder Ihrer CI-Umgebung. VETKIT_API_URL ist der Origin Ihrer vetkit-API ohne /v1. Speichern Sie den Schlüssel in einem Secret-Manager oder als CI-Secret, nicht in der Workflow-Datei, im Repository oder in einem Shell-Skript. Dieser Befehl benötigt curl und jq:

$ set -euo pipefail$ : "${VETKIT_API_URL:?Set the API origin}"$ : "${VETKIT_ORG_ID:?Set the organization ID}"$ : "${VETKIT_AUDIT_ID:?Set the completed audit ID}"$ : "${VETKIT_API_KEY:?Set a reports:read key}" $ curl --fail-with-body --silent --show-error --max-time 30 \  "$VETKIT_API_URL/v1/orgs/$VETKIT_ORG_ID/audits/$VETKIT_AUDIT_ID/report?format=sarif" \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -o vetkit.sarif$ jq -e '.version == "2.1.0" and (.runs | type == "array")' vetkit.sarif >/dev/null

Der Endpunkt liefert application/sarif+json und einen Anhang-Dateinamen, der auf dem auditierten Commit basiert. Der Befehl speichert die Datei bewusst als vetkit.sarif für den Upload-Schritt. Die jq-Prüfung ist eine einfache Formatprüfung, keine vollständige Schema-Validierung und keine Bestätigung, dass der Scan vollständig ist. Behandeln Sie den heruntergeladenen Bericht als Information über das Repository und kontrollieren Sie den Zugriff darauf.

3. Aus Ihrem Workflow hochladen

Checken Sie in einem Workflow für das gescannte Repository den passenden Quellcode aus, holen Sie das abgeschlossene Audit und führen Sie den obigen Download-Befehl aus. Halten Sie VETKIT_API_KEY in einem Actions-Secret. Das folgende Fragment zeigt die Berechtigungen und den abschließenden Upload-Schritt; es ist kein eigenständiger Scan-Workflow. Fügen Sie den Download zwischen Checkout und Upload ein:

permissions:  contents: read  actions: read  security-events: write # Inside the job's steps, after choosing the matching audit:steps:  - uses: actions/checkout@v6    with:      persist-credentials: false  # Insert the authenticated download step here.  - name: Upload vetkit results    uses: github/codeql-action/upload-sarif@v4    with:      sarif_file: vetkit.sarif      category: vetkit

GitHubs Upload-Action verwendet sarif_file für den Pfad zum Bericht und category, um Analysen zu unterscheiden. Wird eine Kombination aus Tool und Kategorie für denselben Commit wiederverwendet, können frühere Ergebnisse ersetzt werden; verwenden Sie für getrennte Analysen unterschiedliche Kategorien. Die Berechtigungen und Action-Versionen oben folgen GitHubs Beispiel.

Das Integrationsbeispiel im vetkit-Repository macht den SARIF-Upload über VETKIT_UPLOAD_SARIF=true optional. Sein Full-Scan-Workflow fordert ein Audit für genau diesen Commit an und weist fehlgeschlagene, unvollständige oder unbewertete Ergebnisse vor dem optionalen Upload zurück. Diese Abschlussprüfung setzt keine Schwelle für Schweregrad oder Score: Legen Sie Ihre Release-Richtlinie separat fest. Checks der GitHub App und ein SARIF-Upload sind getrennte Integrationswege.

4. Die importierten Ergebnisse interpretieren

vetkit exportiert einen einzelnen SARIF-Run mit vetkit als Driver. Die Ergebnisse enthalten Regel-IDs, Dateistellen, sofern verfügbar, Hinweise zur Behebung und vetkit-Fingerprints. Analyzer-Versionen werden als Extensions erfasst, und die Herkunft aus Repository und Commit ist enthalten. Die Zuordnung der Schweregrade nutzt SARIF-Levels neben den Schweregrad-Eigenschaften von vetkit; diese numerischen Zuordnungen sind keine unabhängig berechneten CVSS-Scores.

Befunde auf Repository-Ebene verwenden die synthetische Stelle (repository) und verweisen daher womöglich nicht auf eine echte Quellcodezeile. Unterdrückte Befunde bleiben mit SARIF-Suppression-Metadaten im Export. Gehen Sie nicht davon aus, dass die Zahl der exportierten Ergebnisse der Zahl der aktiven Warnungen in GitHub entspricht. Bewahren Sie den ursprünglichen vetkit-Bericht für Abdeckung, Kontext der Bewertung und Details für das Review auf.

Fehlerbehebung

• Der Download schlägt fehl: Prüfen Sie API-Origin, Organisations- und Audit-ID, die Gültigkeit des Schlüssels und den Scope reports:read. Geben Sie den Schlüssel beim Debuggen nicht aus.
• Falsche Quellcodestellen: Vergleichen Sie den Commit des Audits mit dem Commit und Checkout des Workflows. Laden Sie keinen älteren Bericht als Beleg für eine neuere Revision hoch.
• Der Upload wird abgelehnt: Prüfen Sie die Berechtigung bei GitHub, die Workflow-Berechtigungen und die Fehlerausgabe der Upload-Action. GitHub wendet eigene unterstützte SARIF-Eigenschaften und Größenlimits an.
• Keine sichtbaren Warnungen: Prüfen Sie die Ergebnisse in der Datei, die Suppression-Metadaten, die ausgewählte Analyse und die Abdeckung des ursprünglichen Audits. Eine erfolgreiche Übertragung beweist keinen sauberen Scan.

Quellen und Grenzen

Geprüft am 1. November 2026 anhand von Report-Controller und -Service, SARIF-Serializer und dem GitHub-Actions-Integrationsbeispiel im vetkit-Repository. Für die beiden Seiten der Integration siehe die API-Referenz und GitHubs Anforderungen an den Upload. Berechtigungen bei GitHub und das Verhalten der Action können sich ändern. Der SARIF-Export überträgt vorhandene Befunde; er führt weder CodeQL aus noch ergänzt er Checks im ursprünglichen Audit, und er garantiert nicht, dass jedes Detail des vetkit-Berichts in der Oberfläche von GitHub erscheint.