创建并使用 CodeQL 包

关于 CodeQL 包和 CodeQL CLI

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

有两种类型的 CodeQL 包：查询包和库包。

• 查询包专为运行设计。 发布查询包时，除了查询源外，捆绑包还包括每个查询的所有可传递依赖项和预编译表示形式。 这可确保一致且高效地执行包中的查询。

• 库包旨在供查询包（或其他库包）使用，并且不包含查询本身。 这些库不是单独编译的。

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

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

所有受支持语言的标准 CodeQL 包在 Container registry 中发布。 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 pack add 添加对 CodeQL 包的依赖项。 必须指定范围、名称和（可选）兼容版本范围。

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

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

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

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

codeql pack install

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

自定义下载的 CodeQL 包

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

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

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

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