Aktivieren von Codescans mit Tools von Drittanbietern
Anstatt Codescans in GitHub auszuführen, können Sie die Analyse an anderer Stelle durchführen und die Ergebnisse dann hochladen. Warnungen für extern ausgeführte Codescans werden auf die gleiche Weise angezeigt wie für die Codescans, die Sie in GitHub ausführen. Sie können SARIF-Dateien (Static Analysis Results Interchange Format) hochladen, die außerhalb GitHub oder mit GitHub Actions generiert wurden, um Codescanwarnungen von Drittanbietertools in Ihrem Repository anzuzeigen.
In dieser Lerneinheit erfahren Sie, wie Sie Codeüberprüfungen mit Tools von Drittanbietern aktivieren und SARIF-Dateien verwenden und hochladen.
Informationen zu SARIF-Dateiuploads für Codescans
GitHub erstellt unter Verwendung von Informationen aus SARIF-Dateien in einem Repository Warnungen zur Codeüberprüfung. Sie können SARIF-Dateien mit vielen Sicherheitstesttools für statische Analysen generieren, einschließlich CodeQL. Für die Ergebnisse muss SARIF Version 2.1.0 verwendet werden.
Sie können die Ergebnisse mit der API für die Codeüberprüfung, der CodeQL CLI oder GitHub Actions hochladen. Die beste Uploadmethode hängt davon ab, wie Sie die SARIF-Datei generiert haben.
API für die Codeüberprüfung
Mit der API für die Codeüberprüfung können Sie Informationen zu Warnungen zur Codeüberprüfung, Analysen, Datenbanken und der Standardsetupkonfiguration aus einem Repository abrufen. Darüber hinaus können Sie Warnungen zur Codeüberprüfung und die Standardsetupkonfiguration aktualisieren. Sie können die Endpunkte verwenden, um automatisierte Berichte für die Warnungen zur Codeüberprüfung in einer Organisation zu erstellen oder Analyseergebnisse hochzuladen, die mithilfe von Tools für Offlinecodescans generiert wurden.
Sie können von https://api.github.com über HTTPS auf die GitHub-API zugreifen. Alle Daten werden im JSON-Format gesendet und empfangen. Die API verwendet benutzerdefinierte Medientypen, damit Consumer das Format der Daten auswählen können, die sie empfangen möchten. Medientypen sind ressourcenspezifisch, sodass sie unabhängig voneinander geändert werden können und Formate unterstützen, die von anderen Ressourcen nicht unterstützt werden.
Es gibt einen unterstützten benutzerdefinierten Medientyp für die REST-API zum Codescannen. application/sarif+json
Sie können diesen Medientyp mit GET-Anforderungen verwenden, die an den /analyses/{analysis_id}-Endpunkt gesendet werden. Wenn Sie diesen Medientyp mit diesem Vorgang verwenden, enthält die Antwort eine Teilmenge der tatsächlichen Daten, die für die angegebene Analyse hochgeladen wurden, anstatt der Zusammenfassung der Analyse, die zurückgegeben wird, wenn Sie den Standardmedientyp verwenden. Die Antwort enthält auch zusätzliche Daten, z. B. die github/alertNumber- und github/alertUrl-Eigenschaften. Die Daten werden mit SARIF Version 2.1.0 formatiert.
Es folgt ein Beispiel für einen cURL-Befehl, der die API verwendet, um die Codeüberprüfungswarnungen für eine Organisation auflisten zu können:
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/code-scanning/alerts
Weitere Informationen zur Verwendung der Codescan-API finden Sie in der Dokumentation zur GitHub REST-API.
CodeQL-Befehlszeilenschnittstelle
Die CodeQL CLI ist ein eigenständiges Produkt, das Sie zum Analysieren von Code verwenden können. Ihr Hauptzweck besteht darin, eine Datenbankdarstellung einer Codebasis zu generieren: eine CodeQL-Datenbank. Sobald die Datenbank fertig ist, können Sie sie interaktiv abfragen, oder Sie können eine Reihe von Abfragen ausführen, um eine Reihe von Ergebnissen im SARIF-Format zu generieren und die Ergebnisse in GitHub.com hochzuladen. Die CodeQL CLI ist kostenlos für öffentliche Repositorys, die auf GitHub.com verwaltet werden, und sie ist für die Verwendung in privaten Repositorys im Besitz von Kunden mit einer Advanced Security-Lizenz verfügbar. Laden Sie das CodeQL-Paket von https://github.com/github/codeql-action/releases herunter.
Das Paket enthält Folgendes:
- Das CodeQL CLI-Produkt
- Eine kompatible Version der Abfragen und Bibliotheken von https://github.com/github/codeql
- Vorkompilierte Versionen aller im Paket enthaltenen Abfragen
Sie sollten immer das CodeQL-Paket verwenden, weil dieses die Kompatibilität gewährleistet und außerdem eine viel bessere Leistung bietet als ein separater Download der CodeQL CLI und ein Check-Out der CodeQL-Abfragen.
Codeüberprüfungsanalyse mit GitHub Actions
Um GitHub Actions zum Hochladen einer SARIF-Datei eines Drittanbieters in ein Repository verwenden zu können, benötigen Sie einen GitHub Actions-Workflow. Ein GitHub Actions-Workflow ist ein automatisierter Prozess, der aus mindestens einem Auftrag besteht und als .yml-Datei konfiguriert ist. Workflows werden im Verzeichnis .github/workflows für Ihr Repository gespeichert.
Ihr Workflow verwendet die upload-sarif-Aktion, die Teil des github/codeql-action-Repositorys ist. Dieser Workflow enthält Eingabeparameter, die Sie zum Konfigurieren des Uploads verwenden können.
Der Haupteingabeparameter ist sarif-file. Er konfiguriert die hochzuladende Datei oder das Verzeichnis der SARIF-Dateien. Das Verzeichnis oder der Dateipfad ist relativ zum Stammverzeichnis des Repositorys.
Die upload-sarif-Aktion kann so konfiguriert werden, dass sie ausgeführt wird, wenn das push-Ereignis und das scheduled-Ereignis auftreten.
In diesem Beispiel werden die Elemente der YML-Datei der upload-sarif-Aktion beschrieben:
name: 'Code Scanning : Upload SARIF'
description: 'Upload the analysis results'
author: 'GitHub'
inputs:
sarif_file:
description: |
The SARIF file or directory of SARIF files to be uploaded to GitHub code scanning.
See https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/
uploading-a-sarif-file-to-github#uploading-a-code-scanning-analysis-with-github-actions
for information on the maximum number of results and maximum file size supported by code scanning.
required: false
default: '../results'
checkout_path:
description: "The path at which the analyzed repository was checked out.
Used to relativize any absolute paths in the uploaded SARIF file."
required: false
default: ${{ github.workspace }}
token:
default: ${{ github.token }}
matrix:
default: ${{ toJson(matrix) }}
category:
description: String used by Code Scanning for matching the analyses
required: false
wait-for-processing:
description: If true, the Action will wait for the uploaded SARIF to be processed before completing.
required: true
default: "false"
runs:
using: 'node12'
main: '../lib/upload-sarif-action.js'
Jedes Mal, wenn die Ergebnisse eines neuen Codescans hochgeladen werden, werden die Ergebnisse verarbeitet und dem Repository Warnungen hinzugefügt. GitHub verwendet Eigenschaften in der SARIF-Datei, um Warnungen anzuzeigen. Um beispielsweise doppelte Warnungen für dasselbe Problem zu verhindern, verwendet der Codescan Fingerabdrücke, um Ergebnisse in verschiedenen Ausführungen abzugleichen, sodass sie nur ein Mal in der letzten Ausführung für den ausgewählten Branch angezeigt werden. SARIF-Dateien, die vom CodeQL-Analyseworkflow erstellt wurden, enthalten diese Fingerabdruckdaten im partialFingerprints-Feld. Wenn Sie eine SARIF-Datei mithilfe der upload-sarif-Aktion hochladen und diese Daten fehlen, versucht GitHub, das partialFingerprints-Feld aus den Quelldateien mit Daten aufzufüllen.
Wenn Ihre SARIF-Datei keine partialFingerprints enthält, berechnet die upload-sarif-Aktion das partialFingerprints-Feld für Sie und versucht, doppelte Warnungen zu verhindern. GitHub kann partialFingerprints nur erstellten, wenn das Repository sowohl die SARIF-Datei als auch den Quellcode enthält, der in der statischen Analyse verwendet wird.
SARIF-Upload unterstützt maximal 5.000 Ergebnisse pro Upload. Alle Ergebnisse, die diesen Grenzwert überschreiten, werden ignoriert. Wenn ein Tool zu viele Ergebnisse generiert, sollten Sie die Konfiguration aktualisieren, um sich auf die Ergebnisse für die wichtigsten Regeln oder Abfragen zu konzentrieren.
Für jeden Upload unterstützt der SARIF-Upload eine maximale Größe von 10 MB für die mit gzip komprimierte SARIF-Datei. Uploads, die diesen Grenzwert überschreiten, werden abgelehnt. Wenn Ihre SARIF-Datei zu groß ist, weil sie zu viele Ergebnisse enthält, sollten Sie die Konfiguration aktualisieren, um sich auf die Ergebnisse für die wichtigsten Regeln oder Abfragen zu konzentrieren.
Hochladen von SARIF-Dateien, die außerhalb Ihres Repositorys generiert wurden
Sie können auch einen neuen Workflow erstellen, der SARIF-Dateien hochlädt, nachdem Sie sie in Ihr Repository committet haben. Dies ist nützlich, wenn die SARIF-Datei als Artefakt außerhalb Ihres Repositorys generiert wird.
Im folgenden Beispiel wird der Workflow 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. Dieser Workflow lädt die results.sarif-Datei hoch, die sich im Stammverzeichnis des Repositorys befindet. Sie können diesen Workflow auch ändern, um ein Verzeichnis mit SARIF-Dateien hochzuladen. Beispielsweise können Sie alle SARIF-Dateien in einem Verzeichnis im Stammverzeichnis Ihres Repositorys mit dem Namen sarif-output platzieren und den Eingabeparameter sarif_file der Aktion auf sarif-output festlegen.
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:
security-events: write
steps:
# This step checks out a copy of your repository.
- name: Checkout repository
uses: actions/checkout@v2
- name: Upload SARIF file
uses: github/codeql-action/upload-sarif@v1
with:
# Path to SARIF file relative to the root of the repository
sarif_file: results.sarif
Hochladen von SARIF-Dateien, die als Teil eines CI-Workflows generiert werden
Wenn Sie die SARIF-Datei eines Drittanbieters als Teil eines CI-Workflows (Continuous Integration) generieren, können Sie die upload-sarif-Aktion als Schritt nach dem Ausführen der CI-Tests hinzufügen. Wenn Sie noch nicht über einen CI-Workflow verfügen, können Sie einen solchen mithilfe eines Startworkflows im https://github.com/actions/starter-workflows-Repository erstellen.
In diesem Beispiel wird der Workflow 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.
Dieses Beispiel zeigt das statische Analysetool ESLint 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.
```
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:
security-events: write
steps:
- uses: actions/checkout@v2
- 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@v1
with:
// Path to SARIF file relative to the root of the repository
sarif_file: results.sarif
```