创建和使用 CodeQL 包

关于 CodeQL 包和 CodeQL CLI

CodeQL 包用于创建、共享、依赖并运行 CodeQL 查询和库。

您可以在 CodeQL CLI 中使用 pack 命令来创建 CodeQL 包、向包添加依赖项以及安装或更新依赖项。您还可以使用 pack 命令来发布和下载 CodeQL 包。

创建 CodeQL 包

您可以在项目的检出根目录下运行以下命令来创建 CodeQL 包

codeql pack init <scope>/<pack>

您必须指定

<scope>：您将发布到的 GitHub 组织或用户账户的名称。
<pack>：您正在创建的包的名称。

codeql pack init 命令会为 CodeQL 包创建目录结构和配置文件。默认情况下，该命令会创建一个查询包。如果您想创建库包，则必须编辑 qlpack.yml 文件，通过在其中添加 library: true 属性显式声明该文件为库包。

创建 CodeQL 模型包

注意

CodeQL 模型包目前处于公开预览阶段，可能会更改。模型包支持 C/C++、C#、Java/Kotlin、Python、Ruby 和 Rust 的分析。

Visual Studio Code 的 CodeQL 扩展中的 CodeQL 模型编辑器支持对 C#、Java/Kotlin、Python 和 Ruby 的依赖建模。

模型包可用于扩展代码扫描分析，以识别默认情况下不受支持的库和框架。模型包使用数据扩展（以 YAML 实现），描述如何为新依赖项添加数据。当指定模型包时，该包中的数据扩展会自动添加到代码扫描分析中。有关 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 文档中的使用语义化版本控制以及语义化版本规范。

创建模型包后，您可以像处理其他 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 包的目录结构

每个 CodeQL 包的根目录下必须包含名为 qlpack.yml 的文件。在 qlpack.yml 文件中，name: 字段的值必须遵循 <scope>/<pack> 的格式，其中 <scope> 为将要发布该包的 GitHub 组织或用户账户，<pack> 为包的名称。

此外，带有 CodeQL 测试的查询包和库包会包含一个 codeql-pack.lock.yml 文件，其中记录了包解析后的依赖关系。该文件在调用 codeql pack install 时生成，不应手动编辑，并应加入版本控制系统。

包内的其他文件和目录应进行合乎逻辑的组织。例如，通常情况下：

查询会按特定分类放入相应目录。
针对特定产品、库和框架的查询会放入各自的顶层目录。

自定义已下载的 CodeQL 包

实验性修改包的推荐方式是克隆包含其源代码的仓库。

如果没有可用的源仓库且您需要基于从容器注册表下载的包进行修改，请注意这些包并非设计用于下载后进行修改或自定义，其格式将来可能会在没有太多通知的情况下更改。若需修改内容，建议在下载包后执行以下步骤：

在 qlpack.yml 中更改包的名称，以免与未修改的包的结果产生混淆。
删除解压后目录结构中所有名为 *.qlx 的文件。这些文件包含查询的预编译版本，在某些情况下，CodeQL 会优先使用它们而不是您已修改的 QL 源代码。

谁可以使用此功能？

本文内容