À propos des packs CodeQL

À propos des packs CodeQL

Les packs CodeQL sont utilisés pour créer, partager et exécuter des requêtes et des bibliothèques CodeQL ainsi que pour définir une dépendance à celles-ci. Vous pouvez publier vos propres packs CodeQL et télécharger des packs créés par d’autres personnes. Les packs CodeQL contiennent des requêtes, des fichiers de bibliothèque, des suites de requêtes et des métadonnées.

Il existe deux types de packs CodeQL : les packs de requêtes et les packs de bibliothèques.

• Les packs de requêtes sont conçus pour être exécutés. Quand un pack de requêtes est publié, le bundle inclut toutes les dépendances transitives et les représentations précompilées de chaque requête, en plus des sources de requête. Ceci garantit une exécution cohérente et efficace des requêtes dans le pack.

• Les packs de bibliothèques sont conçus pour être utilisés par des packs de requêtes (ou d’autres packs de bibliothèques) et ne contiennent pas de requêtes. Les bibliothèques ne sont pas compilées séparément.

Vous pouvez utiliser les commandes de gestion de package dans CodeQL CLI pour créer des packs CodeQL, ajouter des dépendances aux packs et installer ou mettre à jour des dépendances. Pour plus d’informations, consultez « Création et utilisation des packs CodeQL ». Vous pouvez également publier et télécharger des packs CodeQL à l’aide de CodeQL CLI. Pour plus d’informations, consultez « Publication et utilisation de packs CodeQL ».

Les packages CodeQL standard pour tous les langages pris en charge sont publiés dans le Container registry. Le dépôt CodeQL contient des fichiers sources pour les packs CodeQL standard pour tous les langages pris en charge.

Structure des packs CodeQL

Un pack CodeQL doit contenir un fichier nommé qlpack.yml dans son répertoire racine. Dans le fichierqlpack.yml, le champ name: doit avoir une valeur au format <scope>/<pack>, où <scope> est le compte d’organisation ou d’utilisateur GitHub dans lequel le pack sera publié et <pack> le nom du pack. En outre, les packs de requêtes et les packs de bibliothèques avec des tests CodeQL contiennent un fichier codeql-pack.lock.yml contenant les dépendances résolues du pack. Ce fichier est généré durant un appel à la commande codeql pack install, n’est pas destiné à être modifié manuellement et doit être ajouté à votre système de gestion de versions.

Les autres fichiers et répertoires au sein du pack doivent être organisés logiquement. Par exemple, en général :

• Les requêtes sont organisées en répertoires pour des catégories spécifiques.

• Les requêtes pour des produits, des bibliothèques et des infrastructures spécifiques sont organisées dans leurs propres répertoires de niveau supérieur.

À 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. Durant l’analyse d’une base de données avec une requête d’un pack publié, CodeQL charge ces fichiers au lieu de la source .ql. 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.

À 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
  

dependencies

• Nécessaire pour les packs qui définissent des dépendances de package CodeQL sur d’autres packs.
• 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`
  

defaultSuiteFile

• Required by packs that export a set of default queries to run.
• Defines the path to a query suite file relative to the package root, containing all of the queries that are run by default when this pack is passed to the codeql database analyze command. Supported from CLI version v2.6.0 and onwards. Only one of defaultSuiteFile or defaultSuite can be defined. For example:

  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
  

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.
• Définit le chemin d’un répertoire dans le pack, contenant les suites de requêtes que vous souhaitez faire connaître de CodeQL CLI (chemin relatif par rapport au répertoire du pack). Les utilisateurs du pack CodeQL peuvent exécuter des suites connues stockées dans ce répertoire en spécifiant le nom du pack sans fournir leur chemin complet. Ceci n’est pas pris en charge pour les packs CodeQL téléchargés à partir du registre de conteneurs. Pour plus d’informations sur les suites de requêtes, consultez « Création de suites de requêtes CodeQL ». Par exemple :

  suites: octo-org-query-suites
  

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 le test des requêtes, consultez « Test des requêtes personnalisées ». Par exemple :

  extractor: javascript
  

authors

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

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

• facultatif.
• 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: .
  

À 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 « Structure des 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

où 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
suites: my-custom-suites

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

La propriété suites indique un répertoire où se trouvent des suites de requêtes connues. Ces suites peuvent être utilisées sur la ligne de commande en faisant référence à leur nom uniquement et non à leur chemin complet. Pour plus d’informations sur les suites de requêtes, consultez « Création de suites de requêtes CodeQL ».

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

Pour plus d’informations sur l’exécution de tests, consultez « Test des 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 QL 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.