此版本的 GitHub Enterprise Server 将于以下日期停止服务 2026-03-17. 即使针对重大安全问题，也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能，请升级到最新版本的 GitHub Enterprise。 如需升级帮助，请联系 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.

谁可以使用此功能？

CodeQL 可用于以下存储库类型：

本文内容

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.

注意

使用 database analyze 运行的查询具有严格的元数据要求。 还可使用以下管道级子命令执行查询：

  • 数据库运行查询：以称为 BQRS 的中间二进制格式输出非解释结果。
  • 查询运行：将输出 BQRS 文件，或将结果表直接输出到命令行。 直接在命令行中查看结果对于使用 CLI 进行迭代查询开发可能很有用。

使用这些命令运行的查询具有不同的元数据要求。 但是，若要保存人类可读数据，必须使用 bqrs 解码 管道子命令处理每个 BQRS 结果文件。 因此，对于大多数用例，最简单的方法是使用数据库分析直接生成解释结果。

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)

注意

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 发布及使用 CodeQL 包.

Further reading