通过多库变体分析大规模运行 CodeQL 查询

使用多存储库变体分析（MRVA），可以在GitHub上对Visual Studio Code的最多 1,000 个存储库列表运行CodeQL查询。

先决条件

在将存储库添加到列表进行分析之前，需要在GitHub上使用CodeQL启用code scanning，可以选择使用默认设置或高级设置。要了解如何使用CodeQL来启用code scanning，请参阅配置代码扫描的默认设置。
必须先定义控制器存储库，然后才能运行第一个多存储库变体分析。
控制器存储库可以为空，但必须至少提交一个。
控制器存储库必须托管在要使用 MRVA 分析的存储库所在的同一站点上，即： GitHub.com 或 SUBDOMAIN.ghe.com。如果要运行 MRVA 带有数据驻留权的 GitHub Enterprise Cloud，请参阅更改 GitHub 扩展使用的 URL。
在GitHub.com上，如果计划仅分析公共存储库，则控制器存储库的可见性可以设置为“公共”。变体分析免费。
如果需要分析任何专用或内部存储库， GitHub.com控制器存储库可见性必须为“专用”。

超出免费限额且用于对专用或内部存储库运行变体分析的任何操作分钟数都将向存储库所有者收费。有关免费分钟数和计费的详细信息，请参阅 GitHub Actions计费。

为 MRVA 设置控制器存储库

在“变体分析存储库”视图中，单击设置控制器存储库以显示控制器存储库的字段。
键入要用作控制器存储库的存储库 GitHub 的所有者和名称，然后按 Enter 键。此存储库必须与要分析的 GitHub 存储库位于同一实例上，请参阅更改 GitHub 扩展使用的 URL。
如果系统提示你进行身份验证 GitHub，请按照说明登录帐户。完成后，GitHub 身份验证可能会请求在 Visual Studio Code 中开启权限，请单击打开。

控制器存储库的名称保存在扩展的设置中 CodeQL 。有关如何编辑控制器仓库的信息，请参阅自定义设置。

使用 MRVA 大规模运行查询

默认情况下，“变体分析存储库”视图显示所分析语言的前 10 个、前 100 个和前 1000 个公共存储库 GitHub.com 的默认列表。如果控制器存储库托管在上 SUBDOMAIN.ghe.com，则这些列表不可用。
（可选）可添加新的存储库、组织或列表。
1. 在“变体分析存储库”视图中，单击 + 以添加新数据库。
2. 从下拉菜单中，选择从某个GitHub存储库或GitHub组织或所有者的所有存储库。
3. 在字段中键入要使用的存储库或组织的标识符。
请选择要运行查询的一个或多个存储库。
打开要运行的查询，右键单击查询文件中，然后选择 CodeQL：运行变体分析 以启动变体分析。

注意

若要取消变体分析运行，请单击“变体分析结果”视图中的停止查询。

选择要分析的单个 GitHub 存储库或组织

在“变体分析存储库”视图中，单击 + 以添加新数据库。
从下拉菜单中，选择从一个存储库GitHub 或组织或所有者的所有存储库GitHub。
在字段中键入要使用的存储库或组织的标识符。

错误和警告

运行 MRVA 时，有两个关键位置显示错误和警告：

        Visual Studio Code 错误：在创建 CodeQL 包并将分析发送到 GitHub 时的任何问题，将在应用程序的右下角报告为 Visual Studio Code 错误。 “问题”视图中也提供了信息。

“变体分析结果”：此视图中报告变体分析运行所有问题。

了解结果

一旦对 GitHub 的变体分析工作流启动，就会打开“变体分析结果”视图，以便在结果准备就绪时显示结果。可使用此视图来监视进度、查看所有错误以及访问控制器存储库中的工作流日志。

显示“FileAccessToHttp.ql”运行的“变体分析结果”的屏幕截图。蓝色圆圈表示已找到的搜索结果数量或“-”仍在运行。

安排变体分析运行后，“结果”视图会自动弹出。最初，该视图显示计划进行分析的每个存储库的列表。在分析每个存储库时，视图将更新以显示结果数的摘要。要查看存储库的详细结果（包括结果路径），请单击存储库名称。

对于每个存储库，可以看到：

查询找到的结果数量
存储库的可见性
分析是否仍在运行或已完成
存储库在GitHub上拥有的星标数量

查看存储库的结果

单击存储库名称以显示每个结果的摘要。
使用指向源文件 GitHub的链接浏览每个结果的信息。对于数据流查询,将有一个额外的“显示路径”链接。

导出结果

可导出结果以供进一步分析或与合作者讨论。在“结果”视图中，单击 导出结果，将结果导出到 GitHub 上的机密 gist 或工作区中的 Markdown 文件。

创建自定义存储库列表

注意

          CodeQL 分析始终需要一个 CodeQL 数据库来运行查询。 针对存储库列表运行变体分析时，查询将仅针对当前有 CodeQL 可供下载的数据库的存储库执行。 使存储库可用于变体分析的最佳方法是使用 code scanningCodeQL。 有关使用CodeQL启用code scanning的信息，请参阅 [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning)。

在“变体分析存储库”视图中，单击“添加列表”图标。
为该查询键入一个新名称，再按下 Enter。
在视图中选择列表，然后单击 + 以将存储库添加到列表中。

管理自定义存储库列表

可通过右键单击列表中的列表名称或存储库名称，然后从上下文菜单中选择一个选项来管理和编辑自定义列表。

自定义列表存储在 databases.json 文件中的工作区中。如果要直接编辑 Visual Studio Code此文件，可以通过单击视图标头中的 { } 将其打开。

例如，如果要继续分析一组具有查询结果的存储库，请单击“变体分析结果”视图中的复制存储库列表，以仅将具有结果的存储库的列表以 JSON 形式添加到剪贴板。

在以下示例代码片段中，my-organization/my-repository 中有查询的结果：

{
    "name": "new-repo-list",
    "repositories": [
        "my-organization/my-repository"
    ]
}

然后，可将存储库的 new-repo-list 插入 databases.json，以便在“变体分析存储库”视图中轻松访问。

使用 GitHub 代码搜索将存储库添加到自定义列表

注意

此功能通过 GitHub 代码搜索 API 使用遗留代码搜索。有关要使用的语法的详细信息，请参阅搜索代码（旧版）。

可以直接在 CodeQL 扩展中使用代码搜索将存储库的子集添加到 GitHub 自定义列表中。

例如，若要在rails组织中于GitHub上添加所有存储库，请搜索org:rails。

每次搜索最多可以将 1,000 个存储库添加到自定义列表中。

在“变体分析存储库”视图中，选择要向其添加存储库的列表。可创建新列表或选择已包含存储库的现有列表。
右键单击所选列表，然后单击 “添加包含代码搜索的 GitHub 存储库”。
在应用程序顶部显示的弹出窗口的搜索栏下，从下拉列表中的选项中选择要搜索的语言。
在搜索栏中，键入要使用的搜索查询，然后按下 Enter。

可在应用程序右下角的带有文本 Searching for repositories... 的框中查看搜索进度。如果您单击取消，则不会将任何存储库添加到您的列表中。完成后，将看到生成的存储库显示在“变体分析存储库”视图中自定义列表下的下拉列表中。

某些生成的仓库将不会包含CodeQL数据库，有些可能不允许CodeQL扩展对Visual Studio Code的访问。在对列表运行分析时，“变体分析结果”视图将显示哪些存储库已被分析、哪些拒绝访问，以及哪些没有CodeQL数据库。

在 CodeQL 自承载运行程序上运行具有多存储库变体分析的查询

若要对自承载运行程序使用多存储库变体分析运行 CodeQL 查询，首先需要确保已将自承载运行程序添加到控制器存储库，或确保控制器存储库有权访问组织或企业级运行程序。

然后，你需要在控制器存储库中添加一个名称为 MRVA_RUNNER_OS 的新 Actions 存储库变量，其中包含想要使用的自托管运行器的 JSON 格式的标签列表。例如：

["self-hosted", "macOS", "ARM64"]

注意

你必须在控制器存储库的设置中的 Actions 仓库变量下设置 MRVA_RUNNER_OS 变量，而不是在 Actions 设置中或工作流的 .yml 文件中设置环境变量或 Actions 机密。请参阅“在变量中存储信息”。

有关详细信息，请参阅添加自托管的运行器和使用组管理对自托管运行程序的访问。

在自托管运行器上通过多存储库变体分析运行查询时，分析完全在自托管运行器上运行。无需创建新的工作流，但必须指定 Visual Studio Code 扩展应将哪个 CodeQL 存储库用作控制器存储库。随着每个存储库的分析完成，系统会向你 VS Code 发送结果以供查看。

通过多库变体分析大规模运行 CodeQL 查询

在本文中