| title | intro | product | versions | topics | redirect_from | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Using custom queries with the CodeQL CLI |
You can write your own {% data variables.product.prodname_codeql %} queries to find specific vulnerabilities and errors. |
{% data reusables.gated-features.codeql %} |
|
|
|
You can customize your {% data variables.product.prodname_codeql %} analyses by writing your own queries to highlight specific vulnerabilities or errors.
This topic is specifically about writing queries to use with the AUTOTITLE command to produce interpreted results.
{% data reusables.codeql-cli.advanced-query-execution %}
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 "{% data variables.product.prodname_codeql %} queries."
Query metadata is included at the top of each query file. It provides users with information about the query, and tells the {% data variables.product.prodname_codeql_cli %} how to process the query results.
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 metricand@tags summary).
For more information about these metadata properties, see "Metadata for {% data variables.product.prodname_codeql %} queries" and the Query metadata style guide.
Note
Metadata requirements may differ if you want to use your query with other applications. For more information, see "Metadata for {% data variables.product.prodname_codeql %} queries."
When you write your own queries with the intention to share them with others, you should save them in a custom {% data variables.product.prodname_codeql %} pack. You can publish the pack as a {% data variables.product.prodname_codeql %} pack to {% data variables.product.prodname_registry %} - the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}. For more information, see "AUTOTITLE."
{% data variables.product.prodname_codeql %} packs organize the files used in {% data variables.product.prodname_codeql %} analysis and can store queries, library files, query suites, and important metadata. Their root directory must contain a file named qlpack.yml. Your custom queries should be saved in the {% data variables.product.prodname_codeql %} pack root, or its subdirectories.
For each {% data variables.product.prodname_codeql %} pack, the qlpack.yml file includes information that tells the {% data variables.product.prodname_codeql_cli %} how to compile the queries, which other {% data variables.product.prodname_codeql %} packs and libraries the pack depends on, and where to find query suite definitions. For more information about what to include in this file, see "AUTOTITLE."
If you use the {% data variables.product.prodname_codeql_cli %} to run code scanning analyses on third party CI/CD systems, you can include the query help for your custom queries in SARIF files generated during an analysis. After uploading the SARIF file to {% data variables.product.prodname_dotcom %}, the query help is shown in the code scanning UI for any alerts generated by the custom queries.
From {% data variables.product.prodname_codeql_cli %} v2.7.1 onwards, you can include markdown-rendered query help in SARIF files
by providing the --sarif-add-query-help option when running
codeql database analyze.
You can write query help for custom queries directly in a markdown file and save it alongside the
corresponding query. Alternatively, for consistency with the standard {% data variables.product.prodname_codeql %} queries,
you can write query help in the .qhelp format. Query help written in .qhelp
files can’t be included in SARIF files, and they can’t be processed by code
scanning so must be converted to markdown before running
the analysis. For more information, see "Query help files"
and "AUTOTITLE."
If you would like to share your query with other {% data variables.product.prodname_codeql %} users, you can open a pull request in the {% data variables.product.prodname_codeql %} repository. For more information, see Contributing to {% data variables.product.prodname_codeql %}.