Création et utilisation de packs CodeQL

À propos des packs CodeQL et CodeQL CLI

Avec les packs CodeQL et les commandes de gestion de packages dans CodeQL CLI, vous pouvez publier vos requêtes personnalisées et les intégrer à votre analyse de codebase.

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 la commande pack dans CodeQL CLI pour créer des packs CodeQL, ajouter des dépendances aux packs et installer ou mettre à jour des dépendances. Vous pouvez également publier et télécharger des packs CodeQL à l’aide de la commande pack. Pour plus d’informations, consultez « Publication et utilisation de packs CodeQL ».

Pour plus d’informations sur la compatibilité entre les packs de requêtes publiés et les différentes versions de CodeQL, consultez « Publication et utilisation de packs CodeQL ».

Création d’un pack CodeQL

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

codeql pack init <scope>/<pack>

Vous devez spécifier :

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

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

La commande codeql pack init crée la structure de répertoires et les fichiers de configuration d’un pack CodeQL. 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.

Modification d’un pack QL hérité existant pour créer un pack CodeQL

Si vous avez déjà un fichier qlpack.yml, vous pouvez le modifier manuellement pour le convertir en pack CodeQL.

1. Modifiez la propriété name afin qu’elle corresponde au format <scope>/<name>, où <scope> est le nom de l’organisation ou du compte d’utilisateur GitHub sur lequel vous allez publier.

2. Dans le fichier qlpack.yml, incluez une propriété version avec un identificateur semver, ainsi qu’un bloc dependencies facultatif.

3. Migrez la liste des dépendances de libraryPathDependencies vers le bloc dependencies. Spécifiez la plage de versions pour chaque dépendance. Si la plage n’est pas importante ou si vous n’êtes pas sûr de la compatibilité, vous pouvez spécifier "\*", qui indique que toute version est acceptable et que la version la plus récente est utilisée par défaut lorsque vous exécutez codeql pack install.

Pour plus d’informations sur les propriétés, consultez « Personnalisation de l’analyse avec des packs CodeQL ».

Ajout et installation de dépendances à un pack CodeQL

Vous pouvez ajouter des dépendances sur les packs CodeQL à 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.

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

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 les 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 que leur format peut changer à l’avenir sans beaucoup de 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 certains cas, CodeQL les utilise de préférence dans la source QL que vous avez modifiée.