database analyze

Synopsis

codeql database analyze --format=<format> --output=<output> [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>...

codeql database analyze --format=<format> --output=<output> [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>...

Description

Analyse une base de données en produisant des résultats significatifs dans le contexte du code source.

Exécute une suite de requêtes (ou des requêtes individuelles) sur une base de données CodeQL en produisant des résultats sous la forme d’alertes ou de chemins, dans un format SARIF ou un autre format interprété.

Cette commande combine l’effet des commandes codeql database run-queries et codeql database interpret-results. Si vous souhaitez exécuter des requêtes dont les résultats ne répondent pas aux conditions requises pour être interprétés comme des alertes de code source, utilisez plutôt codeql database run-queries ou codeql query run, puis codeql bqrs decode pour convertir les résultats bruts en notation lisible.

Options

Options principales

<database>

[Obligatoire] Chemin vers la base de données CodeQL à interroger.

<querysuite|pack>...

Requêtes à exécuter. Chaque argument se présente sous la forme scope/name@range:path où :

• scope/name est le nom qualifié d’un pack CodeQL.
• range est une plage semver.
• path est un chemin de système de fichiers.

Si scope/name est spécifié, range et path sont facultatifs. Un range manquant implique la dernière version du pack spécifié. Un path manquant implique la suite de requêtes par défaut du pack spécifié.

path peut être, au choix, un fichier de requête *.ql, un répertoire contenant une ou plusieurs requêtes ou un fichier de suite de requêtes .qls. Si aucun nom de pack n’est spécifié, un path doit être fourni et sera interprété comme relatif au répertoire de travail actuel du processus en cours.

Pour spécifier un path qui contient un littéral @ ou :, utilisez path: comme préfixe de l’argument, comme suit : path:directory/with:and@/chars.

Si scope/name et path sont spécifiés, path ne peut pas être absolu. Il est considéré comme relatif à la racine du pack CodeQL.

Si aucune requête n’est spécifiée, l’interface CLI détermine automatiquement un jeu approprié de requêtes à exécuter. En particulier, si un fichier de configuration d’Analyse du code a été spécifié au moment de la création de la base de données en utilisant --codescanning-config, les requêtes de cette commande sont utilisées. Sinon, les requêtes par défaut pour le langage en cours d’analyse sont utilisées.

--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.

--[no-]rerun

Évalue les requêtes paires qui semblent déjà avoir un résultat BQRS stocké dans la base de données.

--no-print-diagnostics-summary

N’affiche pas de résumé des diagnostics analysés dans la sortie standard.

--no-print-metrics-summary

N’affiche pas de résumé des métriques analysées dans la sortie standard.

--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] [Recommandé] Spécifiez 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 s’affiche (avec une barre oblique de fin ajoutée si elle n’est pas déjà présente) en tant que propriété <run>.automationDetails.id.

--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-database-threat-models

[Avancé] Omettez la configuration du modèle de risque stockée dans la base de données lors de la création d’une base de données à partir d’un fichier de configuration d’analyse du code.

--[no-]download

Télécharge toutes les requêtes manquantes avant l’analyse.

Options permettant de contrôler les modèles de risque à utiliser

--threat-model=<name>...

Liste des modèles de risque à activer ou désactiver.

L’argument est le nom d’un modèle de risque, éventuellement précédé d’un « ! ». Si aucun « ! » n’est présent, le modèle de risque nommé et tous ses descendants sont activés. Si un « ! » est présent, le modèle de risque nommé et tous ses descendants sont désactivés.

Le modèle de risque « par défaut » est activé par défaut, mais peut être désactivé en spécifiant « --threat-model !default ».

Le modèle de risque « all » peut être utilisé pour activer ou désactiver tous les modèles de risque.

Les options -- modeles de risque sont traitées dans l’ordre. Par exemple, « --threat-model local --threat-model !environment » active tous les modèles de risque dans le groupe « local », à l’exception du modèle de risque « environnement ».

Cette option a uniquement un effet pour les langages qui prennent en charge les modèles de risque.

Disponible depuis v2.15.3.

Options pour contrôler l’évaluateur de requête

--[no-]tuple-counting

[Avancé] Affiche le nombre de tuples pour chaque étape d’évaluation dans les journaux de l’évaluateur de requêtes. Si l’option --evaluator-log est fournie, les nombres de tuples sont inclus dans les journaux JSON textuels et structurés générés par la commande. (Cela peut être utile pour l’optimisation des performances du code QL complexe.)

--timeout=<seconds>

[Avancé] Définit la durée du délai d’expiration pour l’évaluation de la requête, en secondes.

La fonctionnalité de délai d’expiration est destinée à intercepter les cas où l’évaluation d’une requête complexe durerait « indéfiniment ». Il ne s’agit pas d’un moyen efficace de limiter la durée totale de l’évaluation de la requête. L’évaluation est autorisée à se poursuivre tant que chaque partie du calcul se termine dans le délai d’expiration qui lui a été imparti séparément. Pour l’instant, ces parties sont des « couches RA » de la requête optimisée, mais cela peut changer.

Si aucun délai d’expiration n’est spécifié ou que 0 est fourni, aucun délai n’est défini (sauf pour codeql test run, où le délai d’expiration par défaut est de 5 minutes).

-j, --threads=<num>

Utilise le nombre de threads spécifié pour évaluer les requêtes.

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-]save-cache

[Avancé] Écrit de manière agressive des résultats intermédiaires dans le cache de disque. Cela prend plus de temps et utilise (beaucoup) plus d’espace disque, mais peut accélérer l’exécution ultérieure de requêtes similaires.

--[no-]expect-discarded-cache

[Avancé] Prend des décisions sur les prédicats à évaluer et sur ce qu’il faut écrire dans le cache de disque, en supposant que le cache soit ignoré une fois les requêtes exécutées.

--[no-]keep-full-cache

[Avancé] Ne nettoie pas le cache de disque une fois l’évaluation terminée. Cela peut faire gagner du temps si vous êtes amené à exécuter codeql dataset cleanup ou codeql database cleanup par la suite.

--max-disk-cache=<MB>

Définit la quantité maximale d’espace que le cache de disque peut utiliser pour les résultats de requête intermédiaires.

Si cette taille n’est pas configurée explicitement, l’évaluateur essaie d’utiliser une quantité « raisonnable » d’espace de cache en fonction de la taille du jeu de données et de la complexité des requêtes. La définition explicite d’une limite supérieure à cette utilisation par défaut permet une mise en cache supplémentaire qui peut accélérer les requêtes ultérieures.

--min-disk-free=<MB>

[Avancé] Définit la quantité cible d’espace disponible sur le système de fichiers.

Si --max-disk-cache n’est pas donné, l’évaluateur s’efforce de limiter l’utilisation du cache de disque si l’espace disponible sur le système de fichiers passe en dessous de cette valeur.

--min-disk-free-pct=<pct>

[Avancé] Définit la fraction cible d’espace disponible sur le système de fichiers.

Si --max-disk-cache n’est pas donné, l’évaluateur s’efforce de limiter l’utilisation du cache de disque si l’espace disponible sur le système de fichiers passe en dessous de ce pourcentage.

--external=<pred>=<file.csv>

Fichier CSV qui contient des lignes pour le prédicat <pred> externe. Vous pouvez fournir plusieurs options --external.

--xterm-progress=<mode>

[Avancé] Contrôle s’il faut afficher le suivi de la progression pendant l’évaluation du code QL avec des séquences de contrôle xterm. Les valeurs possibles sont les suivantes :

no : ne produit jamais de progression fantaisiste ; suppose qu’il s’agit d’un terminal idiot.

auto (par défaut)  : détermine automatiquement si la commande s’exécute dans un terminal approprié.

yes : suppose que le terminal peut comprendre les séquences de contrôle xterm. La fonctionnalité dépend toujours de la possibilité de détecter automatiquement la taille du terminal et est également désactivée si -q est donné.

25x80 (ou similaire) : comme yes, et donne aussi explicitement la taille du terminal.

25x80:/dev/pts/17 (ou similaire) : affiche une progression fantaisiste sur un terminal différent de stderr. Principalement utile pour les tests internes.

Options pour contrôler la sortie des journaux structurés de l’évaluateur

--evaluator-log=<file>

[Avancé] Génère des journaux structurés sur les performances de l’évaluateur dans le fichier donné. Le format de ce fichier journal est susceptible d’être modifié sans préavis, mais il s’agit d’un flux d’objets JSON séparés par deux caractères de nouvelle ligne (par défaut) ou un seul si l’option --evaluator-log-minify est transmise. Utilisez codeql generate log-summary <file> pour produire un résumé plus stable de ce fichier et évitez d’analyser le fichier directement. Le fichier est remplacé, s’il existe déjà.

--evaluator-log-minify

[Avancé] Si l’option --evaluator-log est transmise, le passage de cette option réduit également la taille du journal JSON produit, mais celui-ci devient beaucoup moins lisible par les êtres humains en contrepartie.

Options pour contrôler l’utilisation de la RAM

-M, --ram=<MB>

L'évaluateur de requêtes s'efforcera de maintenir son empreinte mémoire totale en dessous de cette valeur. (Toutefois, pour les grandes bases de données, il est possible que le seuil soit dépassé par les cartes mémoire sauvegardées sur fichier, qui peuvent être basculées sur disque en cas de sollicitation de la mémoire).

La valeur doit être d'au moins 2048 Mo ; les valeurs inférieures seront arrondies de manière transparente.

Options pour contrôler la compilation QL

--warnings=<mode>

Comment gérer les avertissements du compilateur QL. Valeurs possibles :

hide : Supprime les avertissements.

show (par défaut)  : Affiche les avertissements, mais poursuit la compilation.

error : Traite les avertissements comme des erreurs.

--no-debug-info

N’émet pas d’informations d’emplacement source dans RA pour le débogage.

--[no-]fast-compilation

[Déprécié] [Avancé] Omet les étapes d’optimisation particulièrement lentes.

--no-release-compatibility

[Avancé] Utilise les fonctionnalités les plus récentes du compilateur, au détriment de la portabilité.

Parfois, les nouvelles fonctionnalités du langage QL et les optimisations de l’évaluateur sont prises en charge par l’évaluateur QL quelques versions avant qu’elles ne soient activées par défaut dans le compilateur QL. Cela permet de garantir que les performances dont vous bénéficiez lors du développement de requêtes dans la dernière version de CodeQL peuvent être atteintes par des versions légèrement plus anciennes qui peuvent encore être utilisées pour l’Analyse du code ou les intégrations CI.

Si la compatibilité de vos requêtes avec d’autres versions (antérieures ou ultérieures) de CodeQL n’est pas un souci pour vous, vous pouvez parfois atteindre des performances un peu meilleures en utilisant cet indicateur pour activer les améliorations récentes du compilateur dès le début.

Dans les versions pour lesquelles il n’y a pas d’améliorations récentes à activer, cette option ne fait rien. Par conséquent, vous pouvez sans problème la définir une fois pour toutes dans votre fichier de configuration CodeQL global.

Disponible depuis v2.11.1.

--[no-]local-checking

Effectue uniquement les vérifications initiales sur la partie de la source QL utilisée.

--no-metadata-verification

Ne vérifie pas les métadonnées de requête incorporées dans les commentaires QLDoc à des fins de validité.

--compilation-cache-size=<MB>

[Avancé] Remplace la taille maximale par défaut d’un répertoire de cache de compilation.

--fail-on-ambiguous-relation-name

[Avancé] Échec de la compilation si un nom de relation ambigu est généré pendant la compilation.

Options pour configurer l’environnement de compilation

--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 ;.)

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

[Avancé] Liste facultative des répertoires qui sont ajoutés au chemin de recherche d’importation brut pour les bibliothèques QL. Doit être utilisé seulement si vous utilisez des bibliothèques QL qui n’ont pas été empaquetées en tant que packs QL.

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

--dbscheme=<file>

[Avancé] Définit explicitement les requêtes de schéma de base de données à compiler. Ne doit être donné que par les appelants qui sont extrêmement sûrs de ce qu’ils font.

--compilation-cache=<dir>

[Avancé] Spécifie un répertoire supplémentaire à utiliser comme cache de compilation.

--no-default-compilation-cache

[Avancé] N’utilise pas de caches de compilation dans des emplacements standard, comme dans le pack QL contenant la requête ou dans le répertoire de la chaîne d’outils CodeQL.

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 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.