hyj28/mvx-audit

# MVX Audit：Chrome Manifest V2 与 V3 安全性分析 [](https://github.com/hyj28/mvx-audit/actions/workflows/ci.yml) [](LICENSE) [](package.json) MVX Audit 是一款确定性的、无依赖的 Chrome 扩展安全研究工具包。 它集成了静态审计、MV2/MV3 能力对比、可复现的真实世界威胁情报、哈希校验的隔离机制、 真实样本筛选基准测试，以及可选的无网络动态 canary 实验室。 该仓库包含一个精心整理的语料库，涵盖 **17 个威胁场景和 34 对 MV2/MV3 固件**， 并提供了一个可复现的真实世界情报快照，涵盖 **4,716 个唯一的扩展 ID** 和 **504 个已索引的非空 CRX 构件**。 常规命令永远不会打包或获取在线软件包。 ## 本项目存在的原因 Manifest V3 改进了重要的平台边界：扩展 Service Worker 替代了持久化的 background pages， 禁止了远程托管代码，并且大多数扩展使用声明式网络规则，而不是通过阻塞 `webRequest` 来处理。 但这**并不**意味着所有被授予的权限都是安全的。诸如 Cookie 访问、宽泛的 content scripts、 debugger 访问、history、proxy 和 native messaging 等能力仍然需要审查。 Chrome 138 是最后一个提供有限 MV2 支持的 Chrome 版本；Chrome 139 移除了该支持， 其余的 MV2 Web Store 条目计划于 2026 年 8 月 31 日被移除。 请参阅官方的 [MV2 支持时间表](https://developer.chrome.com/docs/extensions/develop/migrate/mv2-deprecation-timeline) 以及 [MV3 概述](https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3)。 ## 快速开始 环境要求：Node.js 20 或更高版本。没有运行时依赖，也不需要下载浏览器。 ``` git clone https://github.com/hyj28/mvx-audit.git cd mvx-audit npm ci # 审计已解压的 extension 目录 node bin/mvx.js audit /path/to/extension # 当存在 high- 或 critical-severity finding 时使 CI 失败 node bin/mvx.js audit /path/to/extension --format sarif \ --output results.sarif --fail-on high # 比较一个 migration node bin/mvx.js compare /path/to/mv2 /path/to/mv3 \ --format markdown --output migration-review.md # 探索并验证内置的 research corpus node bin/mvx.js corpus list npm run corpus:validate # 无需下载 malware 即可查询 real-world threat intelligence node bin/mvx.js intel stats node bin/mvx.js intel lookup npm run intel:validate # 检查 live-artifact plan；这不会下载任何内容 node bin/mvx.js sample plan node bin/mvx.js sample plan-many --label behavior-confirmed-malicious --limit 100 # 明确 opt-in 下载到被 Git 忽略的 quarantine node bin/mvx.js sample fetch --acknowledge-risk node bin/mvx.js sample fetch-many --acknowledge-risk \ --label behavior-confirmed-malicious --limit 100 --max-total-bytes 250000000 # 用于 static analysis 的有界 CRX2/CRX3 提取 node bin/mvx.js sample unpack quarantine//.crx --acknowledge-risk node bin/mvx.js audit quarantine//unpacked/ # 对已 quarantine 的真实样本进行 benchmark 且不执行 extension code node bin/mvx.js benchmark static quarantine --acknowledge-risk \ --label behavior-confirmed-malicious --threshold high --format json ``` 如果你想在本地开发期间使用等效的 `mvx` 命令，请使用 `npm link`。 ## 审计包含的内容 - Manifest 版本和迁移兼容性检查。 - 宽泛的 host、content-script、外部 messaging 和 web-resource 暴露情况。 - 敏感权限审查，包括诸如 `cookies` + `` 等能力链。 - 针对 `webRequest` 阻塞和 MV3 `declarativeNetRequest` header 规则的网络控制审查。 - 用于动态评估、HTML 注入、通配符 messaging、击键记录、Cookie 枚举、不安全传输、 下载、剪贴板读取以及未经验证的特权消息桥接的源指标。 - 基于远程 iframe 的扩展 UI 以及向被嵌入的 origin 委派敏感能力的情况。 - 稳定的证据位置、风险摘要、明确的假设，以及适用于 GitHub code scanning 的 SARIF 2.1.0 报告。 - 对所有打包源代码（包括 vendored 目录）的有界扫描，拒绝符号链接的根目录， 跳过嵌套的符号链接，并在达到文件或字节限制时安全关闭。 请参阅完整的 [规则参考](docs/rule-reference.md) 和 [方法论](docs/methodology.md)。 ## 合成语料库与真实世界情报 旧版本的代码库混合了复制的概念验证扩展、真实的公共 endpoint、 不同的浏览器版本以及数百个重复的 CSV 文件。这些构件无法支撑科学的 MV2/MV3 结论，并带来了不可接受的安全风险。它们在 2.0 版本中被移除。 替代的[合成语料库](corpus/README.md) 通过单一的机器验证注册表， 涵盖了 17 种不同的能力和实现模式。每个条目都包含成对的 manifest、 明确的 MV3 影响分类、预期的分析器发现，以及指向 Chrome 官方文档的链接。 生成的[能力矩阵](docs/research-report.md) 可从当前源码中复现。 独立的[真实世界情报目录](intel/README.md) 将三个锁定的开源数据去重为 4,716 个扩展 ID。它保留了来源、标签类型、验证级别、商店状态、威胁类别、 SHA-256 值以及外部构件的可用性。“Reported（已报告）”、“policy violation（策略违规）” 和“confirmed malware（已确认的恶意软件）”仍然是不同的状态。 请参阅[数据源与真实基准方法论](docs/data-sources.md)。 对于已索引的构件，`sample plan` 会显示不可变的源版本、大小、 Git blob 身份以及任何提供商报告的 SHA-256。 `sample fetch` 是一个明确的自愿参与（opt-in）操作，它仅接受白名单中的 HTTPS host， 强制执行大小上限，验证 Git 内容哈希，计算实际的 SHA-256， 并将文件存储在 `quarantine/` 下。它永远不会解包、导入或执行 CRX。 `sample unpack` 是一个独立的显式操作。内置的提取器会拒绝路径遍历、链接、 加密、不受支持的方法、重复路径、CRC 校验失败、过度扩展以及归档炸弹， 然后才会将解包后的目录暴露给静态审计器。它仍然不能保证执行活跃的恶意软件是安全的。 `sample plan-many` 和 `sample fetch-many` 添加了确定性优先级排序、 数量限制、单构件限制、总字节预算以及隔离的失败报告。 `benchmark static` 会安全地解包被隔离的 CRX，对它们进行审计， 并报告**审查触发率**。它故意不将该数值称为恶意软件分类准确率， 因为扩展 ID 标签可能跨越多个版本。 ## 结果语义 风险分数是一个有界的审查优先级分数，而不是概率或可利用性度量。 一项发现意味着“审查此能力或模式”，而不是“此扩展是恶意的”。 反之，没有任何静态分析器能够证明一个扩展是绝对安全的。 可选的[动态 canary 实验室](docs/dynamic-analysis.md) 仅在具有 `--network none` 的 只读、非 root Docker container 中运行。它通过 Chrome DevTools Protocol 提供一个虚拟的 HTTPS canary 页面，阻塞并记录外部请求，拒绝下载， 并将确切的 canary 泄漏或受保护状态更改归类为 `confirmed_attack`。 普通的 CI 测试会运行事件预言机，但永远不会执行活跃的扩展。 `no_trigger_observed` 并不是一个良性的判定。 ## 开发 ``` npm test # unit and integration tests npm run test:coverage # built-in Node coverage npm run lint # syntax and repository hygiene checks npm run docs:generate # regenerate the corpus report npm run intel:validate # validate real-world intelligence offline npm run intel:check # reproduce it from pinned upstream sources npm run lab:build # build the optional isolated Chromium image npm run lab:smoke -- --acknowledge-risk # real Docker/Chromium smoke test npm run check # all required checks npm audit --omit=dev # expected: zero dependencies, zero advisories ``` 公共 API： ``` import { auditExtension, compareExtensions } from 'mvx-audit'; const audit = await auditExtension('/path/to/unpacked-extension'); const comparison = await compareExtensions('/path/to/mv2', '/path/to/mv3'); ``` ## 安全与负责地使用 仅分析您被授权检查的扩展。将未知的扩展包视为不受信任的输入， 并且不要将它们加载到您的日常浏览器中。 MVX Audit 不执行扩展文件。在报告敏感问题之前，请阅读 [SECURITY.md](SECURITY.md)； 在添加新场景之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 基于 [MIT License](LICENSE) 授权。

标签：GNU通用公共许可证, MITM代理, Node.js, 云安全监控, 威胁情报, 开发者工具, 数据泄露, 知识库安全, 自定义脚本, 请求拦截, 静态分析