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 zum Auswählen eines Dateiformats für deine Analyseergebnisse findest du im Befehl database analyze (Datenbank analysieren) in der CodeQL-Dokumentation.

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:

• Kein Feld, das als „Always“ gekennzeichnet ist, wird entfernt.

• Die Umstände, unter denen „optionale“ Felder generiert werden, können sich ä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	Wann generiert?	Notizen
$schema	Immer	Stellt einen Link zum SARIF-Schema bereit
version	Immer	Die SARIF-Version, die zum Generieren der Ausgabe verwendet wurde
runs	Immer	Ein Array, das ein einzelnes Ausführungsobjekt für eine Sprache enthält

run-Objekt

JSON-Eigenschaftenname	Wann generiert?	Notizen
tool	Always	–
originalUriBaseIds	Immer	Ein Wörterbuch von uriBaseIds bis artifactLocations, das die ursprünglichen Speicherorte auf dem Analysecomputer darstellt. Dieses enthält mindestens die %SRCROOT%``uriBaseId, die den Stammspeicherort auf dem Analysecomputer des Quellcodes für das analysierte Projekt darstellt. Jede artifactLocation enthält die Eigenschaften uri und description.
artifacts	Always	Ein Array, das mindestens ein Artefaktobjekt für jede Datei enthält, auf die in einem Ergebnis verwiesen wird
results	Always	–
newLineSequences	Always	–
columnKind	Always	–
properties	Always	Das Eigenschaftenwörterbuch enthält den semmle.formatSpecifier, der den an die CodeQL CLI übergebenen Formatbezeichner identifiziert

tool-Objekt

JSON-Eigenschaftenname	Wann generiert?	Notizen
driver	Always	–

toolComponent-Objekt

JSON-Eigenschaftenname	Wann generiert?	Notizen
name	Immer	Festgelegt auf „Befehlszeilentoolkette von CodeQL“ für die Ausgabe aus den CodeQL CLI-Tools. 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	Immer	Auf „GitHub“ festgelegt
version	Immer	Auf die CodeQL-Releaseversion festgelegt, zum Beispiel „2.0.0“
rules	Immer	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	Wann generiert?	Notizen
id	Immer	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	Immer	Enthält die in der Abfrage angegebene @id-Eigenschaft. Ein Beispiel findest du in der obigen id-Eigenschaft.
shortDescription	Immer	Enthält die in der Abfrage angegebene @name-Eigenschaft, die die Regel definiert
fullDescription	Immer	Enthält die in der Abfrage angegebene @description-Eigenschaft, die die Regel definiert
defaultConfiguration	Immer	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	Wann generiert?	Notizen
location	Immer	Ein artifactLocation-Objekt.
index	Immer	Der Index des artifact-Objekts.
contents	Optional	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	Wann generiert?	Notizen
uri	Always	–
index	Always	–
uriBaseId	Optional	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 hängt von den für CodeQL bereitgestellten Optionen ab. 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	Wann generiert?	Notizen
ruleId	Immer	Weitere Informationen findest du in der Beschreibung der id-Eigenschaft im reportingDescriptor-Objekt (für Regel).
ruleIndex	Immer	–
message	Immer	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	Immer	Ein Array, das ein einzelnes location-Objekt enthält
partialFingerprints	Immer	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	Optional	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	Optional	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	Optional	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	Wann generiert?	Notizen
physicalLocation	Always	–
id	Optional	location-Objekte, die im relatedLocations-Array eines result-Objekts angezeigt werden, können die id-Eigenschaft enthalten.
message	Optional	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	Wann generiert?	Notizen
artifactLocation	Always	–
region	Optional	Wenn die angegebene physicalLocation in einer Textdatei vorhanden ist, z. B. in einer Quellcodedatei, ist die region-Eigenschaft möglicherweise vorhanden.
contextRegion	Optional	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	Wann generiert?	Notizen
startLine	Always	–
startColumn	Optional	Nicht enthalten, wenn Eigenschaft dem Standardwert 1 entspricht
endLine	Optional	Nicht enthalten, wenn Eigenschaft identisch mit startLine ist
endColumn	Immer	–
snippet	Optional	–

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

JSON-Eigenschaftenname	Wann generiert?	Notizen
charOffset	Optional	Wird angegeben, wenn startLine, startColumn, endLine und endColumn nicht aufgefüllt sind
charLength	Optional	Wird angegeben, wenn startLine, startColumn, endLine und endColumn nicht aufgefüllt sind
snippet	Optional	–

codeFlow-Objekt

JSON-Eigenschaftenname	Wann generiert?	Notizen
threadFlows	Always	–

threadFlow-Objekt

JSON-Eigenschaftenname	Wann generiert?	Notizen
locations	Always	–

threadFlowLocation-Objekt

JSON-Eigenschaftenname	Wann generiert?	Notizen
location	Always	–