À propos des packs CodeQL
Les packs CodeQL sont utilisés pour créer, partager et exécuter des requêtes et des bibliothèques CodeQL ainsi que pour définir une dépendance à celles-ci. Les packs CodeQL contiennent des requêtes, des fichiers de bibliothèque, des suites de requêtes et des métadonnées. Vous pouvez personnaliser votre analyse CodeQL en téléchargeant des packs créés par d'autres utilisateurs et en les exécutant sur votre codebase.
Il existe trois types de CodeQL packs : query packs, library packs et model packs.
-
Les packs de requêtes contiennent un ensemble de requêtes précompilées qui peuvent être évaluées sur une base de données CodeQL. Les packs de requêtes sont conçus pour être exécutés. Quand un pack de requêtes est publié, le bundle inclut toutes les dépendances transitives et les représentations précompilées de chaque requête, en plus des sources de requête. Ceci garantit une exécution cohérente et efficace des requêtes dans le pack.
-
Les packs de bibliothèques sont conçus pour être utilisés par des packs de requêtes (ou d’autres packs de bibliothèques) et ne contiennent pas de requêtes. Les bibliothèques ne sont pas compilées séparément.
Les packs CodeQL standard pour tous les langages pris en charge sont publiés dans le Container registry. Si vous avez installé CodeQL CLI de manière standard, en utilisant l'offre groupée CodeQL CLI, les packs de requêtes de base sont déjà téléchargés et disponibles. Il s'agit de :
codeql/cpp-queries
codeql/csharp-queries
codeql/go-queries
codeql/java-queries
codeql/javascript-queries
codeql/python-queries
codeql/ruby-queries
codeql/swift-queries
Vous pouvez également utiliser CodeQL CLI pour créer vos propres packs CodeQL, ajouter des dépendances aux packs et installer ou mettre à jour des dépendances. Pour plus d’informations, consultez « Création et utilisation de packs CodeQL ».
Vous pouvez publier vous-même des packs CodeQL que vous avez créés en utilisant CodeQL CLI. Pour en savoir plus sur comment publier et télécharger les packs CodeQL, référez-vous à « Publication et utilisation de packs CodeQL ».
Téléchargement et utilisation de packs de requêtes CodeQL
Le bundle de l’CodeQL CLI inclut des requêtes gérées par les experts GitHub, les chercheurs en sécurité et les contributeurs de la communauté. Si vous souhaitez exécuter des requêtes développées par d'autres organisations, les packs de requêtes CodeQL constituent un moyen efficace et fiable de télécharger et d'exécuter des requêtes, tandis que les packs de modèles (beta) peuvent être utilisés pour étendre l'analyse code scanning afin de reconnaître les bibliothèques et les frameworks qui ne sont pas pris en charge par défaut. Pour plus d’informations sur les packs de requêtes, consultez « À propos de l’analyse du code avec CodeQL ».
Avant de pouvoir utiliser un pack de requête CodeQL pour analyser une base de données, vous devez télécharger tous les packages dont vous avez besoin à partir du Container registry GitHub. Cela peut se faire soit en utilisant le drapeau --download
dans la commande codeql database analyze
, soit en exécutant codeql pack download
. Si un package n’est pas disponible publiquement, vous devez utiliser une GitHub App ou un personal access token pour vous authentifier. Pour plus d’informations et obtenir un exemple, consultez « Chargement des résultats d'analyse de CodeQL sur GitHub ».
Option | Obligatoire | Usage |
---|---|---|
<scope/name@version:path> | Spécifiez l’étendue et le nom d’un ou plusieurs packs de requêtes CodeQL à télécharger en utilisant une liste séparée par des virgules. Si vous le souhaitez, incluez la version à télécharger et décompresser. Par défaut, la dernière version de ce pack est téléchargée. Si vous le souhaitez, incluez un chemin d’accès à une requête, un répertoire ou une suite de requêtes à exécuter. Si aucun chemin d’accès n’est inclus, exécutez les requêtes par défaut de ce pack. | |
--github-auth-stdin | Passer à l'interface CLI la GitHub App ou le personal access token créé pour l'authentification avec l'API REST de GitHub depuis le magasin de secrets via une entrée standard. Cette option n’est pas nécessaire si la commande a accès à une variable d’environnement GITHUB_TOKEN définie avec ce jeton. |
Remarque : Si vous spécifiez une version particulière d’un pack de requêtes à utiliser, notez qu’elle peut devenir trop ancienne pour une utilisation efficace de la dernière version de CodeQL. Pour garantir des performances optimales, si vous devez spécifier des versions précises du pack de requêtes, vous devez les réévaluer chaque fois que vous mettez à niveau l’interface CLI de CodeQL CLI que vous utilisez.
Pour plus d’informations sur la compatibilité des packs, consultez « Publication et utilisation de packs CodeQL ».
Exemple simple de téléchargement et d’utilisation de packs de requêtes
Cet exemple exécute la commande codeql database analyze
avec l’option --download
pour :
- Télécharger la dernière version du pack
octo-org/security-queries
. - Télécharger une version du pack
octo-org/optional-security-queries
compatible avec la version 1.0.1 (dans ce cas, la version 1.0.2). Pour plus d’informations sur la compatibilité avec semver, consultez la documentation sur la plage de versions sémantiques de npm. - Exécuter toutes les requêtes par défaut dans
octo-org/security-queries
. - Exécuter uniquement la requête
queries/csrf.ql
à partir deocto-org/optional-security-queries
$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
octo-org/security-queries \
octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
--format=sarif-latest --output=/temp/example-repo-js.sarif
> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/[email protected]
> Installed fresh octo-org/[email protected]
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.
Téléchargement direct de packs CodeQL
Si vous souhaitez télécharger un pack CodeQL sans l’exécuter immédiatement, vous pouvez utiliser la commande codeql pack download
. Cela est utile si vous souhaitez éviter d’accéder à Internet lors de l’exécution de requêtes CodeQL. Lorsque vous exécutez l’analyse CodeQL, vous pouvez spécifier des packs, des versions et des chemins d’accès de la même façon que dans l’exemple précédent :
echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...
Téléchargement des packs CodeQL à partir de plusieurs registres de conteneurs GitHub
Si vos packs CodeQL se trouvent sur plusieurs registres de conteneurs, vous devez indiquer à CodeQL CLI où trouver chaque pack. Pour plus d’informations, consultez « Personnalisation de votre configuration avancée pour l’analyse de code ».
Spécification des requêtes à exécuter dans un pack CodeQL
Les spécificateurs de requêtes sont utilisés par codeql database analyze
et d’autres commandes qui opèrent sur un ensemble de requêtes.
La forme complète d’un spécificateur de requête est 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 vers une requête unique, un répertoire contenant des requêtes ou un fichier de suite de requêtes.
Lorsque vous spécifiez un scope/name
, range
et path
sont facultatifs. Si vous omettez une range
, la dernière version du pack spécifié est utilisée. Si vous omettez un path
, la suite de requêtes par défaut du pack spécifié est utilisée.
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 vous omettez un nom de pack, vous devez fournir un path
, qui sera interprété en fonction du répertoire de travail du processus en cours. Les modèles glob ne sont pas pris en charge.
Si vous spécifiez à la fois un scope/name
et un path
, le path
ne peut pas être absolu. Il est considéré comme relatif à la racine du pack CodeQL.
Exemples de spécificateurs de requêtes
-
codeql/python-queries
- Toutes les requêtes de la suite de requêtes par défaut de la dernière version du packcodeql/python-queries
. -
codeql/[email protected]
- Toutes les requêtes de la suite de requêtes par défaut de la version1.2.3
du packcodeql/python-queries
. -
codeql/python-queries@~1.2.3
- Toutes les requêtes de la suite de requêtes par défaut de la dernière version du packcodeql/python-queries
qui est >=1.2.3
et <1.3.0
. -
codeql/python-queries:Functions
- Toutes les requêtes du répertoireFunctions
dans la dernière version du packcodeql/python-queries
. -
codeql/[email protected]:Functions
- Toutes les requêtes du répertoireFunctions
dans la version 1.2.3 du packcodeql/python-queries
. -
codeql/[email protected]:codeql-suites/python-code-scanning.qls
- Toutes les requêtes du répertoirecodeql-suites/python-code-scanning.qls
dans la version 1.2.3 du packcodeql/python-queries
. -
suites/my-suite.qls
- Toutes les requêtes du fichiersuites/my-suite.qls
relatives au répertoire de travail actuel.
Conseil
La suite de requêtes par défaut des packs de requêtes standard CodeQL est codeql-suites/<lang>-code-scanning.qls
. Vous trouverez également plusieurs autres suites de requêtes utiles dans le répertoire codeql-suites
de chaque pack. Par exemple, le pack codeql/cpp-queries
contient les suites de requêtes suivantes :
-
cpp-code-scanning.qls
- Requêtes d’analyse de code standard pour C++. Suite de requêtes par défaut pour ce pack. -
cpp-security-extended.qls
- Requêtes de la suitecpp-code-scanning.qls
par défaut pour C++, plus des requêtes de gravité et de précision moindres. -
cpp-security-and-quality.qls
- Requêtes decpp-security-extended.qls
, plus des requêtes de maintenabilité et de fiabilité.
Vous pouvez voir les sources de ces suites de requêtes dans le dépôt CodeQL. Les suites de requêtes pour les autres langages sont similaires.
Utilisation des packs de modèles pour analyser les appels aux dépendances personnalisées
Vous pouvez inclure les packs de modèles publiés dans une analyse code scanning avec l'option --model-packs
. Par exemple :
$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
--model-packs my-repo/my-java-model-pack \
--output=/temp/my-company.sarif codeql/java-queries
Dans cet exemple, les requêtes pertinentes du pack de requêtes standard codeql/java-queries
utilisent les informations sur les dépendances du pack de modèles, my-repo/my-java-model-pack
, pour vérifier les vulnérabilités du code qui fait appel à ces dépendances.
Vous pouvez spécifier plusieurs packs de modèles publiés dans une analyse.
Pour en savoir plus sur l'écriture de vos propres packs de modèles, référez-vous à « Création et utilisation de packs CodeQL ».
À propos des packages publiés
Quand un pack est publié pour une utilisation dans des analyses, la commande codeql pack create
ou codeql pack publish
vérifie que le contenu est complet et y ajoute des éléments de contenu supplémentaires :
-
Pour un pack de requêtes, une copie de chacun des packs de bibliothèques dont il dépend, dans les versions précises avec lesquelles il a été développé. Les utilisateurs du pack de requêtes n’auront pas besoin de télécharger ces packs de bibliothèques séparément.
-
Pour un pack de requêtes, les représentations précompilées de chacune des requêtes. Elles sont plus rapides à exécuter que s’il fallait compiler la source QL pour la requête à chaque analyse.
La plupart de ces données se trouvent dans un répertoire nommé .codeql
dans le pack publié, mais les requêtes précompilées se trouvent dans des fichiers avec un suffixe .qlx
avec la source .ql
pour chaque requête. Durant l’analyse d’une base de données avec une requête d’un pack publié, CodeQL charge ces fichiers au lieu de la source .ql
. Si vous devez modifier le contenu d’un pack publié, veillez à supprimer tous les fichiers .qlx
, car ils peuvent empêcher les modifications apportées aux fichiers .ql
de prendre effet.