创建和使用 CodeQL 包

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

谁可以使用此功能？

CodeQL 可用于以下类型的仓库

本文档内容

关于 CodeQL 包和 CodeQL CLI

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

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

  • 查询包旨在运行。发布查询包时，捆绑包除了查询源外，还包括所有传递依赖项和每个查询的预编译表示。这确保了包中查询的一致性和高效执行。

  • 库包旨在供查询包（或其他库包）使用，本身不包含查询。库不会单独编译。

  • 模型包可用于扩展代码扫描分析，以包含默认情况下不支持的依赖项。模型包目前处于公开预览阶段，可能会发生更改。在公开预览期间，模型包可用于 C#、Java/Kotlin、Python 和 Ruby 分析。有关创建您自己的模型包的更多信息，请参阅“创建 CodeQL 模型包”。

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

有关已发布查询包与不同 CodeQL 版本之间兼容性的更多信息，请参阅“发布和使用 CodeQL 包”。

所有受支持语言的标准 CodeQL 包都发布在 容器注册表 中。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 模型包

注意

CodeQL 模型包和 CodeQL 模型编辑器目前处于公开预览阶段，如有更改，恕不另行通知。模型包支持 C#、Java/Kotlin、Python 和 Ruby 分析。

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

模型包是一个 CodeQL 包，其`qlpack.yml` 文件具有以下特征：

  • 它定义了`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 文档中的“使用语义版本控制”和语义版本规范。

创建模型包后，您可以像其他 CodeQL 包一样发布它。更多信息，请参见“发布和使用 CodeQL 包”。然后，您可以使用`--model-packs`选项在代码扫描分析中使用已发布的模型包。更多信息，请参见“使用 CodeQL 包定制分析”。

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

注意

这仅支持 CodeQL 查询包和库包。

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

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

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

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

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

codeql pack install

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

注意

  • 运行`codeql pack add`和`codeql pack install`命令将生成或更新`codeql-pack.lock.yml`文件。此文件应签入版本控制。`codeql-pack.lock.yml`文件包含包使用的精确版本号。更多信息，请参见“关于 codeql-pack.lock.yml 文件”。
  • 默认情况下，`codeql pack install`将从 GitHub.com 的容器注册表安装依赖项。您可以通过创建`qlconfig.yml`文件来从 GitHub Enterprise Server 容器注册表安装依赖项。更多信息，请参见 GitHub Enterprise Server 文档中的“发布和使用 CodeQL 包”。

自定义下载的 CodeQL 包

尝试更改包的推荐方法是克隆包含其源代码的存储库。

如果无法使用源存储库，并且您需要基于从容器注册表下载的包进行修改，请注意，这些包不打算在下载后进行修改或自定义，并且它们的格式将来可能会在没有太多通知的情况下更改。如果您需要修改内容，我们建议您在下载包后执行以下步骤：

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

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