Publication et utilisation de packs CodeQL

Utilisation des packs CodeQL sur GitHub Enterprise Server

Par défaut, CodeQL CLI s’attend à télécharger des packs CodeQL depuis Container registry sur GitHub.com et à publier des packs sur celui-ci. Cependant, vous pouvez également utiliser des packs CodeQL dans un Container registry sur GitHub Enterprise Server en créant un fichier pour indiquer à la CLI quel Container registry utiliser pour chaque pack.

Créez un fichier ~/.codeql/qlconfig.yml sur Linux/MacOS ou %HOMEPATH%\.codeql\qlconfig.yml sur Windows à l’aide de votre éditeur de texte préféré, puis ajoutez des entrées pour spécifier le registre à utiliser pour un ou plusieurs modèles de nom de package. Par exemple, le fichier suivant associe tous les packs au Container registry à l'emplacement , à l'exception des packs correspondant à ou à l'organisation , qui sont associés au Container registry sur GitHub.com :

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  # Container registry on GitHub.com
  url: https://ghcr.io/v2/
- packages: '*'
  # Container registry hosted at `https://GHE_HOSTNAME`
  url: https://containers.GHE_HOSTNAME/v2/

CodeQL CLI va déterminer quel registre utiliser pour un nom de package donné en recherchant le premier élément de la liste avec une propriété qui correspond à ce nom de package. Cela signifie que vous allez généralement d’abord définir les modèles de nom de package les plus spécifiques. La propriété peut être un seul nom de package, un modèle Glob, ou une liste YAML de noms de package et de modèles Glob.

La liste peut également être placée dans un fichier . Procéder ainsi vous permet de définir les registres à utiliser dans un espace de travail spécifique, afin qu’il puisse être partagé entre d’autres utilisateurs CodeQL de l’espace de travail. La liste dans sera fusionnée avec la liste dans le global et aura priorité sur celle-ci. Pour plus d’informations sur , consultez AUTOTITLE.

Vous pouvez désormais utiliser , et pour gérer les packs sur GitHub Enterprise Server.

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 GitHub Container registry approprié.

Authentification auprès des Container registries sur GitHub.com

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

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

Authentification auprès des Container registries sur GitHub Enterprise Server

De même, vous pouvez vous authentifier auprès d'un Container registry sur GitHub Enterprise Server, ou vous authentifier auprès de plusieurs registres simultanément (par exemple, pour télécharger ou exécuter des packs privés depuis plusieurs registres) de deux façons :

Passer l’option à CodeQL CLI, puis fournir une chaîne d’authentification de registre via une entrée standard.
Définir la variable d’environnement sur une chaîne d’authentification de registre.

Une chaîne d'authentification du registre est une liste de paires séparées par des virgules, où est une URL Container registry, telle que , et est un token GitHub Apps ou personal access token pour ce Container registry. Ceci garantit que chaque jeton est passé seulement au Container registry que vous spécifiez.

Par exemple, la chaîne d'authentification du registre suivante indique que la CodeQL CLI doit s'authentifier comme suit :

Utilisez le token pour vous authentifier auprès du Container registry sur GitHub.com.
Utilisez le token pour vous authentifier auprès du Container registry de l'entreprise à l'emplacement .

https://ghcr.io/v2/=<token1>,https://containers.GHE_HOSTNAME/v2/=<token2>

Publication de votre CodeQL pack

Pour partager votre pack CodeQL à d'autres personnes, vous pouvez le publier sur le registre Container registry.

Configuration du fichier avant la publication

Vous pouvez vérifier et modifier les détails de configuration de votre pack CodeQL avant la publication. Ouvrez le fichier 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>
defaultSuite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
defaultSuiteFile: 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

doit avoir le format , où est l’organisation GitHub dans laquelle vous allez publier et est le nom du pack.
Un maximum d’une ou d’un 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

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 .

Remarque

Si vous publiez des packs de modèles dans le Container registry GitHub afin d'étendre la couverture à tous les référentiels d'une organisation dans le cadre d'une configuration d'installation par défaut, vous devez vous assurer que les référentiels exécutant l'analyse de code peuvent accéder à ces packs de modèles. Pour plus d’informations, consultez « AUTOTITLE » et « AUTOTITLE ».

Téléchargement d'un pack existant de CodeQL

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

: nom de l’organisation GitHub à partir de laquelle vous allez télécharger.
: nom du pack que vous voulez télécharger.
: 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 le téléchargement d'une version particulière d'un pack de requêtes, gardez à l'esprit que lorsque vous mettez à jour votre version de CodeQL vers une version plus récente, vous devrez peut-être également 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, veuillez consulter la section À 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>

: base de données CodeQL à analyser.
: nom de l’organisation GitHub sur laquelle le pack est publié.
: nom du pack que vous utilisez.
: numéro de version facultatif. S’il est omis, c’est la dernière version qui est utilisée.
: 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 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>