关于自定义查询和 CodeQL CLI
可以通过编写自己的查询来突出显示特定漏洞或错误来自定义 CodeQL 分析。
本主题专门介绍如何编写要与 数据库分析 命令一起使用的查询，用于生成解释结果。
Note
使用 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 查询的元数据和查询元数据样式指南。
Note
如果要将查询与其他应用程序一起使用，则元数据要求可能会有所不同。 有关详细信息，请参阅 CodeQL 查询的元数据。
打包自定义 QL 查询
如果要编写自己的查询以与他人共享时，应将其保存在自定义 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。