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 |