Skip to main content

SARIF-Ausgabe der CodeQL CLI

Du kannst SARIF aus der CodeQL CLI ausgeben und statische Analyseergebnisse mit anderen Systemen teilen.

Wer kann dieses Feature verwenden?

GitHub CodeQL wird nach der Installation auf Benutzerbasis lizenziert. Du kannst CodeQL nur für bestimmte Aufgaben unter den Lizenzeinschränkungen verwenden. Weitere Informationen findest du unter Informationen zur CodeQL-CLI.

Wenn du über eine GitHub Advanced Security-Lizenz verfügst, kannst du CodeQL für eine automatisierte Analyse sowie für Continuous Integration und Continuous Delivery verwenden. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

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-VersionFormattypÄnderungen
2.0.0sarifv2.1.0Erste 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-EigenschaftennameImmer generiert?Hinweise
$schemaStellt einen Link zum SARIF-Schema bereit
versionDie SARIF-Version, die zum Generieren der Ausgabe verwendet wurde
runsEin Array, das ein einzelnes Ausführungsobjekt für eine Sprache enthält

run-Objekt

JSON-EigenschaftennameImmer generiert?Hinweise
toolKeine
artifactsEin Array, das mindestens ein Artefaktobjekt für jede Datei enthält, auf die in einem Ergebnis verwiesen wird
resultsKeine
newLineSequencesKeine
columnKindKeine
propertiesDas Eigenschaftenwörterbuch enthält den semmle.formatSpecifier, der den an die CodeQL CLI übergebenen Formatbezeichner identifiziert

tool-Objekt

JSON-EigenschaftennameImmer generiert?Hinweise
driverKeine

toolComponent-Objekt

JSON-EigenschaftennameImmer generiert?Hinweise
nameAuf „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.
organizationAuf „GitHub“ festgelegt
versionAuf die CodeQL-Releaseversion festgelegt, zum Beispiel „2.0.0“
rulesArray 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-EigenschaftennameImmer generiert?Hinweise
idEnthä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.
nameEnthält die in der Abfrage angegebene @id-Eigenschaft. Ein Beispiel findest du in der obigen id-Eigenschaft.
shortDescriptionEnthält die in der Abfrage angegebene @name-Eigenschaft, die die Regel definiert
fullDescriptionEnthält die in der Abfrage angegebene @description-Eigenschaft, die die Regel definiert
defaultConfigurationEin 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-EigenschaftennameImmer generiert?Hinweise
locationEin artifactLocation-Objekt.
indexDer Index des artifact-Objekts.
contentsWenn 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-EigenschaftennameImmer generiert?Hinweise
uriKeine
indexKeine
uriBaseIdWenn 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-EigenschaftennameImmer generiert?Hinweise
ruleIdWeitere Informationen findest du in der Beschreibung der id-Eigenschaft im reportingDescriptor-Objekt (für Regel).
ruleIndexKeine
messageEine 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.
locationsEin Array, das ein einzelnes location-Objekt enthält
partialFingerprintsein 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.
codeFlowsDieses 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.
relatedLocationsDieses 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.
suppressionsWenn 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-EigenschaftennameImmer generiert?Hinweise
physicalLocationKeine
idlocation-Objekte, die im relatedLocations-Array eines result-Objekts angezeigt werden, können die id-Eigenschaft enthalten.
messagelocation-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-EigenschaftennameImmer generiert?Hinweise
artifactLocationKeine
regionWenn die angegebene physicalLocation in einer Textdatei vorhanden ist, z. B. in einer Quellcodedatei, ist die region-Eigenschaft möglicherweise vorhanden.
contextRegionKann 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-EigenschaftennameImmer generiert?Hinweise
startLineKeine
startColumnNicht enthalten, wenn Eigenschaft dem Standardwert 1 entspricht
endLineNicht enthalten, wenn Eigenschaft identisch mit startLine ist
endColumnKeine
snippetKeine

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

JSON-EigenschaftennameImmer generiert?Hinweise
charOffsetWird angegeben, wenn startLine, startColumn, endLine und endColumn nicht aufgefüllt sind
charLengthWird angegeben, wenn startLine, startColumn, endLine und endColumn nicht aufgefüllt sind
snippetKeine

codeFlow-Objekt

JSON-EigenschaftennameImmer generiert?Hinweise
threadFlowsKeine

threadFlow-Objekt

JSON-EigenschaftennameImmer generiert?Hinweise
locationsKeine

threadFlowLocation-Objekt

JSON-EigenschaftennameImmer generiert?Hinweise
locationKeine