Sortie SARIF dans l’interface CLI de CodeQL

À propos de la sortie SARIF

Le format SARIF est conçu pour représenter la sortie d’un large éventail d’outils d’analyse statique et il existe de nombreuses fonctionnalités dans la spécification SARIF considérées comme « facultatives ». Ce document décrit la sortie produite lors de l’utilisation du type de format sarifv2.1.0, qui correspond à la spécification SARIF v2.1.0.csd1. Pour plus d’informations sur la sélection d’un format de fichier pour vos résultats d’analyse, consultez la commande database analyze dans la documentation de CodeQL.

Spécification et schéma SARIF

Cet article est destiné à être lu de concert avec la spécification SARIF détaillée. Pour plus d’informations sur la spécification et le schéma SARIF, consultez la documentation sur la spécification SARIF.

Notes sur les modifications

Modifications entre les versions

Version de CodeQL	Type de format	Modifications
2.0.0	sarifv2.1.0	Première version de ce format.

Modifications à venir de la sortie

La sortie produite pour un type de format spécifique donné (par exemple, sarifv2.1.0) est susceptible d’être modifiée dans les versions ultérieures de CodeQL. Nous nous efforcerons de maintenir la compatibilité descendante avec les consommateurs de la sortie SARIF générée en veillant à ceci :

• Aucun champ généré marqué comme « Toujours » ne sera supprimé.

• Les circonstances dans lesquelles les champs « facultatifs » seront générés pourront changer. Les consommateurs de la sortie SARIF CodeQL devraient résister à la présence ou à l’absence de ces champs.

De nouveaux champs de sortie pourront être ajoutés dans les versions ultérieures sous le même type de format : ils ne seront pas considérés comme antagonistes à la compatibilité descendante, et les consommateurs devraient résister à la présence de champs nouvellement ajoutés.

De nouveaux types d’arguments de format pourront être ajoutés dans les versions à venir de CodeQL, par exemple pour prendre en charge les nouvelles versions de SARIF. Ces types n’offrent aucune garantie de compatibilité descendante, sauf indication explicite contraire.

Objets SARIF générés

Voici des informations détaillées sur chaque composant SARIF susceptible d’être généré, ainsi que toutes les éventuelles circonstances spécifiques. Nous omettons toutes les propriétés qui ne sont jamais générées.

l'objet sarifLog

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
$schema	Toujours	Fournit un lien vers le schéma SARIF.
version	Toujours	Version du format SARIF utilisé pour générer la sortie.
runs	Toujours	Tableau contenant un objet d’exécution unique, pour un seul langage.

l'objet run

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
tool	Toujours	–
originalUriBaseIds	Toujours	Dictionnaire des uriBaseIds avec les artifactLocations représentant les emplacements d’origine sur la machine d’analyse. Au minimum, ce dictionnaire contient l’uriBaseId %SRCROOT%, qui représente l’emplacement racine sur la machine d’analyse du code source pour le projet analysé. Chaque artifactLocation contient les propriétés uri et description.
artifacts	Toujours	Tableau contenant au moins un objet d’artefact pour chaque fichier référencé dans un résultat.
results	Toujours	–
newLineSequences	Toujours	–
columnKind	Toujours	–
properties	Toujours	Le dictionnaire des propriétés contient le semmle.formatSpecifier, qui identifie le spécificateur de format passé à l’CodeQL CLI.

l'objet tool

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
driver	Toujours	–

l'objet toolComponent

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
name	Toujours	Définissez ce nom sur « Chaîne d’outils en ligne de commande CodeQL » pour une sortie provenant des outils CodeQL CLI. Notez que si la sortie a été générée à l’aide d’un autre outil, une autre propriété name est signalée et le format risque de ne pas être celui décrit ici.
organization	Toujours	Définissez cette propriété sur « GitHub ».
version	Toujours	Définissez cette propriété sur la version de CodeQL, par exemple « 2.0.0 ».
rules	Toujours	Tableau d’objets reportingDescriptor qui représentent des règles. Ce tableau contient au minimum toutes les règles exécutées pendant cette analyse, mais il peut contenir des règles qui étaient disponibles et qui n’ont pas été exécutées. Pour plus d’informations sur l’activation des requêtes, consultez defaultConfiguration.

Objet reportingDescriptor (pour une règle)

Des objets reportingDescriptor peuvent être utilisés à plusieurs endroits dans la spécification SARIF. Quand un reportingDescriptor est inclus dans le tableau de règles d’un objet toolComponent, ses propriétés sont les suivantes.

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
id	Toujours	Contient la propriété @id spécifiée dans la requête qui définit la règle, dont le format est généralement language/rule-name (par exemple cpp/unsafe-format-string). Si votre organisation définit la propriété @opaqueid dans la requête, celle-ci est utilisée à la place.
name	Toujours	Contient la propriété @idspécifiée dans la requête. Pour obtenir un exemple, consultez la propriété id ci-dessus.
shortDescription	Toujours	Contient la propriété @name spécifiée dans la requête qui définit la règle.
fullDescription	Toujours	Contient la propriété @description spécifiée dans la requête qui définit la règle.
defaultConfiguration	Toujours	Objet reportingConfiguration, dont la propriété activée est définie sur true ou false et dont une propriété de niveau est définie en fonction de la propriété @severity spécifiée dans la requête qui définit la règle. Omis si la propriété @severity n’a pas été spécifiée.

l'objet artifact

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
location	Toujours	Objet artifactLocation.
index	Toujours	Index de l'objet artifact.
contents	Au choix	Si les résultats sont générés à l’aide de l’indicateur --sarif-add-file-contents et que le code source est disponible au moment de la génération du fichier SARIF, alors la propriété contents est renseignée avec un objet artifactContent et avec la propriété text définie.

l'objet artifactLocation

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
uri	Toujours	–
index	Toujours	–
uriBaseId	Au choix	Si le fichier est lié à un emplacement abstrait connu, comme l’emplacement source racine sur la machine d’analyse, alors cette propriété est définie.

l'objet result

La composition des résultats dépend des options fournies à CodeQL. Par défaut, les résultats sont regroupés par chaîne de format de message unique et par emplacement principal. Ainsi, deux résultats qui se produisent au même emplacement avec le même message sous-jacent apparaissent sous la forme d’un résultat unique dans la sortie. Ce comportement peut être désactivé à l’aide de l’indicateur --ungroup-results, auquel cas aucun résultat n’est regroupé.

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
ruleId	Toujours	Consultez la description de la propriété id dans l’objet reportingDescriptor (pour la règle).
ruleIndex	Toujours	–
message	Toujours	Message décrivant le ou les problèmes qui se produisent à cet emplacement. Ce message peut être un « message avec espace réservé » au format SARIF, contenant des liens qui font référence à des emplacements dans la propriété relatedLocations.
locations	Toujours	Tableau contenant un objet location unique.
partialFingerprints	Toujours	Il existe un dictionnaire des types d’empreintes digitales nommées. Celui-ci contient, au minimum, une valeur pour primaryLocationLineHash, qui fournit une empreinte digitale selon le contexte de l’emplacement principal.
codeFlows	Au choix	Ce tableau peut être renseigné avec un ou plusieurs objets codeFlow si la requête qui définit la règle pour ce résultat est de @kind path-problem.
relatedLocations	Au choix	Ce tableau est renseigné si la requête qui définit la règle pour ce résultat a un message avec des options d’espace réservé. Chaque emplacement unique est inclus une seule fois.
suppressions	Au choix	Si le résultat est supprimé, alors il contient un seul objet suppression, avec la propriété @kind définie sur IN_SOURCE. Si ce résultat n’est pas supprimé, mais qu’au moins un résultat fait l’objet d’une suppression, alors il est défini sur un tableau vide ; sinon, il n’est pas défini.

l'objet location

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
physicalLocation	Toujours	–
id	Au choix	Les objets location qui apparaissent dans le tableau relatedLocations d’un objet result peuvent contenir la propriété id.
message	Au choix	Les objets location peuvent contenir la propriété message si : – Ils apparaissent dans le tableau relatedLocations d’un objet result pouvant contenir la propriété message. – Ils apparaissent dans la propriété threadFlowLocation.location.

l'objet physicalLocation

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
artifactLocation	Toujours	–
region	Au choix	Si le physicalLocation donné existe dans un fichier texte, comme un fichier de code source, alors la propriété region est peut-être présente.
contextRegion	Au choix	Éventuellement présente si cet emplacement a un snippet associé.

l'objet region

Il existe deux types d’objets region produits par CodeQL :

• Régions de décalage de ligne/colonne

• Régions de longueur et de décalage de caractères

Toute région produite par CodeQL peut être spécifiée dans l’un ou l’autre format, et les consommateurs doivent gérer l’un ou l’autre type de manière robuste.

Pour les régions de décalage de ligne/colonne, les propriétés suivantes sont définies :

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
startLine	Toujours	–
startColumn	Au choix	Non incluse si elle est égale à la valeur par défaut de 1.
endLine	Au choix	Non incluse si identique à startLine.
endColumn	Toujours	–
snippet	Au choix	–

Pour les régions de longueur et de décalage de caractères, les propriétés suivantes sont définies :

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
charOffset	Au choix	Fournie si les propriétés startLine, startColumn, endLine et endColumn ne sont pas renseignées.
charLength	Au choix	Fournie si les propriétés startLine, startColumn, endLine et endColumn ne sont pas renseignées.
snippet	Au choix	–

l'objet codeFlow

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
threadFlows	Toujours	–

l'objet threadFlow

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
locations	Toujours	–

l'objet threadFlowLocation

Nom de la propriété JSON	Quand cette propriété est-elle générée ?	Notes
location	Toujours	–