Skip to content

custom-codeql-queries.md

Latest commit

 

History

History
64 lines (44 loc) · 3.86 KB

custom-codeql-queries.md

File metadata and controls

64 lines (44 loc) · 3.86 KB
title Custom CodeQL queries
shortTitle Custom queries
intro Custom queries extend {% data variables.product.prodname_codeql %}'s built-in security analysis to detect vulnerabilities and enforce coding standards specific to your codebase.
product {% data reusables.gated-features.codeql %}
versions
fpt ghes ghec
*
*
*
contentType concepts
category
Customize vulnerability detection with CodeQL

What are custom {% data variables.product.prodname_codeql %} queries?

Custom queries extend {% data variables.product.prodname_codeql %}'s built-in security analysis to detect vulnerabilities, coding standards, and patterns specific to your codebase.

{% data reusables.codeql-cli.advanced-query-execution %}

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 {% data variables.product.prodname_codeql %} query packs
  • Analyze {% data variables.product.prodname_codeql %} databases with the database analyze command using the {% data variables.product.prodname_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 {% data variables.product.prodname_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)

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.

For more information about query metadata, see Metadata for {% data variables.product.prodname_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 {% data variables.product.prodname_code_scanning %} UI
  • .qhelp files: Consistent with standard {% data variables.product.prodname_codeql %} queries, but must be converted to Markdown for use with {% data variables.product.prodname_code_scanning %}

When SARIF files containing query help are uploaded to {% data variables.product.prodname_dotcom %}, the documentation appears in the {% data variables.product.prodname_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 AUTOTITLE.

Further reading