创建并使用 CodeQL 包

关于 CodeQL 包和 CodeQL CLI

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

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

创建 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 模型编辑器。

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

创建模型包后，可以像其他 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 将从 Container registry 安装依赖项到 GitHub.com。可以通过从GitHub Enterprise ServerContainer registry创建qlconfig.yml文件来安装依赖项。有关详细信息，请参阅文档中的 GitHub Enterprise Server。

组织 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 源。

谁可以使用此功能？

在本文中