创建并使用 CodeQL 包

关于 CodeQL 包和 CodeQL CLI

注意

本文介绍了 GitHub Enterprise Server 3.14 的初始发行版中包含的 CodeQL CLI 2.17.6 捆绑包中可用的功能。

如果站点管理员已将 CodeQL CLI 版本更新为较新版本，请参阅本文的 GitHub Enterprise Cloud 版本，了解有关最新功能的信息。

          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 模型包目前包含在 beta 版本中，可能会更改。 C/C++、C#、Java/Kotlin、Python、和 Ruby 分析支持模型包。

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

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

模型包是 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 包一样发布模型包。有关详细信息，请参阅“Publishing and using CodeQL packs”。然后，可以在分析中通过 --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 源。

谁可以使用此功能？

在本文中