创建并使用 CodeQL 包

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

谁可以使用此功能？

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 的依赖项建模。

模型包可用于扩展 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/**/ 中的所有数据扩展注入到版本范围是 codeql/java-all 到最高 1.2.3（含该版本）的 1.3.0 查询包和版本范围是 codeql/util 到最高 4.5.6（含该版本）的 4.6.0 查询包中。 有关详细信息，请参阅 npm 文档中的使用语义化版本控制和语义化版本控制规范。

创建模型包后，可以使用与其他 % data variables.product.prodname_codeql %} 包相同的方式来发布模型包。 有关详细信息，请参阅“发布及使用 CodeQL 包”。 然后可以使用 --model-packs 选项，在 code scanning 分析中使用已发布的模型。 有关详细信息，请参阅“使用 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 上安装来自 Container registry 的依赖项。 可以通过创建 qlconfig.yml 文件从 GitHub Enterprise Server Container registry 安装依赖项。 有关详细信息，请参阅 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 包

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

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

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

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