编写和共享 CodeQL CLI 的自定义查询

可以编写自己的 CodeQL 查询来查找特定漏洞和错误。

谁可以使用此功能？

CodeQL 可用于以下存储库类型：

本文内容

本文专门介绍如何编写用于 数据库分析 命令的查询，以生成 解释的结果。 有关自定义查询的概念性信息，请参阅 自定义 CodeQL 查询。

编写有效查询

在运行自定义分析之前，需要编写有效的查询，并将其保存在扩展名为的 .ql 文件中。 有大量文档可帮助你编写查询。 有关更多信息，请参阅 CodeQL 查询。

包括查询元数据

使用 database analyze 命令运行查询时，必须包含以下两个属性，以确保正确解释结果：

  • 查询标识符 (@id)：由小写字母或数字组成的单词序列，由 / 或 - 分隔，用于标识查询并对其进行分类。

  • 查询类型 (@kind)：将查询标识为简单警报 (@kind problem)、由一系列代码位置记录的警报 (@kind path-problem)、用于提取器故障排除 (@kind diagnostic) 或摘要指标（@kind metric 和 @tags summary）。

有关这些元数据属性的详细信息，请参阅 CodeQL 查询的元数据和查询元数据样式指南。

打包自定义查询

当你编写要与他人共享的查询时，将它们保存在自定义 CodeQL 包中。

要打包你的自定义查询：

  1. 创建一个 CodeQL 包，其根目录中包含 qlpack.yml 文件。
  2. 将自定义查询（.ql 文件）保存在包根目录或其子目录中。
  3. 将 qlpack.yml 文件配置为指定：
    • 如何编写查询
    • 对其他 CodeQL 包和库的依赖关系
    • 查询套件定义 有关 qlpack.yml 属性的更多信息，请参阅 使用 CodeQL 包自定义分析。
  4. 将你的包发布到 GitHub Packages - GitHub 容器注册表。 有关详细信息，请参阅“使用 CodeQL 包自定义分析”。

在 SARIF 文件中包括自定义 CodeQL 查询的查询帮助

有关查询帮助和文档格式的信息，请参阅 自定义 CodeQL 查询。

若要在运行代码扫描分析时在 SARIF 文件中包括查询帮助，

  1. 使用以下格式之一编写查询帮助： * Markdown 文件：将 Markdown 文件与同名查询一起保存（例如， my-query.md 对于 my-query.ql） * ** .qhelp 文件**：将查询帮助写为 .qhelp 格式，然后在运行分析之前将其转换为 Markdown。 有关详细信息，请参阅查询帮助文件和 测试查询帮助文件。

  2. 通过 --sarif-add-query-help 选项运行 codeql database analyze：

    codeql database analyze <database> --format=sarif-latest --output=results.sarif --sarif-add-query-help

    注意

    从 CodeQL CLI v2.7.1 及更高版本开始提供 --sarif-add-query-help 选项。

  3. 将 SARIF 文件上传到 GitHub。

延伸阅读

  •         [CodeQL 查询](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)