关于自定义查询和 CodeQL CLI
可以通过编写自己的查询来突出显示特定漏洞或错误来自定义 CodeQL 分析。
本主题专门介绍如何编写要与 数据库分析 命令一起使用的查询，用于生成解释结果。
注意：使用 database analyze 运行的查询具有严格的元数据要求。 还可使用以下管道级子命令执行查询：
- 数据库运行查询：以称为 BQRS 的中间二进制格式输出非解释结果。
- query run：将输出 BQRS 文件，或将结果表直接输出到命令行。 直接在命令行中查看结果对于使用 CLI 进行迭代查询开发可能很有用。
使用这些命令运行的查询具有不同的元数据要求。 但是，若要保存人类可读数据，必须使用 bqrs 解码 管道子命令处理每个 BQRS 结果文件。 因此，对于大多数用例，最简单的方法是使用数据库分析直接生成解释结果。
编写有效查询
在运行自定义分析之前，需要编写有效的查询，并将其保存在扩展名为的 .ql 文件中。 有大量文档可帮助你编写查询。 有关详细信息，请参阅“CodeQL 查询”。
包括查询元数据
查询元数据包含在每个查询文件的顶部。 它为用户提供有关查询的信息，并告知 CodeQL CLI 如何处理查询结果。
使用 database analyze 命令运行查询时，必须包含以下两个属性，以确保正确解释结果：
-
查询标识符 (
@id)：由小写字母或数字组成的单词序列，由/或-分隔，用于标识查询并对其进行分类。 -
查询类型 (
@kind)：将查询标识为简单警报 (@kind problem)、由一系列代码位置记录的警报 (@kind path-problem)、用于提取器故障排除 (@kind diagnostic) 或摘要指标（@kind metric和@tags summary）。
有关这些元数据属性的详细信息，请参阅“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。