Création et utilisation de packs CodeQL

À propos des CodeQL packs et des CodeQL CLI

          CodeQL les packs sont utilisés pour créer, partager, dépendre et exécuter CodeQL des requêtes et des bibliothèques.

Vous pouvez utiliser la commande pack dans CodeQL CLI pour créer des paquets CodeQL, ajouter des dépendances aux paquets, et installer ou mettre à jour les dépendances. Vous pouvez également publier et télécharger les packs à l’aide de la commande pack.

Création d’un CodeQL pack

Vous pouvez créer un CodeQL pack en exécutant la commande suivante à partir de la racine de dépôt de votre projet :

codeql pack init <scope>/<pack>

Vous devez spécifier :

•         `<scope>`: nom de l’organisation GitHub ou du compte d’utilisateur sur lequel vous allez publier.
  

•         `<pack>` : nom du pack que vous créez.
  

La codeql pack init commande crée la structure de répertoires et les fichiers de configuration d’un CodeQL pack. Par défaut, la commande crée un pack de requêtes. Si vous souhaitez créer un pack de bibliothèques, vous devez modifier le fichier qlpack.yml pour déclarer explicitement le fichier en tant que pack de bibliothèques en incluant la propriété library:true.

Création d’un CodeQL pack de modèles

Les packs de modèles peuvent être utilisés pour développer code scanning l’analyse pour reconnaître les bibliothèques et les frameworks qui ne sont pas pris en charge par défaut. Les packs de modèles utilisent des extensions de données, qui sont implémentées en tant que YAML et décrivent comment ajouter des données pour les nouvelles dépendances. Lorsqu’un pack de modèles est spécifié, les extensions de données de ce pack seront ajoutées automatiquement à l’analyse code scanning . Pour plus d’informations sur les CodeQL packs de modèles et les extensions de données, consultez Utiliser l'éditeur de modèles CodeQL.

Un pack de modèles est un ensemble CodeQL avec les caractéristiques suivantes dans le fichier qlpack.yml :

• Il définit library: true.
• Il n’a aucune dépendance.
• Il a un ou plusieurs extensionTargets.
• Il a une propriété dataExtensions qui pointe vers un ou plusieurs fichiers d’extension de données.

Un pack de modèles injectera ses extensions de données spécifiées dans chaque pack de requêtes nommé dans extensionTargets, s’il se trouve dans la plage de versions spécifiée. Par exemple:

name: my-repo/my-java-model-pack
version: 1.2.3
extensionTargets:
  codeql/java-all: ~1.2.3
  codeql/util: ~4.5.6
dataExtensions:
  - models/**/*.yml

Dans cet exemple, le pack de modèles injectera toutes les extensions de données dans models/**/ dans un pack de requêtes codeql/java-all qui se trouve dans une version allant de 1.2.3 jusqu’à et y compris 1.3.0, et un pack de requêtes codeql/util qui se trouve dans une version allant de 4.5.6 jusqu’à et y compris 4.6.0. Pour plus d’informations, consultez Utilisation du contrôle de version sémantique dans la documentation npm ainsi que la Spécification du contrôle de version sémantique.

Une fois que vous avez créé un pack de modèles, vous pouvez le publier de la même façon que d’autres CodeQL packs. Pour plus d’informations, consultez « Publication et utilisation de packs CodeQL ». Vous pouvez ensuite utiliser des packs de modèles publiés dans une code scanning analyse avec l’option --model-packs . Pour plus d’informations, consultez « Personnalisation de l’analyse avec des packs CodeQL ».

Ajout et installation de dépendances sur un CodeQL pack

Vous pouvez ajouter des dépendances pour les packs à l’aide de la commande codeql pack add. Vous devez spécifier l’étendue, le nom et (éventuellement) une plage de versions compatibles.

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

Si vous ne spécifiez pas de plage de versions, la dernière version est ajoutée. Dans le cas contraire, la version la plus récente répondant à la plage demandée sera ajoutée.

Cette commande met à jour le fichier qlpack.yml avec les dépendances demandées et les télécharge dans le cache du package. Notez que cette commande va changer la mise en forme du fichier et supprimer tous les commentaires.

Vous pouvez également modifier manuellement le fichier qlpack.yml pour inclure des dépendances et installer les dépendances avec la commande :

codeql pack install

Cette commande télécharge toutes les dépendances dans le cache partagé sur le disque local.

Organisation de la structure de répertoire d’un CodeQL pack

Un CodeQL pack doit contenir un fichier appelé qlpack.yml dans son répertoire racine. Dans le qlpack.yml fichier, le name: champ doit avoir une valeur qui suit le format de <scope>/<pack>, où <scope> se trouve l’organisation ou le GitHub compte d’utilisateur sur lequel le pack sera publié et <pack> est le nom du pack.

En outre, les packs de requête et les packs de bibliothèque avec 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.

Personnalisation d’un pack téléchargé CodeQL

La méthode recommandée pour tester les modifications apportées à un pack consiste à cloner le dépôt contenant son code source.

Si aucun référentiel source n’est disponible et que vous devez baser des modifications sur un pack téléchargé à partir du Container registry, sachez que ces packs ne sont pas destinés à être modifiés ou personnalisés après le téléchargement, et leur format peut changer à l’avenir sans aucun préavis. Nous vous recommandons d’effectuer les étapes suivantes après le téléchargement d’un pack si vous devez modifier le contenu :

• Changez le nom du pack dans qlpack.yml afin d’éviter toute confusion avec les résultats du pack non modifié.

• Supprimez tous les fichiers nommés *.qlx dans la structure de répertoires décompressée. Ces fichiers contiennent des versions précompilées des requêtes et, dans certaines situations CodeQL , les utiliseront en préférence pour la source QL que vous avez modifiée.