什么是自定义 CodeQL 查询？
自定义查询扩展了 CodeQL 内置的安全分析，以检测特定于您代码库的漏洞、编码标准和模式。
注意
使用 database analyze 运行的查询具有严格的 元数据要求。您还可以使用以下底层子命令执行查询
- database run-queries，它以一种称为 BQRS 的中间二进制格式输出未解释的结果。
- query run，它会输出 BQRS 文件，或直接在命令行打印结果表。直接在命令行查看结果可能有助于使用 CLI 进行迭代式查询开发。
使用这些命令运行的查询没有相同的元数据要求。但是，要保存可读的数据，您必须使用 bqrs decode 底层子命令处理每个 BQRS 结果文件。因此，对大多数使用场景而言，最简单的方法是使用 database analyze 直接生成已解释的结果。
何时使用自定义查询
使用自定义查询可以
- 检测特定于您应用程序架构或框架的漏洞
- 强制执行组织特定的编码标准或最佳实践
- 查找标准 CodeQL 查询包未覆盖的模式
- 使用 CodeQL CLI 的
database analyze命令分析 CodeQL 数据库，以生成已解释的结果
查询结构
自定义查询编写在查询文件中，文件扩展名为 .ql。这些文件还包含重要的元数据，提供有关查询目的的信息，并告诉 CodeQL CLI 如何处理结果。必需的属性包括
- 查询标识符 (
@id)：小写字母或数字，用/或-分隔 - 查询类型 (
@kind)：以下之一problem- 简单警报path-problem- 带有代码位置序列的警报diagnostic- 提取器故障排除metric- 汇总指标（需要@tags summary）
注意
如果您希望将查询用于其他应用程序，元数据要求可能会有所不同。更多信息请参阅 Metadata for CodeQL queries。
有关查询元数据的更多信息，请参阅 Metadata for CodeQL queries 和 Query metadata style guide。
查询文档
查询文档帮助用户了解查询检测了什么以及如何解决识别出的问题。您可以以两种格式为自定义查询包含文档
- Markdown 文件：与查询文件放在一起，可包含在 SARIF 文件中并在代码扫描 UI 中显示
.qhelp文件：与标准 CodeQL 查询保持一致，但必须转换为 Markdown 才能在代码扫描中使用
当包含查询帮助的 SARIF 文件上传到 GitHub 时，文档会出现在代码扫描 UI 中，显示在查询生成的任何警报旁边。
更多信息请参阅 Query help files。
共享自定义查询
您可以通过发布自己的查询包与社区共享自定义查询。参见 Publishing and using CodeQL packs。