{"meta":{"title":"CodeQL 查询包参考","intro":"了解 CodeQL 包的兼容性、内容和结构。","product":"安全性和代码质量","breadcrumbs":[{"href":"/zh/code-security","title":"安全性和代码质量"},{"href":"/zh/code-security/reference","title":"Reference"},{"href":"/zh/code-security/reference/code-scanning","title":"代码扫描"},{"href":"/zh/code-security/reference/code-scanning/codeql","title":"CodeQL"},{"href":"/zh/code-security/reference/code-scanning/codeql/codeql-cli","title":"CodeQL命令行界面 (CLI)"},{"href":"/zh/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs","title":"CodeQL 查询包"}],"documentType":"article"},"body":"# CodeQL 查询包参考\n\n了解 CodeQL 包的兼容性、内容和结构。\n\n## CodeQL 包兼容性\n\n发布查询包时，它将包括其中所有查询的预编译表示形式，以提高分析速度。 但是，如果执行分析的 CodeQL 版本比运行 `codeql pack publish` 的版本更新了 6 个月以上，则可能需要在分析过程中从源代码编译查询，从而大大减缓了过程。\n\n由 CodeQL 的\\_最新\\_公开版本发布的包可供 CodeQL 和 code scanning 使用的 GitHub Actions 版本使用，即使该版本通常略微更旧也是如此。\n\n如果分析包含如下行，则 CodeQL 已成功使用预编译查询：\n\n```shell\n[42/108] Loaded /long/path/to/query/Filename.qlx.\n```\n\n如果你的分析包含以下行，则表示 CodeQL 手动从源代码重新编译查询：\n\n```shell\nCompiling query plan for /long/path/to/query/Filename.ql.\n[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.\n```\n\n为了帮助查询包的用户从预编译的查询中受益，我们建议使用最新版本的 CodeQL 来发布包。 此外，你应该每 6 个月发布一个新版本的包，其中包含更新的 CodeQL 版本。\n\n如果发布查询包的目的是在使用其捆绑的 GitHub Enterprise Server 二进制文件的 CodeQL 安装上使用查询包，请使用相同的 CodeQL 版本来运行 `codeql pack publish`。\n\n##\n\n```\n          `qlpack.yml` 文件\n```\n\n执行与查询相关的命令时，CodeQL 首先查找安装目录同级目录（及其子目录）中的 `qlpack.yml` 文件，然后在包缓存中检查下载的 CodeQL 包。 这意味着，当安装目录中的本地包替代包缓存中同名的包时，可以测试本地更改。\n\n每个 `qlpack.yml` 文件中的元数据显示了 CodeQL 如何编译包中的任何查询、包依赖于哪些库以及在何处查找查询套件定义。\n\nCodeQL 包（CodeQL 分析中使用的查询或库）的内容与 `qlpack.yml` 或其子目录包含在同一目录中。\n\n包含 `qlpack.yml` 文件的目录用作 CodeQL 包内容的根目录。 也就是说，对于包中的所有 `.ql` 和 `.qll` 文件，CodeQL 将解析与包根目录中包含 `qlpack.yml` 文件的目录相关的所有 import 语句。\n\n###\n\n```\n          `qlpack.yml` 属性\n\n          `qlpack.yml` 文件中支持以下属性。\n```\n\n#### `name`\n\n* 这是所有包所必需的。\n* 定义包的范围、发布 CodeQL 包的位置，以及使用字母数字字符和连字符定义的包名称。 它必须是唯一的，因为 CodeQL 无法区分具有相同名称的 CodeQL 包。 使用包名称指定要使用 `database analyze` 运行的查询，并定义 CodeQL 包之间的依赖项（请参阅下面的示例）。 例如：\n\n  ```yaml\n  name: octo-org/security-queries\n  ```\n\n#### `version`\n\n* 对于已发布的所有包，这是必需的。\n* 为此 CodeQL 包定义一个语义版本，该版本必须符合 [SemVer v2.0.0 规范](https://semver.org/spec/v2.0.0.html)。 例如：\n\n  ```yaml\n  version: 0.0.0\n  ```\n\n#### `dataExtensions`\n\n* 这是所有模型包所必需的。\n* 获取 glob 模式列表，该模式指定数据扩展插件文件相对于查询包或库包的根目录的位置。\n\n#### `dependencies`\n\n* 对于定义 CodeQL 包对其他包的依赖项的查询包和库包而言，这是必需的。 模型包不能定义任何依赖项并改用 `extensionTargets`。\n* 定义从包引用到与此包兼容的语义版本范围的映射。 支持用于 CodeQL CLI v2.6.0 及更高版本。 例如：\n\n  ```yaml\n  dependencies:\n    codeql/cpp-all: ^0.0.2\n  ```\n\n  如果不确定或应使用哪个版本不重要，则可以使用 `\"*\"`，这表示此依赖项的任何版本都与此包兼容。 在实践中，这通常会解析为依赖项的最高已发布版本。\n\n  有一个特殊的版本占位符 `${workspace}`，其指示此 CodeQL 包依赖于同一工作区中的依赖项版本。 有关详细信息，请参阅“[关于 CodeQL 工作区](/zh/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#using-workspace-as-a-version-range-in-qlpackyml-files)”。\n\n#### `defaultSuiteFile`\n\n* 对于导出要运行的一组默认查询的包，这是必需的。\n* 定义相对于程序包根目录的查询套件文件的路径，其中包含将此包传递给 `codeql database analyze` 命令时默认运行的所有查询。 从 CLI v2.6.0 及更高版本开始支持。 只能定义 `defaultSuiteFile` 或 `defaultSuite` 之一。 例如：\n\n  ```yaml\n  defaultSuiteFile: cpp-code-scanning.qls\n  ```\n\n#### `defaultSuite`\n\n* 对于导出要运行的一组默认查询的包，这是必需的。\n* 定义一个内联查询套件，其中包含将此包传递至 `codeql database analyze` 命令时默认运行的所有查询。 从 CLI v2.6.0 及更高版本开始支持。 只能定义 `defaultSuiteFile` 或 `defaultSuite` 之一。 例如：\n\n  ```yaml\n  defaultSuite:\n    queries: .\n    exclude:\n      precision: medium\n  ```\n\n#### `extensionTargets`\n\n* 这是所有模型包所必需的。\n* 声明模型包中的扩展适用的查询包。 如果扩展包位于指定的版本范围内，并且在评估中使用，则扩展包会将其数据扩展注入 `extensionTargets` 字典中命名的每个包中。\n\n#### `groups`\n\n* 可选。\n* 定义 CodeQL 工作区中包的逻辑分组。 使用组是将包操作应用于工作区中的包子集的一种方法。 例如，以下包定义为 `java` 和 `experimental` 组的一部分：\n\n  ```yaml\n  groups:\n    - java\n    - experimental\n  ```\n\n  运行 `codeql pack publish --groups java,-experimental` 将发布 `java` 组中的所有包（\\_\\_ 包除外）。`experimental` 可以运行 `codeql pack ls --groups [-]<group>[,[-]<group>...]` 命令，列出工作区中与指定组集匹配的包。\n\n  如果满足以下条件，给定工作区中的 CodeQL 包将包含在列表中：\n\n  * 它至少在一个不带减号的所列组中（如果没有不带减号的所列组，则自动满足此条件），并且\n  * 它不在任何带减号的组中。\n\n#### `library`\n\n* 这是库包所必需的。\n* 定义一个布尔值，该值指示此包是否为库包。 库包不包含查询，也不会进行编译。 查询包可忽略此字段或将其显式设置为 `false`。 例如：\n\n  ```yaml\n  library: true\n  ```\n\n#### `suites`\n\n* 对于定义查询套件的包，这是可选项。 这使用户能够通过指定包名称来运行存储在指定目录中的查询套件，而无需提供完整路径。\n* 目前仅对于 CodeQL CLI 捆绑中包含的标准查询包提供支持。\n* 从 CodeQL 容器注册表下载的 GitHub 包不支持此选项。\n\n#### `tests`\n\n* 对于具有 CodeQL 测试的包，这是可选的。 针对没有测试的包已忽略。\n* 定义包中具有测试的目录的路径，此路径相对于包目录进行定义。 使用 `.` 指定整个包。 当 `test run` 使用 `--strict-test-discovery` 选项运行时，此目录中的任何查询都作为测试运行。 使用 `queries` 或 `qlpack` 指令请求特定包中的所有查询的查询套件定义会忽略这些查询。 如果缺少此属性，则假定 `.`。 例如：\n\n  ```yaml\n  tests: .\n  ```\n\n#### `extractor`\n\n* 对于具有 CodeQL 测试的所有包，这是必需的。\n* 定义在包中运行 CodeQL 测试时要使用的 CodeQL 语言提取程序。 有关测试查询的详细信息，请参阅 [测试自定义查询](/zh/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries)。 例如：\n\n  ```yaml\n  extractor: javascript-typescript\n  ```\n\n#### `authors`\n\n* 可选。\n* 定义将在 CodeQL 包发布到的帐户的“包”部分的“打包搜索”页面上显示的元数据。 例如：\n\n  ```yaml\n  authors: author1@github.com,author2@github.com\n  ```\n\n#### `license`\n\n* 可选。\n* 定义将在 CodeQL 包发布到的帐户的“包”部分的“打包搜索”页面上显示的元数据。 有关允许的许可证列表，请参阅 SPDX 规范中的 [SPDX 许可证列表](https://spdx.org/licenses/)。 例如：\n\n  ```yaml\n  license: MIT\n  ```\n\n#### `description`\n\n* 可选。\n* 定义将在 CodeQL 包发布到的帐户的“包”部分的“打包搜索”页面上显示的元数据。 例如：\n\n  ```yaml\n  description: Human-readable description of the contents of the CodeQL pack.\n  ```\n\n#### `libraryPathDependencies`\n\n* 可选，弃用。 请改用`dependencies`属性。\n* 以前用于将此 CodeQL 包所依赖的任何 CodeQL 包的名称定义为数组。 这使得包能够访问依赖项中定义的任何库、数据库架构和查询套件。 例如：\n\n  ```yaml\n  libraryPathDependencies: codeql/javascript-all\n  ```\n\n#### `dbscheme`\n\n* 只有对于核心语言包来说是必需的。\n* 对于为此 CodeQL 语言编写的所有库和查询，定义[数据库架构](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database-schema)的路径（请参阅下面的示例）。 例如：\n\n  ```yaml\n  dbscheme: semmlecode.python.dbscheme\n  ```\n\n#### `upgrades`\n\n* 只有对于核心语言包来说是必需的。\n* 定义包中包含数据库升级脚本的目录的路径，该路径相对于包目录进行定义。 数据库升级在内部使用，以确保使用其他版本的 CodeQL CLI 创建的数据库与当前版本的 CLI 兼容。 例如：\n\n  ```yaml\n  upgrades: .\n  ```\n\n#### `warnOnImplicitThis`\n\n* 可选。 如果未定义 `false` 属性，则默认为 `warnOnImplicitThis`。\n* 定义一个布尔值，指定编译器是否应发出有关带有隐式 `this` 调用接收器（即没有显式接收器）的成员谓词调用的警告。 自 CodeQL CLI v2.13.2 起可用。 例如：\n\n  ```yaml\n  warnOnImplicitThis: true\n  ```\n\n##\n\n```\n          `codeql-pack.lock.yml` 文件\n\n          `codeql-pack.lock.yml` 文件会存储 CodeQL 包已解析的可传递依赖项的版本。 如果此文件尚不存在，则由 `codeql pack install` 命令创建，并且应将其添加到版本控制系统中。 \n          `dependencies` 文件的 `qlpack.yml` 部分包含与包兼容的版本范围。 \n          `codeql-pack.lock.yml` 文件将版本锁定到精确的依赖项。 这可确保在此包上运行 `codeql pack install` 将始终检索相同版本的依赖项，即使存在较新的兼容版本也是如此。\n```\n\n例如，如果 `qlpack.yml` 文件包含以下依赖项：\n\n```yaml\ndependencies:\n  codeql/cpp-all: ^0.1.2\n  my-user/my-lib: ^0.2.3\n  other-dependency/from-source: \"*\"\n```\n\n```\n          `codeql-pack.lock.yml` 文件将包含如下内容：\n```\n\n```yaml\ndependencies:\n  codeql/cpp-all:\n    version: 0.1.4\n  my-user/my-lib:\n    version: 0.2.4\n  my-user/transitive-dependency:\n    version: 1.2.4\n```\n\n```\n          `codeql/cpp-all` 依赖项锁定到版本 0.1.4。 \n          `my-user/my-lib` 依赖项锁定到版本 0.2.4。 \n          `my-user/transitive-dependency` 是可传递依赖项，未在 `qlpack.yml` 文件中指定，并且已锁定到版本 1.2.4。 锁定文件中没有 `other-dependency/from-source`，因为它是从源解析的。 此依赖项必须在与包相同的 CodeQL 工作区中可用。 若要详细了解 CodeQL 工作区以及如何从源解析依赖项，请参阅 [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces)。\n```\n\n在大多数情况下，`codeql-pack.lock.yml` 文件仅与查询包相关，因为库包不可执行，通常不需要修复其可传递依赖项。 对于包含测试的库包，这种情况除外。 在这种情况下，`codeql-pack.lock.yml` 文件用于确保始终使用相同的依赖项版本运行测试，以避免在依赖项不匹配时出现虚假故障。\n\n## 自定义 CodeQL 的包示例\n\n应将文件保存在单独的包中用于自定义查询和测试，并将自定义包组织到每个目标语言的特定文件夹中。\n\n### 自定义库的 CodeQL 包\n\n包含自定义 C++ 库的自定义 CodeQL 包（没有查询或测试）可能具有包含以下内容的 `qlpack.yml` 文件：\n\n```yaml\nname: my-github-user/my-custom-libraries\nversion: 1.2.3\nlibrary: true\ndependencies:\n  codeql/cpp-all: ^0.1.2\n```\n\n其中，`codeql/cpp-all` 是 CodeQL 存储库中包含的用于 C/C++ 分析的 CodeQL 包的名称。 版本范围 `^0.1.2` 表示此包与大于等于 `codeql/cpp-all` 且小于 `0.1.2` 的所有 `0.2.0` 版本兼容。 此包中定义的任何 CodeQL 库文件（扩展名为 `.qll` 的文件）都可用于在其依赖项块中包含此包的任何查询包中定义的查询。\n\n```\n          `library` 属性指示此包是库包，不包含任何查询。\n```\n\n### 自定义查询的 CodeQL 包\n\n包含自定义 C++ 查询和库的自定义 CodeQL 包可能具有包含以下内容的 `qlpack.yml` 文件：\n\n```yaml\nname: my-github-user/my-custom-queries\nversion: 1.2.3\ndependencies:\n  codeql/cpp-all: ^0.1.2\n  my-github-user/my-custom-libraries: ^1.2.3\n```\n\n其中，`codeql/cpp-all` 是 CodeQL 存储库中包含的用于 C/C++ 分析的 CodeQL 包的名称。 版本范围 `^0.1.2` 表示此包与大于等于 `codeql/cpp-all` 且小于 `0.1.2` 的所有 `0.2.0` 版本兼容。\n`my-github-user/my-custom-libraries` 是包含用于 C++ 的自定义 CodeQL 库的 CodeQL 包的名称。 此包中定义的任何 CodeQL 库文件（扩展名为 `.qll` 的文件）都可用于 `my-github-user/my-custom-queries` 包中的查询。\n\n### 自定义测试的 CodeQL 包\n\n对于包含测试文件的自定义 CodeQL 包，还需要包含 `extractor` 属性，以便 `test run` 命令知道如何创建测试数据库。 你可能还希望指定 `tests` 属性。\n\n以下 `qlpack.yml` 文件说明 `my-github-user/my-query-tests` 取决于版本高于或等于 1.2.3 且低于 2.0.0 的 `my-github-user/my-custom-queries`。 同时还声明 CLI 在创建测试数据库时应使用 Java `extractor`。 `tests: .` 行声明在使用 `--strict-test-discovery` 选项运行 `codeql test run` 时，包中的所有 `.ql` 文件都应作为测试运行。 通常，测试包不包含 `version` 属性。 这样可以防止意外发布它们。\n\n```yaml\nname: my-github-user/my-query-tests\ndependencies:\n  my-github-user/my-custom-queries: ^1.2.3\nextractor: java-kotlin\ntests: .\n```\n\n有关运行测试的详细信息，请参阅 [测试自定义查询](/zh/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries)。\n\n## CodeQL 存储库中的 CodeQL 包示例\n\nCodeQL 存储库中的每种语言都有 4 个主要的 CodeQL 包：\n\n* 语言的核心库包，其中包含该语言使用的数据库架构、CodeQL 库和 `<language>/ql/lib` 处的查询\n\n* 语言的核心查询包，其中包含该语言的默认查询及其在 `<language>/ql/src` 处的查询套件\n\n* `<language>/ql/test` 处用于核心语言库和查询的测试\n\n* `<language>/ql/examples` 处的语言示例查询\n\n### 核心库包\n\n下面是 `qlpack.yml`核心语言包的示例 [](https://github.com/github/codeql/blob/main/cpp/ql/lib/qlpack.yml) 文件：\n\n```yaml\nname: codeql/cpp-all\nversion: x.y.z-dev\ndbscheme: semmlecode.cpp.dbscheme\nlibrary: true\nupgrades: upgrades\n```\n\n有关以下属性的一些额外说明：\n\n* `library`：指示这是没有可执行查询的库包。 它只能用作其他包的依赖项。\n\n* `dbscheme` 和 `upgrades`：这些属性是 CodeQL CLI 的内部属性，应仅在语言的核心 CodeQL 查询包中定义。\n\n### 核心查询包\n\n下面是 `qlpack.yml`核心查询包的示例 [](https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml) 文件：\n\n```yaml\nname: codeql/cpp-queries\nversion: x.y.z-dev\ndependencies:\n    codeql/cpp-all: \"*\"\n    codeql/suite-helpers: \"*\"\nsuites: codeql-suites\ndefaultSuiteFile: codeql-suites/cpp-code-scanning.qls\n```\n\n有关以下属性的一些额外说明：\n\n* `dependencies`：此查询包依赖于 `codeql/cpp-all` 和 `codeql/suite-helpers`。 由于这些依赖项是从源解析的，因此它们与 CodeQL 包的哪个版本兼容并不重要。 若要详细了解如何从源解析依赖项，请参阅[源依赖项](/zh/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#source-dependencies)。\n\n* `suites`：指示包含“已知”查询套件的目录。\n\n* `defaultSuiteFile`：未指定查询套件时使用的默认查询套件文件的名称。\n\n### 核心 CodeQL 包的测试\n\n下面是 `qlpack.yml`核心测试包的示例 [](https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml) 文件：\n\n```yaml\nname: codeql/cpp-tests\ndependencies:\n  codeql/cpp-all: \"*\"\n  codeql/cpp-queries: \"*\"\nextractor: cpp\ntests: .\n```\n\n有关以下属性的一些额外说明：\n\n* `dependencies`：此包依赖于用于C++ 的核心 CodeQL 查询和库包。\n\n* `extractor`：这指定所有测试将使用相同的 C++ 提取程序为测试创建数据库。\n\n* `tests`：这指定测试的位置。 在这种情况下，测试位于包的根文件夹（和所有子文件夹）中。\n\n* `version`：测试包没有 `version` 属性。 这可防止意外发布测试包。"}