Hochladen von CodeQL-Analyseergebnissen in GitHub

Nachdem Sie eine CodeQL Datenbank mithilfe der CodeQL CLIDatenbank analysiert haben, verfügen Sie über eine SARIF-Datei, die die Ergebnisse enthält. Anschließend können Sie mit CodeQL CLI Ergebnisse zu GitHub hochladen.

Wenn Sie eine andere Methode als die zum Generieren von CodeQL CLI Ergebnissen verwendeten, können Sie andere Uploadmethoden verwenden. Weitere Informationen finden Sie unter Hochladen einer SARIF-Datei in GitHub.

Generieren eines Tokens für die Authentifizierung mit GitHub

Bevor Sie Ihre Ergebnisse auf GitHub hochladen können, müssen Sie zuerst ein personal access token erzeugen. Weitere Informationen findest du unter Verwalten deiner persönlichen Zugriffstoken.

•         **
          Personal access token (classic)
          ** erfordert "Code scanning Warnungen" **Lese- und Schreibzugriff** für die erforderlichen Repositorys.
  

•         **
          Fine-grained personal access token
          ** erfordert "Repo" Zugriff auf **security_events**.
  

Wenn Sie das CodeQL CLI in einem CI-System eines Drittanbieters installiert haben, können Sie auch eine GitHub App verwenden, um Ergebnisse zu GitHub hochzuladen. Weitere Informationen findest du unter Verwenden der Codeüberprüfung mit deinem vorhandenen CI-System.

Hochladen von Ergebnissen in GitHub

1. Ü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.

2. Ermitteln Sie die beste Methode, um die im vorherigen Abschnitt erstellten GitHub App oder personal access token an den CodeQL CLI zu übergeben. Es wird empfohlen, den Leitfaden Ihres 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.

3. 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-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> 
   

Option	Erforderlich	Usage
--repository		Gib OWNER/NAME (dendie Besitzerin/den Namen) des Repositorys an, in das Daten hochgeladen werden. Der Besitzer muss eine Organisation innerhalb eines Unternehmens oder in einem GitHub Team Plan sein, der GitHub Code Security für das Repository aktiviert ist, es sei denn, das Repository ist öffentlich. Weitere Informationen finden Sie 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. Für einen Branch verwenden Sie refs/heads/BRANCH-NAME, für den Head-Commit einer Pull-Anfrage verwenden Sie refs/pull/NUMBER/head, oder für den von GitHub generierten Merge-Commit einer Pull-Anfrage verwenden Sie refs/pull/NUMBER/merge.
--commit		Geben Sie die vollständigen SHA des analysierten Commits an.
--sarif		Geben Sie die zu ladende SARIF-Datei an.
--github-auth-stdin		Geben Sie der CLI über die Standardeingabe das GitHub App oder personal access token zur Authentifizierung mit der REST-API von GitHub aus Ihrem geheimen Speicher. Dies ist nicht erforderlich, wenn der Befehl über Zugriff auf GITHUB_TOKEN-Umgebungsvariablen verfügt, die mit diesem Token festgelegt wurden.

Weitere Informationen finden Sie unter GitHub-Upload-Ergebnisse.

Grundlegendes Beispiel für das Hochladen von Ergebnissen in GitHub

Im folgenden Beispiel werden Ergebnisse aus der SARIF-Datei temp/example-repo-js.sarif in das Repository my-org/example-repo hochgeladen. Sie teilt der code scanning API mit, dass sich die Ergebnisse auf den Commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 auf der main Branch beziehen. Im Beispiel wird davon ausgegangen, dass die für die Authentifizierung mit der REST-API von GitHub erstellte GitHub App oder personal access token die Umgebungsvariable GITHUB_TOKEN verwendet.

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

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 sollten Sie kurz danach die code scanning Warnungen GitHub untersuchen können. Je nach ausgechecktem Code können Sie Warnungen direkt im Pull-Request oder auf der Security and quality Registerkarte für Verzweigungen anzeigen.

Hochladen von Diagnoseinformationen zu GitHub, wenn die Analyse fehlschlägt

Wenn CodeQL CLI die Analyse einer Datenbank erfolgreich abgeschlossen ist, sammelt sie Diagnoseinformationen wie Dateiabdeckung, Warnungen und Fehler und schließt sie in die SARIF-Datei mit den Ergebnissen ein. Wenn Sie die SARIF-Datei auf GitHub hochladen, werden die Diagnoseinformationen auf code scanningSeite mit dem Toolstatus für das Repository angezeigt, um leicht zu erkennen, wie gut CodeQL funktioniert und um Probleme zu debuggen. Weitere Informationen finden Sie unter Verwenden der Toolstatusseite zum Scannen von Code.

Wenn codeql database analyze jedoch aus irgendeinem Grund keine SARIF-Datei hochgeladen werden kann, gibt es keine Diagnoseinformationen, die im code scanningSeite mit dem Toolstatus für das Repository angezeigt werden können. Dies erschwert Benutzer*innen die Problembehandlung bei der Analyse, es sei denn, sie haben Zugriff auf Protokolldateien in deinem CI-System.

Wir empfehlen, dass Sie Ihren CI-Workflow so konfigurieren, dass Diagnoseinformationen zu GitHub exportiert und hochgeladen werden, wenn eine Analyse fehlschlägt. Dazu können Sie die folgenden einfachen Befehle verwenden, um Diagnoseinformationen zu exportieren und sie an GitHub hochzuladen.

Exportieren von Diagnoseinformationen, wenn bei der Analyse ein Fehler auftritt

Sie können mit Datenbankexportdiagnose 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-typescript --format=sarif-latest \
    --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

Sie können diese Diagnoseinformationen verfügbar machen auf Seite mit dem Toolstatus, indem Sie die SARIF-Datei unter Verwendung von GitHub-Upload-Ergebnisse in GitHub hochladen, z. B.:

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

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