Publication et utilisation de packs CodeQL

Partagez ou téléchargez un ensemble CodeQL, puis analysez votre base de données CodeQL.

Qui peut utiliser cette fonctionnalité ?

CodeQL est disponible pour les types de référentiels suivants :

Dans cet article

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

Vous pouvez vous authentifier auprès du Container registry 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.

Publication de votre pack CodeQL

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

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

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

  • Un maximum d’une defaultSuite ou d’un defaultSuiteFile 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.

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 « Modification de la configuration d’installation par défaut » et « Configuration du contrôle d’accès et de la visibilité d’un package ».

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

  •         `<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 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>

  •         `<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>

Remarque

La commande codeql pack download stocke le pack qu’elle télécharge à un emplacement interne qui n’est pas destiné à la modification locale. Un comportement inattendu (et difficile à résoudre) peut se produire si le pack est modifié après le téléchargement. Pour plus d'informations sur la personnalisation des packs, veuillez consulter la section Création et utilisation de packs CodeQL.