Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

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

Um Ergebnisse aus einem statischen Drittanbieter-Analysetool in deinem Repository auf GitHub anzuzeigen, müssen deine Ergebnisse in einer SARIF-Datei gespeichert sein, die einen bestimmten Teil des JSON-Schemas von SARIF 2.1.0 für code scanning unterstützt. Wenn du die statische Standard-Analyse-Engine von CodeQL verwendest, werden deine Ergebnisse automatisch in deinem Repository auf GitHub angezeigt.

Code scanning ist für alle öffentlichen Repositorys auf GitHub.com verfügbar. Code scanning ist auch für private organisationseigene Repositorys verfügbar, die GitHub Enterprise Cloud nutzen und im Besitz einer Lizenz für GitHub Advanced Security sind. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

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. Das 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 auf 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 analysis workflow oder der CodeQL CLI nutzt, verwenden die code scanning-Ergebnisse automatisch die unterstützte Teilmenge von SARIF 2.1.0. Weitere Informationen findest du unter Konfigurieren der code scanning für ein Repository oder Installieren der CodeQL-CLI in deinem CI-System.

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 Konfigurieren der CodeQL-CLI in deinem CI-System.
  • 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 dies ü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 code scanning-Analyse mit GitHub Actions.
  • 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 weiter unten.

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.

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 Verwalten von code scanning-Warnungen für dein Repository.

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 über den CodeQL analysis workflow, 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 auf 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 Hochladen einer Analyse als SARIF-Daten.

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

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.

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

Für jede mit gzip komprimierte SARIF-Datei unterstützt der SARIF-Upload eine maximale Größe von 10 MB. Uploads, die diesen Grenzwert überschreiten, werden abgelehnt. Wenn deine SARIF-Datei zu groß ist, weil sie zu viele Ergebnisse enthält, solltest du die Konfiguration aktualisieren, um sich auf die Ergebnisse für die wichtigsten Regeln oder Abfragen zu konzentrieren.

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 einen zusätzlichen Grenzwert für die Anzahl angezeigter 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.

SARIF-DatenMaximalwerteZusätzliche Grenzwerte
Ausführungen pro Datei20
Ergebnisse pro Ausführung25,000Es werden nur die ersten 5.000 Ergebnisse (nach Schweregrad priorisiert) berücksichtigt.
Regeln pro Ausführung25,000
Toolerweiterungen pro Ausführung100
Threadfluss-Speicherorte pro Ergebnis10.000Es werden nur die ersten 1.000 Threadfluss-Speicherorte anhand ihrer Priorisierung berücksichtigt.
Speicherorte pro Ergebnis1.000Es werden nur 100 Speicherorte berücksichtigt.
Tags pro Regel20Es werden nur 10 Tags berücksichtigt.

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.

Hinweis: Du musst für jede als erforderlich gekennzeichnete Eigenschaft einen expliziten Wert angeben. Die leere Zeichenfolge wird für erforderliche Eigenschaften nicht unterstützt.

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

sarifLog-Objekt

NameBESCHREIBUNG
$schemaErforderlich. URI des SARIF-JSON-Schemas für Version 2.1.0. Beispiel: https://json.schemastore.org/sarif-2.1.0.json.
versionErforderlich. Das Code scanning unterstützt nur die SARIF-Version 2.1.0.
runs[]Erforderlich. 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

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

NameBESCHREIBUNG
tool.driverErforderlich. Ein toolComponent-Objekt, das das Analysetool beschreibt. Weitere Informationen findest du im Abschnitt zum toolComponent-Objekt.
tool.extensions[]Optional. 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.uriOptional. 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[]Erforderlich. Ergebnisse des Analysetools. Das Code scanning zeigt die Ergebnisse auf GitHub an. Weitere Informationen findest du im Abschnitt zum result-Objekt.

toolComponent-Objekt

NameBESCHREIBUNG
nameErforderlich. Name des Analysetools. Das Code scanning zeigt den Namen auf GitHub an, damit du die Ergebnisse nach Tool filtern kannst.
versionOptional. Version des Analysetools. Das 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.
semanticVersionOptional. Version des Analysetools, angegeben durch das Format für die semantische Versionierung 2.0. Das 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[]Erforderlich. 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.

NameBESCHREIBUNG
idErforderlich. 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.
nameOptional. Der Name der Regel. Das Code scanning zeigt den Namen auf GitHub an, damit die Ergebnisse nach Tool gefiltert werden können.
shortDescription.textErforderlich. Präzise Beschreibung der Regel. Das Code scanning zeigt die kurze Beschreibung auf GitHub neben den zugeordneten Ergebnissen an.
fullDescription.textErforderlich. Eine Beschreibung der Regel. Das Code scanning zeigt die vollständige Beschreibung auf GitHub neben den zugeordneten Ergebnissen an. Die maximale Zeichenanzahl ist auf 1000 beschränkt.
defaultConfiguration.levelOptional. Standardschweregrad der Regel. Das Code scanning verwendet Schweregrade, damit du verstehst, wie wichtig das Ergebnis für eine bestimmte Regel ist. Dieser Wert kann durch das level-Attribut im result-Objekt überschrieben werden. Weitere Informationen findest du im Abschnitt zum result-Objekt. Standardwert: warning.
help.textErforderlich. Dokumentation für die Regel mithilfe des Textformats. Das Code scanning zeigt diese Hilfedokumentation neben den zugeordneten Ergebnissen an.
help.markdownEmpfohlen. Dokumentation für die Regel mithilfe des Markdown-Formats. Das 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[]Optional. Ein Array der Zeichenfolgen. Das Code scanning verwendet tags, damit du Ergebnisse auf GitHub filtern kannst. Beispielsweise kannst du nach allen Ergebnissen filtern, die das Tag security umfassen.
properties.precisionEmpfohlen. 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. Das Code scanning ordnet Ergebnisse nach Genauigkeit auf GitHub an, sodass die Ergebnisse mit dem höchsten level und dem höchsten precision-Wert zuerst angezeigt werden. Dies kann very-high, high, medium oder low entsprechen.
properties.problem.severityEmpfohlen. Zeichenfolge, die den Schweregrad aller Warnungen angibt, die von einer nicht sicherheitsrelevanten 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-severityEmpfohlen. Zeichenfolge, die eine Bewertung darstellt, die den Schweregrad zwischen 0.0 und 10.0 für Sicherheitsabfragen angibt (@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. Das Code scanning übersetzt numerische Bewertungen wie folgt: über 9.0 entspricht critical, 7.0 bis 8.9 ergibt high, 4.0 bis 6.9 hat medium die Bewertung zur Folge und 3.9 oder weniger entspricht low.

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 Überprüfen deiner SARIF-Datei.

NameBESCHREIBUNG
ruleIdOptional. Eindeutiger Bezeichner der Regel (reportingDescriptor.id). Weitere Informationen findest du im Abschnitt zum reportingDescriptor-Objekt. Das Code scanning verwendet den Regelbezeichner, damit du Ergebnisse nach Regel auf GitHub filtern kannst.
ruleIndexOptional. 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.
ruleOptional. Verweis, der zum Suchen der Regel (Berichterstellungsdeskriptor) für dieses Ergebnis verwendet wird. Weitere Informationen findest du im Abschnitt zum reportingDescriptor-Objekt.
levelOptional. Schweregrad des Ergebnisses. Diese Ebene überschreibt den Standardschweregrad, der von der Regel definiert wird. Das Code scanning verwendet die Ebene zum Filtern der Ergebnisse nach Schweregrad auf GitHub.
message.textErforderlich. Meldung, in der das Ergebnis beschrieben wird. Das 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[]Erforderlich. 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. Das 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.
partialFingerprintsErforderlich. Reihe von Zeichenfolgen, die zum Nachverfolgen der eindeutigen Identität des Ergebnisses verwendet werden. Das Code scanning verwendet partialFingerprints, um genau zu identifizieren, welche commit- und branchübergreifenden Ergebnisse identisch sind. Das Code scanning versucht partialFingerprints zu verwenden, wenn diese vorhanden sind. 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: Das Code scanning verwendet nur primaryLocationLineHash.
codeFlows[].threadFlows[].locations[]Optional. 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. Das Code scanning stellt eine Verknüpfung mit zugehörigen Speicherorten her, wenn sie in die Ergebnismeldung eingebettet werden. 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).

NameBESCHREIBUNG
location.idOptional. 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.physicalLocationErforderlich. Identifiziert das Artefakt und den Bereich. Weitere Informationen findest du unter physicalLocation.
location.message.textOptional. Meldung, die für den Speicherort relevant ist.

physicalLocation-Objekt

NameBESCHREIBUNG
artifactLocation.uriErforderlich. 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.startLineErforderlich. Zeilennummer des ersten Zeichens im Bereich.
region.startColumnErforderlich. Spaltennummer des ersten Zeichens im Bereich.
region.endLineErforderlich. Zeilennummer des letzten Zeichens im Bereich.
region.endColumnErforderlich. Spaltennummer des Zeichens nach dem Ende des Bereichs.

runAutomationDetails-Objekt

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

Hinweis: runAutomationDetails ist ein SARIF v2.1.0-Objekt. Wenn du die CodeQL CLI verwendest, kannst du die zu verwendende SARIF-Version angeben. Das entsprechende Objekt für runAutomationDetails ist <run>.automationId fpr SARIF v1 und <run>.automationLogicalId für SARIF v2.

NameBESCHREIBUNG
idOptional. 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.

idcategoryrun_id
my-analysis/tool1/2021-02-01my-analysis/tool12021-02-01
my-analysis/tool1/my-analysis/tool1keine run-id
my-analysis for tool1Keine Kategoriemy-analysis for tool1
  • Die Ausführung mit der id „my-analysis/tool1/2021-02-01“ gehört zur Kategorie „my-analysis/tool1“. Vermutlich ist dies die Ausführung vom 2. Februar 2021.
  • 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"
          }
        }
      ]
    }
  ]
}

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"
    }
  ]
}