使用 CodeQL 包自定义分析

您可以通过下载他人创建的包并在代码库中运行它们，来自定义您的 CodeQL 分析。有关详细信息，请参阅“CodeQL 查询包”。

下载和使用 CodeQL 查询包

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

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

注意

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

有关包兼容性的详细信息，请参阅 CodeQL 查询包参考。

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

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

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

$ 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 查询时访问 Internet，这非常有用。运行 CodeQL 分析时，可以按与上一示例中相同的方式指定包、版本和路径：

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

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

如果您的 CodeQL 包位于多个容器镜像注册表中，则必须告知 CodeQL CLI 到哪里查找每个包。有关详细信息，请参阅“代码扫描的工作流配置选项”。

指定在 CodeQL 包中运行哪些查询

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

scope/name 是 CodeQL 包的限定名。
range 是语义化版本范围。
path 是指向单个查询、包含查询的目录或查询套件文件的文件系统路径。

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

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

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

示例查询说明符

codeql/python-queries - codeql/python-queries 包最新版本的默认查询套件中的所有查询。
codeql/[email protected] - 1.2.3 包 codeql/python-queries 版本的默认查询套件中的所有查询。
codeql/python-queries@~1.2.3 - codeql/python-queries 包最新版本（>= 1.2.3 且 < 1.3.0）的默认查询套件中的所有查询。
codeql/python-queries:Functions - Functions 包最新版本的 codeql/python-queries 目录中的所有查询。
codeql/[email protected]:Functions - Functions 包 1.2.3 版本的 codeql/python-queries 目录中的所有查询。
codeql/[email protected]:codeql-suites/python-code-scanning.qls - codeql-suites/python-code-scanning.qls 包 1.2.3 版本的 codeql/python-queries 目录中的所有查询。
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 选项，在 code scanning 分析中包含已发布的模型包。例如：

$ 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 的目录中，但预编译查询位于每个查询的 .qlx 源旁边带有 .ql 后缀的文件中。使用来自已发布包的查询分析数据库时，CodeQL 将加载这些文件，而不是加载 .ql 源中的文件。如果需要修改_已发布_包的内容，请务必删除所有 .qlx 文件，因为它们可能会阻止 .ql 文件中的修改生效。

谁可以使用此功能？

在本文中