发布及使用 CodeQL 包

共享或下载 CodeQL 包，然后分析 CodeQL 数据库。

谁可以使用此功能？

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

在本文中

对 GitHub Container registries 进行身份验证

可通过向相应的 GitHub Container registry 进行身份验证来发布包和下载专用包。

您可以通过两种方式对 Container registry 进行身份验证：

  1. 将 --github-auth-stdin 选项传递给 CodeQL CLI，然后通过标准输入提供 GitHub Apps 令牌或 personal access token。
  2. 将 GITHUB_TOKEN 环境变量设置为 GitHub Apps 令牌或 personal access token。

发布 CodeQL 包

若要与其他人共享你的 CodeQL 包，你可以将其发布到 Container registry。

在发布前配置 qlpack.yml 文件

可以在发布之前检查和修改 CodeQL 包的配置详细信息。 在你喜欢的文本编辑器中打开 qlpack.yml 文件。

library: # set to true if the pack is a library. Set to false or omit for a query pack
name: <scope>/<pack>
version: <x.x.x>
description: <Description to publish with the package>
defaultSuite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
defaultSuiteFile: default-queries.qls # optional, a pointer to a query-suite in this pack
license: # optional, the license under which the pack is published
dependencies: # map from CodeQL pack name to version range

  •         `name:` 必须采用 `<scope>/<pack>` 格式，其中 `<scope>` 是将发布到的 GitHub 组织，`<pack>` 是包的名称。

  • 最多只能选择 defaultSuite 和 defaultSuiteFile 中的一个。 有两种不同的方法来定义要运行的默认查询套件，第一种是直接在 qlpack.yml 文件中指定查询，第二种是在包中指定查询套件。

正在运行 codeql pack publish

准备好将包发布到 GitHub Container registry 时，可在包目录的根目录中运行以下命令：

codeql pack publish

已发布的包将显示在 GitHub 组织的“包”部分中，该组织由 qlpack.yml 文件中的范围指定。

注意

如果要将模型包发布到 GitHub Container registry，以便将覆盖范围扩展到组织中的所有存储库作为默认设置配置的一部分，则需要确保运行代码扫描的存储库可以访问这些模型包。 有关详细信息，请参阅 编辑默认设置配置 和 配置包的访问控制和可见性。

下载现有CodeQL包

若要运行其他人创建的包，必须先运行以下命令来下载它：

codeql pack download <scope>/<pack>@x.x.x

  •         `<scope>`：将从中下载的 GitHub 组织的名称。

  •         `<pack>`：要下载的包的名称。

  •         `@x.x.x`：可选版本号。 如果省略，将下载最新版本。

此命令接受多个包的参数。

如果编写脚本来指定要下载的查询包的特定版本号，请记住，在将 CodeQL 的版本更新为更新的版本时，可能还需要切换到更新的查询包版本。 与固定到非常旧的版本的查询包一起使用时，较新版本的 CodeQL _可能_会导致性能降低。 有关详细信息，请参阅“CodeQL 查询包参考”。

使用 CodeQL 包分析 CodeQL 数据库

若要使用 CodeQL 包分析 CodeQL 数据库，请运行以下命令：

codeql database analyze <database> <scope>/<pack>@x.x.x:<path>

  •         `<database>`：要分析的 CodeQL 数据库。

  •         `<scope>`：将包发布到的 GitHub 组织的名称。

  •         `<pack>`：正在使用的包的名称。

  •         `@x.x.x`：可选版本号。 如果省略，将使用最新版本。

  •         `:<path>`：查询、目录或查询套件的可选路径。 如果省略，将使用包的默认查询套件。

        `analyze` 命令将运行任何指定的 CodeQL 包的默认套件。 可以指定多个用于分析 CodeQL 数据库的 CodeQL 包。 例如：

codeql <database> analyze <scope>/<pack> <scope>/<other-pack>

注意

          `codeql pack download` 命令将其下载的包存储在不用于本地修改的内部位置。 如果在下载后修改包，可能会导致意外（且很难进行排除故障）的行为。 有关自定义包的详细信息，请参阅 [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs)。