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

关于使用多存储库变体分析大规模运行 CodeQL 查询

凭借多存储库变体分析 (MRVA)，可在 GitHub 上对 Visual Studio Code 中的最多 1,000 个存储库列表运行 CodeQL 查询。

针对存储库列表运行 MRVA 时，将针对具有可供分析的 CodeQL 数据库的每个存储库运行查询。 GitHub 为数千个公共存储库的默认分支创建并存储最新的 CodeQL 数据库，包括使用 CodeQL 运行code scanning的每个存储库。

在将存储库添加到列表进行分析之前，需使用默认设置或高级设置在 GitHub 上使用 CodeQL 启用 code scanning。有关使用 CodeQL 启用 code scanning 的信息，请参阅“配置代码扫描的高级设置”。

MRVA 如何对 GitHub.com 上的 CodeQL 数据库运行查询

运行 MRVA 时，分析完全使用 GitHub Actions 运行。无需创建任何工作流，但必须指定 Visual Studio Code 的 CodeQL 扩展应使用哪个存储库作为控制器存储库。随着每个存储库的分析完成，结果将发送到 VS Code 供您查看。

CodeQL 扩展使用库和任何库依赖项构建一个 CodeQL 包。 CodeQL 包和所选的存储库列表将发布到 GitHub 上的 API 终结点，这会触发控制器存储库中的 GitHub Actions 动态工作流。工作流启动多个并行作业，以对列表中的存储库执行 CodeQL 查询，从而优化查询执行。分析每个存储库时，将处理结果并将其显示在 VS Code 中。

先决条件

必须先定义控制器存储库，然后才能运行第一个多存储库变体分析。
控制器存储库可以为空，但必须至少提交一个。
控制器存储库必须与要使用 MRVA 分析的存储库托管在同一站点上，即：GitHub.com 或 SUBDOMAIN.ghe.com。如果要在具有数据驻留的 GitHub Enterprise Cloud 上运行 MRVA，请参阅“更改扩展使用的 GitHub URL”。
在 GitHub.com 上，如果计划仅分析公共存储库，则控制器存储库可见性可以为“公共”。变体分析免费。
如果需要在 GitHub.com 上分析任何专用或内部存储库，则控制器存储库可见性必须为“专用”。

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

为 MRVA 设置控制器存储库

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

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

使用 MRVA 大规模运行查询

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

Note

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

选择单个 GitHub 存储库或组织进行分析

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

错误和警告

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

Visual Studio Code 错误：创建 CodeQL 包并将分析发送到 GitHub 时出现的任何问题都会在应用程序的右下角报告为 Visual Studio Code 错误。 “问题”视图中也提供了信息。
“变体分析结果”：此视图中报告变体分析运行所有问题。

了解结果

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

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

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

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

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

查看存储库的结果

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

导出结果

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

创建自定义存储库列表

**注意：**CodeQL 分析始终需要 CodeQL 数据库来运行查询。当您对存储库列表运行变体分析时，将仅针对当前具有可供下载的 CodeQL 数据库的存储库执行查询。使存储库可用于变体分析的最佳方法是使用 CodeQL 启用 code scanning。有关使用 CodeQL 启用 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 中的存储库子集添加到自定义列表。

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

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

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

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

生成的某些存储库将没有 CodeQL 数据库，有些存储库可能不允许通过 CodeQL 扩展名访问 Visual Studio Code。当你对列表运行分析时，“变体分析结果”视图将显示分析了哪些存储库，哪些存储库拒绝访问，以及哪些存储库没有 CodeQL 数据库。

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

本文内容