创建并使用 CodeQL 包

可以使用 CodeQL 包创建、共享、依赖和运行 CodeQL 查询和库。

谁可以使用此功能？

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

本文内容

关于 CodeQL 包和 CodeQL CLI

CodeQL 包用于创建、共享、依赖和运行 CodeQL 查询和库。 CodeQL 包中具有查询、库文件、查询套件和元数据。 使用 CodeQL 包和 CodeQL CLI 中的包管理命令，可以发布自定义查询并将其集成到代码库分析中。

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

  • 查询包专为运行设计。 发布查询包时，除了查询源外，捆绑包还包括每个查询的所有可传递依赖项和预编译表示形式。 这可确保一致且高效地执行包中的查询。

  • 库包旨在供查询包（或其他库包）使用，并且不包含查询本身。 这些库不是单独编译的。

  • 模型包可用于扩展 code scanning 分析，以包含默认情况下不支持的依赖项。 模型包目前为 公共预览版，可能会更改。 在 公共预览版 期间，模型包可用于 C#、Java/Kotlin、Python，以及 Ruby 分析。 有关创建自己的模型包的详细信息，请参阅创建 CodeQL 模型包。

可以使用 CodeQL CLI 中的 pack 命令创建 CodeQL 包、向包添加依赖项以及安装或更新依赖项。 还可以使用 pack 命令发布和下载 CodeQL 包。 有关详细信息，请参阅“发布及使用 CodeQL 包”。

有关已发布查询包与不同 CodeQL 版本之间的兼容性的详细信息，请参阅 发布及使用 CodeQL 包。

所有受支持语言的标准 CodeQL 包在 Container registry 中发布。 CodeQL 存储库包含所有受支持语言的标准 CodeQL 包的源文件。 CodeQL CLI 捆绑包中包含的但可以以其他方式下载的核心查询包包括：

  • codeql/cpp-queries
  • codeql/csharp-queries
  • codeql/go-queries
  • codeql/java-queries
  • codeql/javascript-queries
  • codeql/python-queries
  • codeql/ruby-queries

CodeQL 包结构

CodeQL 包的根目录中必须包含名为 qlpack.yml 的文件。 在 qlpack.yml 文件中，name: 字段必须具有采用 <scope>/<pack> 格式的值，其中 <scope> 是包将发布到的 GitHub 组织或用户帐户，<pack> 是包的名称。 此外，具有 CodeQL 测试的查询包和库包一个中有一个 codeql-pack.lock.yml 文件，该文件中有包的已解析依赖项。 此文件是在调用 codeql pack install 命令期间生成的，不应手动编辑，并且应将其添加到版本控制系统中。

包内的其他文件和目录应按逻辑组织。 例如，通常：

  • 查询按特定类别组织到目录中。

  • 对特定产品、库和框架的查询组织为其自己的顶级目录。

创建 CodeQL 包

可以通过从项目的签出根运行以下命令来创建 CodeQL 包：

codeql pack init <scope>/<pack>

必须指定以下内容：

  • <scope>：将发布到的 GitHub 组织或用户帐户的名称。

  • <pack>：正在创建的包的名称。

codeql pack init 命令为 CodeQL 包创建目录结构和配置文件。 默认情况下，此命令会创建查询包。 如果要创建库包，必须编辑 qlpack.yml 文件，通过包含 library:true 属性将文件显式声明为库包。

创建 CodeQL 模型包

Note

CodeQL 模型包和 CodeQL 模型编辑器当前为 公共预览版，可能随时更改。 模型包由 C#、Java/Kotlin、Python，以及 Ruby 分析支持。

模型包可用于扩展 code scanning 分析，以识别默认情况下不支持的库和框架。 模型包使用作为 YAML 实现的数据扩展，并描述如何为新依赖项添加数据。 指定模型包后，该包中的数据扩展将自动添加到 code scanning 分析中。 有关 CodeQL 模型包和数据扩展的详细信息，请参阅 使用 CodeQL 模型编辑器。

模型包是在 qlpack.yml 文件中具有以下特征的 CodeQL 包：

  • 其定义 library: true。
  • 其没有依赖项。
  • 其有一个或多个 extensionTargets。
  • 其具有指向一个或多个数据扩展文件的 dataExtensions 属性。

如果模型包位于指定的版本范围内，则模型包会将指定的数据扩展注入到已在 extensionTargets 中命名的每个查询包中。 例如：

name: my-repo/my-java-model-pack
version: 1.2.3
extensionTargets:
  codeql/java-all: ~1.2.3
  codeql/util: ~4.5.6
dataExtensions:
  - models/**/*.yml

在此示例中，模型包会将 models/**/ 中的所有数据扩展注入到版本范围是 1.2.3 到最高 1.3.0（含该版本）的 codeql/java-all 查询包和版本范围是 4.5.6 到最高 4.6.0（含该版本）的 codeql/util 查询包中。 有关详细信息，请参阅 npm 文档中的使用语义版本控制和语义版本控制规范。

创建模型包后，可以使用与其他 % data variables.product.prodname_codeql %} 包相同的方式来发布模型包。 有关详细信息，请参阅“发布及使用 CodeQL 包”。 然后可以使用 --model-packs 选项，在 code scanning 分析中使用已发布的模型。 有关详细信息，请参阅“使用 CodeQL 包自定义分析”。

在 CodeQL 包中添加和安装依赖项

Note

仅 CodeQL 查询包和库包支持此功能。

可以使用命令 codeql pack add 添加对 CodeQL 包的依赖项。 必须指定范围、名称和（可选）兼容版本范围。

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

如果未指定版本范围，则将添加最新版本。 否则，将添加满足所请求范围的最新版本。

此命令使用请求的依赖项更新 qlpack.yml 文件，并将其下载到包缓存中。 请注意，此命令将重新格式化文件并删除所有注释。

还可以手动编辑 qlpack.yml 文件以包含依赖项，并使用以下命令安装依赖项：

codeql pack install

此命令将所有依赖项下载到本地磁盘上的共享缓存。

Note

  • 运行 codeql pack add 和 codeql pack install 命令将生成或更新 codeql-pack.lock.yml 文件。 此文件应签入版本控制。 codeql-pack.lock.yml 文件包含包使用的确切版本号。 有关详细信息，请参阅关于 codeql-pack.lock.yml 文件。
  • 默认情况下，codeql pack install 将在 GitHub.com 上安装来自 Container registry 的依赖项。 可以通过创建 qlconfig.yml 文件从 GitHub Enterprise Server Container registry 安装依赖项。 有关详细信息，请参阅 GitHub Enterprise Server 文档中的 发布及使用 CodeQL 包。

自定义下载的 CodeQL 包

试验更改包的建议方法是克隆包含其源代码的存储库。

如果没有可用的源存储库，并且需要基于从 Container registry 下载的包进行修改，请注意，下载后不应修改或自定义这些包，并且其格式将来可能会更改，而不会另行通知。 如果需要修改内容，建议在下载包后执行以下步骤：

  • 更改 qlpack.yml 中的包名称，以避免与未修改的包的结果混淆。

  • 删除解压缩目录结构中任意位置的名为 *.qlx 的所有文件。 这些文件包含查询的预编译版本，在某些情况下，CodeQL 将优先使用它们，而不是已修改的 QL 源。