Skip to main content

Publication et utilisation de packs CodeQL

Vous pouvez publier vos propres packs CodeQL et utiliser des packs publiés par d’autres personnes.

Qui peut utiliser cette fonctionnalité ?

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

Utilisation de packs CodeQL sur GitHub Enterprise Cloud avec résidence des données

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 les packs CodeQL dans un Container registry sur GitHub Enterprise Cloud avec résidence des données en créant un fichier qlconfig.yml pour indiquer à la console 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 paquet. Par exemple, le fichier suivant qlconfig.yml associe tous les paquets avec le Container registry à SUBDOMAIN.ghe.com, sauf les paquets correspondant à codeql/\* ou à other-org/* de l’entreprise, 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 `SUBDOMAIN.ghe.com`
  url: https://containers.SUBDOMAIN.ghe.com

CodeQL CLI va déterminer quel registre utiliser pour un nom de package donné en recherchant le premier élément de la liste registries avec une propriété packages 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é packages 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 registries peut également être placée à l’intérieur d’un fichier codeql-workspace.yml. 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 registries dans codeql-workspace.yml sera fusionnée avec la liste dans le fichier global qlconfig.ymlsera prioritaire. Pour plus d’informations sur codeql-workspace.yml, consultez À propos des espaces de travail CodeQL.

Vous pouvez désormais utiliser codeql pack publish, codeql pack download, et codeql database analyze pour gérer les packs sur GitHub Enterprise Cloud avec résidence des données.

Authentification auprès des GitHub Container registries

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 de Container registries on GitHub.com

Vous pouvez vous authentifier auprès de Container registry de deux manières :

  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.

Authentification auprès de Container registries sur GitHub Enterprise Cloud avec résidence des données

De même, vous pouvez vous authentifier auprès d’un Container registry sur GitHub Enterprise Cloud avec résidence des données, ou vous authentifier auprès de plusieurs registres simultanément (pour télécharger ou exécuter des packs privés depuis plusieurs registres, par exemple) de deux manières :

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

Une chaîne d’authentification de registre est constituée d’une liste séparée par des virgules de paires <registry-url>=<token>, où registry-url est une URL de Container registry, telle que https://containers.SUBDOMAIN.ghe.com, et token est un jeton de 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 de registre suivante spécifie que les CodeQL CLI doivent s’authentifier comme suit :

  • Utilisez le jeton <token1> pour vous authentifier auprès de Container registry sur GitHub.com.
  • Utilisez le jeton <token2> pour vous authentifier auprès du Container registry de l’entreprise, à https://containers.SUBDOMAIN.ghe.com.
https://ghcr.io/v2/=<token1>,https://containers.SUBDOMAIN.ghe.com=<token2>

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.

Note

Si vous publiez des packs de modèles sur les GitHub Container registry 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 du 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 ».

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>

Note

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 les packs de personnalisation, consultez Création et utilisation de packs CodeQL.

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

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

À propos des fichiers qlpack.yml

Durant l’exécution de commandes liées aux requêtes, CodeQL recherche d’abord les fichiers qlpack.yml dans les répertoires frères du répertoire d’installation (et leurs sous-répertoires). Ensuite, il recherche dans le cache de package les packs CodeQL qui ont été téléchargés. Cela signifie que quand vous développez des requêtes localement, les packages locaux dans le répertoire d’installation remplacent les packages du même nom dans le cache de package pour que vous puissiez tester vos modifications locales.

Les métadonnées de chaque fichier qlpack.yml indiquent à CodeQL comment compiler les requêtes dans le pack, les bibliothèques dont dépend le pack et où trouver les définitions des suites de requêtes.

Le contenu du pack CodeQL (requêtes ou bibliothèques utilisées dans l’analyse CodeQL) est inclus dans le même répertoire que qlpack.yml ou dans ses sous-répertoires.

Le répertoire contenant le fichier qlpack.yml sert de répertoire racine pour le contenu du pack CodeQL. Autrement dit, pour tous les fichiers .ql et .qll du pack, CodeQL résout toutes les instructions d’importation relatives au répertoire contenant le fichier qlpack.yml à la racine du pack.

Propriétés qlpack.yml

Les propriétés suivantes sont prises en charge dans les fichiers qlpack.yml.

name

  • Nécessaire pour tous les packs.

  • Définit l’étendue du pack, où le pack CodeQL est publié et le nom du pack défini avec des caractères alphanumériques et des traits d’union. Elle doit être unique, car CodeQL ne peut pas faire la différence entre des packs CodeQL ayant des noms identiques. Utilisez le nom du pack pour spécifier les requêtes à exécuter à l’aide de database analyze et pour définir des dépendances entre les packs CodeQL (consultez les exemples ci-dessous). Par exemple :

    name: octo-org/security-queries
    

version

  • Nécessaire pour tous les packs publiés.

  • Définit une version sémantique pour ce pack CodeQL, qui doit respecter la spécification SemVer v2.0.0. Par exemple :

    version: 0.0.0
    

dataExtensions

  • Nécessaire pour les packs de modèles.
  • Prend une liste de modèles Glob qui spécifie l'emplacement des fichiers d'extension de données par rapport à la racine du pack de requêtes ou du pack de bibliothèques.

dependencies

  • Nécessaire pour les packs de requêtes et de bibliothèques qui définissent des dépendances de package CodeQL sur d’autres packs. Les packs de modèles ne peuvent pas définir de dépendances et utilisent extensionTargets à la place.

  • Définit un mappage entre les références de pack et la plage de versions sémantiques compatible avec ce pack. Prise en charge pour les versions v2.6.0 et ultérieures de CodeQL CLI. Par exemple :

    dependencies:
      codeql/cpp-all: ^0.0.2
    

    Si vous n’êtes pas sûr ou que n’importe quelle version peut être utilisée, vous pouvez utiliser "*", ce qui indique que toute version de cette dépendance sont compatibles avec ce pack. Dans la pratique, cela se résout généralement en la version publiée la plus élevée de la dépendance.

    Il existe un espace réservé de version spécial, ${workspace}, qui indique que ce pack CodeQL dépend de la version de la dépendance qui est dans le même espace de travail. Pour plus d’informations, consultez « À propos des espaces de travail CodeQL ».

defaultSuiteFile

  • Nécessaire pour les packs qui exportent un ensemble de requêtes par défaut à exécuter.

  • Définit le chemin d’accès à un fichier de suites de requêtes par rapport à la racine du package, contenant toutes les requêtes exécutées par défaut lorsque ce pack est passé à la commande codeql database analyze. Prise en charge à partir de la version v2.6.0 de l’interface CLI. Un seul defaultSuiteFile ou defaultSuite peut être défini. Par exemple :

    defaultSuiteFile: cpp-code-scanning.qls
    

defaultSuite

  • Nécessaire pour les packs qui exportent un ensemble de requêtes par défaut à exécuter.

  • Définit une suite de requêtes inlined contenant toutes les requêtes exécutées par défaut quand ce pack est transféré à la commande codeql database analyze. Prise en charge à partir de la version v2.6.0 de l’interface CLI. Un seul defaultSuiteFile ou defaultSuite peut être défini. Par exemple :

    defaultSuite:
      queries: .
      exclude:
        precision: medium
    

extensionTargets

  • Nécessaire pour les packs de modèles.
  • Déclare à quels packs de requêtes s'appliquent les extensions du pack de modèles. Le pack d'extension injectera ses extensions de données dans chaque pack nommé dans l’ensemble de clés extensionTargets, si le pack se situe dans la plage de versions spécifiée et s'il est utilisé dans l'évaluation.

groups

  • facultatif.

  • Définit des regroupements logiques de packs dans un espace de travail CodeQL. L’utilisation de groupes est un moyen d’appliquer des opérations de pack à des sous-ensembles de packs dans un espace de travail. Par exemple, le pack suivant est défini comme faisant partie des groupes java et experimental :

    groups:
      - java
      - experimental
    

    L’exécution de codeql pack publish --groups java,-experimental publie tous les packs dans le groupe java, à l’exception des packs experimental. Vous pouvez exécuter la commande codeql pack ls --groups [-]<group>[,[-]<group>...] pour répertorier les packs dans un espace de travail qui correspondent à l’ensemble spécifié de groupes.

    Un pack CodeQL dans l’espace de travail donné est inclus dans la liste si :

    • Il se trouve dans au moins un des groupes cités sans signe moins (cette condition est automatiquement remplie en l’absence de groupe sans signe moins).
    • Il ne se trouve dans aucun groupe listé avec un signe moins.

library

  • Nécessaire pour les packs de bibliothèques.

  • Définit une valeur booléenne qui indique si ce pack est un pack de bibliothèques. Les packs de bibliothèques ne contiennent pas de requête et ne sont pas compilés. Les packs de requêtes peuvent ignorer ce champ ou le définir explicitement sur false. Par exemple :

    library: true
    

suites

  • Facultative pour les packs qui définissent des suites de requêtes. Cela permet aux utilisateurs d’exécuter des suites de requêtes stockées dans le répertoire spécifié en spécifiant le nom du pack, sans fournir le chemin complet.
  • Actuellement pris en charge uniquement pour les packs de requêtes standard inclus dans le pack CLI CodeQL.
  • Cette option n’est pas prise en charge pour les packs CodeQL téléchargés à partir du registre de conteneurs GitHub.

tests

  • Facultative pour les packs contenant des tests CodeQL. Ignorée pour les packs sans tests.

  • Définit le chemin d’un répertoire dans le pack, contenant les tests (chemin relatif par rapport au répertoire du pack). Utilisez . pour spécifier l’ensemble du pack. Toutes les requêtes de ce répertoire sont exécutées comme tests quand test run est exécuté avec l’option --strict-test-discovery. Ces requêtes sont ignorées par les définitions de suite de requêtes qui utilisent des instructions queries ou qlpack pour demander toutes les requêtes dans un pack particulier. Si cette propriété est manquante, . est utilisé. Par exemple :

    tests: .
    

extractor

  • Nécessaire pour tous les packs contenant des tests CodeQL.

  • Définit l’extracteur de langage CodeQL à utiliser pour l’exécution des tests CodeQL dans le pack. Pour plus d’informations sur les tests de requêtes, consultez Test de requêtes personnalisées. Par exemple :

    extractor: javascript-typescript
    

authors

  • Optionnel.

  • Définit les métadonnées qui seront affichées sur la page de recherche relative à l’empaquetage dans la section des packages du compte dans lequel le pack CodeQL est publié. Par exemple :

    authors: author1@github.com,author2@github.com
    

license

  • Optionnel.

  • Définit les métadonnées qui seront affichées sur la page de recherche relative à l’empaquetage dans la section des packages du compte dans lequel le pack CodeQL est publié. Pour obtenir la liste des licences autorisées, consultez la liste des licences SPDX dans la spécification SPDX. Par exemple :

    license: MIT
    

description

  • Optionnel.

  • Définit les métadonnées qui seront affichées sur la page de recherche relative à l’empaquetage dans la section des packages du compte dans lequel le pack CodeQL est publié. Par exemple :

    description: Human-readable description of the contents of the CodeQL pack.
    

libraryPathDependencies

  • Facultative, dépréciée. Utilisez plutôt la propriété dependencies.

  • Précédemment utilisée pour définir les noms des packs CodeQL dont ce pack CodeQL dépend, sous forme de tableau. Elle permet au pack d’accéder à toutes les bibliothèques, à tout schéma de base de données et à toutes les suites de requêtes définis dans la dépendance. Par exemple :

    libraryPathDependencies: codeql/javascript-all
    

dbscheme

  • Nécessaire pour les packs de langages de base uniquement.

  • Définit le chemin du schéma de base de données pour toutes les bibliothèques et requêtes écrites pour ce langage CodeQL (consultez l’exemple ci-dessous). Par exemple :

    dbscheme: semmlecode.python.dbscheme
    

upgrades

  • Nécessaire pour les packs de langages de base uniquement.

  • Définit le chemin d’un répertoire dans le pack, contenant les scripts de mise à niveau de base de données (chemin relatif par rapport au répertoire du pack). Les mises à niveau de base de données sont utilisées en interne pour garantir qu’une base de données créée avec une version différente de CodeQL CLI est compatible avec la version actuelle de l’interface CLI. Par exemple :

    upgrades: .
    

warnOnImplicitThis

  • facultatif. La valeur par défaut est false si la propriété warnOnImplicitThis n’est pas définie.

  • Définit une valeur booléenne qui spécifie si le compilateur doit émettre des avertissements sur les appels de prédicat membres avec des récepteurs d’appels implicites this, c’est-à-dire sans récepteur explicite. Disponible à partir de CodeQL CLI v2.13.2. Par exemple :

    warnOnImplicitThis: true
    

À propos des fichiers codeql-pack.lock.yml

Les fichiers codeql-pack.lock.yml stockent les versions des dépendances transitives résolues d’un pack CodeQL. Ce fichier est créé par la commande codeql pack install s’il n’existe pas déjà et doit être ajouté à votre système de gestion de versions. La section dependencies du fichier qlpack.yml contient des plages de versions compatibles avec le pack. Le fichier codeql-pack.lock.yml verrouille les dépendances sur des versions précises. Ceci garantit que quand codeql pack install est exécuté sur ce pack, les mêmes versions des dépendances sont systématiquement récupérées, même si des versions compatibles plus récentes existent.

Par exemple, si un fichier qlpack.yml contient les dépendances suivantes :

dependencies:
  codeql/cpp-all: ^0.1.2
  my-user/my-lib: ^0.2.3
  other-dependency/from-source: "*"

Le contenu du fichier codeql-pack.lock.yml ressemblera à ceci :

dependencies:
  codeql/cpp-all:
    version: 0.1.4
  my-user/my-lib:
    version: 0.2.4
  my-user/transitive-dependency:
    version: 1.2.4

La dépendance codeql/cpp-all est verrouillée sur la version 0.1.4. La dépendance my-user/my-lib est verrouillée sur la version 0.2.4. La dépendance my-user/transitive-dependency, qui est une dépendance transitive et qui n’est pas spécifiée dans le fichier qlpack.yml, est verrouillée sur la version 1.2.4. La dépendance other-dependency/from-source est absente du fichier de verrouillage, car elle est résolue à partir de la source. Cette dépendance doit être disponible dans le même espace de travail CodeQL que le pack. Pour plus d’informations sur les espaces de travail CodeQL et la résolution des dépendances à partir de la source, consultez À propos des espaces de travail CodeQL.

Dans la plupart des cas, le fichier codeql-pack.lock.yml est adapté aux packs de requêtes uniquement, car les packs de bibliothèques ne sont pas exécutables et n’ont généralement pas besoin que leurs dépendances transitives soient corrigées. Les packs de bibliothèques contenant des tests font cependant exception. Dans ce cas, le fichier codeql-pack.lock.yml est utilisé afin de garantir que les tests sont toujours exécutés avec les mêmes versions de dépendances pour éviter les faux échecs en cas de disparité des dépendances.

Exemples de packs CodeQL personnalisés

Quand vous écrivez des requêtes ou des tests personnalisés, vous devez les enregistrer dans des packs CodeQL personnalisés. Par souci de simplicité, essayez d’organiser chaque pack logiquement. Pour plus d’informations, consultez « Création et utilisation de packs CodeQL ». Enregistrez les fichiers relatifs aux requêtes et aux tests dans des packs distincts et, si possible, organisez les packs personnalisés dans des dossiers spécifiques pour chaque langage cible. Cette approche est particulièrement utile si vous envisagez de publier vos packs CodeQL pour qu’ils puissent être partagés avec d’autres utilisateurs ou utilisés pour l’analyse du code. Pour plus d’informations, consultez « À propos de l’analyse du code avec CodeQL ».

Packs CodeQL pour les bibliothèques personnalisées

Un pack CodeQL personnalisé contenant des bibliothèques C++ personnalisées sans requête ni test peut avoir un fichier qlpack.yml contenant :

name: my-github-user/my-custom-libraries
version: 1.2.3
library: true
dependencies:
  codeql/cpp-all: ^0.1.2

codeql/cpp-all est le nom du pack CodeQL pour l’analyse C/C++, inclus dans le dépôt CodeQL. La plage de versions ^0.1.2 indique que ce pack est compatible avec la version 0.1.2 de codeql/cpp-all et toutes les versions supérieures ou toutes les versions inférieures à 0.2.0. Tout fichier de bibliothèque CodeQL (fichier avec extension .qll) défini dans ce pack sera disponible pour les requêtes définies dans n’importe quel pack de requêtes incluant ce pack dans son bloc de dépendances.

La propriété library indique que ce pack est un pack de bibliothèques et qu’il ne contient aucune requête.

Packs CodeQL pour les requêtes personnalisées

Un pack CodeQL personnalisé contenant des requêtes et des bibliothèques C++ personnalisées peut avoir un fichier qlpack.yml contenant :

name: my-github-user/my-custom-queries
version: 1.2.3
dependencies:
  codeql/cpp-all: ^0.1.2
  my-github-user/my-custom-libraries: ^1.2.3

codeql/cpp-all est le nom du pack CodeQL pour l’analyse C/C++, inclus dans le dépôt CodeQL. La plage de versions ^0.1.2 indique que ce pack est compatible avec la version 0.1.2 de codeql/cpp-all et toutes les versions supérieures ou toutes les versions inférieures à 0.2.0. my-github-user/my-custom-libraries est le nom d’un pack CodeQL contenant des bibliothèques CodeQL personnalisées pour C++. Tout fichier de bibliothèque CodeQL (fichier avec extension .qll) défini dans ce pack sera disponible pour les requêtes dans le pack my-github-user/my-custom-queries.

Packs CodeQL pour les tests personnalisés

Pour les packs CodeQL personnalisés contenant des fichiers de test, vous devez également inclure une propriété extractor pour que la commande test run sache comment créer les bases de données de test. Vous pouvez également spécifier la propriété tests.

Le fichier qlpack.yml suivant indique que my-github-user/my-query-tests dépend de my-github-user/my-custom-queries dont la version est ultérieure ou égale à 1.2.3 et antérieure à 2.0.0. Il déclare également que l’interface CLI doit utiliser l’extracteur (extractor) Java lors de la création de bases de données de test. La ligne tests: . déclare que tous les fichiers .ql du pack doivent être exécutés en tant que tests quand codeql test run est exécuté avec l’option --strict-test-discovery. En général, les packs de test ne contiennent pas de propriété version. Cela vous empêche de les publier accidentellement.

name: my-github-user/my-query-tests
dependencies:
  my-github-user/my-custom-queries: ^1.2.3
extractor: java-kotlin
tests: .

Pour plus d’informations sur l’exécution des tests, consultez Test de requêtes personnalisées.

Exemples de packs CodeQL dans le dépôt CodeQL

Il existe quatre packs CodeQL principaux pour chacun des langages dans le dépôt CodeQL :

  • Pack de bibliothèques de base pour le langage avec le schéma de base de données utilisé par le langage, les bibliothèques CodeQL et les requêtes sous <language>/ql/lib

  • Pack de requêtes de base pour le langage, qui inclut les requêtes par défaut pour le langage avec leurs suites de requêtes sous <language>/ql/src

  • Tests pour les bibliothèques de langages de base et les requêtes sous <language>/ql/test

  • Exemples de requêtes pour le langage sous <language>/ql/examples

Pack de bibliothèques de base

Voici un exemple de fichier qlpack.yml pour le pack de langages de base des bibliothèques d’analyse C/C++ :

name: codeql/cpp-all
version: x.y.z-dev
dbscheme: semmlecode.cpp.dbscheme
library: true
upgrades: upgrades

Quelques remarques supplémentaires sur les propriétés suivantes :

  • library : Indique qu’il s’agit d’un pack de bibliothèques sans requêtes exécutables. Il est uniquement destiné à être utilisé comme dépendance pour d’autres packs.

  • dbscheme et upgrades : Ces propriétés sont internes à CodeQL CLI et doivent être définies uniquement dans le pack de requêtes CodeQL de base pour un langage.

Pack de requêtes de base

Voici un exemple de fichier qlpack.yml pour le pack de requêtes de base des requêtes d’analyse C/C++ :

name: codeql/cpp-queries
version: x.y.z-dev
dependencies:
    codeql/cpp-all: "*"
    codeql/suite-helpers: "*"
suites: codeql-suites
defaultSuiteFile: codeql-suites/cpp-code-scanning.qls

Quelques remarques supplémentaires sur les propriétés suivantes :

  • dependencies : Ce pack de requêtes dépend de codeql/cpp-all et codeql/suite-helpers. Étant donné que ces dépendances sont résolues à partir de la source, la version du pack CodeQL avec laquelle elles sont compatibles n’a pas d’importance. Pour plus d’informations sur la résolution des dépendances à partir de la source, consultez Dépendances sources.

  • suites : Indique le répertoire contenant des suites de requêtes connues.

  • defaultSuiteFile : Nom du fichier de suite de requêtes par défaut utilisé quand aucune suite de requêtes n’est spécifiée.

Tests pour le pack CodeQL de base

Voici un exemple de fichier qlpack.yml pour le pack de tests de base des tests d’analyse C/C++ :

name: codeql/cpp-tests
dependencies:
  codeql/cpp-all: "*"
  codeql/cpp-queries: "*"
extractor: cpp
tests: .

Quelques remarques supplémentaires sur les propriétés suivantes :

  • dependencies : Ce pack dépend des packs de bibliothèques et de requêtes CodeQL de base pour C++.

  • extractor : Spécifie que tous les tests utiliseront le même extracteur C++ pour créer la base de données pour les tests.

  • tests : Spécifie l’emplacement des tests. Dans ce cas, les tests se trouvent dans le dossier racine (et tous les sous-dossiers) du pack.

  • version : Il n’existe aucune propriété version pour le pack de tests. Ceci empêche la publication accidentelle de packs de tests.