关于自定义查询和 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 查询的元数据”。
打包自定义 QL 查询
注意：CodeQL 包管理功能（包括 CodeQL 包）当前提供 beta 版本，可能会发生更改。 在 beta 版本发布期间，CodeQL 包只能使用 GitHub 包，即 Container registry。 若要使用此 beta 版功能，请安装最新版本的 CodeQL CLI 捆绑包： https://github.com/github/codeql-action/releases 。
如果要编写自己的查询以与他人共享时，应将其保存在自定义 CodeQL 包中。 可以将包作为 CodeQL 包发布到 GitHub Packages - GitHub Container registry。 有关详细信息，请参阅“使用 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。