trailofbits/vscode-sarif-explorer

# SARIF Explorer：享受审查静态分析结果的过程 SARIF Explorer 是一款 VSCode 扩展，它能让你高效且愉快地审查静态分析结果。从此告别浏览 `.txt` 或 `.csv` 文件的日子。 无论你是开发者还是代码审计人员，SARIF Explorer 都允许你将工具的结果分类为 `Bug` 或 `误报`，为结果添加注释，导出你已分流的错误等等（详见下方[功能](#features)）。  ## 安装说明 在 VSCode 扩展浏览器中搜索 [SARIF Explorer](https://marketplace.visualstudio.com/items?itemName=trailofbits.sarif-explorer) 来安装此扩展。关于如何从代码构建和安装，请参阅下方的[构建与安装](#development)部分。 ## 功能 - [**打开多个 SARIF 文件**](#open-multiple-sarif-files)：同时打开并浏览多个 SARIF 文件的结果。 - [**浏览结果**](#browse-results)：通过点击结果来浏览它们，这将在 VSCode 中打开其关联的位置。如果结果存在数据流步骤，你也可以浏览这些步骤。 - [**分类结果**](#classify-results)：通过将每个结果分类为 `Bug`、`误报` 或 `待办`，并添加自定义文本注释，为结果添加元数据。 - [**过滤结果**](#filter-results)：按关键字、路径（包含或排除）、级别（`error`、`warning`、`note` 或 `none`）和状态（`Bug`、`误报` 或 `待办`）过滤结果。你还可以隐藏特定 SARIF 文件或特定规则的所有结果。 - [**复制 GitHub 永久链接**](#copy-github-permalinks)：复制指向结果关联位置的 GitHub 永久链接。需要安装 [weAudit](https://github.com/trailofbits/vscode-weaudit)。 - [**创建 GitHub Issues**](#create-github-issues)：为特定结果或给定规则下所有未过滤的结果创建格式化的 GitHub Issues。需要安装 [weAudit](https://github.com/trailofbits/vscode-weaudit)。 - [**将 Bug 发送到 weAudit**](#send-bugs-to-weaudit)：将所有分类为 `Bug` 的结果发送到 [weAudit](https://github.com/trailofbits/vscode-weaudit)（结果会自动去重）。需要安装 [weAudit](https://github.com/trailofbits/vscode-weaudit)。 - [**协作**](#collaborate)：与同事（例如在 GitHub 上）共享 `.sarifexplorer` 文件，以共享你的注释和分类结果。 ## 建议的工作流程 1. 运行你所有的静态分析工具，并将生成的 SARIF 文件保存在运行它们的文件夹中 2. 打开 SARIF Explorer 并打开所有 SARIF 文件 3. 过滤掉嘈杂的结果： - 你是否有不感兴趣的规则？隐藏它们！ - 你是否有不关心结果的文件夹（例如 `./tests` 文件夹）？过滤掉它们！ 4. 对结果进行分流： - 确定每个结果是误报还是缺陷 - 相应地向左或向右滑动（即点击左箭头或右箭头） - 如有必要，添加带注释的额外上下文 5. 与其他团队成员合作？通过提交 [`.sarifexplorer` 文件](./docs/sarif_explorer_spec.md)来分享你的进展 6. 将所有标记为缺陷的结果发送到 [weAudit](https://github.com/trailofbits/vscode-weaudit)，并继续 [weAudit](https://github.com/trailofbits/vscode-weaudit) 工作流 ## 核心概念 - **SARIF 文件**：你已打开并可在 `SARIF 文件` 标签页中查看的 SARIF 文件。 - **结果**：从 SARIF 文件加载的结果，可在 `结果` 标签页中查看。 - **基础文件夹**：你运行静态分析工具时所针对的文件夹的绝对路径。SARIF Explorer 使用此路径来确定在哪里打开结果的关联代码。在大多数情况下，SARIF Explorer 的启发式方法会自动为你找到此文件夹。 ## 快捷键 在 `结果` 标签页中： - `下箭头`：选择下方的结果 - `上箭头`：选择上方的结果 - `右箭头`：将选定结果分类为 `Bug` 并选择下方的结果 - `左箭头`：将选定结果分类为 `误报` 并选择下方的结果 - `Backspace`：将选定结果分类为 `待办` 并选择下方的结果 ### 打开多个 SARIF 文件 点击顶部栏中的 按钮，选择多个 SARIF 文件来打开它们。你可以在 `SARIF 文件` 标签页中浏览已打开的 SARIF 文件列表，也可以在其中关闭或重新加载给定的 SARIF 文件。 在 SARIF 文件的详细视图中，你可以看到它的完整路径、它发现的结果数量，以及它对代码运行了哪些规则（即使该规则没有找到任何结果）（如果工具生成了正确的 SARIF 文件）。在此视图中，你还可以修改与 SARIF 文件关联的[基础文件夹](#concepts)。  在 VSCode 中打开扩展名为 `.sarif` 的文件也会触发 SARIF Explorer 打开它并显示其结果。 ### 浏览结果 在 `结果` 标签页中，通过打开一个规则并点击结果来浏览所有已打开的结果。这将打开与结果关联的代码位置。 在结果的详细视图中，你有更详细的信息，包括数据流数据，你可以从源浏览到汇。  ### 分类结果 使用鼠标或键盘快捷键对结果进行分类。 **使用鼠标**：选择一个结果后，点击 按钮将其分类为 `Bug`，点击 按钮将其分类为 `误报`，点击 按钮将分类重置为 `待办`。这些按钮出现在结果旁边以及结果的详细视图中。 **使用键盘**：为了更高效，选择一个结果并按 `右箭头` 键将其分类为 `Bug`，按 `左箭头` 键将其分类为 `误报`，按 `Backspace` 键将分类重置为 `待办`。  ### 过滤结果 通过在顶部栏的过滤区域输入关键字来过滤。关键字搜索不区分大小写，并且会匹配结果的显示路径、行号、消息、关联的 SARIF 文件、注释、规则名称、规则描述以及生成结果的工具名称。 要获取更多过滤选项，请点击顶部栏中的 按钮打开过滤菜单。在过滤菜单中，你可以： - 按包含或排除关键字的路径过滤（你可以使用逗号分隔的多个路径） - 按结果的级别过滤（`error`、`warning`、`note` 或 `none`） - 按结果的状态过滤（`待办`、`Bug` 或 `误报`） 示例：你想移除 `tests` 和 `third_party` 文件夹中的所有结果，并且只查看分类为 `待办` 的结果。你应该： - 将 `排除包含以下路径` 设置为 `/tests/, /third_party`，并在 - `状态` 部分，勾选 `待办` 复选框，取消勾选 `Bug` 和 `误报` 复选框 注意：当结果更新时，过滤器不会自动重新应用；你需要点击 按钮来刷新过滤器。选择此设计是为了防止在你分类结果或添加注释时 UI 跳动。  ### 复制 GitHub 永久链接 复制指向结果关联位置的 GitHub 永久链接。通过点击结果旁边或结果详细视图中的 按钮来执行此操作。 永久链接的目标仓库将根据你的 [weAudit](https://github.com/trailofbits/vscode-weaudit) 配置进行选择。此功能需要安装 [weAudit](https://github.com/trailofbits/vscode-weaudit)。  ### 创建 GitHub Issues 创建包含结果数据的 GitHub Issue。你可以创建两种类型的 GitHub Issues： 1. 为特定结果创建 Issue，通过点击结果旁边或结果详细视图中的 按钮。 2. 为一组结果创建 Issue，通过点击结果表格中规则旁边的 按钮。该 Issue 将包含该规则下所有未被过滤的结果（不仅仅是那些分类为 `Bug` 的）。 GitHub Issues 将根据你的 [weAudit](https://github.com/trailofbits/vscode-weaudit) 配置在某个仓库中创建。此功能需要安装 [weAudit](https://github.com/trailofbits/vscode-weaudit)。  ### 将 Bug 发送到 weAudit 点击顶部栏中的 按钮，将所有分类为 `Bug` 的结果发送到 [weAudit](https://github.com/trailofbits/vscode-weaudit)。结果会自动去重（在 [weAudit](https://github.com/trailofbits/vscode-weaudit) 端）；因此，如果你分类了一个新的 `Bug` 并再次发送所有 `Bug`，只有新的那个会被添加。 显然，此功能需要安装 [weAudit](https://github.com/trailofbits/vscode-weaudit)。  ### 协作 与同事（例如在 GitHub 上）共享 `.sarifexplorer` 文件，以共享你的注释和分类结果。该文件是一个格式化的 JSON 文件，这有助于在多人同时写入文件时解决冲突。 ## 开发 ### 构建与安装 要构建和安装新的 vsix 文件，请运行以下脚本： ``` npm install ./scripts/build_and_install.sh ``` ### 架构 该扩展有两个部分：扩展本身——可以读取文件系统文件并执行任意 nodeJS 的特权部分，以及 Webview——负责绘制 UI 的非特权部分。这两个部分通过 `postMessage` 进行通信。它们的代码位于不同的文件夹中，每个文件夹都包含一个 README，解释了其用途。 ### SARIF Explorer 文件格式 SARIF Explorer 文件格式的详细说明见 [sarif_explorer_spec.md](./docs/sarif_explorer_spec.md)。

标签：Bug跟踪, SARIF格式, SOC Prime, TLS抓取, VSCode扩展, 云安全监控, 导出功能, 开发工具, 开发效率, 数据可视化, 注释添加, 结果分类, 结果可视化, 结果浏览, 结果过滤, 网络可观测性, 自动化攻击, 误报管理, 软件安全, 静态分析