Que fait Analyse CodeQL ?
Langages pris en charge : Python, JavaScript/TypeScript, Go, Java/Kotlin, C/C++, C#, Ruby, Swift.
Ressources de compétence : Les fichiers de référence et les modèles se trouvent dans {baseDir}/references/ et {baseDir}/workflows/.
Principes Essentiels
-
La qualité de la base de données est non négociable. Une base de données qui se construit n'est pas automatiquement bonne – une construction en cache n'extrait rien tout en signalant un succès.
-
Les extensions de données capturent ce que CodeQL manque. Les projets Django, Spring et Express encapsulent toujours les appels à la base de données, l'analyse des requêtes et l'exécution de commandes shell dans des API spécifiques au projet qu'aucun modèle livré ne couvre.
-
Les références explicites aux suites empêchent la suppression silencieuse des requêtes. Ne passez jamais de noms de paquets à
codeql database analyze– chaquedefaultSuiteFiledu paquet applique des filtres cachés qui peuvent produire zéro résultat. Générez toujours un.qls. -
Zéro résultat nécessite une enquête, pas une célébration. Cela peut signifier une mauvaise extraction, des modèles manquants, les mauvais paquets ou un filtrage de suite. Exécutez
{baseDir}/scripts/check_db_quality.pyaprès la construction, confirmez que{baseDir}/scripts/verify_query_suite.pys'est terminé avec zéro pour la suite utilisée – les scripts de génération l'exécutent, donc invoquez-le manuellement uniquement pour une suite réutilisée ou modifiée à la main – et dites dans le rapport que les deux ont réussi. -
macOS Apple Silicon nécessite des solutions de contournement pour les langages compilés. Le code de sortie 137 est une incompatibilité
arm64e/arm64, pas un échec de construction. Essayez les outils Homebrew arm64 ou Rosetta avant de recourir àbuild-mode=none. -
Suivez les workflows étape par étape. Chaque phase conditionne la suivante ; sauter l'évaluation de la qualité ou les extensions de données laisse l'écart invisible dans les résultats.
Chaque appel Bash est un nouveau shell
Rien n'est conservé d'un appel Bash à l'autre : ni les variables, ni les tableaux, ni les fonctions sourcées depuis build_log.sh. Chaque bloc ci-dessous qui utilise une valeur doit la rétablir dans le même bloc. Les workflows pointent ici plutôt que de le répéter ; ce qu'ils précisent est le dommage spécifique à cet endroit, car chacun échoue différemment et silencieusement :
- une fonction perdue fait que
run_loggedse termine avec le code 127, que l'échelle de construction lit comme une méthode échouée et descend vers--build-mode=none, sans jamais avoir invoqué CodeQL - un tableau perdu se développe en rien, donc chaque
--threat-modelet--model-packschoisi par l'utilisateur est supprimé tandis que le rapport final les liste toujours comme utilisés - un scalaire perdu sous
set -uabandonne le bloc avecunbound variable
Répertoire de Sortie
Tous les fichiers générés (base de données, journaux de construction, diagnostics, extensions, résultats) sont stockés dans un seul répertoire de sortie.
- Si l'utilisateur spécifie un répertoire de sortie dans son invite, utilisez-le comme
OUTPUT_DIR. - Si non spécifié, par défaut sur
./static_analysis_codeql_1. Si cela existe déjà, incrémentez vers_2,_3, etc.
Dans les deux cas, créez toujours le répertoire avec mkdir -p avant d'écrire des fichiers.
Définissez USER_SPECIFIED_DIR sur le chemin littéral de l'invite de l'utilisateur avant d'exécuter ceci, ou laissez-le non défini pour un auto-incrémentation. Rien d'autre ne l'assigne.
# Résoudre le répertoire de sortie
USER_SPECIFIED_DIR="${USER_SPECIFIED_DIR:-}" # remplacez par le chemin de l'utilisateur ici, le cas échéant
if [ -n "$USER_SPECIFIED_DIR" ]; then
OUTPUT_DIR="$USER_SPECIFIED_DIR"
else
BASE="static_analysis_codeql"
N=1
while [ -e "${BASE}_${N}" ]; do
N=$((N + 1))
done
OUTPUT_DIR="${BASE}_${N}"
fi
mkdir -p "$OUTPUT_DIR"
Le répertoire de sortie est résolu une fois au début avant l'exécution de tout workflow. Tous les workflows reçoivent $OUTPUT_DIR et y stockent leurs artefacts :
$OUTPUT_DIR/
├── rulesets.txt # Ensembles de requêtes sélectionnés (journalisés après l'étape 3)
├── codeql.db/ # Base de données CodeQL (répertoire contenant codeql-database.yml)
├── build.log # Journal de construction
├── codeql-config.yml # Configuration d'exclusion (langages interprétés)
├── diagnostics/ # Requêtes de diagnostic et CSVs
├── extensions/ # YAML d'extension de données
├── raw/ # Sortie d'analyse non filtrée
│ ├── results.sarif
│ └── run-all.qls | important-only.qls
└── results/ # Résultats finaux (filtrés pour important-only, copiés pour run-all)
└── results.sarif
Découverte de Base de Données
Une base de données CodeQL est identifiée par la présence d'un fichier marqueur codeql-database.yml dans son répertoire. Lors de la recherche de bases de données existantes, collectez toujours toutes les correspondances – il peut y avoir plusieurs bases de données d'exécutions précédentes ou pour différents langages.
Commande de découverte. find_databases.sh affiche un chemin de base de données par ligne, en filtrant les fichiers marqueurs qu'une construction échouée laisse derrière elle. Construisez le tableau dans le même bloc qui le sélectionne – chaque appel Bash est un nouveau shell, donc un tableau construit ici est vide au prochain appel, et l'exécution conclut qu'il n'y a pas de base de données :
# Substitution de commande, pas `done < <(...)` : une substitution de processus ignore le
# code de sortie du script, donc "codeql n'est pas sur le PATH de ce shell" (code de sortie 2)
# arriverait comme une liste vide et dirigerait vers "construire une nouvelle base de données"
# avec trois bonnes bases de données sur le disque.
if ! DB_LIST=$("{baseDir}/scripts/find_databases.sh" "${OUTPUT_DIR:-.}" .); then
echo "ERREUR : la découverte de la base de données a échoué – voir le message ci-dessus" >&2
exit 1
fi
FOUND_DBS=()
while IFS= read -r db; do
[ -n "$db" ] || continue
FOUND_DBS+=("$db")
done <<<"$DB_LIST"
echo "Trouvé ${#FOUND_DBS[@]} base(s) de données existante(s)"
# Les métadonnées nécessaires à l'invite de sélection, collectées ici plutôt que dans un bloc
# qui leur est propre : FOUND_DBS est perdu au prochain appel Bash, et une boucle sur un
# tableau qui n'existe plus n'affiche rien et signale un succès.
for db in "${FOUND_DBS[@]}"; do
CODEQL_LANG=$(codeql resolve database --format=json -- "$db" 2>/dev/null | jq -r '.languages[0]')
CREATED=$(grep '^creationMetadata:' -A5 "$db/codeql-database.yml" 2>/dev/null | grep 'creationTime' | awk '{print $2}')
echo "$db — langage : $CODEQL_LANG, créé : $CREATED"
done
Ne supposez jamais qu'une base de données est nommée codeql.db – découvrez-la par son fichier marqueur.
Lorsque plusieurs bases de données sont trouvées : utilisez AskUserQuestion pour permettre à l'utilisateur de sélectionner la base de données à utiliser, ou d'en construire une nouvelle, à partir du langage et de l'heure de création imprimés ci-dessus. AskUserQuestion prend au maximum quatre options, donc avec plus de bases de données que cela, proposez les trois plus récentes plus "Construire une nouvelle base de données" et listez les autres dans le texte de l'invite. Ignorer AskUserQuestion si l'utilisateur a explicitement indiqué quelle base de données utiliser ou s'il faut en construire une nouvelle dans son invite.
Démarrage Rapide
Pour le cas courant ("analyser ce codebase à la recherche de vulnérabilités") :
# Vérifier que CodeQL est installé. Arrêtez-vous ici si ce n'est pas le cas – chaque commande
# ultérieure échoue avec une erreur moins informative, et l'exécution gaspille un cycle de
# construction avant d'en donner la raison.
if ! command -v codeql >/dev/null 2>&1; then
echo "ERREUR : codeql introuvable sur le PATH. Installez-le avec l'une des commandes :" >&2
echo " gh extension install github/gh-codeql # puis : gh codeql install-stub" >&2
echo " brew install --cask codeql" >&2
echo " https://github.com/github/codeql-action/releases (codeql-bundle)" >&2
exit 1
fi
# jq analyse `codeql resolve database --format=json` à l'étape suivante. Sans lui, CODEQL_LANG
# revient vide et l'exécution continue avec le mauvais langage.
if ! command -v jq >/dev/null 2>&1; then
echo "ERREUR : jq introuvable sur le PATH (brew install jq / apt install jq)" >&2
exit 1
fi
# uv exécute à la fois les scripts de garde et les deux générateurs de suites. Vérifiez-le ici
# plutôt qu'au moment de la génération de la suite, qui a lieu après la construction – sinon
# une machine sans uv passe toute la construction avant d'échouer.
if ! command -v uv >/dev/null 2>&1; then
echo "ERREUR : uv introuvable sur le PATH (https://docs.astral.sh/uv/getting-started/)" >&2
exit 1
fi
codeql --version
Ensuite, résolvez OUTPUT_DIR en utilisant le bloc dans Répertoire de Sortie ci-dessus – il honore un répertoire spécifié par l'utilisateur, ce qu'un simple auto-incrément ne fait pas.
Ensuite, exécutez le pipeline complet : construire la base de données → créer les extensions de données → exécuter l'analyse en utilisant les workflows ci-dessous.
Rationalisations à Rejeter
Ces raccourcis conduisent à des résultats manqués. Ne les acceptez pas :
- "security-extended suffit" - C'est la base. Vérifiez toujours si les packs Trail of Bits et Community Packs sont disponibles pour le langage. Ils capturent des catégories que
security-extendedmanque complètement. - "security-and-quality est la suite la plus large" -
security-and-qualityexclut tous les chemins de requêteexperimental/. Pour le mode run-all, importez à la foissecurity-and-qualityetsecurity-experimental. Le delta est de 1 à 52 requêtes selon le langage. - "La base de données s'est construite, donc elle est bonne" - Une base de données qui se construit ne signifie pas qu'elle s'est bien extraite. Exécutez toujours l'évaluation de la qualité et vérifiez le nombre de fichiers par rapport aux fichiers source attendus.
- "Les extensions de données ne sont pas nécessaires pour les frameworks standard" - Même les applications Django/Spring ont des wrappers personnalisés que CodeQL ne modélise pas. Ignorer les extensions signifie manquer des vulnérabilités.
- "build-mode=none est acceptable pour les langages compilés" - Cela produit une analyse gravement incomplète. À n'utiliser qu'en dernier recours absolu. Sur macOS, essayez d'abord la solution de contournement de la chaîne d'outils arm64 ou Rosetta.
- "La construction échoue sur macOS, utilisez simplement build-mode=none" - Le code de sortie 137 est causé par une incompatibilité
arm64e/arm64, pas un échec de construction fondamental. Voir macos-arm64e-workaround.md. - "Aucun résultat signifie que le code est sécurisé" - Exécutez
check_db_quality.pyetverify_query_suite.pyet signalez qu'ils ont réussi. Sans eux, zéro résultat et une base de données qui n'a rien extrait produisent la même sortie. - "Je vais simplement exécuter la suite par défaut" / "Je vais simplement passer les noms des packs directement" - Chaque
defaultSuiteFiledu pack applique des filtres cachés et peut produire zéro résultat. Utilisez toujours une référence de suite explicite. - "Je vais placer les fichiers dans le répertoire courant" - Tous les fichiers générés doivent aller dans
$OUTPUT_DIR. Disperser des fichiers dans le répertoire de travail rend le nettoyage impossible et risque d'écraser les exécutions précédentes. - "Utilisez simplement la première base de données que je trouve" - Plusieurs bases de données peuvent exister pour différents langages ou d'exécutions précédentes. Lorsque plus d'une est trouvée, présentez toutes les options à l'utilisateur. Ignorez l'invite uniquement lorsque l'utilisateur a déjà spécifié la base de données à utiliser.
- "L'utilisateur a dit 'analyser', cela signifie qu'il veut que je choisisse une base de données" - "Analyser" n'est pas une sélection de base de données. Si plusieurs bases de données existent et que l'utilisateur n'en a pas nommé une, demandez.
Sélection du Workflow
Cette compétence comporte trois workflows. Une fois un workflow sélectionné, exécutez-le étape par étape sans sauter de phases.
Ces exécutions sont longues. Une construction de base de données comporte quatre méthodes de repli, donc utilisez les outils de tâche pour suivre la progression. Décidez quelles étapes méritent d'être suivies en fonction de l'exécution.
| Workflow | Objectif |
|---|---|
| build-database | Créer la base de données CodeQL en utilisant les méthodes de construction en séquence |
| create-data-extensions | Détecter ou générer des modèles d'extension de données pour les API du projet |
| run-analysis | Sélectionner les ensembles de règles, exécuter les requêtes, traiter les résultats |
Construction sans assistance
Ce plugin fournit /static-analysis:codeql-build, qui exécute les étapes de construction de la base de données de bout en bout : détecter le langage et la chaîne d'outils, parcourir l'échelle des méthodes en appliquant les correctifs de build-fixes.md entre les échelons, et appliquer le contrôle de qualité.
/static-analysis:codeql-build {"target": "/abs/path", "lang": "cpp"}
Il ne demande rien. Le fait que chaque méthode échoue et qu'une base de données construite mais sous le seuil de qualité reviennent sous forme de statuts – no-method-succeeded et built-below-threshold – pour que vous agissiez ici, car savoir si les erreurs d'extracteur restantes se limitent à du code dont personne n'a besoin d'analyse est un jugement que l'exécution ne peut pas prendre.
Utilisez-le lorsque la construction est la partie longue et incertaine et que vous souhaitez qu'elle soit menée à son terme. Travaillez build-database.md à la main lorsque vous voulez avoir votre mot à dire sur la méthode à essayer, ou lorsqu'un échec de construction nécessite une interprétation en temps réel.
Logique d'Auto-Détection
Si l'utilisateur spécifie explicitement quoi faire (par exemple, "construire une base de données", "exécuter l'analyse sur ./my-db"), exécutez ce workflow directement. N'appelez PAS AskUserQuestion pour la sélection de la base de données si l'invite de l'utilisateur rend déjà son intention claire – par exemple, "construire une nouvelle base de données", "analyser la base de données CodeQL dans static_analysis_codeql_2", "exécuter une analyse complète à partir de zéro".
Pipeline par défaut pour "test", "analyser", "scanner" ou similaire : Découvrez les bases de données existantes en utilisant la commande dans Découverte de Base de Données ci-dessus, puis décidez.
| Condition | Action |
|---|---|
| Aucune base de données trouvée | Résoudre un nouveau $OUTPUT_DIR, exécuter construction → extensions → analyse (pipeline complet) |
| Une base de données trouvée | Utiliser AskUserQuestion : la réutiliser ou en construire une nouvelle ? |
| Plusieurs bases de données trouvées | Utiliser AskUserQuestion, limitée à quatre options – voir Découverte de Base de Données |
| L'utilisateur a explicitement indiqué son intention | Ignorer AskUserQuestion, agir selon ses instructions directement |
Invite de Sélection de Base de Données
Lorsque des bases de données existantes sont trouvées et que l'utilisateur n'a pas explicitement spécifié laquelle utiliser, présentez-les via AskUserQuestion sous l'en-tête "Bases de Données CodeQL Existantes". Étiquetez chaque option avec le chemin, le langage et l'heure de création collectés ci-dessus – ./static_analysis_codeql_1/codeql.db (langage : python, créé : 2026-02-24) – et faites de la dernière option "Construire une nouvelle base de données".
Après la sélection :
- Si l'utilisateur choisit une base de données existante : Définissez
$OUTPUT_DIRsur son répertoire parent (ou le répertoire le contenant), définissez$DB_NAMEsur le chemin sélectionné, puis procédez aux extensions → analyse. - Si l'utilisateur choisit "Construire nouvelle" : Résolvez un nouveau
$OUTPUT_DIR, exécutez construction → extensions → analyse.
Invite de Décision Générale
Si ni la base de données ni le workflow ne sont clairs à partir de l'invite, proposez les quatre workflows via AskUserQuestion