{"meta":{"title":"Informations de référence sur les packs de requêtes CodeQL","intro":"Comprendre la compatibilité, le contenu et la structure des CodeQL packs.","product":"Sécurité et qualité du code","breadcrumbs":[{"href":"/fr/code-security","title":"Sécurité et qualité du code"},{"href":"/fr/code-security/reference","title":"Reference"},{"href":"/fr/code-security/reference/code-scanning","title":"Analyse du code"},{"href":"/fr/code-security/reference/code-scanning/codeql","title":"CodeQL"},{"href":"/fr/code-security/reference/code-scanning/codeql/codeql-cli","title":"Interface de ligne de commande CLI CodeQL"},{"href":"/fr/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs","title":"Packs de requêtes CodeQL"}],"documentType":"article"},"body":"# Informations de référence sur les packs de requêtes CodeQL\n\nComprendre la compatibilité, le contenu et la structure des CodeQL packs.\n\n## CodeQL Compatibilité des packs\n\nLorsqu’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 celle-ci 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 CodeQL la source pendant l’analyse, ce qui ralentit considérablement le processus.\n\nUn paquet publié par la *version publique la plus récente* de CodeQL sera utilisable par la version de CodeQL utilisée par code scanning et GitHub Actions, bien qu’il s’agisse souvent d’une version légèrement plus ancienne.\n\nSi votre analyse contient des lignes comme celles-ci, elle CodeQL utilise correctement des requêtes précompilées :\n\n```shell\n[42/108] Loaded /long/path/to/query/Filename.qlx.\n```\n\nSi votre analyse contient plutôt des lignes qui ressemblent à ce qui suit, recompilez CodeQL manuellement les requêtes à partir de la source :\n\n```shell\nCompiling query plan for /long/path/to/query/Filename.ql.\n[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.\n```\n\nPour 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 CodeQL tous les 6 mois.\n\nSi vous publiez des packs de requêtes avec l’intention de les utiliser sur une GitHub Enterprise Server installation qui utilise ses fichiers binaires groupés CodeQL , utilisez la même CodeQL version pour l’exécuter `codeql pack publish`.\n\n## `qlpack.yml` fichiers\n\nLors de l’exécution de commandes liées à la requête, CodeQL examine d’abord les frères du répertoire d’installation (et leurs sous-répertoires) pour les `qlpack.yml` fichiers, puis vérifie le cache du package pour les packs téléchargés CodeQL . 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.\n\nLes métadonnées de chaque `qlpack.yml` fichier indiquent CodeQL comment compiler les requêtes dans le pack, les bibliothèques dont dépend le pack et où trouver des définitions de suite de requêtes.\n\nLe contenu du CodeQL pack (requêtes ou bibliothèques utilisées dans CodeQL l’analyse) est inclus dans le même répertoire que `qlpack.yml`, ou ses sous-répertoires.\n\nLe répertoire contenant le `qlpack.yml` fichier sert de répertoire racine pour le contenu du CodeQL pack. Autrement dit, pour tous les fichiers `.ql` et `.qll` du pack, CodeQL résoudra toutes les instructions d’import par rapport au répertoire contenant le fichier `qlpack.yml` à la racine du pack.\n\n### `qlpack.yml` propriétés\n\nLes propriétés suivantes sont prises en charge dans les fichiers `qlpack.yml`.\n\n#### `name`\n\n* Nécessaire pour tous les packs.\n* Définit l’étendue du pack, où le CodeQL pack est publié et le nom du pack défini à l’aide de caractères alphanumériques et de traits d’union. Il doit être unique, car CodeQL il ne peut pas différencier les CodeQL packs avec des noms identiques. Utilisez le nom du pack pour spécifier les requêtes à exécuter `database analyze` et définir des dépendances entre CodeQL les packs (voir les exemples ci-dessous). Par exemple:\n\n  ```yaml\n  name: octo-org/security-queries\n  ```\n\n#### `version`\n\n* Nécessaire pour tous les packs publiés.\n* Définit une version sémantique pour ce CodeQL pack qui doit respecter la [spécification SemVer v2.0.0](https://semver.org/spec/v2.0.0.html). Par exemple:\n\n  ```yaml\n  version: 0.0.0\n  ```\n\n#### `dataExtensions`\n\n* Requis par les packs de modèles.\n* 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.\n\n#### `dependencies`\n\n* Requis par les packs de requêtes et de bibliothèque qui définissent des dépendances de packages CodeQL vis-à-vis d’autres packs. Les packs de modèles ne peuvent pas définir de dépendances et utilisent `extensionTargets` à la place.\n* Définit un mappage entre les références de pack et la plage de versions sémantiques compatible avec ce pack. Compatible avec CodeQL CLI les versions v2.6.0 et ultérieures. Par exemple:\n\n  ```yaml\n  dependencies:\n    codeql/cpp-all: ^0.0.2\n  ```\n\n  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.\n\n  Il existe un espace réservé de version spécial, `${workspace}`, qui indique que ce CodeQL package dépend de la version de la dépendance présente dans le même espace de travail, quelle qu’elle soit. Pour plus d’informations, consultez « [Espaces de travail CodeQL](/fr/code-security/concepts/code-scanning/codeql/codeql-workspaces#using-workspace-as-a-version-range-in-qlpackyml-files) ».\n\n#### `defaultSuiteFile`\n\n* Nécessaire pour les packs qui exportent un ensemble de requêtes par défaut à exécuter.\n* 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:\n\n  ```yaml\n  defaultSuiteFile: cpp-code-scanning.qls\n  ```\n\n#### `defaultSuite`\n\n* Nécessaire pour les packs qui exportent un ensemble de requêtes par défaut à exécuter.\n* 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:\n\n  ```yaml\n  defaultSuite:\n    queries: .\n    exclude:\n      precision: medium\n  ```\n\n#### `extensionTargets`\n\n* Requis par les packs de modèles.\n* 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.\n\n#### `groups`\n\n* Optionnel.\n* Définit des regroupements logiques de packs dans un CodeQL espace de travail. 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` :\n\n  ```yaml\n  groups:\n    - java\n    - experimental\n  ```\n\n  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é.\n\n  Un CodeQL pack dans l’espace de travail donné est inclus dans la liste si :\n\n  * 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\n  * Il n'est dans aucun groupe répertorié avec un signe moins.\n\n#### `library`\n\n* Nécessaire pour les packs de bibliothèques.\n* 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:\n\n  ```yaml\n  library: true\n  ```\n\n#### `suites`\n\n* 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.\n* Actuellement pris en charge uniquement pour les packs de requêtes standard inclus dans CodeQL le bundle CLI.\n* Cette option n’est pas prise en charge pour CodeQL les packs téléchargés à partir du GitHub registre de conteneurs.\n\n#### `tests`\n\n* Facultatif pour les packs contenant des CodeQL tests. Ignorée pour les packs sans tests.\n* 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:\n\n  ```yaml\n  tests: .\n  ```\n\n#### `extractor`\n\n* Requis pour tous les packs contenant CodeQL tests.\n* Définit l’extracteur CodeQL de langue à utiliser lors de l’exécution des CodeQL tests dans le pack. Pour plus d'informations sur le test des requêtes, veuillez consulter la section [Test de requêtes personnalisées](/fr/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/test-custom-queries). Par exemple:\n\n  ```yaml\n  extractor: javascript-typescript\n  ```\n\n#### `authors`\n\n* Optionnel.\n* Définit les métadonnées qui seront affichées sur la page de recherche des packages dans la section des packages du compte sur lequel le package CodeQL est publié. Par exemple:\n\n  ```yaml\n  authors: author1@github.com,author2@github.com\n  ```\n\n#### `license`\n\n* Optionnel.\n* Définit les métadonnées qui seront affichées sur la page de recherche des packages dans la section des packages du compte sur lequel le package CodeQL est publié. Pour obtenir la liste des licences autorisées, consultez la [liste des licences SPDX](https://spdx.org/licenses/) dans la spécification SPDX. Par exemple:\n\n  ```yaml\n  license: MIT\n  ```\n\n#### `description`\n\n* Optionnel.\n* Définit les métadonnées qui seront affichées sur la page de recherche des packages dans la section des packages du compte sur lequel le package CodeQL est publié. Par exemple:\n\n  ```yaml\n  description: Human-readable description of the contents of the CodeQL pack.\n  ```\n\n#### `libraryPathDependencies`\n\n* Facultatif, fermeture. Utilisez plutôt la propriété `dependencies`.\n* Précédemment utilisé pour définir, sous forme de tableau, les noms de tous les packs CodeQL dont ce pack CodeQL dépend. 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:\n\n  ```yaml\n  libraryPathDependencies: codeql/javascript-all\n  ```\n\n#### `dbscheme`\n\n* Nécessaire pour les packs de langages de base uniquement.\n* Définit le chemin d’accès au [schéma de base de données](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database-schema) pour toutes les bibliothèques et requêtes écrites pour ce CodeQL langage (voir l’exemple ci-dessous). Par exemple:\n\n  ```yaml\n  dbscheme: semmlecode.python.dbscheme\n  ```\n\n#### `upgrades`\n\n* Nécessaire pour les packs de langages de base uniquement.\n* 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 s’assurer qu’une base de données créée avec une version différente de celle-ci CodeQL CLI est compatible avec la version actuelle de l’interface CLI. Par exemple:\n\n  ```yaml\n  upgrades: .\n  ```\n\n#### `warnOnImplicitThis`\n\n* Optionnel. La valeur par défaut est `false` si la propriété `warnOnImplicitThis` n’est pas définie.\n* 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 la version 2.13.2. Par exemple:\n\n  ```yaml\n  warnOnImplicitThis: true\n  ```\n\n## `codeql-pack.lock.yml` fichiers\n\n`codeql-pack.lock.yml` les fichiers stockent les versions des dépendances transitives résolues d’un CodeQL pack. 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.\n\nPar exemple, si un fichier `qlpack.yml` contient les dépendances suivantes :\n\n```yaml\ndependencies:\n  codeql/cpp-all: ^0.1.2\n  my-user/my-lib: ^0.2.3\n  other-dependency/from-source: \"*\"\n```\n\nLe contenu du fichier `codeql-pack.lock.yml` ressemblera à ceci :\n\n```yaml\ndependencies:\n  codeql/cpp-all:\n    version: 0.1.4\n  my-user/my-lib:\n    version: 0.2.4\n  my-user/transitive-dependency:\n    version: 1.2.4\n```\n\nLa 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 CodeQL espace de travail que le pack. Pour plus d’informations sur CodeQL les espaces de travail et la résolution des dépendances à partir de la source, consultez [Espaces de travail CodeQL](/fr/code-security/concepts/code-scanning/codeql/codeql-workspaces).\n\nDans 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.\n\n## Exemples de packs personnalisés CodeQL\n\nVous 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.\n\n### CodeQL packages pour les bibliothèques personnalisées\n\nUn pack personnalisé CodeQL contenant des bibliothèques C++ personnalisées, sans requêtes ni tests, peut avoir un `qlpack.yml` fichier contenant :\n\n```yaml\nname: my-github-user/my-custom-libraries\nversion: 1.2.3\nlibrary: true\ndependencies:\n  codeql/cpp-all: ^0.1.2\n```\n\noù `codeql/cpp-all` est le nom du CodeQL pack pour l’analyse C/C++ incluse dans le CodeQL référentiel. 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 CodeQL fichier de bibliothèque (un fichier avec une `.qll` extension) défini dans ce pack sera disponible pour les requêtes définies dans n’importe quel pack de requêtes qui inclut ce pack dans son bloc de dépendances.\n\nLa propriété `library` indique que ce pack est un pack de bibliothèques et qu’il ne contient aucune requête.\n\n### CodeQL modules pour les requêtes personnalisées\n\nUn pack personnalisé contenant des requêtes et des bibliothèques C++ personnalisées CodeQL peut avoir un `qlpack.yml` fichier contenant :\n\n```yaml\nname: my-github-user/my-custom-queries\nversion: 1.2.3\ndependencies:\n  codeql/cpp-all: ^0.1.2\n  my-github-user/my-custom-libraries: ^1.2.3\n```\n\noù `codeql/cpp-all` est le nom du CodeQL pack pour l’analyse C/C++ incluse dans le CodeQL référentiel. 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`.\n`my-github-user/my-custom-libraries` est le nom d’un CodeQL pack contenant des bibliothèques personnalisées CodeQL pour C++. Tout CodeQL fichier de bibliothèque (un fichier avec une `.qll` extension) défini dans ce pack sera disponible pour les requêtes dans le `my-github-user/my-custom-queries` pack.\n\n### CodeQL packs pour les tests personnalisés\n\nPour les packs personnalisés CodeQL contenant des fichiers de test, vous devez également inclure une `extractor` propriété afin que la `test run` commande sache comment créer des bases de données de test. Vous pouvez également spécifier la propriété `tests`.\n\nLe 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.\n\n```yaml\nname: my-github-user/my-query-tests\ndependencies:\n  my-github-user/my-custom-queries: ^1.2.3\nextractor: java-kotlin\ntests: .\n```\n\nPour plus d’informations sur l’exécution des tests, consultez [Test de requêtes personnalisées](/fr/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/test-custom-queries).\n\n## Exemples de CodeQL packs dans le CodeQL référentiel\n\nChacune des langues du CodeQL référentiel comporte quatre packs principaux CodeQL :\n\n* Pack de bibliothèques de base pour le langage, avec le schéma de base de données utilisé par le langage, ainsi que les bibliothèques CodeQL et les requêtes sur `<language>/ql/lib`\n\n* 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`\n\n* Tests pour les bibliothèques de langages de base et les requêtes sous `<language>/ql/test`\n\n* Exemples de requêtes pour le langage sous `<language>/ql/examples`\n\n### Pack de bibliothèques de base\n\nVoici un exemple de fichier `qlpack.yml` pour le pack de langages de base des [bibliothèques d’analyse C/C++](https://github.com/github/codeql/blob/main/cpp/ql/lib/qlpack.yml) :\n\n```yaml\nname: codeql/cpp-all\nversion: x.y.z-dev\ndbscheme: semmlecode.cpp.dbscheme\nlibrary: true\nupgrades: upgrades\n```\n\nQuelques remarques supplémentaires sur les propriétés suivantes :\n\n* `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.\n\n* `dbscheme` et `upgrades` : Ces propriétés sont internes au CodeQL CLI et ne doivent être définies que dans le pack de requêtes CodeQL principal pour une langue.\n\n### Pack de requêtes de base\n\nVoici un exemple de fichier `qlpack.yml` pour le pack de requêtes de base des [requêtes d’analyse C/C++](https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml) :\n\n```yaml\nname: codeql/cpp-queries\nversion: x.y.z-dev\ndependencies:\n    codeql/cpp-all: \"*\"\n    codeql/suite-helpers: \"*\"\nsuites: codeql-suites\ndefaultSuiteFile: codeql-suites/cpp-code-scanning.qls\n```\n\nQuelques remarques supplémentaires sur les propriétés suivantes :\n\n* `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, il n’importe pas avec quelle version du CodeQL pack elles sont compatibles. Pour plus d’informations sur la résolution des dépendances à partir de la source, consultez [Dépendances sources](/fr/code-security/concepts/code-scanning/codeql/codeql-workspaces#source-dependencies).\n\n* `suites` : Indique le répertoire contenant des suites de requêtes connues.\n\n* `defaultSuiteFile` : Nom du fichier de suite de requêtes par défaut utilisé quand aucune suite de requêtes n’est spécifiée.\n\n### Tests pour le pack principal CodeQL\n\nVoici un exemple de fichier `qlpack.yml` pour le pack de tests de base des [tests d’analyse C/C++](https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml) :\n\n```yaml\nname: codeql/cpp-tests\ndependencies:\n  codeql/cpp-all: \"*\"\n  codeql/cpp-queries: \"*\"\nextractor: cpp\ntests: .\n```\n\nQuelques remarques supplémentaires sur les propriétés suivantes :\n\n* `dependencies`: ce pack dépend des CodeQL principaux packs de requête et de bibliothèque pour C++.\n\n* `extractor` : Spécifie que tous les tests utiliseront le même extracteur C++ pour créer la base de données pour les tests.\n\n* `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.\n\n* `version` : Il n’existe aucune propriété `version` pour le pack de tests. Ceci empêche la publication accidentelle de packs de tests."}