Utilisation de requêtes personnalisées avec CodeQL CLI

Vous pouvez écrire vos propres requêtes CodeQL pour rechercher des vulnérabilités et des erreurs spécifiques.

Qui peut utiliser cette fonctionnalité ?

CodeQL est disponible pour les types de référentiels suivants :

Dans cet article

À propos des requêtes personnalisées et de CodeQL CLI

Vous pouvez personnaliser vos analyses CodeQL en écrivant vos propres requêtes pour mettre en évidence des vulnérabilités ou des erreurs spécifiques.

Cette rubrique concerne spécifiquement l’écriture de requêtes à utiliser avec la commande database analyze pour produire des résultats interprétés.

Note

Les requêtes exécutées avec database analyze ont des exigences de métadonnées strictes. Vous pouvez également exécuter des requêtes à l’aide des sous-commandes de niveau plomberie suivantes :

  • database run-queries, qui génère des résultats non interprétés dans un format binaire intermédiaire appelé BQRS.
  • query run, qui génère des fichiers BQRS ou affiche les tables de résultats directement dans la ligne de commande. L’affichage des résultats directement dans la ligne de commande peut être utile pour le développement de requêtes itératives à l’aide de l’interface CLI.

Les requêtes exécutées avec ces commandes n’ont pas les mêmes exigences de métadonnées. Toutefois, pour enregistrer des données lisibles par l’homme, vous devez traiter chaque fichier de résultats BQRS avec la sous-commande de plomberie bqrs decode. Par conséquent, dans la plupart des cas d’usage, il est plus simple d’utiliser l’analyse de base de données (database analyze) pour générer directement des résultats interprétés.

Écriture d’une requête valide

Avant d’exécuter une analyse personnalisée, vous devez écrire une requête valide et l’enregistrer dans un fichier avec une extension .ql. Une documentation complète est disponible pour vous aider à écrire des requêtes. Pour plus d’informations, consultez Requêtes CodeQL.

Inclusion des métadonnées de requête

Les métadonnées de requête sont incluses en haut de chaque fichier de requête. Elles fournissent aux utilisateurs des informations sur la requête et indique à CodeQL CLI comment traiter les résultats de la requête.

Lors de l’exécution de requêtes avec la commande database analyze, vous devez inclure les deux propriétés suivantes pour garantir que les résultats sont interprétés correctement :

  • Identificateur de requête (@id) : séquence de mots composés de lettres minuscules ou de chiffres, délimités par / ou par -, identifiant et classifiant la requête.

  • Type de requête (@kind) : identifie la requête comme une alerte simple (@kind problem), une alerte documentée par une séquence d’emplacements de code (@kind path-problem), pour la résolution des problèmes de l’extracteur (@kind diagnostic) ou une métrique récapitulative (@kind metric et @tags summary).

Pour plus d’informations sur ces propriétés de métadonnées, consultez Métadonnées pour les requêtes CodeQL et Guide de style pour les métadonnées de requête.

Note

Les exigences en matière de métadonnées peuvent différer si vous voulez utiliser votre requête avec d’autres applications. Pour plus d’informations, consultez Métadonnées pour les requêtes CodeQL.

Empaquetage de requêtes QL personnalisées

Quand vous écrivez vos propres requêtes avec l’intention de les partager avec d’autres personnes, vous devez les enregistrer dans un pack CodeQL personnalisé. Vous pouvez publier le pack en tant que pack CodeQL sur GitHub Packages - le Container registry GitHub. Pour plus d’informations, consultez « Personnalisation de l’analyse avec des packs CodeQL ».

Les packs CodeQL organisent les fichiers utilisés dans l’analyse CodeQL et peuvent stocker des requêtes, des fichiers de bibliothèque, des suites de requêtes et des métadonnées importantes. Leur répertoire racine doit contenir un fichier nommé qlpack.yml. Vos requêtes personnalisées doivent être enregistrées à la racine du pack CodeQL ou dans ses sous-répertoires.

Pour chaque pack CodeQL, le fichier qlpack.yml inclut des informations qui indiquent à CodeQL CLI comment compiler les requêtes, de quels autres packs et bibliothèques CodeQL dépend le pack, et où trouver les définitions de suite de requêtes. Pour plus d’informations sur ce qu’il faut inclure dans ce fichier, consultez Personnalisation de l’analyse avec des packs CodeQL.

Inclusion d’une aide aux requêtes pour les requêtes CodeQL personnalisées dans les fichiers SARIF

Si vous utilisez CodeQL CLI pour exécuter des analyses de code sur des systèmes CI/CD tiers, vous pouvez inclure l’aide aux requêtes pour vos requêtes personnalisées dans les fichiers SARIF générés lors d’une analyse. Après avoir chargé le fichier SARIF dans GitHub, l’aide aux requêtes s’affiche dans l’interface utilisateur de l’analyse du code pour toutes les alertes générées par les requêtes personnalisées.

À partir de CodeQL CLI version 2.7.1 et ultérieure, vous pouvez inclure l’aide aux requêtes restituée au format Markdown dans les fichiers SARIF en fournissant l’option --sarif-add-query-help lors de l’exécution de codeql database analyze.

Vous pouvez écrire une aide aux requêtes pour les requêtes personnalisées directement dans un fichier Markdown et l’enregistrer en même temps que la requête correspondante. Par souci de cohérence avec les requêtes CodeQL standard, vous pouvez aussi écrire une aide aux requêtes au format .qhelp. L’aide aux requêtes écrite dans les fichiers .qhelp ne peut pas être incluse dans les fichiers SARIF et ne peut pas être traitée par l’analyse du code, elle doit par conséquent être convertie au format Markdown avant d’exécuter l’analyse. Pour plus d’informations, consultez Fichiers d’aide aux requêtes et Test des fichiers d’aide aux requêtes.

Contribution au dépôt CodeQL

Si vous voulez partager votre requête avec d’autres utilisateurs CodeQL, vous pouvez ouvrir une demande de tirage dans le dépôt CodeQL. Pour plus d’informations, consultez Contribution à CodeQL.

Pour aller plus loin