什么是自定义 CodeQL 查询？
自定义查询扩展了 CodeQL 的内置安全分析功能，以检测特定于你的代码库的漏洞、编码标准和模式。
注意
使用 database analyze 运行的查询具有严格的元数据要求。 还可使用以下管道级子命令执行查询：
- 数据库运行查询：以称为 BQRS 的中间二进制格式输出非解释结果。
- 查询运行：将输出 BQRS 文件，或将结果表直接输出到命令行。 直接在命令行中查看结果对于使用 CLI 进行迭代查询开发可能很有用。
使用这些命令运行的查询具有不同的元数据要求。 但是，若要保存人类可读数据，必须使用 bqrs 解码 管道子命令处理每个 BQRS 结果文件。 因此，对于大多数用例，最简单的方法是使用数据库分析直接生成解释结果。
何时使用自定义查询
使用自定义查询可以：
- 检测特定于应用程序的体系结构或框架的漏洞
- 强制实施组织特定的编码标准或最佳做法
- 查找标准 CodeQL 查询包未涵盖的模式
- 使用 CodeQL CLI 通过
database analyze命令分析 CodeQL 数据库，以生成解释结果
查询结构
自定义查询是用查询文件编写的，这些文件用 .ql 扩展名保存。 这些文件还包含重要的元数据，提供有关查询用途的信息，并告知 CodeQL CLI 如何处理结果。 必需的属性包括：
-
**查询标识符（`@id`）**：小写字母或数字，由 `/` 或 `-` 分隔。 -
***查询类型 （`@kind`）**：以下类型之一：problem- 简单警报 *path-problem- 包含代码位置序列的警报 *diagnostic- 提取程序故障排除 *metric- 摘要指标（需要@tags summary）
注意
如果要将查询与其他应用程序一起使用，则元数据要求可能会有所不同。 有关详细信息，请参阅 CodeQL 查询的元数据。
有关查询元数据的详细信息，请参阅 Metadata for CodeQL queries 和 查询元数据风格指南。
查询文档
查询文档可帮助用户了解查询检测的内容以及如何解决已识别的问题。 可以包含两种格式的自定义查询文档：
-
**Markdown 文件**：与查询一起保存，可包含在 SARIF 文件中，并显示在 code scanning UI 中 -
** `.qhelp` 文件**：与标准 CodeQL 查询一致，但必须转换为 Markdown 格式才能与 code scanning 一起使用
当包含查询帮助的 SARIF 文件上传到 GitHub 时，该文档会在 code scanning UI 中显示由该查询生成的所有警报。
有关详细信息，请参阅 查询帮助文件。
共享自定义查询
可以通过发布自己的查询包来与社区共享自定义查询。 请参阅“发布及使用 CodeQL 包”。
延伸阅读
-
[AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli) -
[CodeQL 查询](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)