database interpret-results

Synopsis

codeql database interpret-results --format=<format> --output=<output> [--threads=<num>] <options>... -- <database> <file|dir|suite>...

codeql database interpret-results --format=<format> --output=<output> [--threads=<num>] <options>... -- <database> <file|dir|suite>...

Description

[Plomberie] Interprète les résultats des requêtes calculées dans des formats pertinents tels que SARIF ou CSV.

Les résultats doivent avoir été calculés et stockés dans un répertoire de base de données CodeQL avec codeql database run-queries. (Vous voudrez généralement effectuer ces étapes ensemble avec codeql database analyze.)

Options

Options principales

<database>

[Obligatoire] Chemin de la base de données CodeQL qui a été interrogée.

<filesuite>...

Répète la spécification des requêtes qui ont été exécutées ici.

En cas d’omission, l’interface CLI détermine un ensemble de requêtes approprié à l’aide de la même logique que codeql database run-queries.

(Dans une version ultérieure, il devrait être possible d’omettre cela et d’interpréter à la place tous les résultats trouvés dans la base de données. Cet avenir glorieux n’est pas pour tout de suite. Désolé.)

--format=<format>

[Obligatoire] Format dans lequel écrire les résultats. Valeurs possibles :

csv : Valeurs séparées par des virgules mises en forme, notamment des colonnes avec des métadonnées de règle et d’alerte.

sarif-latest : Format SARIF (Static Analysis Results Interchange Format), basé sur JSON pour décrire les résultats d’analyse statique. Cette option de format utilise la version prise en charge la plus récente (v2.1.0). Cette option ne convient pas dans le cadre d’une automatisation, car elle produit différentes versions de format SARIF entre les différentes versions de CodeQL.

sarifv2.1.0 : SARIF v2.1.0.

graphtext : Format texte représentant un graphe. Compatible uniquement avec les requêtes avec @kind graph.

dgml : Directed Graph Markup Language, format XML permettant de décrire des graphes. Compatible uniquement avec les requêtes avec @kind graph.

dot : Langage DOT Graphviz, format texte permettant de décrire des graphes. Compatible uniquement avec les requêtes avec @kind graph.

-o, --output=<output>

[Obligatoire] Chemin de sortie dans lequel écrire les résultats. Pour les formats de graphe, ce doit être un répertoire, et le résultat (ou les résultats si cette commande prend en charge l’interprétation de plusieurs requêtes) est écrit dans ce répertoire.

--max-paths=<maxPaths>

Nombre maximal de chemins à produire pour chaque alerte avec des chemins. (Par défaut : 4)

--[no-]sarif-add-file-contents

[Formats SARIF uniquement] Incluez le contenu entier de tous les fichiers référencés dans au moins un résultat.

--[no-]sarif-add-snippets

[Formats SARIF uniquement] Incluez des extraits de code pour chaque emplacement mentionné dans les résultats, avec deux lignes de contexte avant et après l’emplacement signalé.

--[no-]sarif-add-query-help

[Formats SARIF uniquement] [Déconseillé] Incluez l’aide de requête Markdown pour toutes les requêtes. Elle charge l’aide des requêtes pour /path/to/query.ql à partir du fichier /path/to/query.md. Si cet indicateur n’est pas fourni, le comportement par défaut consiste à inclure l’aide uniquement pour les requêtes personnalisées, c’est-à-dire celles des packs de requêtes qui ne sont pas du formulaire `codeql/<lang&rt;-requêtes`. Cette option n’a aucun effet lorsqu’elle est passée à codeql bqrs interpret.

--sarif-include-query-help=<mode>

[Formats SARIF uniquement] Spécifiez s’il faut inclure l’aide de requête dans la sortie SARIF. Valeurs possibles :

always : incluez l’aide sur les requêtes pour toutes les requêtes.

custom_queries_only (par défaut)  : incluez l’aide de requête uniquement pour les requêtes personnalisées, c’est-à-dire celles des packs de requêtes qui ne sont pas du formulaire `codeql/<lang&rt;-requêtes`.

never : n’incluez aucune aide sur les requêtes.

Cette option n’a aucun effet lorsqu’elle est passée à codeql bqrs interpret.

Disponible depuis v2.15.2.

--[no-]sarif-group-rules-by-pack

[Formats SARIF uniquement] Place l’objet de règle pour chaque requête sous son pack QL correspondant dans la propriété <run>.tool.extensions. Cette option n’a aucun effet lorsqu’elle est passée à codeql bqrs interpret.

--[no-]sarif-multicause-markdown

[Formats SARIF uniquement] Pour les alertes qui ont plusieurs causes, les inclut comme liste détaillée au format Markdown dans la sortie, en plus d’une chaîne simple.

--no-group-results

[Formats SARIF uniquement] Produit un résultat par message, plutôt qu’un résultat par emplacement unique.

--csv-location-format=<csvLocationFormat>

Format dans lequel produire des emplacements dans une sortie CSV. Un des éléments suivants : uri, ligne-colonne, décalage-longueur. (Par défaut : ligne-colonne)

--dot-location-url-format=<dotLocationUrlFormat>

Chaîne de format définissant le format dans lequel produire les URL d’emplacement de fichier dans une sortie DOT. Les espaces réservés suivants peuvent être utilisés : {path} {start:line} {start:column} {end:line} {end:column}, {offset}, {length}

--[no-]sublanguage-file-coverage

[GitHub.com et GitHub Enterprise Server v3.12.0+ uniquement] Utilisez les informations de couverture des fichiers de sous-langage. Cela permet de calculer, d’afficher et d’exporter des informations de couverture de fichiers distinctes pour les langages qui partagent un extracteur CodeQL comme C et C++, Java et Kotlin, et JavaScript et TypeScript.

Disponible depuis v2.15.2.

--sarif-category=<category>

[Formats SARIF uniquement] Spécifie une catégorie pour cette analyse à inclure dans la sortie SARIF. Une catégorie peut être utilisée pour distinguer plusieurs analyses effectuées sur le même commit et le même dépôt, mais dans différents langages ou différentes parties du code.

Si vous analysez la même version d’une base de code de différentes manières (par exemple, pour différents langages) et que vous chargez les résultats sur GitHub pour les présenter dans l’Analyse du code, cette valeur doit différer entre chacune des analyses pour indiquer à l’Analyse du code que les analyses se complètent plutôt qu’elles ne se remplacent. (Les valeurs doivent être cohérentes entre les exécutions de la même analyse pour différentes versions de la base de code.)

Cette valeur apparaît (avec une barre oblique finale ajoutée si elle n’est pas déjà présente) sous forme de propriété <run>.automationId au format SARIF v1, de propriété <run>.automationLogicalId au format SARIF v2 et de propriété <run>.automationDetails.id au format SARIF v2.1.0.

-j, --threads=<num>

Nombre de threads utilisés pour les chemins de calcul.

La valeur par défaut est de 1. Vous pouvez passer 0 pour utiliser un thread par cœur sur la machine ou -N pour laisser N cœurs inutilisés (sauf si au moins un thread est toujours utilisé).

--no-database-extension-packs

[Avancé] Omettez les packs d’extension stockés dans la base de données lors de la création de la base de données, soit à partir d’un fichier de configuration d’analyse du code, soit à partir de fichiers d’extension stockés dans le répertoire « extensions » de la base de code analysée.

--[no-]print-diagnostics-summary

Affiche un résumé des diagnostics analysés dans la sortie standard.

--[no-]print-metrics-summary

Affiche un résumé des métriques analysées dans la sortie standard.

--[no-]analysis-summary-v2

[GitHub.com et GitHub Enterprise Server v3.9.0+ uniquement] Utilisez une version améliorée du résumé de l’analyse. Cela permet d’intégrer les informations de couverture des fichiers et d’améliorer la façon dont les résultats de diagnostic sont affichés.

Disponible depuis v2.15.2.

--[no-]print-baseline-loc

Affiche les lignes de base de code comptabilisées dans la sortie standard.

Options pour configurer le gestionnaire de package CodeQL

--registries-auth-stdin

Permet de vous authentifier auprès des registres de conteneurs GitHub Enterprise Server en passant une liste de paires <registry_url>=<token> séparées par des virgules.

Par exemple, vous pouvez passer https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 pour vous authentifier auprès de deux instances GitHub Enterprise Server.

Cela remplace les variables d’environnement CODEQL_REGISTRIES_AUTH et GITHUB_TOKEN. Si vous avez seulement besoin de vous authentifier auprès du registre de conteneurs github.com, vous pouvez vous authentifier en utilisant l’option plus simple --github-auth-stdin.

--github-auth-stdin

Permet de vous authentifier auprès du registre de conteneurs github.com en passant un jeton github.com GitHub Apps ou un jeton d’accès personnel via une entrée standard.

Pour vous authentifier auprès des registres de conteneurs GitHub Enterprise Server, passez --registries-auth-stdin ou utilisez la variable d’environnement CODEQL_REGISTRIES_AUTH.

Cela remplace la variable d’environnement GITHUB_TOKEN.

Options pour trouver des packs QL (qui peuvent être nécessaires pour interpréter les suites de requêtes)

--search-path=<dir>[:<dir>...]

Liste des répertoires sous lesquels les packs QL peuvent être trouvés. Chaque répertoire peut être un pack QL (ou un bundle de packs contenant un fichier .codeqlmanifest.json à la racine) ou le parent immédiat d’un ou plusieurs de ces répertoires.

Si le chemin contient plusieurs répertoires, leur ordre définit la priorité entre eux : quand un nom de pack qui doit être résolu est mis en correspondance dans plusieurs arborescences de répertoires, celle donnée en premier gagne.

Le pointage de ce chemin vers une extraction du dépôt CodeQL open source devrait fonctionner lors de l’interrogation d’un des langages qui y résident.

Si vous avez extrait le dépôt CodeQL en tant que frère de la chaîne d’outils CodeQL décompressée, vous n’avez pas besoin de donner cette option ; ces répertoires frères sont toujours recherchés pour les packs QL qui ne peuvent pas être trouvés autrement. (Si cette valeur par défaut ne fonctionne pas, il est fortement recommandé de configurer --search-path une fois pour toutes dans un fichier de configuration par utilisateur).

(Remarque : Sur Windows, le séparateur de chemin est ;.)

--additional-packs=<dir>[:<dir>...]

Si cette liste de répertoires est donnée, des packs y sont recherchés avant ceux indiqués dans --search-path. L’ordre entre eux n’a pas d’importance ; il s’agit d’une erreur si un nom de pack est trouvé dans deux répertoires différents de cette liste.

Cette option est utile si vous développez temporairement une nouvelle version d’un pack qui apparaît aussi dans le chemin par défaut. En revanche, il n’est pas recommandé de remplacer cette option dans un fichier de configuration ; certaines actions internes ajoutent cette option à la volée, remplaçant toute valeur configurée.

(Remarque : Sur Windows, le séparateur de chemin est ;.)

Options courantes

-h, --help

Affiche ce texte d’aide.

-J=<opt>

[Avancé] Donne une option à l’environnement JVM exécutant la commande.

(Attention, les options contenant des espaces ne sont pas gérées correctement.)

-v, --verbose

Augmente de façon incrémentielle le nombre de messages de progression affichés.

-q, --quiet

Diminue de façon incrémentielle le nombre de messages de progression affichés.

--verbosity=<level>

[Avancé] Définit explicitement le niveau de détail sur errors, warnings, progress, progress+, progress++ ou progress+++. Remplace -v et -q.

--logdir=<dir>

[Avancé] Écrit des journaux détaillés dans un ou plusieurs fichiers du répertoire donné, avec des noms générés qui incluent des horodatages et le nom de la sous-commande en cours d’exécution.

(Pour écrire un fichier journal avec un nom sur lequel vous avez un contrôle total, donnez plutôt --log-to-stderr et redirigez stderr comme vous le souhaitez.)

--common-caches=<dir>

[Avancé] Contrôle l’emplacement des données en cache sur le disque qui persisteront entre plusieurs exécutions de l’interface CLI, telles que les packs QL téléchargés et les plans de requête compilés. S’il n’est pas défini explicitement, il s’agit par défaut d’un répertoire nommé .codeql dans le répertoire de base de l’utilisateur. S’il n’existe pas déjà, il est créé.

Disponible depuis v2.15.2.