{"meta":{"title":"使用 CodeQL 模型编辑器","intro":"可以在CodeQL中查看、写入和编辑Visual Studio Code模型包。","product":"安全性和代码质量","breadcrumbs":[{"href":"/zh/code-security","title":"安全性和代码质量"},{"href":"/zh/code-security/how-tos","title":"How-tos"},{"href":"/zh/code-security/how-tos/find-and-fix-code-vulnerabilities","title":"查找和修复代码漏洞"},{"href":"/zh/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code","title":"从 VS Code 扫描"},{"href":"/zh/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/using-the-codeql-model-editor","title":"使用模型编辑器"}],"documentType":"article"},"body":"# 使用 CodeQL 模型编辑器\n\n可以在CodeQL中查看、写入和编辑Visual Studio Code模型包。\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##\n\n```\n          CodeQL关于模型编辑器\n```\n\n使用 CodeQL 模型包，可以扩展 CodeQLcode scanning 分析，以识别默认情况下不支持的代码库使用的自定义库和框架。\nCodeQL使用模型编辑器，可以创建自己的模型包。 模型编辑器将指导你对应用程序中外部依赖项的调用进行建模，或对外部依赖项中的所有公共入口点和出口点进行完全建模。\n\n有关使用模型包自定义code scanning分析的更多信息，请参阅[编辑默认设置配置](/zh/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup) 和[代码扫描的工作流配置选项](/zh/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#codeql-model-packs)。\n\n打开模型编辑器时，它会分析当前选定的 CodeQL 数据库，并标识应用程序使用外部 API 和所有公共方法的位置。 外部（或第三方）API 是指任何不属于你所选 CodeQL 数据库的 API。\n\n模型编辑器具有两种不同的模式：\n\n* **应用程序模式（默认视图）**：编辑器列出了所选 CodeQL 数据库使用的每个外部框架。 展开框架时，将显示与外部 API 之间的所有调用的列表，其中包含可用于对每个调用的数据流进行建模的选项。 此模式最适用于改进 CodeQL 特定代码库的结果。\n\n* **依赖项模式：** 编辑器标识所选 CodeQL 数据库中所有可公开访问的 API。 此视图将指导你完成对代码库提供的每个公共 API 的建模。 完成整个 API 建模后，可以保存模型并使用它来改进 CodeQL 使用依赖项的所有代码库的分析。\n\n本文的其余部分介绍使用 CodeQL 模型编辑器对依赖项进行建模的实际方面。 有关技术信息，请参阅[自定义适用于 Java 和 Kotlin](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-java-and-kotlin/) 的库模型、[自定义适用于 Python 的库模型](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-python/)、为 [Ruby 自定义库模型](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-ruby/)以及自定义适用于 C# [](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-csharp/)的CodeQL 库模型。\n\n## 显示CodeQL模型编辑器\n\n> \\[!NOTE]\n> 若要使用此公共预览版功能，请安装用于Visual Studio Code的最新版本CodeQL扩展。\n\n1. 在VS Code中打开CodeQL工作区。 例如，[`vscode-codeql-starter` 工作区](https://github.com/github/vscode-codeql-starter)。 如果使用初学者工作区，请从 `ql` 更新 `main` 子模块，以确保查询用于收集模型编辑器的数据。\n\n2. 在 Visual Studio Code左侧栏中单击 **QL** 以显示 CodeQL 扩展。\n\n3. 在“数据库”视图中，选择要建模的 CodeQL 数据库。\n\n4. 在 CodeQL “方法建模”视图中，单击“ **开始建模** ”以显示模型编辑器。 或者，使用 VS Code Command Palette 以下命令运行 **CodeQL：打开模型编辑器（Beta）** 命令。 <!-- markdownlint-disable-line outdated-release-phase-terminology --> <!-- \"Beta\" is in the name of the command in the VS Code extension -->\n\n5. 模型 CodeQL 编辑器运行一系列遥测查询来标识代码中的 API，编辑器将显示在新选项卡中。\n\n6. 遥测查询完成后，已标识的 API 将显示在编辑器中。\n\n> \\[!TIP]\n> 如果要在对调用或方法进行建模时需要更多空间，可以将“方法建模”视图从主边栏移动到 CodeQL 辅助边栏。 如果关闭视图，可以从“视图”菜单 VS Code 重新打开它，然后单击“ **打开视图...”**。\n\n## 对代码库对外部 API 的调用进行建模\n\n通常，当您查看特定代码库以提高CodeQL结果的精度时，会使用这种方法。 如果代码库使用的框架或库不被 CodeQL 支持，并且框架或库的源代码未包含在分析中时，这将非常有用。\n\n本部分使用名为“sofa-jraft”的open source Java项目作为示例。 与使用其他编译语言编写的外部 API 进行建模调用的体验类似。\n\n1. 在 Visual Studio Code 中，选择要改进其覆盖范围的 CodeQL 数据库。\n\n2. 显示CodeQL的模型编辑器。 默认情况下，编辑器在应用程序模式下运行，因此会显示所选代码库使用的外部 API 列表。\n\n   ![“应用程序模式”视图的屏幕截图，显示了在“sofa-jraft”代码库中使用的两个外部Java框架。](/assets/images/help/security/codeql-for-vs-code-model-application-mode.png)\n\n3. 单击以展开外部 API，并查看从代码库到外部依赖项的调用列表。\n\n   ![“应用程序模式”的屏幕截图，显示对“rocksdbjni”框架的调用。 第一个调用的“查看”选项以橙色边框突出显示。](/assets/images/help/security/codeql-for-vs-code-model-application-mode-expanded.png)\n\n4. 单击与 API 调用或方法关联的**视图**，以显示它在代码库中的使用位置。\n\n5. 打开包含您的代码库第一次调用 API 的文件，将显示“方法用法”视图（此处通常显示“问题”和“终端”视图）。 “ CodeQL 方法使用情况”视图列出了从代码到 API 的所有调用，按方法分组。 可单击每个用法，以决定如何对方法的使用进行建模。\n\n6. 确定如何使用该方法进行建模后，可以选择其他模型类型。 在扩展的CodeQL“方法建模”视图中单击“模型类型”CodeQL下的下拉列表。 此更改将自动反映在主模型编辑器中。\n\n7. 该行中的其余字段将更新为适用于所选模型类型的选项：\n\n   * “源”：选择“输出”元素进行建模。\n   * “接收器”：选择“输入”元素进行建模。\n   * “流程摘要”：选择要建模的\"输入\"和\"输出\"元素。\n\n8. 定义模型数据流的\"种类\"。\n\n9. 完成建模后，显示主模型编辑器，然后单击**全部保存**或**保存**（显示在每个展开的方法列表的右下角）。 编辑器中建模的方法的百分比已更新。\n\n模型存储在您的工作区中的 `.github/codeql/extensions/CODEQL-MODEl-PACK`，其中 `CODEQL-MODEL-PACK` 是您选择的数据库名称 CodeQL。 也就是说，仓库名称、连字符、由 CodeQL 分析的语言。 有关详细信息，请参阅“[创建并使用 CodeQL 包](/zh/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-codeql-model-pack)”。\n\n这些模型存储在一系列 YAML 数据扩展文件中，每个外部 API 各有一个文件。 例如：\n\n```yaml\n.github/codeql/extensions/sofa-jraft-java # the model pack directory\n    models\n        jmh-core.model.yml                  # models calls to jmh-core@1.20\n        rocksdbjni.model.yml                # models calls to rocksdbjni@7.7.3\n```\n\n## 对代码库的公共 API 进行建模\n\n对组织在多个代码库中使用的框架或库进行建模，通常使用此方法。 创建并测试模型后，可以将模型包发布到CodeQLGitHubContainer registry整个组织以供使用。\n\n本部分使用名为“sofa-jraft”的open source Java项目作为示例。 与使用其他编译语言编写的外部 API 进行建模调用的体验类似。\n\n1. ```\n          CodeQL选择要建模的数据库。\n   ```\n\n2. 显示CodeQL模型编辑器。 默认情况下,编辑器以应用程序模式运行。 单击**以模型作为依赖项**以显示依赖模式。 屏幕更改为显示框架或库的公共 API。\n\n   ![“依赖项模式”视图的屏幕截图，显示“sofa-jraft”代码库发布的三个包。](/assets/images/help/security/codeql-for-vs-code-model-dependency-mode.png)\n\n3. 单击可展开包并查看可用方法列表。\n\n4. 单击与方法关联的**视图**以显示其定义。\n\n   ![“依赖项模式”的屏幕截图，包含“com.alipay.sofa.jraft.option.BallotBoxOptions.getClosureQueue()”的一个模型。 “+”按钮以边框突出显示。](/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-expanded.png)\n\n5. 确定如何对方法进行建模后，请定义“模型类型”。\n\n6. 该行中的其余字段将更新为适用于所选模型类型的选项：\n\n   * “源”：选择“输出”元素进行建模。\n   * “接收器”：选择“输入”元素进行建模。\n   * “流程摘要”：选择要建模的\"输入\"和\"输出\"元素。\n\n7. 定义模型数据流的\"种类\"。\n\n8. 完成建模后，单击**全部保存**或**保存**（显示在每个展开的调用列表的右下角）。 更新编辑器中建模的调用的百分比。\n\n模型存储在工作区中 `.github/codeql/extensions/CODEQL-MODEL-PACK`，其中 `CODEQL-MODEL-PACK` 所选数据库的名称 CodeQL 。 也就是说，存储库的名称，连字符，由该语言分析。CodeQL 有关详细信息，请参阅“[创建并使用 CodeQL 包](/zh/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-codeql-model-pack)”。\n\n模型存储在一系列 YAML 数据扩展文件中，每个公共方法各有一个。 例如：\n\n```yaml\n.github/codeql/extensions/sofa-jraft-java          # the model pack directory\n    models\n        com.alipay.sofa.jraft.option.model.yml # models public methods in package\n        com.alipay.sofa.jraft.rhea.options.model.yml\n```\n\n编辑器将为建模的每个包创建一个单独的模型文件。\n\n## 具有多个潜在流的建模方法\n\n某些方法支持多个数据流。 对方法的所有数据流进行建模非常重要，否则无法检测到与使用该方法相关的所有潜在问题。 首先为该方法建模一个数据流，然后使用方法行中的 **+** 按钮指定第二个数据流模型。\n\n![“依赖项模式”视图的屏幕截图，显示“com.alipay.soft.jraft.option”中可用的公共方法。 “查看”选项以橙色边框突出显示。](/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-plus.png)\n\n##\n\n```\n          CodeQL测试模型包VS Code\n```\n\n在VS Code中创建的任何CodeQL模型包可以通过“正在运行的查询：使用扩展包”设置来测试。 有关详细信息，请参阅“[自定义设置](/zh/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings)”。 此方法适用于数据库和变体分析存储库。\n\n* 若要对CodeQL数据库使用存储在工作区的`.github/codeql/extensions`目录中的任何模型包运行查询，请将您的`settings.json`文件更新为：`\"codeQL.runningQueries.useExtensionPacks\": \"all\",`\n\n* 若要在不使用模型包的情况下对 CodeQL 数据库运行查询，请使用以下内容更新 `settings.json` 文件：`\"codeQL.runningQueries.useExtensionPacks\": \"none\",`\n\n如果模型运行良好，则应该会看到两次不同运行的结果存在差异。 如果在结果中没有看到任何差异，则可能需要引入已知 bug 来验证模型的行为是否符合预期。\n\n## 延伸阅读\n\n* [编辑默认设置配置](/zh/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup)\n* [代码扫描的工作流配置选项](/zh/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#codeql-model-packs)[使用 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)。"}