Personnalisation de l’analyse avec des packs CodeQL

Vous pouvez personnaliser votre CodeQL analyse en téléchargeant des packs créés par d’autres utilisateurs et en les exécutant sur votre codebase. Pour plus d’informations, consultez « Packs de requêtes CodeQL ».

Téléchargement et utilisation de CodeQL packs de requêtes

Avant de pouvoir utiliser un CodeQL pack de requêtes pour analyser une base de données, vous devez télécharger tous les packages dont vous avez besoin à partir du GitHubContainer registry. Cela peut être fait en utilisant l’indicateur --download dans la commande codeql database analyze ou en exécutant codeql pack download. Si un package n’est pas disponible publiquement, vous devez utiliser une GitHub App ou personal access token pour vous authentifier. Pour plus d’informations et obtenir un exemple, consultez Chargement des résultats d’analyse CodeQL dans GitHub.

Option	Obligatoire	Usage
<scope/name@version:path>		Spécifiez l’étendue et le nom d’un ou CodeQL plusieurs packs de requêtes à télécharger à l’aide d’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		Transmettez au CLI le GitHub App ou personal access token créé pour l'authentification avec l’API REST de GitHub depuis votre 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-queriescompatible 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/[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 des CodeQL packs

Si vous souhaitez télécharger un CodeQL pack sans l’exécuter immédiatement, vous pouvez utiliser la codeql pack download commande. Cela est utile si vous souhaitez éviter d’accéder à Internet lors de l’exécution CodeQL de requêtes. 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 CodeQL de packs à partir de plusieurs GitHub registres de conteneurs

Si vos CodeQL packs résident sur plusieurs registres de conteneurs, vous devez indiquer où CodeQL CLI trouver chaque pack. Pour plus d’informations, consultez « Options de configuration de flux de travail pour l’analyse du code ».

Spécification des requêtes à exécuter dans un CodeQL pack

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 CodeQL pack.
• 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. Elle est considérée par rapport à la racine du CodeQL paquet.

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 version la plus récente du pack codeql/python-queries.

• codeql/[email protected] - 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 version la plus récente 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 version la plus récente du pack codeql/python-queries.

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

• codeql/[email protected]: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.

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 CodeQL référentiel. Les suites de requêtes pour les autres langages sont similaires.

Utilisation de packs de modèles pour analyser les appels aux dépendances personnalisées

Vous pouvez inclure des packs de modèles publiés dans une code scanning analyse 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 plus d'informations sur l'écriture de vos propres packs de modèles, consultez 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. Lors de l’analyse d’une base de données avec une requête à partir d’un pack publié, CodeQL charge ces fichiers au lieu de la .ql source. 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.