Requêtes CodeQL personnalisées

Les requêtes personnalisées étendent l'analyse de sécurité intégrée de CodeQL pour détecter les vulnérabilités et appliquer des normes de codage spécifiques à votre codebase.

Qui peut utiliser cette fonctionnalité ?

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

Dans cet article

Qu’est-ce que les requêtes personnalisées CodeQL ?

Les requêtes personnalisées étendent l’analyse de sécurité intégrée de CodeQL pour détecter les vulnérabilités, respecter les normes de codage et les modèles spécifiques de votre base de code.

Remarque

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 :

  • requêtes d’exécution de base de données, qui génère des résultats non interprétés dans un format binaire intermédiaire appelé BQRS.
  • exécution de requête, 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 décodage BQRS. 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.

Quand utiliser des requêtes personnalisées

Utilisez des requêtes personnalisées pour :

  • Détecter les vulnérabilités spécifiques à l’architecture ou aux infrastructures de votre application
  • Appliquer les normes de codage spécifiques à l’organisation ou les meilleures pratiques
  • Rechercher des modèles non couverts par les packs de requêtes standard CodeQL
  • Analyser les bases de données CodeQL avec la commande database analyze à l’aide de CodeQL CLI pour produire des résultats interprétés.

Structure de la requête

Les requêtes personnalisées sont écrites dans les fichiers de requête, qui sont enregistrés avec l’extension .ql . Ces fichiers contiennent également des métadonnées importantes qui fournissent des informations sur l’objectif de la requête et indiquent à CodeQL CLI comment traiter les résultats. Les propriétés requises sont les suivantes :

  •         **Identificateur de requête (`@id`)**  : lettres minuscules ou chiffres, délimités par `/` ou `-`

  •         **Type de requête (`@kind`)**  : l’un des éléments suivants :
    * problem - Alerte simple * path-problem - Alerte avec séquence d’emplacement du code * diagnostic - Résolution des problèmes d’extracteur * metric - Métrique récapitulative (nécessite @tags summary)

Remarque

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.

Pour plus d’informations sur les métadonnées de requête, consultez les métadonnées pour les requêtes CodeQL et le guide de style des métadonnées de requête.

Documentation sur les requêtes

La documentation sur les requêtes aide les utilisateurs à comprendre ce qu’une requête détecte et comment résoudre les problèmes identifiés. Vous pouvez inclure de la documentation pour vos requêtes personnalisées dans deux formats :

  •         **Fichiers Markdown** : enregistrés en même temps que la requête, peuvent être inclus dans les fichiers SARIF et affichés dans l’interface utilisateur code scanning

  •         **
        `.qhelp` fichiers** : cohérent avec les requêtes standard CodeQL, mais doivent être convertis en Markdown afin de pouvoir être utilisé avec code scanning

Lorsque les fichiers SARIF contenant l’assistance de requête sont téléversés sur GitHub, la documentation apparaît dans l’interface utilisateur code scanning pour toute alerte générée par la requête.

Pour plus d’informations, consultez les fichiers d’aide.

Partage de requêtes personnalisées

Vous pouvez partager des requêtes personnalisées avec la communauté en publiant vos propres packs de requêtes. Consultez Publication et utilisation de packs CodeQL.

Lectures complémentaires

  •         [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli)

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