Publication et utilisation de packs CodeQL

Configuration du fichier qlpack.yml avant la publication

Vous pouvez vérifier et modifier les détails de configuration de votre pack CodeQL avant la publication. Ouvrez le fichier qlpack.yml dans l’éditeur de texte de votre choix.

library: # set to true if the pack is a library. Set to false or omit for a query pack
name: <scope>/<pack>
version: <x.x.x>
description: <Description to publish with the package>
default-suite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
default-suite-file: default-queries.qls # optional, a pointer to a query-suite in this pack
license: # optional, the license under which the pack is published
dependencies: # map from CodeQL pack name to version range

• name: doit avoir le format /, où est l’organisation GitHub dans laquelle vous allez publier et est le nom du pack.

• Un maximum d’une default-suite ou d’un default-suite-file est autorisé. Il existe deux façons différentes de définir une suite de requêtes par défaut à exécuter : la première en spécifiant des requêtes directement dans le fichier qlpack.yml et la seconde en spécifiant une suite de requêtes dans le pack.

En cours d’exécution codeql pack publish

Quand vous êtes prêt à publier un pack dans GitHub Container registry, vous pouvez exécuter la commande suivante à la racine du répertoire du pack :

codeql pack publish

Le package publié s’affiche dans la section des packages de l’organisation GitHub spécifiée par l’étendue dans le fichier qlpack.yml.

En cours d’exécution codeql pack download <scope>/<pack>

Pour exécuter un pack créé par quelqu’un d’autre, vous devez d’abord le télécharger en exécutant la commande suivante :

codeql pack download <scope>/<pack>@x.x.x

• <scope> : nom de l’organisation GitHub à partir de laquelle vous allez télécharger.
• <pack> : nom du pack que vous voulez télécharger.
• @x.x.x : numéro de version facultatif. S’il est omis, c’est la dernière version qui est téléchargée.

Cette commande accepte des arguments pour plusieurs packs.

Si vous écrivez des scripts qui spécifient un numéro de version particulier d’un pack de requêtes à télécharger, gardez à l’esprit que quand vous mettez à jour votre version de CodeQL vers une version plus récente, il peut aussi être nécessaire de passer à une version plus récente du pack de requêtes. Les versions plus récentes de CodeQL peuvent présenter des performances dégradées quand elles sont utilisées avec des packs de requêtes qui ont été épinglés à une version très ancienne. Pour plus d’informations, consultez « À propos de la compatibilité des packs CodeQL ».

Utilisation d’un pack CodeQL pour analyser une base de données CodeQL

Pour analyser une base de données CodeQL avec un pack CodeQL, exécutez la commande suivante :

codeql database analyze <database> <scope>/<pack>@x.x.x:<path>

• <database> : base de données CodeQL à analyser.
• <scope> : nom de l’organisation GitHub sur laquelle le pack est publié.
• <pack> : nom du pack que vous utilisez.
• @x.x.x : numéro de version facultatif. S’il est omis, c’est la dernière version qui est utilisée.
• :<path> : chemin facultatif d’une requête, d’un répertoire ou d’une suite de requêtes. S’il est omis, c’est la suite de requêtes par défaut du pack qui est utilisée.

La commande analyze exécute la suite par défaut des packs CodeQL spécifiés. Vous pouvez spécifier plusieurs packs CodeQL à utiliser pour analyser une base de données CodeQL. Par exemple :

codeql <database> analyze <scope>/<pack> <scope>/<other-pack>

À propos de la compatibilité des packs CodeQL

Quand un pack de requêtes est publié, il inclut des représentations précompilées de toutes les requêtes qu’il contient. Ces requêtes précompilées s’exécutent en général beaucoup plus vite que le temps nécessaire pour compiler intégralement la source QL pendant l’analyse. Cependant, les requêtes précompilées dépendent aussi de certains éléments internes de l’évaluateur QL : si la version de CodeQL qui effectue l’analyse est trop différente de la version qui a exécuté codeql pack publish, il peut donc être nécessaire de compiler les requêtes à partir de la source au lieu de le faire pendant l’analyse. La recompilation se produit automatiquement et n’affecte pas les résultats de l’analyse, mais elle peut néanmoins la ralentir considérablement.

On peut généralement supposer que si un pack est publié avec une version donnée de CodeQL, les requêtes précompilées qu’il contient peuvent être utilisées directement par les versions ultérieures de CodeQL dès lors qu’il n’y a pas plus de 6 mois entre les dates de publication. Nous ferons des efforts raisonnables pour maintenir la compatibilité des nouvelles versions plus longtemps, mais nous ne pouvons pas le garantir.

On peut également supposer qu’un pack publié par la dernière version publique de CodeQL sera utilisable par la version de CodeQL utilisée par le code scanning et GitHub Actions, même s’il s’agit souvent d’une version légèrement plus ancienne.

Par exception à ce qui précède, les packs publiés avec des versions de CodeQL antérieures à 2.12.0 ne sont compatibles avec aucune des versions antérieures ou ultérieures. Ces anciennes versions n’écrivaient pas de requêtes précompilées dans un format qui prend en charge la compatibilité entre les versions. Les packs publiés par ces versions peuvent néanmoins toujours être utilisés par des versions plus récentes, mais l’analyse sera plus lente, car les requêtes doivent d’abord être recompilées.

En tant qu’utilisateur d’un pack de requêtes publié, vous pouvez vérifier que CodeQL utilise les requêtes précompilées qu’il contient en inspectant la sortie du terminal provenant d’une analyse qui utilise le pack de requêtes. S’il contient des lignes ressemblant à ce qui suit, c’est que les requêtes précompilées ont été utilisées avec succès :

[42/108] Loaded /long/path/to/query/Filename.qlx.

Cependant, si elles ressemblent plutôt à ce qui suit, c’est que l’utilisation des requêtes précompilées a échoué :

Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.

Les résultats de l’analyse seront néanmoins corrects dans ce cas, mais pour obtenir des performances optimales, vous devrez peut-être effectuer une mise à niveau vers une version plus récente de CodeQL CLI et/ou du pack de requêtes.

Si vous publiez des packs de requêtes sur le Container registry sur GitHub.com pour que d’autres utilisateurs les utilisent, nous vous recommandons d’utiliser une version récente de CodeQL pour exécuter codeql pack publish, et de publier une nouvelle version de votre pack avec une version mise à jour de CodeQL avant que la version que vous avez utilisée ne soit plus ancienne de 6 mois. De cette façon, vous pouvez garantir que les utilisateurs de votre pack qui conservent leur CodeQL à jour bénéficieront des requêtes précompilées dans votre pack.

Si vous publiez des packs de requêtes avec l’intention de les utiliser sur une installation de GitHub Enterprise Server qui utilise ses fichiers binaires CodeQL en bundle, utilisez la même version de CodeQL pour exécuter codeql pack publish. Les versions plus récentes peuvent produire des requêtes précompilées que la version de GitHub Enterprise Server peut ne pas reconnaître. Votre administrateur GitHub Enterprise Server peut choisir de mettre à niveau périodiquement vers une version plus récente de CodeQL. Si c’est le cas, suivez leur exemple.

Authentification auprès des Container registries GitHub

Vous pouvez publier des packs et télécharger des packs privés en vous authentifiant auprès du Container registry GitHub approprié.

Vous pouvez vous authentifier auprès du Container registry sur GitHub.com de deux façons :

1. Passer l’option --github-auth-stdin à CodeQL CLI, puis fournir un jeton GitHub Apps ou un personal access token via une entrée standard.
2. Définir la variable d’environnement GITHUB_TOKEN sur un jeton GitHub Apps ou un personal access token.