使用 CodeQL 模型编辑器

关于 CodeQL 模型编辑器

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

有关使用模型包自定义代码扫描分析的更多信息，请参阅“编辑默认设置的配置”和“自定义代码扫描的高级设置”。

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

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

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

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

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

显示 CodeQL 模型编辑器

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

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

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

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

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

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

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

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

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

1. 在 Visual Studio Code 中，选择要提高 CodeQL 覆盖率的 CodeQL 数据库。

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

   

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

   

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

5. 系统会打开包含代码库中第一次调用 API 的文件，并在 VS Code 中显示 CodeQL“方法使用情况”视图（通常显示“问题”和“终端”视图的位置）。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 [email protected]
        rocksdbjni.model.yml                # models calls to [email protected]

对代码库的公共 API 建模

通常在您想建模组织在多个代码库中使用的框架或库时使用此方法。创建和测试模型完成后，您可以将 CodeQL 模型包发布到 GitHub 容器注册表，供整个组织使用。

本节使用名为“sofa-jraft”的开源 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

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

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

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

在 VS Code 中测试 CodeQL 模型包

您可以使用“运行查询：使用扩展包”设置在 VS Code 中测试创建的任何 CodeQL 模型包。更多信息，请参见“自定义设置”。此方法适用于数据库和变体分析仓库。

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

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

如果您的模型运行良好，您应该会看到两次不同运行的结果有所不同。如果您没有看到任何结果差异，您可能需要引入已知的错误来验证模型是否按预期运行。

进一步阅读

• 编辑默认设置的配置
• 自定义代码扫描的高级设置 使用 CodeQL 包自定义分析。