Écriture et partage de requêtes personnalisées pour l’interface CLI CodeQL

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

Cet article traite spécifiquement de l’écriture de requêtes à utiliser avec la commande analyse de base de données pour produire des résultats interprétés. Pour plus d’informations conceptuelles sur les requêtes personnalisées, consultez Requêtes CodeQL personnalisées.

É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

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.

Empaquetage de requêtes personnalisées

Lorsque vous écrivez des requêtes à partager avec d’autres personnes, enregistrez-les dans un pack CodeQL personnalisé.

Pour empaqueter vos requêtes personnalisées :

  1. Créez un paquet CodeQL avec un fichier qlpack.yml au répertoire racine.
  2. Enregistrez vos requêtes personnalisées (.ql fichiers) dans la racine du pack ou ses sous-répertoires.
  3. Configurez le qlpack.yml fichier pour spécifier :
  4. Publiez votre pack dans GitHub Packages - le GitHub Container registry. Pour plus d’informations, 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

Pour plus d’informations sur les formats d’aide et de documentation des requêtes, consultez Requêtes CodeQL personnalisées.

Pour inclure l’aide sur les requêtes dans les fichiers SARIF lors de l’exécution d’analyses de code :

  1. Rédigez votre demande d'aide dans l’un des formats suivants : * Fichier Markdown : Enregistrez un fichier Markdown en même temps que votre requête portant le même nom (par exemple, my-query.md pour my-query.ql) * ** .qhelp fichier** : rédigez l'assistance pour les requêtes au format .qhelp, puis convertissez-la en 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.

  2. Exécutez codeql database analyze avec l’option --sarif-add-query-help.

    codeql database analyze <database> --format=sarif-latest --output=results.sarif --sarif-add-query-help

    Remarque

    L’option --sarif-add-query-help est disponible à partir de CodeQL CLI v2.7.1 et versions ultérieures.

  3. Chargez le fichier SARIF sur GitHub.

Lectures complémentaires

  •         [Requêtes CodeQL](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)