Skip to main content

Création et utilisation de packs CodeQL

Vous pouvez utiliser les packs CodeQL pour créer, partager, dépendre et exécuter des requêtes et des bibliothèques CodeQL.

GitHub CodeQL est concédé sous licence par utilisateur lors de l’installation. Vous pouvez utiliser CodeQL uniquement pour certaines tâches soumises aux restrictions de licence. Pour plus d’informations, consultez « À propos de CodeQL CLI ».

Si vous disposez d’une licence GitHub Advanced Security, vous pouvez utiliser CodeQL pour l’analyse automatisée, l’intégration continue et la livraison continue. Pour plus d’informations, consultez « À propos de GitHub Advanced Security ».

Remarque : Cet article a été migré à partir du site web de documentation CodeQL en janvier 2023.

Remarque : la fonctionnalité de gestion de packages CodeQL, y compris des packs CodeQL, est actuellement disponible en version bêta et peut faire l’objet de modifications. Pendant la version bêta, les packs CodeQL sont disponibles uniquement à l’aide de packages GitHub, à savoir le Container registry. Pour utiliser cette fonctionnalité bêta, installez la dernière version du bundle CodeQL CLI à partir de : https://github.com/github/codeql-action/releases.

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

Remarques :

  • L’exécution des commandes codeql pack add et codeql pack install génère ou met à jour le fichier codeql-pack.lock.yml. Ce fichier doit être archivé dans la gestion de versions. Le fichier codeql-pack.lock.yml contient les numéros de version exacts utilisés par le pack. Pour plus d’informations, consultez « À propos des fichiers codeql-pack.lock.yml ».

  • Par défaut, codeql pack install installe les dépendances à partir du Container registry sur GitHub.com. Vous pouvez installer des dépendances à partir d’un GitHub Enterprise Server Container registry en créant un fichier qlconfig.yml. Pour plus d’informations, consultez « Publication et utilisation de packs CodeQL » dans la documentation GitHub Enterprise Server.

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.