SARIF-Unterstützung für die Codeüberprüfung

Informationen zur SARIF-Unterstützung

SARIF (Static Analysis Results Interchange Format) ist ein OASIS-Standard, der ein Ausgabedateiformat definiert. Der SARIF-Standard wird verwendet, um zu optimieren, wie statische Analysetools ihre Ergebnisse freigeben. Code scanning unterstützt eine Teilmenge des SARIF 2.1.0-JSON-Schemas.

Um eine SARIF-Datei aus einer Drittanbieter-Engine für die statische Codeanalyse hochzuladen, musst du sicherstellen, dass die hochgeladenen Dateien die SARIF 2.1.0-Version verwenden. GitHub analysiert die SARIF-Datei und zeigt Warnungen an, die die Ergebnisse in deinem Repository als Teil der code scanning-Erfahrung verwenden. Weitere Informationen findest du unter Hochladen einer SARIF-Datei in GitHub. Weitere Informationen zum SARIF 2.1.0-JSON-Schema findest du unter sarif-schema-2.1.0.json.

Wenn du GitHub Actions mit dem CodeQL-Analyseworkflow oder der CodeQL CLI einsetzt, dann verwenden die Ergebnisse der code scanning automatisch die unterstützte Teilmenge von SARIF 2.1.0. Weitere Informationen findest du unter Konfigurieren des erweiterten Setups für das Codescanning oder Verwenden der Codeüberprüfung mit deinem vorhandenen CI-System.

GitHub verwendet Eigenschaften in der SARIF-Datei, um Warnungen anzuzeigen. Beispielsweise werden shortDescription und fullDescription oben in einer code scanning-Warnung angezeigt. location ermöglicht GitHub das Anzeigen von Anmerkungen in deiner Codedatei. Weitere Informationen findest du unter Informationen zu Codeüberprüfungswarnungen.

Wenn du noch nicht mit SARIF vertraut bist und mehr erfahren möchtest, kannst du dir das Repository SARIF tutorials von Microsoft ansehen.

Bereitstellen von Daten zum Nachverfolgen von ausführungsübergreifenden code scanning-Warnungen

Jedes Mal, wenn die Ergebnisse eines neuen Codescans hochgeladen werden, werden die Ergebnisse verarbeitet und dem Repository Warnungen hinzugefügt. Um doppelte Warnungen für dasselbe Problem zu verhindern, verwendet das code scanning Fingerabdrücke, um Ergebnisse in verschiedenen Ausführungen abzugleichen, sodass sie nur einmal in der letzten Ausführung für den ausgewählten Branch angezeigt werden. So ist es möglich, beim Bearbeiten von Dateien Warnungen den richtigen Codezeilen zuzuordnen. Die ruleID für ein Ergebnis muss für alle Analysen gleich lauten.

Melden konsistenter Dateipfade

Der Dateipfad muss über alle Ausführungen hinweg konsistent sein, damit ein stabiler Fingerabdruck berechnet werden kann. Wenn sich die Dateipfade für dasselbe Ergebnis unterscheiden, wird bei jeder neuen Analyse eine neue Warnung erstellt und die alte geschlossen. Dies führt dazu, dass für dasselbe Ergebnis mehrere Warnungen ausgegeben werden.

Einschließen von Daten zum Generieren eines Fingerabdrucks

GitHub verwendet die partialFingerprints-Eigenschaft im OASIS-Standard, um zu erkennen, wann zwei Ergebnisse logisch identisch sind. Weitere Informationen findest du im Eintrag zur Eigenschaft „partFingerprints“ in der OASIS-Dokumentation.

SARIF-Dateien, die mit dem CodeQL-Analyseworkflow oder der CodeQL CLI erstellt wurden, enthalten Fingerabdruckdaten. Wenn du eine SARIF-Datei mithilfe der upload-sarif-Aktion hochlädst und diese Daten fehlen, versucht GitHub, das partialFingerprints-Feld aus den Quelldateien aufzufüllen. Weitere Informationen zum Hochladen von Ergebnissen findest du unter Hochladen einer SARIF-Datei in GitHub.

Wenn du eine SARIF-Datei mithilfe des API-Endpunkts /code-scanning/sarifs ohne Fingerabdruckdaten hochlädst, werden code scanning-Warnungen verarbeitet und angezeigt, aber Benutzer*innen werden möglicherweise doppelte Warnungen angezeigt. Um zu vermeiden, dass doppelte Warnungen angezeigt werden, solltest du Fingerabdruckdaten berechnen und die partialFingerprints-Eigenschaft auffüllen, bevor du die SARIF-Datei hochlädst. Möglicherweise erachtest du das Skript, das die upload-sarif-Aktion verwendet, als hilfreichen Startpunkt: https://github.com/github/codeql-action/blob/main/src/fingerprints.ts. Weitere Informationen zur API findest du unter REST-API-Endpunkte für die Codeüberprüfung.

Grundlegendes zu Regeln und Ergebnissen

SARIF-Dateien unterstützen sowohl Regeln als auch Ergebnisse. Die in diesen Elementen gespeicherten Informationen sind ähnlich, dienen jedoch unterschiedlichen Zwecken.

• Regeln sind ein Array von reportingDescriptor-Objekten, die im toolComponent-Objekt enthalten sind. Hier speicherst du Details der Regeln, die während der Analyse ausgeführt werden. Informationen in diesen Objekten sollten sich selten ändern – normalerweis nur, wenn du das Tool aktualisierst.

• Ergebnisse werden als Eine Reihe von result-Objekten unter results im run-Objekt gespeichert. Jedes result-Objekt enthält Details zu einer Warnung in der Codebasis. Innerhalb des results-Objekts kannst du auf die Regel verweisen, die die Warnung erkannt hat.

Wenn du SARIF-Dateien vergleichst, die durch die Analyse verschiedener Codebasen mit demselben Tool und den gleichen Regeln generiert werden, solltest du Unterschiede in den Ergebnissen der Analysen, aber nicht in den Regeln sehen.

Angeben des Standorts für Quelldateien

Durch die Angabe der Speicherorte von Quelldateien und von Codezeilen wird sichergestellt, dass Codeüberprüfungswarnungen in der Datei, die das identifizierte Problem enthält, korrekt angezeigt werden, sodass eine gezielte Problembehebung möglich ist.

Diese Genauigkeit verbessert die Effizienz von Code Review- und Lösungsprozessen, indem Entwicklungsworkflows optimiert werden, da Entwickler Probleme direkt im Kontext ihrer Codebasis beheben können.

Code scanning zeigt außerdem Warnungen in den Ergebnissen der Überprüfung von Pull Requests an, wenn alle Codezeilen, die durch die Warnung identifiziert werden, in der Pull-Request-Diff vorhanden sind.

Damit eine Warnung in einer Pull-Request-Überprüfung angezeigt wird, muss sie alle folgenden Bedingungen erfüllen:

• Alle Codezeilen, die durch die Warnung identifiziert werden, sind in der Pull-Request-Diff vorhanden, einschließlich der ersten Zeile der Warnung.
• Die Warnung muss in den Codezeilen vorhanden sein, die im Pull Request hinzugefügt oder bearbeitet wurden, nicht in Zeilen, die gelöscht wurden.

Das Objekt physicalLocation in einer übermittelten SARIF-Datei gibt die Codezeilen für eine Warnung an. Weitere Informationen findest du unter: physicalLocation-Objekt.

Angeben des Stamms für Quelldateien

Code scanning interpretiert Ergebnisse, die mit relativen Pfaden gemeldet werden, als relativ zum Stamm des analysierten Repositorys. Wenn ein Ergebnis einen absoluten URI enthält, wird er in einen relativen URI konvertiert. Der relative URI kann dann mit einer Datei abgeglichen werden, die per Commit in das Repository übertragen wurde.

Du kannst den Quellstamm für die Konvertierung von absoluten in relative URIs auf eine der folgenden Arten bereitstellen.

• checkout_path-Eingabe für die Aktion github/codeql-action/analyze
• checkout_uri-Parameter für den API-Endpunkt zum SARIF-Upload. Weitere Informationen findest du unter REST-API-Endpunkte für die Codeüberprüfung.
• invocations[0].workingDirectory.uri-Eigenschaft im run-Objekt in der SARIF-Datei

Wenn du einen Quellstamm angibst, muss jeder Speicherort eines Artefakts, der mit einem absoluten URI angegeben wird, das gleiche URI-Schema verwenden. Wenn das URI-Schema für den Quellstamm und mindestens einen der absoluten URIs nicht übereinstimmen, wird der Upload abgelehnt.

Ein Beispiel: Eine SARIF-Datei wird mit dem Quellstamm file:///github/workspace hochgeladen.

# Conversion of absolute URIs to relative URIs for location artifacts

file:///github/workspace/src/main.go -> src/main.go
file:///tmp/go-build/tmp.go          -> file:///tmp/go-build/tmp.go

Der Upload der Datei ist erfolgreich, weil beide absoluten URIs das gleiche URI-Schema verwenden wie der Quellstamm.

Auflösen von Symlinks vor dem Generieren von SARIF-Ergebnissen

Wenn der relative URI für ein Ergebnis mit einer Datei abgeglichen wird, die mit einem Symlink definiert wurde, kann die Codeüberprüfung das Ergebnis nicht anzeigen. Daher müssen Sie alle symlinkierten Dateien auflösen und alle Ergebnisse in diesen Dateien melden, indem Sie den aufgelösten URI verwenden.

Überprüfen deiner SARIF-Datei

Du kannst eine SARIF-Datei mit code scanning kompatibel sein, indem du sie anhand der GitHub}-Aufnahmeregeln testest. Weitere Informationen findest du auf der Seite mit dem SARIF-Validator von Microsoft.

Bei mit gzip komprimierten SARIF-Dateien unterstützt der SARIF-Upload eine maximale Größe von 10 MB pro 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. Weitere Informationen findest du unter SARIF-Ergebnisdatei zu groß.

Code scanning unterstützt das Hochladen einer maximalen Anzahl von Einträgen für die Datenobjekte in der folgenden Tabelle. Wenn eines dieser Objekte den Maximalwert überschreitet, wird die SARIF-Datei abgelehnt. Für einige Objekte gibt es außerdem einen zusätzlichen Grenzwert in Bezug auf die Anzahl der angezeigten Werte. Nach Möglichkeit werden die wichtigsten Werte angezeigt. Um deine Analyse optimal zu nutzen, wenn darin Daten oberhalb der unterstützten Grenzwerte enthalten sind, optimiere die Analysekonfiguration, indem du beispielsweise für das CodeQL-Tool die Abfragen mit der umfangreichsten Ausgabe identifizierst und deaktivierst. Weitere Informationen findest du unter Überschreiten mindestens eines Grenzwerts durch SARIF-Ergebnisse.

Informationen zu andern Fehlern findest du unter „Problembehandlung bei SARIF-Uploads“

Hochladen von mehr als einer SARIF-Datei für einen Commit

Du kannst mehrere SARIF-Dateien für denselben Commit hochladen und die Daten aus jeder Datei als code scanning-Ergebnisse anzeigen. 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 findest du 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 findest du 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 findest du im Abschnitt zum 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.

Unterstützte SARIF-Ausgabedateieigenschaften

Wenn du eine andere Codeanalyse-Engine als CodeQL verwendest, kannst du die unterstützten SARIF-Eigenschaften überprüfen, um zu optimieren, wie deine Analyseergebnisse auf GitHub angezeigt werden.

Jede gültige SARIF 2.1.0-Ausgabedatei kann hochgeladen werden, aber das code scanning verwendet nur die folgenden unterstützten Eigenschaften.

sarifLog-Objekt

Name	Erforderlich	BESCHREIBUNG
$schema		URI des SARIF-JSON-Schemas für Version 2.1.0. Beispiel: https://json.schemastore.org/sarif-2.1.0.json.
version		Code scanning unterstützt nur die SARIF-Version 2.1.0.
runs[]		Eine SARIF-Datei enthält ein Array einer oder mehrerer Ausführungen. Jede Ausführung stellt eine einzelne Ausführung eines Analysetools dar. Weitere Informationen zu einem run findest du im Abschnitt zum run-Objekt.

run-Objekt

Code scanning verwendet das run-Objekt, um Ergebnisse nach Tool zu filtern und Informationen zur Quelle eines Ergebnisses bereitzustellen. Das run-Objekt enthält das tool.driver-Toolkomponentenobjekt, das Informationen zum Tool enthält, das die Ergebnisse generiert hat. Jeder run kann nur Ergebnisse für ein Analysetool umfassen.

Name	Erforderlich	BESCHREIBUNG
tool.driver		Ein toolComponent-Objekt, das das Analysetool beschreibt. Weitere Informationen findest du im Abschnitt zum toolComponent-Objekt.
tool.extensions[]		Ein Array von toolComponent-Objekten, die alle Plug-Ins oder Erweiterungen darstellen, die das Tool während der Analyse verwendet. Weitere Informationen findest du im Abschnitt zum toolComponent-Objekt.
invocation.workingDirectory.uri		Dieses Feld wird ausschließlich dann verwendet, wenn checkout_uri (nur SARIF-Upload-API) oder checkout_path (nur GitHub Actions) nicht angegeben wurden. Der Wert wird verwendet, um absolute URIs, die in physicalLocation-Objekten verwendet werden, in relative URIs umzuwandeln. Weitere Informationen findest du unter Angeben des Stamms für Quelldateien.
results[]		Ergebnisse des Analysetools. Code scanning zeigt die Ergebnisse auf GitHub an. Weitere Informationen findest du im Abschnitt zum result-Objekt.

toolComponent-Objekt

Name	Erforderlich	BESCHREIBUNG
name		Name des Analysetools. Code scanning zeigt den Namen auf GitHub an, damit du die Ergebnisse nach Tool filtern kannst.
version		Version des Analysetools. Code scanning verwendet die Versionsnummer, um nachzuverfolgen, wann die Ergebnisse aufgrund einer Toolversionsänderung und nicht wegen einer Änderung im analysierten Code geändert wurden. Wenn die SARIF-Datei das semanticVersion-Feld enthält, wird version nicht vom code scanning verwendet.
semanticVersion		Version des Analysetools, angegeben durch das Format für die semantische Versionierung 2.0. Code scanning verwendet die Versionsnummer, um nachzuverfolgen, wann die Ergebnisse aufgrund einer Toolversionsänderung und nicht wegen einer Änderung im analysierten Code geändert wurden. Wenn die SARIF-Datei das semanticVersion-Feld enthält, wird version nicht vom code scanning verwendet. Weitere Informationen findest du unter Semantische Versionierung 2.0.0 in der Dokumentation zur semantischen Versionierung.
rules[]		Array von reportingDescriptor-Objekten, die Regeln darstellen. Das Analysetool verwendet Regeln zum Suchen von Problemen im analysierten Code. Weitere Informationen findest du im Abschnitt zum reportingDescriptor-Objekt.

reportingDescriptor-Objekt

Hier speicherst du Details der Regeln, die während der Analyse ausgeführt werden. Informationen in diesen Objekten sollten sich selten ändern – normalerweis nur, wenn du das Tool aktualisierst. Weitere Informationen findest du weiter oben unter Grundlegendes zu Regeln und Ergebnissen.

Name	Erforderlich	BESCHREIBUNG
id		Eindeutiger Bezeichner für die Regel. Auf die id wird von anderen Teilen der SARIF-Datei verwiesen, und sie kann vom code scanning verwendet werden, um URLs auf GitHub anzuzeigen.
name		Der Name der Regel. Code scanning zeigt den Namen auf GitHub an, damit die Ergebnisse nach Tool gefiltert werden können. Auf 255 Zeichen beschränkt.
shortDescription.text		Präzise Beschreibung der Regel. Code scanning zeigt die kurze Beschreibung auf GitHub neben den zugeordneten Ergebnissen an. Auf 1024 Zeichen beschränkt.
fullDescription.text		Eine Beschreibung der Regel. Code scanning zeigt die vollständige Beschreibung auf GitHub neben den zugeordneten Ergebnissen an. Auf 1024 Zeichen beschränkt.
defaultConfiguration.level		Standardschweregrad der Regel. Code scanning verwendet Schweregrade, damit du nachvollziehen kannst, wie wichtig das Ergebnis für eine bestimmte Regel ist. Standardmäßig ist defaultConfiguration.level auf warning festgelegt. Sie können jedoch die Standardstufe für eine Regel außer Kraft setzen, indem Sie das level-Attribut im result-Objekt, das mit dem Ergebnis verbunden ist, festlegen. Weitere Informationen finden Sie in der Dokumentation zu diesem result Objekt. Die gültigen Werte für defaultConfiguration.level sind: note, warning und error.
help.text		Dokumentation für die Regel mithilfe des Textformats. Code scanning zeigt diese Hilfedokumentation neben den zugeordneten Ergebnissen an.
help.markdown		(Empfohlen) Dokumentation für die Regel mit Markdownformat. Code scanning zeigt diese Hilfedokumentation neben den zugeordneten Ergebnissen an. Wenn help.markdown verfügbar ist, wird dieses Element anstelle von help.text angezeigt.
properties.tags[]		Ein Array der Zeichenfolgen. Code scanning verwendet tags, damit du Ergebnisse auf GitHub filtern kannst. Beispielsweise kannst du nach allen Ergebnissen filtern, die das Tag security umfassen.
properties.precision		(Empfohlen) Zeichenfolge, die angibt, wie oft die von dieser Regel angegebenen Ergebnisse „true“ sind. Wenn eine Regel beispielsweise bekanntermaßen eine hohe False-Positive-Rate aufweist, sollte die Genauigkeit low entsprechen. Code scanning sortiert Ergebnisse auf GitHub nach Genauigkeit, sodass die Ergebnisse mit dem höchsten level-Wert und dem höchsten precision-Wert zuerst angezeigt werden. Dies kann very-high, high, medium oder low entsprechen.
properties.problem.severity		(Empfohlen) Zeichenfolge, die den Schweregrad aller Warnungen angibt, die von einer nicht sicherheitsbezogenen Abfrage generiert werden. Dies bestimmt mit der properties.precision-Eigenschaft, ob die Ergebnisse standardmäßig auf GitHub angezeigt werden, sodass die Ergebnisse mit der höchsten problem.severity und dem höchsten precision-Wert zuerst angezeigt werden. Diese können error, warning oder recommendation lauten.
properties.security-severity		(Nur für Sicherheitsregeln empfohlen) Wenn Sie einen Wert für dieses Feld angeben, werden die Ergebnisse für die Regel als Sicherheitsergebnisse behandelt. Zeichenfolge, die eine Bewertung darstellt, die den Schweregrad für Sicherheitsabfragen angibt, und zwar einen Wert größer als 0,0 bis 10,0 (@tags umfasst security). Dies bestimmt mit der properties.precision-Eigenschaft, ob die Ergebnisse standardmäßig auf GitHub angezeigt werden, sodass die Ergebnisse mit der höchsten security-severity und dem höchsten precision-Wert zuerst angezeigt werden. Code scanning übersetzt numerische Bewertungen wie folgt: über 9,0 entspricht critical, 7,0 bis 8,9 entspricht high, 4,0 bis 6,9 entspricht medium, und 0,1 bis 3,9 entspricht low. Bei einem Wert von 0,0 oder bei einem anderen Wert außerhalb des angegebenen Bereichs liegt kein Sicherheitsschweregrad vor.

result-Objekt

Jedes result-Objekt enthält Details zu einer Warnung in der Codebasis. Innerhalb des results-Objekts kannst du auf die Regel verweisen, die die Warnung erkannt hat. Weitere Informationen findest du weiter oben unter Grundlegendes zu Regeln und Ergebnissen.

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.

Name	Erforderlich	BESCHREIBUNG
ruleId		Eindeutiger Bezeichner der Regel (reportingDescriptor.id). Weitere Informationen findest du im Abschnitt zum reportingDescriptor-Objekt. Code scanning verwendet den Regelbezeichner, damit du Ergebnisse auf GitHub nach Regel filtern kannst.
ruleIndex		Index der zugeordneten Regel (reportingDescriptor-Objekt) im rules-Toolkomponentenarray. Weitere Informationen findest du im Abschnitt zum run-Objekt. Zulässiger Bereich für diese Eigenschaft: 0 bis 2^63 – 1.
rule		Verweis, der zum Suchen der Regel (Berichterstellungsdeskriptor) für dieses Ergebnis verwendet wird. Weitere Informationen findest du im Abschnitt zum reportingDescriptor-Objekt.
level		Schweregrad des Ergebnisses. Diese Ebene überschreibt den Standardschweregrad, der von der Regel definiert wird. Code scanning verwendet die Ebene zum Filtern der Ergebnisse nach Schweregrad auf GitHub.
message.text		Meldung, in der das Ergebnis beschrieben wird. Code scanning zeigt den Meldungstext als Titel des Ergebnisses an. Nur der erste Satz der Meldung wird angezeigt, wenn der sichtbare Bereich begrenzt ist.
locations[]		Gruppe der Speicherorte (maximal 10), an denen das Ergebnis gefunden wurde. Nur ein Speicherort sollte einbezogen werden, es sei denn, das Problem kann nur behoben werden, indem an jedem Speicherort eine Änderung vorgenommen wird. Hinweis: Mindestens ein Speicherort ist für das code scanning erforderlich, um ein Ergebnis anzuzeigen. Code scanning verwendet diese Eigenschaft, um zu entscheiden, welche Datei mit dem Ergebnis kommentiert werden soll. Nur der erste Wert dieses Arrays wird verwendet. Alle anderen Werte werden ignoriert.
partialFingerprints		Reihe von Zeichenfolgen, die zum Nachverfolgen der eindeutigen Identität des Ergebnisses verwendet werden. Code scanning verwendet partialFingerprints, um genau zu identifizieren, welche Ergebnisse commit- und branchübergreifend identisch sind. Code scanning versucht, partialFingerprints zu verwenden (sofern vorhanden). Wenn du SARIF-Dateien von Drittanbietern mithilfe von upload-action hochlädst, werden von der Aktion partialFingerprints für dich erstellt, wenn sie nicht in der SARIF-Datei enthalten sind. Weitere Informationen findest du unter Bereitstellen von Daten zum Nachverfolgen von ausführungsübergreifenden Warnungen bei der Codeüberprüfung. Hinweis: Code scanning verwendet nur primaryLocationLineHash.
codeFlows[].threadFlows[].locations[]		Array von location-Objekten für ein threadFlow-Objekt, das den Fortschritt eines Programms durch einen Ausführungsthread beschreibt. Ein codeFlow-Objekt beschreibt ein Muster der Codeausführung, das zum Erkennen eines Ergebnisses verwendet wird. Wenn Codeflows bereitgestellt werden, erweitert das code scanning Codeflows auf GitHub für das relevante Ergebnis. Weitere Informationen findest du im Abschnitt zum location-Objekt.
relatedLocations[]		Reihe von Speicherorten, die für dieses Ergebnis relevant sind. Code scanning stellt eine Verknüpfung mit zugehörigen Speicherorten her, wenn sie in die Ergebnismeldung eingebettet sind. Weitere Informationen findest du im Abschnitt zum location-Objekt.

location-Objekt

Speicherort in einem Programmierartefakt (z. B. eine Datei im Repository oder eine während eines Builds generierte Datei).

Name	Erforderlich	BESCHREIBUNG
location.id		Eindeutiger Bezeichner, der diesen Speicherort von allen anderen Speicherorten innerhalb eines einzelnen Ergebnisobjekts unterscheidet. Zulässiger Bereich für diese Eigenschaft: 0 bis 2^63 – 1.
location.physicalLocation		Identifiziert das Artefakt und den Bereich. Weitere Informationen findest du unter physicalLocation.
location.message.text		Meldung, die für den Speicherort relevant ist.

physicalLocation-Objekt

Name	Erforderlich	BESCHREIBUNG
artifactLocation.uri		URI, der den Speicherort eines Artefaktes angibt (in der Regel eine Datei im Repository oder eine während eines Builds generierte Datei). Für optimale Ergebnisse empfehlen wir, einen relativen Pfad zum Stamm des zu analysierenden GitHub-Repositorys anzugeben. Beispiel: src/main.js. Weitere Informationen zu Artefakt-URIs findest du unter Angeben des Stamms für Quelldateien.
region.startLine		Zeilennummer des ersten Zeichens im Bereich.
region.startColumn		Spaltennummer des ersten Zeichens im Bereich.
region.endLine		Zeilennummer des letzten Zeichens im Bereich.
region.endColumn		Spaltennummer des Zeichens nach dem Ende des Bereichs.

runAutomationDetails-Objekt

Das runAutomationDetails-Objekt enthält Informationen, die die Identität einer Ausführung angeben.

Name	Erforderlich	BESCHREIBUNG
id		Zeichenfolge, die die Kategorie der Analyse und die Ausführungs-ID identifiziert. Verwende sie, wenn du mehrere SARIF-Dateien für dasselbe Tool und denselben Commit hochladen möchtest, dabei aber verschiedene Sprachen oder Teile des Codes verwendest.

Die Verwendung des runAutomationDetails-Objekts ist optional.

Das id-Feld kann eine Analysekategorie und eine Ausführungs-ID enthalten. Der Teil mit der Ausführungs-ID des id-Felds wird nicht verwendet, aber gespeichert.

Verwende die Kategorie, um zwischen mehreren Analysen für dasselbe Tool oder denselben Commit zu unterscheiden, die jedoch für verschiedene Sprachen oder Teile des Codes ausgeführt werden. Verwende die Ausführungs-ID, um die spezifische Ausführung der Analyse zu identifizieren (z. B. das Datum, an dem die Analyse ausgeführt wurde).

Die id wird als category/run-id interpretiert. Wenn die id keinen Schrägstrich (/) enthält, entspricht die gesamte Zeichenfolge der run_id und category ist leer. Andernfalls entspricht category dem Inhalt der Zeichenfolge bis zum letzten Schrägstrich und run_id dem danach folgenden Inhalt.

id	category	run_id
my-analysis/tool1/2022-01-02	my-analysis/tool1	02.01.2022
my-analysis/tool1/	my-analysis/tool1	Keine
my-analysis for tool1	Keine	my-analysis for tool1

• Die Ausführung mit der id „my-analysis/tool1/2021-02-01“ gehört zur Kategorie „my-analysis/tool1“.
• Die Ausführung mit der id „my-analysis/tool1/“ gehört zur Kategorie „my-analysis/tool1“, wird jedoch nicht von anderen Ausführungen in dieser Kategorie unterschieden.
• Die Ausführung mit der id „my-analysis for tool1“ hat einen eindeutigen Bezeichner, es kann jedoch nicht abgeleitet werden, dass sie zu einer beliebigen Kategorie gehört.

Weitere Informationen zum runAutomationDetails-Objekt und dem id-Feld findest du im Abschnitt zum runAutomationDetails-Objekt in der OASIS-Dokumentation.

Beachte, dass der Rest der unterstützten Felder ignoriert wird.

SARIF-Ausgabedateibeispiele

Diese SARIF-Ausgabedateibeispiele umfassen unterstützte Eigenschaften und Beispielwerte.

Beispiel für minimal erforderliche Eigenschaften

Diese SARIF-Ausgabedatei umfasst Beispielwerte, um zu veranschaulichen, welche Eigenschaften mindestens erforderlich sind, damit die code scanning-Ergebnisse wie erwartet funktionieren. Wenn du Eigenschaften entfernst, Werte auslässt oder eine leere Zeichenfolge verwendest, werden diese Daten nicht ordnungsgemäß angezeigt oder mit GitHub synchronisiert.

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Tool Name",
          "rules": [
            {
              "id": "R01"
                      ...
              "properties" : {
                 "id" : "java/unsafe-deserialization",
                 "kind" : "path-problem",
                 "name" : "...",
                 "problem.severity" : "error",
                 "security-severity" : "9.8",
               }
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "R01",
          "message": {
            "text": "Result text. This result does not have a rule associated."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "fileURI"
                },
                "region": {
                  "startLine": 2,
                  "startColumn": 7,
                  "endColumn": 10
                }
              }
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "39fa2ee980eb94b0:1"
          }
        }
      ]
    }
  ]
}

Anleitung für relative URIs für SARIF-Producer

Diese SARIF-Ausgabedatei enthält Beispielwerte für das Feld originalUriBaseIds und gibt die mindestens erforderlichen Eigenschaften an, die ein SARIF-Producer zur Verwendung von relativen URI-Verweisen aufweisen muss.

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Tool Name",
          "rules": [
            {
              "id": "R01"
                      ...
              "properties" : {
                 "id" : "java/unsafe-deserialization",
                 "kind" : "path-problem",
                 "name" : "...",
                 "problem.severity" : "error",
                 "security-severity" : "9.8",
               }
            }
          ]
        }
      },
      "originalUriBaseIds": {
        "PROJECTROOT": {
         "uri": "file:///C:/Users/Mary/code/TheProject/",
           "description": {
             "text": "The root directory for all project files."
           }
        },
         "%SRCROOT%": {
           "uri": "src/",
           "uriBaseId": "PROJECTROOT",
           "description": {
             "text": "The root of the source tree."
           }
         }
      },
      "results": [
        {
          "ruleId": "R01",
          "message": {
            "text": "Result text. This result does not have a rule associated."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "fileURI",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 2,
                  "startColumn": 7,
                  "endColumn": 10
                }
              }
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "39fa2ee980eb94b0:1"
          }
        }
      ]
    }
  ]
}

Beispiel mit allen unterstützten SARIF-Eigenschaften

Diese SARIF-Ausgabedatei umfasst Beispielwerte, um alle unterstützten SARIF-Eigenschaften für das code scanning zu veranschaulichen.

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Tool Name",
          "semanticVersion": "2.0.0",
          "rules": [
            {
              "id": "3f292041e51d22005ce48f39df3585d44ce1b0ad",
              "name": "js/unused-local-variable",
              "shortDescription": {
                "text": "Unused variable, import, function or class"
              },
              "fullDescription": {
                "text": "Unused variables, imports, functions or classes may be a symptom of a bug and should be examined carefully."
              },
              "defaultConfiguration": {
                "level": "note"
              },
              "properties": {
                "tags": [
                  "maintainability"
                ],
                "precision": "very-high"
              }
            },
            {
              "id": "d5b664aefd5ca4b21b52fdc1d744d7d6ab6886d0",
              "name": "js/inconsistent-use-of-new",
              "shortDescription": {
                "text": "Inconsistent use of 'new'"
              },
              "fullDescription": {
                "text": "If a function is intended to be a constructor, it should always be invoked with 'new'. Otherwise, it should always be invoked as a normal function, that is, without 'new'."
              },
              "properties": {
                "tags": [
                  "reliability",
                  "correctness",
                  "language-features"
                ],
                "precision": "very-high"
              }
            },
            {
              "id": "R01"
            }
          ]
        }
      },
      "automationDetails": {
        "id": "my-category/"
      },
      "results": [
        {
          "ruleId": "3f292041e51d22005ce48f39df3585d44ce1b0ad",
          "ruleIndex": 0,
          "message": {
            "text": "Unused variable foo."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "main.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 2,
                  "startColumn": 7,
                  "endColumn": 10
                }
              }
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "39fa2ee980eb94b0:1",
            "primaryLocationStartColumnFingerprint": "4"
          }
        },
        {
          "ruleId": "d5b664aefd5ca4b21b52fdc1d744d7d6ab6886d0",
          "ruleIndex": 1,
          "message": {
            "text": "Function resolvingPromise is sometimes invoked as a constructor (for example [here](1)), and sometimes as a normal function (for example [here](2))."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/promises.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 2
                }
              }
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "5061c3315a741b7d:1",
            "primaryLocationStartColumnFingerprint": "7"
          },
          "relatedLocations": [
            {
              "id": 1,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/ParseObject.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 2281,
                  "startColumn": 33,
                  "endColumn": 55
                }
              },
              "message": {
                "text": "here"
              }
            },
            {
              "id": 2,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/LiveQueryClient.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 166
                }
              },
              "message": {
                "text": "here"
              }
            }
          ]
        },
        {
          "ruleId": "R01",
          "message": {
            "text": "Specifying both [ruleIndex](1) and [ruleID](2) might lead to inconsistencies."
          },
          "level": "error",
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "full.sarif",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 54,
                  "startColumn": 10,
                  "endLine": 55,
                  "endColumn": 25
                }
              }
            }
          ],
          "relatedLocations": [
            {
              "id": 1,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "full.sarif"
                },
                "region": {
                  "startLine": 81,
                  "startColumn": 10,
                  "endColumn": 18
                }
              },
              "message": {
                "text": "here"
              }
            },
            {
              "id": 2,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "full.sarif"
                },
                "region": {
                  "startLine": 82,
                  "startColumn": 10,
                  "endColumn": 21
                }
              },
              "message": {
                "text": "here"
              }
            }
          ],
          "codeFlows": [
            {
              "threadFlows": [
                {
                  "locations": [
                    {
                      "location": {
                        "physicalLocation": {
                          "region": {
                            "startLine": 11,
                            "endLine": 29,
                            "startColumn": 10,
                            "endColumn": 18
                          },
                          "artifactLocation": {
                            "uriBaseId": "%SRCROOT%",
                            "uri": "full.sarif"
                          }
                        },
                        "message": {
                          "text": "Rule has index 0"
                        }
                      }
                    },
                    {
                      "location": {
                        "physicalLocation": {
                          "region": {
                            "endColumn": 47,
                            "startColumn": 12,
                            "startLine": 12
                          },
                          "artifactLocation": {
                            "uriBaseId": "%SRCROOT%",
                            "uri": "full.sarif"
                          }
                        }
                      }
                    }
                  ]
                }
              ]
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "ABC:2"
          }
        }
      ],
      "columnKind": "utf16CodeUnits"
    }
  ]
}