Personnalisation de l’analyse avec des packs CodeQL

À 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 deux types de CodeQL packs : query packs et library 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 paquet inclut toutes les dépendances transitives et les représentations pré-compilées de chaque requête en plus des sources des requêtes. 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. 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.

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 :

1. Télécharger la dernière version du pack octo-org/security-queries.
2. 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.
3. Exécuter toutes les requêtes par défaut dans octo-org/security-queries.
4. Exécuter uniquement la requête queries/csrf.ql à partir de octo-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/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> 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 pack codeql/python-queries.

• codeql/python-queries@1.2.3 - Toutes les requêtes de la suite de requêtes par défaut de la version 1.2.3 du pack codeql/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 pack codeql/python-queries qui est >= 1.2.3 et < 1.3.0.

• codeql/python-queries:Functions - Toutes les requêtes du répertoire Functions dans la dernière version du pack codeql/python-queries.

• codeql/python-queries@1.2.3:Functions - Toutes les requêtes du répertoire Functions dans la version 1.2.3 du pack codeql/python-queries.

• codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls - Toutes les requêtes du répertoire codeql-suites/python-code-scanning.qls dans la version 1.2.3 du pack codeql/python-queries.

• suites/my-suite.qls - Toutes les requêtes du fichier suites/my-suite.qls relatives au répertoire de travail actuel.

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