您可以通过下载他人创建的包并在代码库上运行它们来自定义 CodeQL 分析。欲了解更多信息，请参阅 CodeQL 查询包。
下载并使用 CodeQL 查询包
在能够使用 CodeQL 查询包分析数据库之前，您必须从 GitHub Container Registry 下载所需的所有软件包。可以通过在 codeql database analyze 命令中使用 --download 标志，或运行 codeql pack download 来完成此操作。如果软件包未公开提供，则需要使用 GitHub App 或个人访问令牌进行身份验证。有关更多信息和示例，请参阅 将 CodeQL 分析结果上传到 GitHub。
| 选项 | 是否必填 | 用途 |
|---|---|---|
<scope/name@version:path> | 使用逗号分隔的列表指定一个或多个 CodeQL 查询包的作用域和名称以下载。可选地，包含要下载并解压的版本。默认情况下会下载该包的最新版本。可选地，包含要运行的查询、目录或查询套件的路径。如果未包含路径，则运行该包的默认查询。 | |
--github-auth-stdin | 通过标准输入将用于 GitHub REST API 身份验证的 GitHub App 或个人访问令牌从您的密钥存储传递给 CLI。如果命令已能够访问设置了该令牌的 GITHUB_TOKEN 环境变量，则无需此操作。 |
注意
如果您指定了特定版本的查询包，请注意您指定的版本可能最终会因为 CodeQL 最新版本而变得过旧，难以高效使用。为确保最佳性能，如果需要固定查询包的确切版本，请在每次升级所使用的 CodeQL CLI 时重新评估您所锁定的版本。
有关包兼容性的更多信息，请参阅 CodeQL 查询包参考。
下载并使用查询包的基本示例
此示例使用 --download 选项运行 codeql database analyze 命令，以
- 下载
octo-org/security-queries包的最新版本。 - 下载与版本
1.0.1兼容 的octo-org/optional-security-queries包的一个版本（本例中为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/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 查询时避免联网时非常有用。运行 CodeQL 分析时，您可以像前面示例那样以相同方式指定包、版本和路径。
echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...
从多个 GitHub Container Registry 下载 CodeQL 包
如果您的 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/python-queries@1.2.3- 版本为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- 最新版本的codeql/python-queries包中Functions目录下的所有查询。 -
codeql/python-queries@1.2.3:Functions- 版本为1.2.3的codeql/python-queries包中Functions目录下的所有查询。 -
codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls- 版本为1.2.3的codeql/python-queries包中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- 来自默认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 文件所做的修改生效。