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

CodeQL Compatibilité des packs

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 date de plus de six mois de plus que la version qui a exécuté codeql pack publish, il peut être nécessaire de compiler les requêtes à partir du code source pendant l’analyse, ce qui ralentit considérablement le processus.

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

Si votre analyse contient des lignes comme celles-ci, elle 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, recompilez CodeQL 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 CodeQL tous les 6 mois.

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

qlpack.yml fichiers

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

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

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

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

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

  name: octo-org/security-queries
  

version

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

• Définit une version sémantique pour ce CodeQL pack 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è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.

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

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

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

  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 CodeQL pack 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 CodeQL le bundle CLI.
• Cette option n’est pas prise en charge pour CodeQL les packs téléchargés à partir du GitHub registre de conteneurs.

tests

• Facultatif pour les packs contenant des CodeQL tests. 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

• Requis pour tous les packs contenant CodeQL tests.

• 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 Testing custom queries. Par exemple:

  extractor: javascript-typescript
  

authors

• Optionnel.

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

  authors: [email protected],[email protected]
  

license

• Optionnel.

• Définit les métadonnées qui seront affichées sur la page de recherche des packages dans la section des packages du compte dans lequel le CodeQL package 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 des packages, dans la section des packages du compte sur lequel le CodeQL pack est publié. Par exemple:

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

libraryPathDependencies

• Facultatif, fermeture. Utilisez plutôt la propriété dependencies.

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

  libraryPathDependencies: codeql/javascript-all
  

dbscheme

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

• Définit le chemin d’accès au schéma de base de données pour toutes les bibliothèques et requêtes écrites pour ce CodeQL langage (voir 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 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:

  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 la version 2.13.2. Par exemple:

  warnOnImplicitThis: true
  

codeql-pack.lock.yml fichiers

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.

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

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.

CodeQL packages pour les bibliothèques personnalisées

Un pack personnalisé CodeQL contenant des bibliothèques C++ personnalisées, sans requêtes ni tests, peut avoir un qlpack.yml fichier 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 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.

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

CodeQL modules pour les requêtes personnalisées

Un pack personnalisé contenant des requêtes et des bibliothèques C++ personnalisées CodeQL peut avoir un qlpack.yml fichier 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 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. 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.

CodeQL packs pour les tests personnalisés

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

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 Testing custom queries.

Exemples de CodeQL packs dans le CodeQL référentiel

Chacune des langues du CodeQL référentiel comporte quatre packs principaux CodeQL :

• 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

• 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 au CodeQL CLI et ne doivent être définies que dans le pack de requêtes CodeQL principal pour une langue.

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

• 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 principal CodeQL

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 CodeQL principaux packs de requête et de bibliothèque 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.