Hochladen von CodeQL-Analyseergebnissen auf GitHub

Informationen zur SARIF-Ausgabe

GitHub erstellt code scanning-Warnungen in einem Repository mithilfe von Informationen aus den SARIF-Dateien (Static Analysis Results Interchange Format). SARIF wurde entwickelt, um die Ausgabe einer breiten Palette statischer Analysetools darzustellen, und es gibt viele Features in der SARIF-Spezifikation, die als „optional“ betrachtet werden. Für die Ergebnisse muss SARIF Version 2.1.0 verwendet werden. Weitere Informationen findest du unter SARIF-Unterstützung für die Codeüberprüfung.

Nach der Analyse einer CodeQL-Datenbank mit der CodeQL CLI erhältst du eine SARIF-Datei mit den Ergebnissen. Weitere Informationen findest du unter Analysieren des Codes mit CodeQL-Abfragen. Du kannst die CodeQL CLI verwenden, um die Ergebnisse auf GitHub hochzuladen.

Wenn du eine andere Methode als die CodeQL CLI zur Generierung der Ergebnisse verwendet hast, kannst du diese mit einer anderen Methode hochladen. Weitere Informationen findest du unter Hochladen einer SARIF-Datei in GitHub.

Hinweis: Das Hochladen von SARIF-Daten zur Anzeige von code scanning-Ergebnissen in GitHub Enterprise Server wird für organisationseigene Repositorys mit aktivierter GitHub Advanced Security unterstützt. Weitere Informationen findest du unter Verwalten von Sicherheits- und Analyseeinstellungen für dein Repository.

Generieren eines Tokens zur Authentifizierung mit GitHub Enterprise Server

Bevor du deine Ergebnisse auf GitHub Enterprise Server hochladen kannst, musst du ein personal access token mit der security_events-Schreibberechtigung generieren. Weitere Informationen findest du unter Verwalten deiner persönlichen Zugriffstoken.

Wenn du die CodeQL CLI in einem CI-System (Continuous Integration) eines Drittanbieters installiert hast, um Ergebnisse zu erstellen, die in GitHub als Codescanwarnungen angezeigt werden, kannst du GitHub App oder ein personal access token verwenden, um die Ergebnisse aufGitHub Enterprise Server hochzuladen. Weitere Informationen findest du unter Verwenden der Codeüberprüfung mit deinem vorhandenen CI-System.

Hochladen von Ergebnissen in GitHub Enterprise Server

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 SARIF-Unterstützung für die Codeüberprüfung.

Bevor du Ergebnisse auf GitHub Enterprise Server hochladen kannst, musst du bestimmen, wie du die GitHub App oder das im vorherigen Abschnitt erstellte personal access token am besten an die CodeQL CLI übergibst. Es wird empfohlen, den Leitfaden deines CI-Systems zur sicheren Verwendung eines Geheimnisspeichers zu lesen. Die CodeQL CLI unterstützt:

Interfacing mit einem Geheimspeicher mithilfe der --github-auth-stdin-Option (empfohlen)
Das Speichern des Geheimnisses in der Umgebungsvariablen GITHUB_TOKEN und das Ausführen der CLI ohne die Option --github-auth-stdin
Zu Testzwecken kannst du die --github-auth-stdin-Befehlszeilenoption übergeben und ein temporäres Token über die Standardeingabe bereitstellen.

Wenn du dich für die sicherste und zuverlässigste Methode für deine Konfiguration entschieden hast, führe codeql github upload-results in jeder SARIF-Ergebnisdatei aus, und schließe --github-auth-stdin ein (es sei denn, das Token ist in der Umgebungsvariablen GITHUB_TOKEN verfügbar).

# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-url=<URL> \
    --github-auth-stdin

# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-url=<URL> \

Option	Erforderlich	Verwendung
`--repository`		Gib OWNER/NAME (dendie Besitzerin/den Namen) des Repositorys an, in das Daten hochgeladen werden. Der Besitzer muss eine Organisation innerhalb eines Unternehmens sein, die über eine Lizenz für GitHub Advanced Security verfügt. GitHub Advanced Security muss für das Repository aktiviert sein. Weitere Informationen findest du unter Verwalten von Sicherheits- und Analyseeinstellungen für dein Repository.
`--ref`		Gib den Namen des von dir ausgecheckten und analysierten Verweises (`ref`) an, damit die Ergebnisse dem richtigen Code zugeordnet werden können. Verwende für einen Branch `refs/heads/BRANCH-NAME`. Verwende für einen Headcommit eines Pull Requests `refs/pull/NUMBER/head` oder für den von GitHub generierten Mergecommit eines Pull Requests `refs/pull/NUMBER/merge`.
`--commit`		Gib die vollständigen SHA des analysierten Commits an.
`--sarif`		Gib die SARIF-Datei an, die geladen werden soll.
`--github-url`		Gib die URL für GitHub Enterprise Server an.
`--github-auth-stdin`		Übergebe die CLI an die GitHub App oder das personal access token, das zur Authentifizierung mit der REST-API von GitHub aus deinem Geheimnisspeicher über die Standardeingabe erstellt wurde. Dies ist nicht erforderlich, wenn der Befehl über Zugriff auf `GITHUB_TOKEN`-Umgebungsvariablen verfügt, die mit diesem Token festgelegt wurden.

Weitere Informationen findest du unter github upload-results.

Hinweis: Wenn du mehrere CodeQL-Datenbanken für einen einzelnen Commit analysiert hast, musst du für alle von diesem Befehl generierten Ergebnisse eine SARIF-Kategorie angegeben haben. Wenn du die Ergebnisse auf GitHub Enterprise Server hochlädst, wird diese Kategorie bei der code scanning verwendet, um die Ergebnisse separat für jede Sprache zu speichern. Wenn du dies vergisst, überschreibt jeder Upload die alten Ergebnisse. Weitere Informationen findest du unter Analysieren des Codes mit CodeQL-Abfragen.

Einfaches Beispiel für das Hochladen von Ergebnissen in GitHub Enterprise Server

Im folgenden Beispiel werden Ergebnisse aus der SARIF-Datei temp/example-repo-js.sarif in das Repository my-org/example-repo hochgeladen. Es teilt der code scanning-API mit, dass die Ergebnisse für den Commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 für den Branch main gelten. Im Beispiel wird angenommen, dass die GitHub App oder personal access token, die für die Authentifizierung mit der REST-API von GitHub erstellt wurden, die Umgebungsvariable GITHUB_TOKEN verwenden.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-url=https://HOSTNAME \

Es gibt keine Ausgabe aus diesem Befehl, sofern der Upload nicht erfolgreich war. Die Eingabeaufforderung kehrt zurück, wenn der Upload abgeschlossen ist und die Datenverarbeitung begonnen hat. Auf kleineren Codebasen solltest du die code scanning-Warnungen in GitHub Enterprise Server kurz danach untersuchen können. Je nach ausgechecktem Code kannst du Warnungen direkt im Pull Request oder auf der Registerkarte Sicherheit für Branches anzeigen. Weitere Informationen findest du unter Filtern von Codescanbenachrichtigungen in Pull-Anforderungen und Verwalten von Codescanwarnungen für dein Repository.

Hochladen von Diagnoseinformationen in GitHub Enterprise Server, wenn bei der Analyse ein Fehler auftritt

Wenn CodeQL CLI die Analyse einer Datenbank erfolgreich abgeschlossen hat, werden Diagnoseinformationen wie Dateiabdeckung, Warnungen und Fehler gesammelt und mit den Ergebnissen in die SARIF-Datei eingeschlossen. Wenn du die SARIF-Datei auf GitHub hochlädst, werden die Diagnoseinformationen auf der code scanning-Seite mit dem Toolstatus für das Repository angezeigt, damit du leicht sehen kannst, wie gut CodeQL funktioniert, und du eventuelle Probleme beheben kannst. Weitere Informationen findest du unter Informationen zur Toolstatusseite für die Codeüberprüfung.

Wenn bei codeql database analyze jedoch aus beliebigem Grund ein Fehler auftritt, liegen weder eine SARIF-Datei zum Hochladen auf GitHub vor, noch Diagnoseinformationen, die auf der code scanning-Seite mit dem Toolstatus für das Repository angezeigt werden. Dies erschwert Benutzer*innen die Problembehandlung bei der Analyse, es sei denn, sie haben Zugriff auf Protokolldateien in deinem CI-System.

Du solltest deinen CI-Workflow so konfigurieren, dass Diagnoseinformationen exportiert und in GitHub Enterprise Server hochgeladen werden, wenn bei einer Analyse ein Fehler auftritt. Dazu kannst du die folgenden einfachen Befehle verwenden, um Diagnoseinformationen zu exportieren und in GitHub hochzuladen.

Exportieren von Diagnoseinformationen, wenn bei der Analyse ein Fehler auftritt

Du kannst mit database export-diagnostics eine SARIF-Datei für die Analyse erstellen, bei der ein Fehler aufgetreten ist, z. B.:

$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript --format=sarifv2.1.0 \
    --output=/temp/example-repo-js.sarif

Diese SARIF-Datei enthält Diagnoseinformationen für die Analyse, bei der ein Fehler aufgetreten ist, einschließlich aller Dateiabdeckungsinformationen, Warnungen und Fehler, die während der Analyse generiert wurden.

Hochladen von Diagnoseinformationen, wenn bei der Analyse ein Fehler auftritt

Du kannst diese Diagnoseinformationen auf der Seite mit dem Toolstatus verfügbar machen, indem du die SARIF-Datei mithilfe von github upload-results auf GitHub Enterprise Server hochlädst, z. B.:

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-url=https://HOSTNAME \

Dies ist identisch mit dem Prozess zum Hochladen von SARIF-Dateien aus erfolgreichen Analysen.