Prise en charge de SARIF pour l’analyse du code

GitHub peut analyser les fichiers SARIF générés par des outils tiers pour afficher des alertes code scanning dans les dépôts. Pour plus d’informations, consultez « À propos des fichiers SARIF pour l’analyse du code ».

Cet article met en évidence les propriétés clés des fichiers SARIF pour vous aider à charger des fichiers SARIF qui répondent aux GitHubexigences et peuvent être convertis en alertes utiles.

Si vous utilisez GitHub Actions avec Workflow d’analyse CodeQL ou CodeQL CLI, les résultats code scanning utiliseront automatiquement le sous-ensemble pris en charge de SARIF 2.1.0.

Données permettant d’empêcher les alertes dupliquées

À chaque fois que les résultats d’une nouvelle analyse du code sont chargés, ils sont traités et les alertes sont ajoutées au référentiel. Pour éviter les alertes en double pour le même problème, code scanning utilise des empreintes digitales pour faire correspondre les résultats entre différentes exécutions afin qu’elles n’apparaissent qu’une seule fois dans la dernière exécution de la branche sélectionnée. Cela permet de faire correspondre les alertes à la ligne de code correcte quand les fichiers sont modifiés. La valeur ruleId d’un résultat doit être la même dans toute l’analyse.

Chemins de fichiers cohérents

Le chemin de fichier doit être cohérent d’une exécution à l’autre pour permettre un calcul d’une empreinte digitale stable. Si les chemins de fichier diffèrent pour le même résultat, chaque fois qu’une nouvelle analyse est créée, l’ancienne est fermée. Il existe alors plusieurs alertes pour le même résultat.

Génération d’empreintes digitales

GitHub utilise la partialFingerprints propriété dans la norme OASIS pour détecter quand deux résultats sont logiquement identiques. Pour plus d’informations, consultez l’entrée partialFingerprints property dans la documentation OASIS.

Les fichiers SARIF créés par le Workflow d’analyse CodeQL, ou à l’aide du CodeQL CLI, incluent des données d’empreinte. Si vous chargez un fichier SARIF à l’aide de l’action upload-sarif et que ces données sont manquantes, GitHub tente de remplir le partialFingerprints champ à partir des fichiers sources. Pour plus d’informations sur le chargement des résultats, consultez Chargement d’un fichier SARIF sur GitHub.

Si vous téléversez un fichier SARIF sans données d’empreinte digitale en utilisant le point de terminaison de l’API /code-scanning/sarifs, les alertes code scanning seront traitées et affichées, mais les utilisateurs peuvent voir des alertes en double. Pour éviter de voir des alertes en double, vous devez calculer les données d’empreinte digitale et renseigner la propriété partialFingerprints avant de charger le fichier SARIF. Le script que l’action upload-sarif utilise peut être un point de départ utile : https://github.com/github/codeql-action/blob/main/src/fingerprints.ts. Pour plus d’informations sur l’API, consultez Points de terminaison d’API REST pour l’analyse de codes.

Règles et résultats

Les fichiers SARIF prennent en charge les règles et les résultats. Les informations stockées dans ces éléments sont similaires, mais ont des buts différents.

Les règles sont un tableau d’objets reportingDescriptor qui sont inclus dans l’objet toolComponent. C’est là que vous stockez les détails des règles exécutées pendant l’analyse. Les informations contenues dans ces objets doivent changer rarement, généralement lorsque vous mettez à jour l’outil.
Les résultats sont stockés sous forme d’une série d’objets result sous results dans l’objet run. Chaque objet result contient les détails d’une alerte dans le codebase. Dans l’objet results, vous pouvez référencer la règle qui a détecté l’alerte.

Lorsque vous comparez les fichiers SARIF générés en analysant différents codebases avec le même outil et les mêmes règles, vous devriez voir des différences dans les résultats des analyses, mais pas dans les règles.

Emplacements des fichiers sources

La spécification de l’emplacement des fichiers sources et des lignes de code garantit que les alertes d’analyse de code sont affichées avec précision dans le fichier contenant le problème identifié, ce qui permet une résolution ciblée du problème.

Cette précision améliore l’efficacité des processus de révision et de résolution du code, en simplifiant les flux de travail de développement et en permettant aux développeurs de résoudre les problèmes directement dans le contexte de leur base de code.

Code scanning affiche également des alertes dans les résultats de vérification des pull requests lorsque toutes les lignes de code identifiées par l’alerte figurent dans le diff de la pull request.

Pour être affichée dans une vérification de demande de tirage, une alerte doit remplir toutes les conditions suivantes :

Toutes les lignes de code identifiées par l’alerte existent dans le différentiel de la demande de tirage, y compris la première ligne de l’alerte.
L’alerte doit exister dans les lignes de code ajoutées ou modifiées dans la demande de tirage, et non dans les lignes qui ont été supprimées.

L’objet physicalLocation d’un fichier SARIF soumis identifie les lignes de code d’une alerte. Pour plus d’informations, consultez l’objet physicalLocation.

Emplacement racine des fichiers sources

Code scanning interprète les résultats signalés avec des chemins d’accès relatifs comme relatifs à la racine du référentiel analysé. Si un résultat contient un URI absolu, l’URI est converti en URI relatif. L’URI relatif peut ensuite être mis en correspondance avec un fichier commité dans le dépôt.

Vous pouvez fournir la racine source pour la conversion de l’URI absolu vers l’URI relatif de l’une des manières suivantes.

checkout_path L’entrée pour l’action github/codeql-action/analyze

          Le paramètre `checkout_uri` du point de terminaison de l’API de chargement SARIF. Pour plus d’informations, consultez « [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data) ».

invocations[0].workingDirectory.uri La propriété dans l’objet run du fichier SARIF

Si vous fournissez une racine source, tout emplacement d’un artefact spécifié à l’aide d’un URI absolu doit utiliser le même schéma d’URI. En cas d’incompatibilité entre le schéma d’URI de la racine source et une ou plusieurs des URI absolus, le chargement est rejeté.

Par exemple, un fichier SARIF est chargé à l’aide de la racine source file:///github/workspace.

# Conversion of absolute URIs to relative URIs for location artifacts

file:///github/workspace/src/main.go -> src/main.go
file:///tmp/go-build/tmp.go          -> file:///tmp/go-build/tmp.go

Le fichier est correctement chargé car les deux URI absolus utilisent le même schéma d’URI que la racine source.

Résolution de lien symbolique

Si l’URI relatif d’un résultat est mis en correspondance avec un fichier défini à l’aide d’un lien symbolique, l’analyse de code ne peut pas afficher le résultat. Vous devez alors résoudre tous les fichiers liés par des liens symboliques et signaler les résultats de ces fichiers à l’aide de l’URI résolu.

Compatibilité des fichiers

Vous pouvez vérifier la compatibilité d’un fichier SARIF avec code scanning en le testant au regard des règles d’ingestion de GitHub. Pour plus d’informations, consultez le validateur SARIF de Microsoft.

Pour chaque fichier SARIF compressé au format gzip, le chargement SARIF prend en charge une taille maximale de 10 Mo. Tous les chargements au-delà de cette limite sont rejetés. Si votre fichier SARIF est trop volumineux parce qu’il contient trop de résultats, vous devez mettre à jour la configuration pour vous concentrer sur les résultats des règles ou requêtes les plus importantes. Pour plus d’informations, consultez « Le fichier de résultats SARIF est trop volumineux ».

Code scanning prend en charge le chargement d’un nombre maximal d’entrées pour les objets de données dans le tableau suivant. Si l’un de ces objets dépasse sa valeur maximale, le fichier SARIF est rejeté. Pour certains objets, il existe également une limite supplémentaire quant au nombre de valeurs qui sont affichées. Dans la mesure du possible, ce sont les valeurs les plus importantes qui sont affichées. Pour tirer le meilleur parti de votre analyse lorsqu’elle inclut des données au-dessus des limites prises en charge, essayez d’optimiser la configuration d’analyse (par exemple, pour l’outil CodeQL , identifier et désactiver les requêtes les plus bruyantes). Pour plus d’informations, consultez « Les résultats SARIF dépassent une ou plusieurs limites ».

Données SARIF	Valeurs maximales	Limites pour la troncation des données
Exécutions par fichier	20	None
Résultats par exécution	25 000	Seuls les 5 000 premiers résultats sont inclus, classés par ordre de gravité.
Règles par exécution	25 000	None
Extensions d’outil par exécution	100	None
Emplacements de flux de thread par résultat	10 000	Seuls les 1 000 principaux emplacements de flux de thread sont inclus, classés par ordre de priorité.
Emplacement par résultat	1 000	Seuls 100 emplacements sont inclus.
Étiquettes par règle	20	Seules 10 étiquettes sont incluses.
Limite d’alerte	1 000 000	Aucun(e)

Pour plus d’informations sur les autres erreurs, consultez Résolution des problèmes de téléchargements SARIF.

Propriétés prises en charge

Si vous utilisez un moteur d’analyse de code autre que CodeQL, vous pouvez passer en revue les propriétés SARIF prises en charge pour optimiser l’affichage GitHubde vos résultats d’analyse.

Remarque

Vous devez fournir une valeur explicite pour toute propriété marquée comme « obligatoire ». La chaîne vide n’est pas prise en charge pour les propriétés obligatoires.

Tout fichier de sortie SARIF 2.1.0 valide peut être téléversé, toutefois, code scanning n’utilisera que les propriétés prises en charge suivantes.

Objet `sarifLog`

Nom	Obligatoire	Description
`$schema`		URI du schéma JSON SARIF pour la version 2.1.0. Par exemple : `https://json.schemastore.org/sarif-2.1.0.json`.
`version`
Code scanning prend uniquement en charge la version `2.1.0`SARIF.
`runs[]`		Un fichier SARIF contient un tableau d’une ou plusieurs exécutions. Chaque exécution représente une seule exécution d’un outil d’analyse. Pour plus d’informations sur un `run`, consultez l’objet `run`.

Objet `run`

Code scanning utilise l’objet run pour filtrer les résultats par outil et fournir des informations sur la source d’un résultat. L’objet run contient l’objet de composant d’outil tool.driver, qui contient des informations sur l’outil qui a généré les résultats. Chaque run ne peut avoir des résultats que pour un seul outil d’analyse.

Nom	Obligatoire	Description
`tool.driver`		Objet `toolComponent` qui décrit l’outil d’analyse. Pour plus d’informations, consultez l’objet `toolComponent`.
`tool.extensions[]`		Tableau d’objets `toolComponent` qui représentent l’ensemble des plug-ins ou extensions utilisés par l’outil pendant l’analyse. Pour plus d’informations, consultez l’objet `toolComponent`.
`invocation.workingDirectory.uri`		Ce champ est utilisé uniquement lorsque `checkout_uri` (API de chargement SARIF uniquement) ou `checkout_path` (GitHub Actions uniquement) ne sont pas fournis. La valeur est utilisée pour convertir les URI absolus utilisés dans les objets `physicalLocation` en URI relatifs. Pour plus d’informations, consultez Spécification de la racine des fichiers sources.
`results[]`		Résultats de l’outil d’analyse.
Code scanning affiche les résultats sur GitHub. Pour plus d’informations, consultez l’objet `result`.

Objet `toolComponent`

Nom	Obligatoire	Description
`name`		Nom de l’outil d’analyse.
Code scanning affiche le nom affiché sur GitHub afin de vous permettre de filtrer les résultats par outil.
`version`		Version de l’outil d’analyse.
Code scanning utilise le numéro de version pour suivre le moment où les résultats ont peut-être changé en raison d’une modification de version de l’outil plutôt qu’une modification du code en cours d’analyse. Si le fichier SARIF inclut le `semanticVersion` champ, `version` n’est pas utilisé par code scanning.
`semanticVersion`		Version de l’outil d’analyse, spécifiée par le format de la Gestion sémantique de version 2.0.
Code scanning utilise le numéro de version pour suivre le moment où les résultats ont peut-être changé en raison d’une modification de version de l’outil plutôt qu’une modification du code en cours d’analyse. Si le fichier SARIF inclut le `semanticVersion` champ, `version` n’est pas utilisé par code scanning. Pour plus d’informations, consultez Semantic Versioning 2.0.0 dans la documentation sur Semantic Versioning.
`rules[]`		Tableau d’objets `reportingDescriptor` qui représentent des règles. L’outil d’analyse utilise des règles pour rechercher les problèmes dans le code en cours d’analyse. Pour plus d’informations, consultez l’objet `reportingDescriptor`.

Objet `reportingDescriptor`

C’est là que vous stockez les détails des règles exécutées pendant l’analyse. Les informations contenues dans ces objets doivent changer rarement, généralement lorsque vous mettez à jour l’outil. Pour plus d’informations, consultez Règles et résultats ci-dessus.

Nom	Obligatoire	Description
`id`		Identificateur unique de la règle.
`id` est référencé dans d’autres parties du fichier SARIF et peut être utilisé par code scanning pour afficher des URL sur GitHub.
`name`		Le nom de la règle.
Code scanning affiche le nom pour autoriser le filtrage des résultats par règle sur GitHub. Limitées à 255 caractères.
`shortDescription.text`		Description concise de la règle.
Code scanning affiche la description courte à GitHub côté des résultats associés. Limitée à 1 024 caractères.
`fullDescription.text`		Description de la règle.
Code scanning affiche la description complète sur GitHub, à côté des résultats associés. Limitée à 1 024 caractères.
`defaultConfiguration.level`		Niveau de gravité par défaut de la règle.
Code scanning utilise des niveaux de gravité pour vous aider à comprendre comment le résultat est critique pour une règle donnée. Par défaut, la valeur `defaultConfiguration.level` est définie sur `warning`. Vous pouvez toutefois remplacer le niveau par défaut d’une règle en définissant l’attribut `level` dans l’objet `result` associé au résultat. Pour plus d’informations, reportez-vous à la documentation sur l’objet `result`. Les valeurs valides pour `defaultConfiguration.level` sont : `note`, `warning` et `error`.
`help.text`		Documentation de la règle au format texte.
Code scanning affiche cette documentation d’aide en regard des résultats associés.
`help.markdown`		(Recommandé) Documentation de la règle au format Markdown.
Code scanning affiche cette documentation d’aide en regard des résultats associés. Quand la documentation `help.markdown` est disponible, elle s’affiche à la place de la documentation `help.text`.
`properties.tags[]`		Tableau de chaînes.
Code scanning utilise `tags` pour vous permettre de filtrer les résultats sur GitHub. Par exemple, il est possible de filtrer tous les résultats qui ont l’étiquette `security`.
`properties.precision`		(Recommandé) Une chaîne qui indique la fréquence à laquelle les résultats indiqués par cette règle sont vrais. Par exemple, si vous savez qu’une règle a un taux de faux positifs élevé, la précision doit être `low`.
Code scanningclasse les résultats par précision sur GitHub afin que les résultats ayant la valeur la plus élevée pour `level` et `precision` soient affichés en premier. Peut avoir l’une des valeurs suivantes : `very-high`, `high`, `medium` ou `low`.
`properties.problem.severity`		(Recommandé) Une chaîne qui indique le niveau de gravité des alertes générées par une requête autre qu’une requête de sécurité. Cela, avec la propriété `properties.precision`, détermine si les résultats sont affichés par défaut sur GitHub, de sorte que les résultats avec la valeur la plus élevée `problem.severity` et la valeur la plus élevée `precision` soient affichés en premier. Il peut s’agir de l’une des valeurs suivantes : `error`, `warning` ou `recommendation`.
`properties.security-severity`		(Recommandé uniquement pour les règles de sécurité) Si vous renseignez une valeur pour ce champ, les résultats de la règle seront traités comme des résultats de sécurité. Une chaîne représentant un score indiquant le niveau de gravité, avec une valeur supérieure à 0,0 et allant jusqu’à 10,0, pour les requêtes de sécurité (`@tags` inclut `security`). Cela, avec la propriété `properties.precision`, détermine si les résultats sont affichés par défaut sur GitHub afin que les résultats ayant les valeurs les plus élevées pour `security-severity` et `precision` soient affichés en premier.
Code scanning traduit les scores numériques comme suit : plus de 9,0 est `critical`, de 7,0 à 8,9 est `high`, de 4,0 à 6,9 est `medium` et de 0,1 à 3,9 est `low`. Une valeur de 0,0 ou toute autre valeur en dehors de la plage donnée est considérée comme n’ayant aucune gravité en matière de sécurité.

Objet `result`

Chaque objet result contient les détails d’une alerte dans le codebase. Dans l’objet results, vous pouvez référencer la règle qui a détecté l’alerte. Pour plus d’informations, consultez Règles et résultats ci-dessus.

Nom	Obligatoire	Description
`ruleId`		Identificateur unique de la règle (`reportingDescriptor.id`). Pour plus d’informations, consultez l’objet `reportingDescriptor`.
Code scanning utilise l’identifiant de règle pour filtrer les résultats en fonction de la règle sur GitHub.
`ruleIndex`		Index de la règle associée (objet `reportingDescriptor`) dans le tableau `rules` de composants d’outil. Pour plus d’informations, consultez l’objet `run`. La plage autorisée pour cette propriété est comprise entre 0 et 2^63 - 1.
`rule`		Référence utilisée pour localiser la règle (descripteur de création de rapports) pour ce résultat. Pour plus d’informations, consultez l’objet `reportingDescriptor`.
`level`		Gravité du résultat. Ce niveau remplace la gravité par défaut définie par la règle.
Code scanning utilise le niveau pour filtrer les résultats par gravité sur GitHub.
`message.text`		Message qui décrit le résultat.
Code scanning affiche le texte du message comme titre du résultat. Seule la première phrase du message s’affiche quand l’espace visible est limité.
`locations[]`		Ensemble d’emplacements où le résultat a été détecté, dans la limite de 10. Un seul emplacement doit être inclus, sauf si le problème ne peut être corrigé qu’en effectuant une modification à chaque emplacement spécifié.
Remarque : Au moins un emplacement est requis pour code scanning afficher un résultat.
Code scanning utilisera cette propriété pour déterminer le fichier à annoter avec le résultat. Seule la première valeur de ce tableau est utilisée. Toutes les autres valeurs sont ignorées.
`partialFingerprints`		Ensemble de chaînes utilisées pour suivre l’identité unique du résultat.
Code scanning utilise `partialFingerprints` pour identifier avec précision quels résultats sont identiques entre les commits et les branches.
Code scanning tentera d’utiliser `partialFingerprints` s’ils existent. Si vous chargez des fichiers SARIF tiers avec l’`upload-action`, l’action crée des `partialFingerprints` pour vous quand elles ne sont pas incluses dans le fichier SARIF. Pour plus d’informations, consultez Fourniture de données pour suivre les alertes d’analyse de code entre les exécutions.
Note:Code scanning utilise uniquement le `primaryLocationLineHash`.
`codeFlows[].threadFlows[].locations[]`		Tableau d’objets `location` pour un objet `threadFlow`, qui décrit la progression d’un programme via un thread d’exécution. Un objet `codeFlow` décrit un modèle d’exécution de code utilisé pour détecter un résultat. Si des flux de code sont fournis, code scanning développera les flux de code sur GitHub pour le résultat concerné. Pour plus d’informations, consultez l’objet `location`.
`relatedLocations[]`		Ensemble d’emplacements pertinents pour ce résultat.
Code scanning liera les emplacements associés lorsqu’ils sont incorporés dans le message de résultat. Pour plus d’informations, consultez l’objet `location`.

Objet `location`

Emplacement dans un artefact de programmation, tel qu’un fichier dans le dépôt ou un fichier qui a été produit lors d’une génération.

Nom	Obligatoire	Description
`location.id`		Identificateur unique qui distingue cet emplacement de tous les autres emplacements au sein d’un objet de résultat unique. La plage autorisée pour cette propriété est comprise entre 0 et 2^63 - 1.
`location.physicalLocation`		Identifie l’artefact et la région. Pour plus d’informations, consultez `physicalLocation`.
`location.message.text`		Message correspondant à l’emplacement.

Objet `physicalLocation`

Nom	Obligatoire	Description
`artifactLocation.uri`		URI indiquant l’emplacement d’un artefact, généralement un fichier dans le dépôt ou produit lors une génération. Pour obtenir les meilleurs résultats, nous recommandons qu’il s’agit d’un chemin relatif à partir de la racine du référentiel GitHub analysé. Par exemple : `src/main.js`. Pour plus d’informations sur les URI d’artefact, consultez Spécification de la racine des fichiers sources.
`region.startLine`		Numéro de ligne du premier caractère de la région.
`region.startColumn`		Numéro de colonne du premier caractère de la région.
`region.endLine`		Numéro de ligne du dernier caractère de la région.
`region.endColumn`		Numéro de colonne du caractère qui suit la fin de la région.

Objet `runAutomationDetails`

L’objet runAutomationDetails contient des informations qui spécifient l’identité d’une exécution.

Nom	Obligatoire	Description
`id`		Chaîne qui identifie la catégorie de l’analyse et l’ID d’exécution. Utilisez cette option si vous souhaitez charger plusieurs fichiers SARIF pour les mêmes outil et commit, mais pour différents langages ou différentes parties du code.

L’utilisation de l’objet runAutomationDetails est facultative.

Le champ id peut inclure une catégorie d’analyse et un ID d’exécution. Nous n’utilisons pas la partie d’ID d’exécution du champ id, mais nous la stockons.

Utilisez la catégorie pour distinguer plusieurs analyses pour le même outil ou le même commit, mais effectuées dans différents langages ou différentes parties du code. Utilisez l’ID d’exécution pour identifier l’exécution spécifique de l’analyse, telle que la date d’exécution de l’analyse.

id est interprété comme category/run-id. Si id ne contient aucune barre oblique (/), la chaîne entière est le run_id et la category est vide. Sinon, category est tout ce qui se trouve dans la chaîne jusqu’à la dernière barre oblique, tandis que run_id est tout ce qui se trouve après.

`id`	catégorie	`run_id`
my-analysis/tool1/2022-01-02	my-analysis/tool1	02-01-2022
my-analysis/tool1/	my-analysis/tool1	None
my-analysis pour tool1	None	my-analysis pour tool1

L’exécution dont l’id est « my-analysis/tool1/2021-02-01 » appartient à la catégorie « my-analysis/tool1 ».
L’exécution dont l’id est « my-analysis/tool1/ » appartient à la catégorie « my-analysis/tool1 », mais n’est pas distinguée des autres exécutions de cette catégorie.
L’exécution dont l’id est « my-analysis for tool1 » a un identificateur unique, mais il est impossible de déduire si elle appartient à telle ou telle catégorie.

Pour plus d’informations sur l’objet runAutomationDetails et le champ id, consultez l’objet runAutomationDetails dans la documentation OASIS.

Notez que le reste des champs pris en charge est ignoré.

Exemples de fichiers de sortie SARIF

Ces exemples de fichiers de sortie SARIF affichent des propriétés prises en charge et des exemples de valeurs.

Exemple avec les propriétés minimales requises

Ce fichier de sortie SARIF contient des valeurs d’exemple pour montrer les propriétés minimales requises afin que les résultats code scanning fonctionnent comme prévu. Si vous supprimez des propriétés, omettez des valeurs ou utilisez une chaîne vide, ces données ne sont pas affichées correctement ou synchronisées sur GitHub.

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Tool Name",
          "rules": [
            {
              "id": "R01"
                      ...
              "properties" : {
                 "id" : "java/unsafe-deserialization",
                 "kind" : "path-problem",
                 "name" : "...",
                 "problem.severity" : "error",
                 "security-severity" : "9.8",
               }
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "R01",
          "message": {
            "text": "Result text. This result does not have a rule associated."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "fileURI"
                },
                "region": {
                  "startLine": 2,
                  "startColumn": 7,
                  "endColumn": 10
                }
              }
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "39fa2ee980eb94b0:1"
          }
        }
      ]
    }
  ]
}

Recommandations relatives aux URI pour les producteurs SARIF

Ce fichier de sortie SARIF contient des exemples de valeurs pour le champ originalUriBaseIds, affichant les propriétés minimales requises qu’un producteur SARIF doit inclure lors de l’utilisation de références d’URI relatives.