Cette version de GitHub Enterprise Server ne sera plus disponible le 2026-03-17. Aucune publication de correctifs n’est effectuée, même pour les problèmes de sécurité critiques. Pour de meilleures performances, une sécurité améliorée et de nouvelles fonctionnalités, effectuez une mise à niveau vers la dernière version de GitHub Enterprise. Pour obtenir de l’aide sur la mise à niveau, contactez le support GitHub Enterprise.

Custom CodeQL queries

Custom queries extend CodeQL's built-in security analysis to detect vulnerabilities and enforce coding standards specific to your codebase.

Qui peut utiliser cette fonctionnalité ?

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

Dans cet article

What are custom CodeQL queries?

Custom queries extend CodeQL's built-in security analysis to detect vulnerabilities, coding standards, and patterns specific to your codebase.

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.

When to use custom queries

Use custom queries to:

  • Detect vulnerabilities specific to your application's architecture or frameworks
  • Enforce organization-specific coding standards or best practices
  • Find patterns not covered by standard CodeQL query packs
  • Analyze CodeQL databases with the database analyze command using the CodeQL CLI to produce interpreted results

Query structure

Custom queries are written in query files, which are saved with the .ql extension. These files also contain important metadata that provides information about the query's purpose and tells the CodeQL CLI how to process results. Required properties include:

  • Query identifier (@id): Lowercase letters or digits, delimited by / or -
  • Query type (@kind): One of:
    • problem - Simple alert
    • path-problem - Alert with code location sequence
    • diagnostic - Extractor troubleshooting
    • metric - Summary metric (requires @tags summary)

Remarque

Metadata requirements may differ if you want to use your query with other applications. For more information, see Metadata for CodeQL queries.

For more information about query metadata, see Metadata for CodeQL queries and the Query metadata style guide.

Query documentation

Query documentation helps users understand what a query detects and how to address identified issues. You can include documentation for your custom queries in two formats:

  • Markdown files: Saved alongside the query, can be included in SARIF files and displayed in the code scanning UI
  • .qhelp files: Consistent with standard CodeQL queries, but must be converted to Markdown for use with code scanning

When SARIF files containing query help are uploaded to GitHub, the documentation appears in the code scanning UI for any alerts generated by the query.

For more information, see Query help files.

Sharing custom queries

You can share custom queries with the community by publishing your own query packs. See Publication et utilisation de packs CodeQL.

Further reading