Writing and sharing custom queries for the CodeQL CLI

You can write your own CodeQL queries to find specific vulnerabilities and errors.

Qui peut utiliser cette fonctionnalité ?

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

Dans cet article

This article is specifically about writing queries to use with the analyse de base de données command to produce interpreted results. For conceptual information about custom queries, see Custom CodeQL queries.

Writing a valid query

Before running a custom analysis you need to write a valid query, and save it in a file with a .ql extension. There is extensive documentation available to help you write queries. For more information, see CodeQL queries.

Including query metadata

When running queries with the database analyze command, you must include the following two properties to ensure that the results are interpreted correctly:

  • Query identifier (@id): a sequence of words composed of lowercase letters or digits, delimited by / or -, identifying and classifying the query.

  • Query type (@kind): identifies the query as a simple alert (@kind problem), an alert documented by a sequence of code locations (@kind path-problem), for extractor troubleshooting (@kind diagnostic), or a summary metric (@kind metric and @tags summary).

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

Packaging custom queries

When you write queries to share with others, save them in a custom CodeQL pack.

To package your custom queries:

  1. Create a CodeQL pack with a qlpack.yml file in the root directory.
  2. Save your custom queries (.ql files) in the pack root or its subdirectories.
  3. Configure the qlpack.yml file to specify:
  4. Publish your pack to GitHub Packages - the GitHub Container registry. For more information, see Personnalisation de l’analyse avec des packs CodeQL.

Including query help for custom CodeQL queries in SARIF files

For information about query help and documentation formats, see Custom CodeQL queries.

To include query help in SARIF files when running code scanning analyses:

  1. Write your query help in one of the following formats:

    • Markdown file: Save a Markdown file alongside your query with the same name (for example, my-query.md for my-query.ql)
    • .qhelp file: Write query help in .qhelp format, then convert it to Markdown before running the analysis. For more information, see Query help files and Test des fichiers d’aide aux requêtes.

  2. Run codeql database analyze with the --sarif-add-query-help option:

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

    Remarque

    The --sarif-add-query-help option is available from CodeQL CLI v2.7.1 onwards.

  3. Upload the SARIF file to GitHub.

Further reading