使用 CodeQL 包自定义分析

关于 CodeQL 包

CodeQL 包用于创建、共享、依赖和运行 CodeQL 查询和库。 CodeQL 包中具有查询、库文件、查询套件和元数据。 可以通过下载其他人创建的包并在代码库上运行这些包来自定义 CodeQL 分析。

有两种类型的 CodeQL 包：查询包和库包。

• 查询包包含一组预编译的查询，这些查询可在 CodeQL 数据库上进行评估。 查询包专为运行设计。 发布查询包时，此捆绑包中具有每个查询的所有可传递依赖项和编译缓存。 这可确保一致且高效地执行包中的查询。

• 库包旨在供查询包（或其他库包）使用，并且不包含查询本身。 库不可编译，并且在发布包时不包含编译缓存。

所有受支持语言的标准 CodeQL 包在 Container registry 中发布。 如果使用 CodeQL CLI 捆绑包以标准方式安装 CodeQL CLI，则核心查询包已下载并可供使用。 它们分别是：

• codeql/cpp-queries
• codeql/csharp-queries
• codeql/go-queries
• codeql/java-queries
• codeql/javascript-queries
• codeql/python-queries
• codeql/ruby-queries

还可以使用 CodeQL CLI 创建你自己的 CodeQL 包、向包添加依赖项以及安装或更新依赖项。 有关详细信息，请参阅“创建并使用 CodeQL 包”。

可以使用 CodeQL CLI 发布已创建的 CodeQL 包。 有关发布和下载 CodeQL 包的详细信息，请参阅“发布及使用 CodeQL 包”。

下载和使用 CodeQL 查询包

CodeQL CLI 捆绑包中包括由 GitHub 专家、安全研究人员和社区贡献者维护的查询。 如果要运行其他组织开发的查询，CodeQL 查询包提供了一种高效、可靠的方法来下载和运行查询。 有关查询包的详细信息，请参阅“关于使用 CodeQL 进行代码扫描”。

在使用 CodeQL 查询包分析数据库之前，必须从 GitHub Container registry 下载所需的任何包。 这可以通过使用 --download 标志作为 codeql database analyze 命令的一部分或运行 codeql pack download 来完成。 如果包不是公开可用，需要使用 GitHub App 或 personal access token 进行身份验证。 有关详细信息和示例，请参阅“将 CodeQL 分析结果上传到 GitHub”。

选项	必选	使用情况
<scope/name@version:path>		使用以逗号分隔的列表指定要下载的一个或多个 CodeQL 查询包的作用域和名称。 （可选）包括要下载和解压缩的版本。 默认情况下，将下载此包的最新版本。 （可选）包括要运行的查询、目录或查询套件的路径。 如果未包括路径，则运行此包的默认查询。
--github-auth-stdin		通过标准输入，将为对 GitHub 的 REST API 进行身份验证而创建的 GitHub App 或 personal access token 从机密存储库传递给 CLI。 如果命令有权访问使用此令牌设置的 GITHUB_TOKEN 环境变量，则不需要执行此操作。

下载并使用查询包的基本示例

此示例运行包含 --download 选项的 codeql database analyze 命令来执行以下操作：

1. 下载最新版本的 octo-org/security-queries 包。
2. 下载与版本 1.0.1 兼容的 octo-org/optional-security-queries 包版本（在本例中为版本 1.0.2）。 有关 SemVer 兼容性的详细信息，请参阅 npm 的语义化版本范围文档。
3. 在 octo-org/security-queries 中运行所有默认查询。
4. 在 octo-org/optional-security-queries 中仅运行查询 queries/csrf.ql

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

直接下载 CodeQL 包

如果要在不立即运行 CodeQL 包的情况下进行下载，则可以使用 codeql pack download 命令。 如果要避免在运行 CodeQL 查询时访问 Internet，此选项非常有用。 运行 CodeQL 分析时，可以采用与上一示例相同的方式指定包、版本和路径：

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

从多 GitHub 容器注册表下载 CodeQL 包

如果 CodeQL 包存在于多个容器注册表上，就必须指示 CodeQL CLI 在何处查找每个包。 有关详细信息，请参阅“自定义 代码扫描的高级设置”。

指定要在 CodeQL 包中运行的查询

查询说明符由 codeql database analyze 和对一组查询进行操作的其他命令使用。 查询说明符的完整形式为 scope/name@range:path，其中：

• scope/name 是 CodeQL 包的限定名称。
• range 是一个 SemVer 范围。
• path 是到单个查询、包含查询的目录或查询套件文件的文件系统路径。

指定 scope/name 时，range 和 path 是可选的。 如果省略 range，则使用指定包的最新版本。 如果省略 path，则使用指定包的默认查询套件。

path 可以是以下项之一：.ql 查询文件、包含一个或多个查询的目录或 .qls 查询套件文件。 如果省略包名称，则必须提供 path，它将相对于当前进程的工作目录进行解释。 不支持 glob 模式。

如果同时指定 scope/name 和 path，则 path 不能为绝对值。 它被视为相对于 CodeQL 包的根。

示例查询说明符

• codeql/python-queries - 最新版本 codeql/python-queries 包的默认查询套件中的所有查询。

• codeql/python-queries@1.2.3 - codeql/python-queries 包的版本 1.2.3 的默认查询套件中的所有查询。

• codeql/python-queries@~1.2.3 - 最新版本 codeql/python-queries 包的默认查询套件中的所有查询 >= 1.2.3 且 < 1.3.0。

• codeql/python-queries:Functions - 最新版本的 codeql/python-queries 包中 Functions 目录中的所有查询。

• codeql/python-queries@1.2.3:Functions - codeql/python-queries 包版本 1.2.3 中 Functions 目录中的所有查询。

• codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls - codeql/python-queries 包版本 1.2.3 中 codeql-suites/python-code-scanning.qls 目录中的所有查询。

• suites/my-suite.qls - suites/my-suite.qls 文件中相对于当前工作目录的所有查询。