使用 CodeQL 包自定义分析

关于 CodeQL 包

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

CodeQL 包有三种类型：查询包、库包和模型包。

查询包包含一组可在 CodeQL 数据库上评估的预编译查询。查询包旨在运行。当发布查询包时，该捆绑包除了查询源之外，还包括所有传递依赖项和每个查询的预编译表示形式。这确保了包中查询的一致且高效的执行。
库包旨在供查询包（或其他库包）使用，本身不包含查询。库不会单独编译。
模型包可用于扩展代码扫描分析以识别默认情况下不支持的库和框架。模型包目前处于公开预览阶段，可能会发生变化。在公开预览期间，模型包可用于 C#、Java/Kotlin、Python 和 Ruby 分析。有关创建自己的模型包的更多信息，请参阅“创建和使用 CodeQL 包”。

所有受支持语言的标准 CodeQL 包都发布在容器注册表中。如果您以标准方式（使用 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/swift-queries

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

您可以使用 CodeQL CLI 发布您创建的 CodeQL 包。有关发布和下载 CodeQL 包的更多信息，请参阅“发布和使用 CodeQL 包”。

CodeQL CLI 包含由 GitHub 专家、安全研究人员和社区贡献者维护的查询。如果您想运行其他组织开发的查询，CodeQL 查询包提供了一种高效且可靠的方式来下载和运行查询，而模型包（公开预览版）可用于扩展代码扫描分析以识别默认情况下不支持的库和框架。有关查询包的更多信息，请参阅“关于使用 CodeQL 进行代码扫描”。有关编写您自己的模型包的信息，请参阅“创建和使用 CodeQL 包”。

在您可以使用 CodeQL 查询包分析数据库之前，必须从 GitHub 容器注册表下载您需要的任何软件包。这可以通过在 codeql database analyze 命令中使用 --download 标志来完成，也可以运行 codeql pack download 来完成。如果软件包不公开可用，则需要使用 GitHub 应用或个人访问令牌进行身份验证。有关更多信息和示例，请参阅“将 CodeQL 分析结果上传到 GitHub”。

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

注意

如果您指定要使用的查询包的特定版本，请注意，您指定的版本最终可能会变得过旧，以至于最新版本的 CodeQL 无法有效地使用它。为了确保最佳性能，如果您需要指定确切的查询包版本，则应在升级正在使用的 CodeQL CLI 时重新评估要固定到哪个版本。

有关包兼容性的更多信息，请参阅“发布和使用 CodeQL 包”。

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

此示例使用 --download 选项运行 codeql database analyze 命令以

下载 octo-org/security-queries 包的最新版本。
下载 octo-org/optional-security-queries 包的与版本 1.0.1 兼容的版本（在本例中为版本 1.0.2）。有关语义版本兼容性的更多信息，请参阅 npm 的语义版本范围文档。
运行 octo-org/security-queries 中的所有默认查询。
仅运行 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/[email protected]
> Installed fresh octo-org/[email protected]
> 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 查询时避免访问互联网，这将非常有用。在运行 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，它将相对于当前进程的工作目录进行解释。不支持通配符模式。

如果您同时指定了 scope/name 和 path，则 path 不能是绝对路径。它被认为相对于 CodeQL 包的根目录。

查询说明符示例

codeql/python-queries - codeql/python-queries 包最新版本默认查询套件中的所有查询。
codeql/[email protected] - 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/[email protected]:Functions - codeql/python-queries 包版本 1.2.3 中 Functions 目录中的所有查询。
codeql/[email protected]: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 文件中的所有查询。

提示

标准 CodeQL 查询包的默认查询套件是 codeql-suites/<lang>-code-scanning.qls。在每个包的 codeql-suites 目录中还可以找到其他一些有用的查询套件。例如，codeql/cpp-queries 包包含以下查询套件

cpp-code-scanning.qls - C++ 的标准代码扫描查询。此包的默认查询套件。
cpp-security-extended.qls - 来自 C++ 默认 cpp-code-scanning.qls 套件的查询，以及较低严重性和精度的查询。
cpp-security-and-quality.qls - 来自 cpp-security-extended.qls 的查询，以及可维护性和可靠性查询。

您可以在 CodeQL 存储库中查看这些查询套件的源代码。其他语言的查询套件与此类似。

使用模型包分析对自定义依赖项的调用

您可以使用 --model-packs 选项在代码扫描分析中包含已发布的模型包。例如

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --model-packs my-repo/my-java-model-pack \
  --output=/temp/my-company.sarif codeql/java-queries

在此示例中，标准查询包 codeql/java-queries 中的相关查询将使用来自模型包 my-repo/my-java-model-pack 的依赖项信息来检查调用这些依赖项的代码中的漏洞。

您可以在分析中指定多个已发布的模型包。

有关编写您自己的模型包的更多信息，请参阅“创建和使用 CodeQL 包”。

关于已发布的包

当发布一个包以供分析使用时，codeql pack create 或 codeql pack publish 命令会验证内容是否完整，并向其中添加一些其他内容

对于查询包，它所依赖的每个库包的副本，以及它开发所使用的精确版本。查询包的用户无需单独下载这些库包。
对于查询包，每个查询的预编译表示形式。与在每次分析时编译查询的 QL 源代码相比，这些查询执行速度更快。

大部分这些数据都位于已发布包中名为 .codeql 的目录中，但预编译的查询位于每个查询的 .ql 源代码旁边的 .qlx 后缀的文件中。在使用来自已发布包的查询分析数据库时，CodeQL 将加载这些文件而不是 .ql 源代码。如果您需要修改已发布包的内容，请务必删除所有 .qlx 文件，因为它们可能会阻止 .ql 文件中的修改生效。

谁可以使用此功能？

本文档内容