使用 CodeQL 模型编辑器

          CodeQL关于模型编辑器

使用 CodeQL 模型包，可以扩展 CodeQLcode scanning 分析，以识别默认情况下不支持的代码库使用的自定义库和框架。 CodeQL使用模型编辑器，可以创建自己的模型包。 模型编辑器将指导你对应用程序中外部依赖项的调用进行建模，或对外部依赖项中的所有公共入口点和出口点进行完全建模。

有关使用模型包自定义code scanning分析的更多信息，请参阅编辑默认设置配置 和代码扫描的工作流配置选项。

打开模型编辑器时，它会分析当前选定的 CodeQL 数据库，并标识应用程序使用外部 API 和所有公共方法的位置。 外部（或第三方）API 是指任何不属于你所选 CodeQL 数据库的 API。

模型编辑器具有两种不同的模式：

•         **应用程序模式（默认视图）**：编辑器列出了所选 CodeQL 数据库使用的每个外部框架。 展开框架时，将显示与外部 API 之间的所有调用的列表，其中包含可用于对每个调用的数据流进行建模的选项。 此模式最适用于改进 CodeQL 特定代码库的结果。
  

•         **依赖项模式：** 编辑器标识所选 CodeQL 数据库中所有可公开访问的 API。 此视图将指导你完成对代码库提供的每个公共 API 的建模。 完成整个 API 建模后，可以保存模型并使用它来改进 CodeQL 使用依赖项的所有代码库的分析。
  

本文的其余部分介绍使用 CodeQL 模型编辑器对依赖项进行建模的实际方面。 有关技术信息，请参阅自定义适用于 Java 和 Kotlin 的库模型、自定义适用于 Python 的库模型、为 Ruby 自定义库模型以及自定义适用于 C# 的CodeQL 库模型。

显示CodeQL模型编辑器

1. 在VS Code中打开CodeQL工作区。 例如，vscode-codeql-starter 工作区。 如果使用初学者工作区，请从 ql 更新 main 子模块，以确保查询用于收集模型编辑器的数据。

2. 在 Visual Studio Code左侧栏中单击 QL 以显示 CodeQL 扩展。

3. 在“数据库”视图中，选择要建模的 CodeQL 数据库。

4. 在 CodeQL “方法建模”视图中，单击“ 开始建模 ”以显示模型编辑器。 或者，使用 VS Code Command Palette 以下命令运行 CodeQL：打开模型编辑器（Beta） 命令。

5. 模型 CodeQL 编辑器运行一系列遥测查询来标识代码中的 API，编辑器将显示在新选项卡中。

6. 遥测查询完成后，已标识的 API 将显示在编辑器中。

对代码库对外部 API 的调用进行建模

通常，当您查看特定代码库以提高CodeQL结果的精度时，会使用这种方法。 如果代码库使用的框架或库不被 CodeQL 支持，并且框架或库的源代码未包含在分析中时，这将非常有用。

本部分使用名为“sofa-jraft”的open source Java项目作为示例。 与使用其他编译语言编写的外部 API 进行建模调用的体验类似。

1. 在 Visual Studio Code 中，选择要改进其覆盖范围的 CodeQL 数据库。

2. 显示CodeQL的模型编辑器。 默认情况下，编辑器在应用程序模式下运行，因此会显示所选代码库使用的外部 API 列表。

   

3. 单击以展开外部 API，并查看从代码库到外部依赖项的调用列表。

   

4. 单击与 API 调用或方法关联的视图，以显示它在代码库中的使用位置。

5. 打开包含您的代码库第一次调用 API 的文件，将显示“方法用法”视图（此处通常显示“问题”和“终端”视图）。 “ CodeQL 方法使用情况”视图列出了从代码到 API 的所有调用，按方法分组。 可单击每个用法，以决定如何对方法的使用进行建模。

6. 确定如何使用该方法进行建模后，可以选择其他模型类型。 在扩展的CodeQL“方法建模”视图中单击“模型类型”CodeQL下的下拉列表。 此更改将自动反映在主模型编辑器中。

7. 该行中的其余字段将更新为适用于所选模型类型的选项：

   • “源”：选择“输出”元素进行建模。
   • “接收器”：选择“输入”元素进行建模。
   • “流程摘要”：选择要建模的"输入"和"输出"元素。

8. 定义模型数据流的"种类"。

9. 完成建模后，显示主模型编辑器，然后单击全部保存或保存（显示在每个展开的方法列表的右下角）。 编辑器中建模的方法的百分比已更新。

模型存储在您的工作区中的 .github/codeql/extensions/CODEQL-MODEl-PACK，其中 CODEQL-MODEL-PACK 是您选择的数据库名称 CodeQL。 也就是说，仓库名称、连字符、由 CodeQL 分析的语言。 有关详细信息，请参阅“创建并使用 CodeQL 包”。

这些模型存储在一系列 YAML 数据扩展文件中，每个外部 API 各有一个文件。 例如：

.github/codeql/extensions/sofa-jraft-java # the model pack directory
    models
        jmh-core.model.yml                  # models calls to jmh-core@1.20
        rocksdbjni.model.yml                # models calls to rocksdbjni@7.7.3

对代码库的公共 API 进行建模

对组织在多个代码库中使用的框架或库进行建模，通常使用此方法。 创建并测试模型后，可以将模型包发布到CodeQLGitHubContainer registry整个组织以供使用。

本部分使用名为“sofa-jraft”的open source Java项目作为示例。 与使用其他编译语言编写的外部 API 进行建模调用的体验类似。

1.        CodeQL选择要建模的数据库。
   

2. 显示CodeQL模型编辑器。 默认情况下,编辑器以应用程序模式运行。 单击以模型作为依赖项以显示依赖模式。 屏幕更改为显示框架或库的公共 API。

   

3. 单击可展开包并查看可用方法列表。

4. 单击与方法关联的视图以显示其定义。

   

5. 确定如何对方法进行建模后，请定义“模型类型”。

6. 该行中的其余字段将更新为适用于所选模型类型的选项：

   • “源”：选择“输出”元素进行建模。
   • “接收器”：选择“输入”元素进行建模。
   • “流程摘要”：选择要建模的"输入"和"输出"元素。

7. 定义模型数据流的"种类"。

8. 完成建模后，单击全部保存或保存（显示在每个展开的调用列表的右下角）。 更新编辑器中建模的调用的百分比。

模型存储在工作区中 .github/codeql/extensions/CODEQL-MODEL-PACK，其中 CODEQL-MODEL-PACK 所选数据库的名称 CodeQL 。 也就是说，存储库的名称，连字符，由该语言分析。CodeQL 有关详细信息，请参阅“创建并使用 CodeQL 包”。

模型存储在一系列 YAML 数据扩展文件中，每个公共方法各有一个。 例如：

.github/codeql/extensions/sofa-jraft-java          # the model pack directory
    models
        com.alipay.sofa.jraft.option.model.yml # models public methods in package
        com.alipay.sofa.jraft.rhea.options.model.yml

编辑器将为建模的每个包创建一个单独的模型文件。

具有多个潜在流的建模方法

某些方法支持多个数据流。 对方法的所有数据流进行建模非常重要，否则无法检测到与使用该方法相关的所有潜在问题。 首先为该方法建模一个数据流，然后使用方法行中的 + 按钮指定第二个数据流模型。

          CodeQL测试模型包VS Code

在VS Code中创建的任何CodeQL模型包可以通过“正在运行的查询：使用扩展包”设置来测试。 有关详细信息，请参阅“自定义设置”。 此方法适用于数据库和变体分析存储库。

• 若要对CodeQL数据库使用存储在工作区的.github/codeql/extensions目录中的任何模型包运行查询，请将您的settings.json文件更新为："codeQL.runningQueries.useExtensionPacks": "all",

• 若要在不使用模型包的情况下对 CodeQL 数据库运行查询，请使用以下内容更新 settings.json 文件："codeQL.runningQueries.useExtensionPacks": "none",

如果模型运行良好，则应该会看到两次不同运行的结果存在差异。 如果在结果中没有看到任何差异，则可能需要引入已知 bug 来验证模型的行为是否符合预期。

延伸阅读

•         [AUTOTITLE](/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)
  

•         [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#codeql-model-packs)[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies)。