SARIF-Ausgabe der CodeQL CLI

Informationen zur SARIF-Ausgabe

SARIF wurde entwickelt, um die Ausgabe einer breiten Palette statischer Analysetools darzustellen, und es gibt viele Features in der SARIF-Spezifikation, die als „optional“ betrachtet werden. In diesem Dokument wird die Ausgabe beschrieben, die bei Verwendung des Formattyps sarifv2.1.0 erzeugt wird, der der SARIF v2.1.0.csd1-Spezifikation entspricht. Weitere Informationen zur Auswahl eines Dateiformats für deine Analyseergebnisse findest du unter database analyze.

SARIF-Spezifikation und -Schema

Dieser Artikel sollte zusammen mit der detaillierten SARIF-Spezifikation gelesen werden. Weitere Informationen zur Spezifikation und zum SARIF-Schema findest du in der SARIF-Spezifikationsdokumentation.

Ändern von Notizen

Änderungen zwischen Versionen

CodeQL-Version	Formattyp	Änderungen
2.0.0	sarifv2.1.0	Erste Version dieses Formats

Zukünftige Änderungen an der Ausgabe

Die Ausgabe, die für einen bestimmten Formattyp (z. B. sarifv2.1.0) erzeugt wird, kann sich in zukünftigen CodeQL-Releases ändern. Unser Ziel ist es, die Abwärtskompatibilität mit Consumern des generierten SARIF-Formats aufrechtzuerhalten, indem Folgendes sichergestellt wird:

• Felder, die als „immer generiert“ gekennzeichnet sind, werden nie entfernt.

• Bei Feldern, die als „nicht immer generiert“ gekennzeichnet sind, können sich die Umstände, unter denen die Felder generiert werden, ändern. Consumer der SARIF-Ausgabe von CodeQL sollten gegenüber dem Vorhandensein oder Fehlen dieser Felder robust sein.

Neue Ausgabefelder können in zukünftigen Versionen unter demselben Formattyp hinzugefügt werden. Diese sollen die Abwärtskompatibilität nicht unterbrechen, und Consumer sollten gegenüber neu hinzugefügter Felder robust sein.

Neue Formatargumenttypen können in zukünftigen Versionen von CodeQL hinzugefügt werden, z. B. zur Unterstützung neuer Versionen von SARIF. Diese haben keine Garantie für eine Abwärtskompatibilität, es sei denn, dies ist explizit dokumentiert.

Generierte SARIF-Objekte

Hier werden die einzelnen SARIF-Komponenten, die generiert werden können, sowie alle spezifischen Umstände detailliert beschrieben. Es werden alle Eigenschaften ausgelassen, die nie generiert werden.

sarifLog-Objekt

JSON-Eigenschaftenname	Immer generiert?	Hinweise
$schema		Stellt einen Link zum SARIF-Schema bereit
version		Die SARIF-Version, die zum Generieren der Ausgabe verwendet wurde
runs		Ein Array, das ein einzelnes Ausführungsobjekt für eine Sprache enthält

run-Objekt

JSON-Eigenschaftenname	Immer generiert?	Hinweise
tool		Keine
artifacts		Ein Array, das mindestens ein Artefaktobjekt für jede Datei enthält, auf die in einem Ergebnis verwiesen wird
results		Keine
newLineSequences		Keine
columnKind		Keine
properties		Das Eigenschaftenwörterbuch enthält den semmle.formatSpecifier, der den an die CodeQL CLI übergebenen Formatbezeichner identifiziert

tool-Objekt

JSON-Eigenschaftenname	Immer generiert?	Hinweise
driver		Keine

toolComponent-Objekt

JSON-Eigenschaftenname	Immer generiert?	Hinweise
name		Auf „Befehlszeilentoolkette von CodeQL“ für die Ausgabe aus den CodeQL CLI-Tools festgelegt. Hinweis: Wenn die Ausgabe mit einem anderen Tool generiert wurde, wird ein anderer name gemeldet, und das Format sieht möglicherweise anders aus wie hier beschrieben.
organization		Auf „GitHub“ festgelegt
version		Auf die CodeQL-Releaseversion festgelegt, zum Beispiel „2.0.0“
rules		Array von reportingDescriptor-Objekten, die Regeln darstellen. Dieses Array enthält mindestens alle Regeln, die während dieser Analyse ausgeführt wurden, enthält aber möglicherweise auch Regeln, die verfügbar waren, aber nicht ausgeführt werden. Weitere Informationen zum Aktivieren von Abfragen findest du unter defaultConfiguration.

reportingDescriptor-Objekt (für Regel)

reportingDescriptor-Objekte können in der SARIF-Spezifikation an mehreren Stellen verwendet werden. Wenn ein reportingDescriptor im Regelarray eines toolComponent-Objekts enthalten ist, verfügt es über die folgenden Eigenschaften.

JSON-Eigenschaftenname	Immer generiert?	Hinweise
id		Enthält die in der Abfrage angegebene Eigenschaft @id, die eine Regel definiert, die normalerweise das Format language/rule-name aufweist (z. B. cpp/unsafe-format-string). Wenn deine Organisation die @opaqueid-Eigenschaft in der Abfrage definiert, wird sie stattdessen verwendet.
name		Enthält die in der Abfrage angegebene @id-Eigenschaft. Ein Beispiel findest du in der obigen id-Eigenschaft.
shortDescription		Enthält die in der Abfrage angegebene @name-Eigenschaft, die die Regel definiert
fullDescription		Enthält die in der Abfrage angegebene @description-Eigenschaft, die die Regel definiert
defaultConfiguration		Ein reportingConfiguration-Objekt mit aktivierter Eigenschaft, die auf TRUE oder FALSE festgelegt ist, und einer Ebeneneigenschaft, die gemäß der in der Abfrage angegebenen @severity-Eigenschaft festgelegt ist, die die Regel definiert. Es wird nicht angegeben, wenn die @severity-Eigenschaft nicht angegeben wurde.

artifact-Objekt

JSON-Eigenschaftenname	Immer generiert?	Hinweise
location		Ein artifactLocation-Objekt.
index		Der Index des artifact-Objekts.
contents		Wenn Ergebnisse mithilfe des --sarif-add-file-contents-Flags generiert werden und der Quellcode zum Zeitpunkt der Generierung der SARIF-Datei verfügbar ist, wird die contents-Eigenschaft mit einem artifactContent-Objekt aufgefüllt, wobei die text-Eigenschaft festgelegt ist.

artifactLocation-Objekt

JSON-Eigenschaftenname	Immer generiert?	Hinweise
uri		Keine
index		Keine
uriBaseId		Wenn die Datei relativ zu einem bekannten abstrakten Speicherort ist, z. B. dem Stammquellenspeicherort auf dem Analysecomputer, wird dies festgelegt.

result-Objekt

Die Zusammensetzung der Ergebnisse richtet sich nach den Optionen, die für CodeQL angegeben werden. Standardmäßig werden die Ergebnisse nach eindeutiger Nachrichtenformatzeichenfolge und primärem Speicherort gruppiert. Daher werden zwei Ergebnisse, die am gleichen Speicherort mit der gleichen zugrunde liegenden Nachricht auftreten, als einzelnes Ergebnis in der Ausgabe angezeigt. Dieses Verhalten kann mithilfe des Flags --ungroup-resultsdeaktiviert werden. In diesem Fall werden keine Ergebnisse gruppiert.

JSON-Eigenschaftenname	Immer generiert?	Hinweise
ruleId		Weitere Informationen findest du in der Beschreibung der id-Eigenschaft im reportingDescriptor-Objekt (für Regel).
ruleIndex		Keine
message		Eine Meldung, die die Probleme beschreibt, die an diesem Speicherort auftreten. Diese Meldung kann eine SARIF-Nachricht mit Platzhalter sein, die Links enthält, die auf Speicherorte in der relatedLocations-Eigenschaft verweisen.
locations		Ein Array, das ein einzelnes location-Objekt enthält
partialFingerprints		ein Wörterbuch aus benannten Fingerabdrucktypen für den Fingerabdruck. Es enthält mindestens einen Wert für primaryLocationLineHash, womit ein Fingerabdruck basierend auf dem Kontext des primären Speicherorts bereitgestellt wird.
codeFlows		Dieses Array kann mit einem oder mehreren codeFlow-Objekten aufgefüllt werden, wenn die Abfrage, die die Regel für dieses Ergebnis definiert, von @kind path-problemist.
relatedLocations		Dieses Array wird aufgefüllt, wenn die Abfrage, die die Regel für dieses Ergebnis definiert, eine Nachricht mit Platzhalteroptionen enthält. Jeder eindeutige Standort ist einmal enthalten.
suppressions		Wenn das Ergebnis unterdrückt wird, enthält dieses ein einzelnes suppression-Objekt, wobei die @kind-Eigenschaft auf IN_SOURCE festgelegt ist. Wenn dieses Ergebnis nicht unterdrückt wird, aber mindestens ein Ergebnis eine Unterdrückung aufweist, wird dieses auf ein leeres Array festgelegt, andernfalls wird es nicht festgelegt.

location-Objekt

JSON-Eigenschaftenname	Immer generiert?	Hinweise
physicalLocation		Keine
id		location-Objekte, die im relatedLocations-Array eines result-Objekts angezeigt werden, können die id-Eigenschaft enthalten.
message		location-Objekte können die message-Eigenschaft enthalten, wenn: – sie im relatedLocations-Array eines result-Objekts angezeigt werden und die message-Eigenschaft enthalten können. – sie in der threadFlowLocation.location-Eigenschaft angezeigt werden.

physicalLocation-Objekt

JSON-Eigenschaftenname	Immer generiert?	Hinweise
artifactLocation		Keine
region		Wenn die angegebene physicalLocation in einer Textdatei vorhanden ist, z. B. in einer Quellcodedatei, ist die region-Eigenschaft möglicherweise vorhanden.
contextRegion		Kann vorhanden sein, wenn dieser Standort über einen zugeordnetes snippet verfügt

region-Objekt

Es gibt zwei region-Objekttypen, die von CodeQL erzeugt werden:

• Linien-/Spaltenoffsetbereiche

• Zeichenoffset- und Längenbereiche

Jede Region, die von CodeQL erzeugt wird, kann in beiden Formaten angegeben werden, und Consumer sollten beide Typen robust verarbeiten.

Für Linien-/Spaltenoffsetbereiche werden die folgenden Eigenschaften festgelegt:

JSON-Eigenschaftenname	Immer generiert?	Hinweise
startLine		Keine
startColumn		Nicht enthalten, wenn Eigenschaft dem Standardwert 1 entspricht
endLine		Nicht enthalten, wenn Eigenschaft identisch mit startLine ist
endColumn		Keine
snippet		Keine

Für Zeichenoffset- und Längenbereiche werden die folgenden Eigenschaften festgelegt:

JSON-Eigenschaftenname	Immer generiert?	Hinweise
charOffset		Wird angegeben, wenn startLine, startColumn, endLine und endColumn nicht aufgefüllt sind
charLength		Wird angegeben, wenn startLine, startColumn, endLine und endColumn nicht aufgefüllt sind
snippet		Keine

codeFlow-Objekt

JSON-Eigenschaftenname	Immer generiert?	Hinweise
threadFlows		Keine

threadFlow-Objekt

JSON-Eigenschaftenname	Immer generiert?	Hinweise
locations		Keine

threadFlowLocation-Objekt

JSON-Eigenschaftenname	Immer generiert?	Hinweise
location		Keine