关于自定义查询和 CodeQL CLI
您可以通过编写自己的查询来突出显示特定漏洞或错误，从而自定义您的 CodeQL 分析。
本主题专门介绍如何编写要与 database analyze 命令一起使用的查询，以生成 解释结果。
注意
使用 database analyze 运行的查询具有严格的 元数据要求。您还可以使用以下管道级子命令执行查询
- database run-queries，它以称为 BQRS 的中间二进制格式输出非解释结果。
- query run，它将输出 BQRS 文件，或将结果表直接打印到命令行。在使用 CLI 进行迭代查询开发时，直接在命令行中查看结果可能很有用。
使用这些命令运行的查询没有相同的元数据要求。但是，要保存人类可读数据，您必须使用 bqrs decode 管道级子命令处理每个 BQRS 结果文件。因此，对于大多数用例来说，最简单的方法是使用 database analyze 直接生成解释结果。
编写有效的查询
在运行自定义分析之前，您需要编写一个有效的查询，并将其保存在扩展名为 .ql 的文件中。提供了大量文档来帮助您编写查询。有关更多信息，请参阅“CodeQL 查询”。
包含查询元数据
查询元数据包含在每个查询文件的顶部。它为用户提供有关查询的信息，并告诉 CodeQL CLI 如何处理查询结果。
使用 database analyze 命令运行查询时，必须包含以下两个属性以确保正确解释结果
-
查询标识符 (
@id)：由小写字母或数字组成的单词序列，以/或-分隔，用于标识和分类查询。 -
查询类型 (
@kind)：将查询标识为简单警报 (@kind problem)、由一系列代码位置记录的警报 (@kind path-problem)、用于提取器故障排除 (@kind diagnostic) 或汇总指标 (@kind metric和@tags summary)。
有关这些元数据属性的更多信息，请参阅“CodeQL 查询的元数据”和 查询元数据样式指南。
注意
如果您想将查询与其他应用程序一起使用，则元数据要求可能会有所不同。有关更多信息，请参阅“CodeQL 查询的元数据”。
打包自定义 QL 查询
当您编写自己的查询并打算与他人共享时，应将其保存在自定义 CodeQL 包中。您可以将该包发布为 CodeQL 包到 GitHub Packages（GitHub 容器注册表）。有关更多信息，请参阅“使用 CodeQL 包自定义分析”。
CodeQL 包组织了 CodeQL 分析中使用的文件，并且可以存储查询、库文件、查询套件和重要元数据。其根目录必须包含一个名为qlpack.yml的文件。您的自定义查询应保存在 CodeQL 包根目录或其子目录中。
对于每个 CodeQL 包，qlpack.yml文件包含一些信息，这些信息告诉 CodeQL CLI 如何编译查询、该包依赖于哪些其他 CodeQL 包和库，以及在哪里可以找到查询套件定义。有关此文件中应包含哪些内容的更多信息，请参阅“使用 CodeQL 包自定义分析”。
在 SARIF 文件中包含自定义 CodeQL 查询的查询帮助
如果您使用 CodeQL CLI 在第三方 CI/CD 系统上运行代码扫描分析，则可以在分析期间生成的 SARIF 文件中包含自定义查询的查询帮助。将 SARIF 文件上传到 GitHub 后，代码扫描 UI 中将显示自定义查询生成的任何警报的查询帮助。
从 CodeQL CLI v2.7.1 开始，您可以在运行codeql database analyze时提供--sarif-add-query-help选项，从而在 SARIF 文件中包含 Markdown 渲染的查询帮助。
您可以直接在 Markdown 文件中为自定义查询编写查询帮助，并将其与相应的查询一起保存。或者，为了与标准 CodeQL 查询保持一致，您可以在.qhelp格式中编写查询帮助。在.qhelp文件中编写的查询帮助无法包含在 SARIF 文件中，并且代码扫描无法处理它们，因此必须在运行分析之前将其转换为 Markdown。有关更多信息，请参阅“查询帮助文件”和“测试查询帮助文件”。
贡献到 CodeQL 存储库
如果您想与其他 CodeQL 用户共享您的查询，可以在CodeQL 存储库中打开一个拉取请求。有关更多信息，请参阅贡献到 CodeQL。