Personnalisation de l’analyse avec des packs CodeQL

Remarque : la fonctionnalité de gestion de packages CodeQL, y compris des packs CodeQL, est actuellement disponible en version bêta et peut faire l’objet de modifications. Pendant la version bêta, les packs CodeQL sont disponibles uniquement à l’aide de packages GitHub, à savoir le Container registry. Pour utiliser cette fonctionnalité bêta, installez la dernière version du bundle CodeQL CLI à partir de : https://github.com/github/codeql-action/releases.

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

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 suite cpp-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 de cpp-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.