发布及使用 CodeQL 包

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

谁可以使用此功能？

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

在本文中

在 带有数据驻留权的 GitHub Enterprise Cloud 上使用 CodeQL 包

默认情况下，CodeQL CLI 期望在 GitHub.com 上下载 CodeQL 包并将包发布到 Container registry。 但是，也可以在 带有数据驻留权的 GitHub Enterprise Cloud 上的 Container registry 中使用 CodeQL 包，方法是创建一个 qlconfig.yml 文件，告诉 CLI 每个包使用哪个 Container registry。

使用首选文本编辑器在 Linux/MacOS 上创建 ~/.codeql/qlconfig.yml 文件或 %HOMEPATH%\.codeql\qlconfig.yml Windows，并添加条目以指定要用于一个或多个包名称模式的注册表。 例如，以下qlconfig.yml文件将所有包与Container registry在SUBDOMAIN.ghe.com相关联，但与codeql/\*匹配的包或属于other-org/*组织的除外，这些包与Container registry在GitHub.com相关联。

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  # Container registry on GitHub.com
  url: https://ghcr.io/v2/
- packages: '*'
  # Container registry hosted at `SUBDOMAIN.ghe.com`
  url: https://containers.SUBDOMAIN.ghe.com

通过在registries列表中查找第一个具备与该包名匹配的packages属性的项，CodeQL CLI将确定使用哪个注册表来处理给定包名。 这意味着，通常需要先定义最具体的包名称模式。 packages 属性可以是单个包名称、glob 模式，也可以是包名称和 glob 模式的 YAML 列表。

          `registries` 列表也可以放在 `codeql-workspace.yml` 文件中。 这样做将允许定义要在特定工作区中使用的注册表，以便它可以在工作区的其他用户 CodeQL 之间共享。 
          `registries` 中的 `codeql-workspace.yml` 列表将与全局 `qlconfig.yml` 中的列表合并，并优先于后者。 有关 `codeql-workspace.yml` 的详细信息，请参阅 [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#about-codeql-workspaces)。

现在可以使用 codeql pack publish、codeql pack download 和 codeql database analyze 在 带有数据驻留权的 GitHub Enterprise Cloud 上管理包。

认证到 GitHubContainer registries

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

在 GitHub.com

上向 Container registries 进行身份验证

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

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

在 带有数据驻留权的 GitHub Enterprise Cloud 上向 Container registries 进行身份验证

同样，您可以在带有数据驻留权的 GitHub Enterprise Cloud上向Container registry进行身份验证，或以两种方式同时向多个注册表进行身份验证（例如，从多个注册表下载或运行专用包）：

  1. 将--registries-auth-stdin选项传递给CodeQL CLI，然后通过标准输入提供注册表身份验证字符串。
  2. 将 CODEQL_REGISTRIES_AUTH 环境变量设置为注册表身份验证字符串。

注册表身份验证字符串是一个以逗号分隔的 <registry-url>=<token> 对列表，其中 registry-url 是一个 Container registry URL，如 https://containers.SUBDOMAIN.ghe.com，token 是 GitHub Apps 令牌或 Container registry 的 personal access token。 这可确保每个令牌仅传递到您所指定的 Container registry。

例如，以下注册表身份验证字符串指定 CodeQL CLI 应按如下所示进行身份验证：

  • 使用令牌 <token1> 在 GitHub.com 上对 Container registry 进行身份验证。
  • 使用令牌 <token2> 对位于 https://containers.SUBDOMAIN.ghe.com 的企业进行 Container registry 身份验证。
https://ghcr.io/v2/=<token1>,https://containers.SUBDOMAIN.ghe.com=<token2>

发布 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

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

codeql pack publish

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

注意

如果要将模型包 GitHubContainer 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)。