{"meta":{"title":"创建并使用 CodeQL 包","intro":"可以使用 CodeQL 包创建、共享、依赖和运行 CodeQL 查询和库。","product":"安全性和代码质量","breadcrumbs":[{"href":"/zh/code-security","title":"安全性和代码质量"},{"href":"/zh/code-security/tutorials","title":"Tutorials"},{"href":"/zh/code-security/tutorials/customize-code-scanning","title":"自定义代码扫描"},{"href":"/zh/code-security/tutorials/customize-code-scanning/creating-and-working-with-codeql-packs","title":"创建并使用 CodeQL 包"}],"documentType":"article"},"body":"# 创建并使用 CodeQL 包\n\n可以使用 CodeQL 包创建、共享、依赖和运行 CodeQL 查询和库。\n\n## 关于 CodeQL 包和 CodeQL CLI\n\n```\n          CodeQL 包用于创建、共享、依赖和运行 CodeQL 查询和库。\n```\n\n可以使用 `pack` 命令在 CodeQL CLI 中创建 CodeQL 包、添加或安装依赖项，以及更新依赖项。 还可以使用CodeQL命令发布和下载`pack`包。\n\n## 创建 CodeQL 包\n\n可以通过从项目的签出根目录运行以下命令来创建 CodeQL 包：\n\n```shell\ncodeql pack init <scope>/<pack>\n```\n\n必须指定以下内容：\n\n* `<scope>`：要发布到的组织 GitHub 或用户帐户的名称。\n\n* `<pack>`：你正在创建的包的名称。\n\n该 `codeql pack init` 命令为 CodeQL 包创建目录结构和配置文件。 默认情况下，此命令会创建查询包。 如果要创建库包，必须编辑 `qlpack.yml` 文件，通过包含 `library:true` 属性将文件显式声明为库包。\n\n## 创建 CodeQL 模型包\n\n> \\[!NOTE]\n> CodeQL 模型包目前包含在 公共预览版 中，可能会更改。 C/C++、C#、Java/Kotlin、Python、Ruby 和 Rust 分析支持模型包。\n>\n> CodeQL 的 CodeQL 扩展中的 Visual Studio Code 支持对  C#、Java/Kotlin、Python 和 Ruby 的依赖项建模。\n\n模型包可用于扩展 code scanning 分析，以识别默认情况下不支持的库和框架。 模型包使用作为 YAML 实现的数据扩展，并描述如何为新依赖项添加数据。 指定模型包后，该包中的数据扩展插件将自动添加到 code scanning 分析中。 有关模型包和数据扩展插件的详细信息 CodeQL ，请参阅 [使用 CodeQL 模型编辑器](/zh/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor)。\n\n模型包是 CodeQL 文件中具有以下特征的 `qlpack.yml` 包：\n\n* 其定义 `library: true`。\n* 其没有依赖项。\n* 其有一个或多个 `extensionTargets`。\n* 其具有指向一个或多个数据扩展文件的 `dataExtensions` 属性。\n\n如果模型包位于指定的版本范围内，则模型包会将指定的数据扩展注入到已在 `extensionTargets` 中命名的每个查询包中。 例如：\n\n```yaml\nname: my-repo/my-java-model-pack\nversion: 1.2.3\nextensionTargets:\n  codeql/java-all: ~1.2.3\n  codeql/util: ~4.5.6\ndataExtensions:\n  - models/**/*.yml\n```\n\n在此示例中，模型包会将 `models/**/` 中的所有数据扩展注入到版本范围是 `codeql/java-all` 到最高 `1.2.3`（含该版本）的 `1.3.0` 查询包和版本范围是 `codeql/util` 到最高 `4.5.6`（含该版本）的 `4.6.0` 查询包中。 有关详细信息，请参阅 npm 文档中的[使用语义化版本控制](https://docs.npmjs.com/about-semantic-versioning#using-semantic-versioning-to-specify-update-types-your-package-can-accept)和[语义化版本控制规范](https://semver.org/)。\n\n创建模型包后，可以像其他 CodeQL 包一样发布模型包。 有关详细信息，请参阅“[发布及使用 CodeQL 包](/zh/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs)”。 然后，可以在分析中通过 `--model-packs` 选项使用 code scanning 已发布的模型包。 有关详细信息，请参阅“[使用 CodeQL 包自定义分析](/zh/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies)”。\n\n## 在 CodeQL 包中安装和添加依赖项\n\n> \\[!NOTE]\n> 这仅适用于 CodeQL 查询和库包。\n\n可以使用命令`codeql pack add`为CodeQL包添加依赖项。 必须指定范围、名称和（可选）兼容版本范围。\n\n```shell\ncodeql pack add <scope>/<name>@x.x.x <scope>/<other-name>\n```\n\n如果未指定版本范围，则将添加最新版本。 否则，将添加满足所请求范围的最新版本。\n\n此命令使用请求的依赖项更新 `qlpack.yml` 文件，并将其下载到包缓存中。 请注意，此命令将重新格式化文件并删除所有注释。\n\n还可以手动编辑 `qlpack.yml` 文件以包含依赖项，并使用以下命令安装依赖项：\n\n```shell\ncodeql pack install\n```\n\n此命令将所有依赖项下载到本地磁盘上的共享缓存。\n\n> \\[!NOTE]\n>\n> * 运行 `codeql pack add` 和 `codeql pack install` 命令将生成或更新 `codeql-pack.lock.yml` 文件。 此文件应签入版本控制。\n>   `codeql-pack.lock.yml` 文件包含包使用的确切版本号。 有关详细信息，请参阅[关于 codeql-pack.lock.yml 文件](/zh/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs##about-codeql-packlockyml-files)。\n> * 默认情况下，`codeql pack install` 将从 Container registry 安装依赖项到 GitHub.com。 可以通过从GitHub Enterprise ServerContainer registry创建`qlconfig.yml`文件来安装依赖项。 有关详细信息，请参阅文档中的 [](/zh/enterprise-server@3.20/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs)GitHub Enterprise Server。\n\n## 组织 CodeQL 包的目录结构\n\n包CodeQL在其根目录中必须包含一个名为`qlpack.yml`的文件。 在`qlpack.yml`文件中，`name:`字段必须有一个值，该值符合`<scope>/<pack>`的格式，其中`<scope>`指的是GitHub，即包将发布到的组织或用户帐户，而`<pack>`是包的名称。\n\n此外，包含 CodeQL 测试的查询包和库包包含包含 `codeql-pack.lock.yml` 包解析依赖项的文件。 此文件是在调用 `codeql pack install` 命令期间生成的，不应手动编辑，并且应将其添加到版本控制系统中。\n\n包内的其他文件和目录应按逻辑组织。 例如，通常：\n\n* 查询按特定类别组织到目录中。\n* 对特定产品、库和框架的查询组织为其自己的顶级目录。\n\n## 自定义下载的 CodeQL 包\n\n试验更改包的建议方法是克隆包含其源代码的存储库。\n\n如果没有可用的源存储库，并且你需要基于从 Container registry中下载的包进行基本修改，请注意，下载后不会修改或自定义这些包，并且其格式将来可能会更改，而无需太多注意。 如果需要修改内容，建议在下载包后执行以下步骤：\n\n* 修改 \\_\\_ 中的包`qlpack.yml`，以避免与未修改包的结果混淆。\n\n* 删除解压缩目录结构中任意位置的名为 `*.qlx` 的所有文件。 这些文件包含预编译的查询版本，并且在某些情况下，CodeQL 将会优先使用这些版本，而不是您已修改的 QL 源。"}