Informations de référence sur les packs de requêtes CodeQL

Compatibilité des packs CodeQL

Lorsqu’un pack de requêtes est publié, il inclut des représentations précompilées de toutes les requêtes qu’il contient pour augmenter la vitesse d’analyse. Toutefois, si la version de CodeQL qui effectue l’analyse est supérieure à 6 mois plus récente que la version exécutée codeql pack publish, il peut être nécessaire de compiler les requêtes à partir de la source pendant l’analyse, ce qui ralentit considérablement le processus.

Un pack publié par la dernière version publique de CodeQL sera utilisable par la version de CodeQL utilisée par code scanning et GitHub Actions, même si c’est souvent une version légèrement plus ancienne.

Si votre analyse contient des lignes comme suit, CodeQL utilise correctement des requêtes précompilées :

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

Si votre analyse contient plutôt des lignes qui ressemblent à ce qui suit, alors CodeQL a recompilé manuellement les requêtes à partir de la source :

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

Pour aider les utilisateurs de votre pack de requêtes à tirer parti des requêtes précompilées, nous vous recommandons d’utiliser une version récente de CodeQL pour publier vos packs. En outre, vous devez publier une nouvelle version de votre pack avec une version mise à jour de CodeQL tous les 6 mois.

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.

          `qlpack.yml` fichiers

Lors de l’exécution de commandes liées à la requête, CodeQL examine d’abord les répertoires voisins du répertoire d’installation (et leurs sous-répertoires) pour des fichiers qlpack.yml, puis vérifie le cache des paquets pour les packs CodeQL téléchargés. Cela signifie que lorsque vos packages locaux dans le répertoire d’installation remplacent les packages du même nom dans le cache du package, vous pouvez donc 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.

          `qlpack.yml` propriétés

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`

Requis par les packs de modèles.
Prend une liste de modèles glob qui spécifient où se trouvent les fichiers d'extension de données par rapport à la racine du pack de requêtes ou du pack de bibliothèques.

`dependencies`

Requis par 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 de la version à utiliser ou si cela n'a pas d'importance, vous pouvez utiliser "*", ce qui indique que n'importe quelle version de cette dépendance est compatible avec ce pack. En pratique, cela correspondra généralement à 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 présente 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`

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

`groups`

Optionnel.
Définit des groupements 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 publiera tous les packs du groupe java, sauf les packs experimental. Vous pouvez exécuter la commande codeql pack ls --groups [-]<group>[,[-]<group>...] pour répertorier les packs d'un espace de travail qui correspondent à l'ensemble de groupes spécifié.

Un pack CodeQL dans l'espace de travail donné est inclus dans la liste si :
- Il se trouve dans au moins l’un des groupes listés sans signe moins (cette condition est automatiquement remplie s’il n’y a aucun groupe listé sans signe moins), et
- Il n'est dans aucun groupe répertorié 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 indiquant le nom du pack, sans fournir le chemin complet.
Actuellement pris en charge uniquement pour les packs de requêtes standard inclus dans le bundle de la CLI CodeQL.
Cette option n'est pas prise en charge pour les packs CodeQL téléchargés depuis le container registry 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 le test des requêtes, veuillez consulter la section 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`

En option, en cours de clôture. 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`

Optionnel. 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 depuis CodeQL CLI v2.13.2. Par exemple:
```
warnOnImplicitThis: true
```

          `codeql-pack.lock.yml` fichiers

          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 depuis la source, veuillez consulter la section À 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 personnalisés CodeQL

Vous devez enregistrer des fichiers pour les requêtes personnalisées et les tests dans des packs distincts, et organiser des packs personnalisés en dossiers spécifiques pour chaque langue cible.

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 codeql/cpp-all de 0.1.2 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

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 codeql/cpp-all de 0.1.2 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.

Exemple de dépôt 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 à la CodeQL CLI et doivent uniquement être définies dans le pack de requêtes CodeQL principal 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](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#source-dependencies).

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

Informations de référence sur les packs de requêtes CodeQL

Qui peut utiliser cette fonctionnalité ?

Dans cet article

Compatibilité des packs CodeQL

`name`

`version`

`dataExtensions`

`dependencies`

`defaultSuiteFile`

`defaultSuite`

`extensionTargets`

`groups`

`library`

`suites`

`tests`

`extractor`

`authors`

`license`

`description`

`libraryPathDependencies`

`dbscheme`

`upgrades`

`warnOnImplicitThis`

Exemples de packs personnalisés CodeQL

Packs CodeQL pour les bibliothèques personnalisées

Packs CodeQL pour les requêtes personnalisées

Packs CodeQL pour les tests personnalisés

Exemple de dépôt CodeQL dans le dépôt CodeQL

Pack de bibliothèques de base

Pack de requêtes de base

Tests pour le pack CodeQL de base