onsomlem/WebReconPack

# WebReconPack 本地优先的 Chrome MV3 扩展程序，可记录用户控制的浏览会话，并导出包含足够运行时上下文的本地 ZIP 文件，以帮助理解网站的行为。 ## 状态 — v0.2.0 (分析器已发布) - **v0.1.0** — 首个可用版本；通过了规范 §31 Sheets 验收。 - **v0.1.1** — 操作体验优化：工具栏 `REC` 徽章，实时持续时间计时器，捕获预设选择器（Light / Standard / Deep）。 - **v0.1.2** — 公开代码规范化；第二次黄金测试（GitHub, 120s, form_submit + 多框架验证通过）。 - **v0.2.0** — **[`webrecon-analyze`](analyzer/)** 配套 CLI。单文件 Python 实现，仅使用标准库。将侦察 ZIP 转化为结构化洞察：认证面、端点聚类、分类、提取策略及 jq + curl 命令示例、解析器警告。已通过针对两套黄金测试包的 19 项验收检查验证。 所有 v0.1 阶段均已发布： | 阶段 | 范围 | 状态 | |---|---|---| | 0 | MV3 骨架，popup ↔ Service Worker 桥接 | ✅ | | 1 | 会话生命周期 (Start / Stop / Cancel) + popup 关闭恢复能力 | ✅ | | 2 | MAIN ↔ isolated ↔ SW 观察桥接，带有严格的标记验证 | ✅ | | 3 | `fetch` 捕获 (请求/响应头、请求体、耗时、发起者调用栈) | ✅ | | 4 | ZIP 组装 + `chrome.downloads.download()` | ✅ | | 5 | `XMLHttpRequest` 捕获 | ✅ | | 6 | DOM / 全局变量 / 存储 / 运行时 / 性能 / 脚本 / 样式快照 | ✅ | | 7 | `console.*` + `error` + `unhandledrejection` 捕获 | ✅ | | 8 | `sendBeacon`、表单、history/navigation、用户事件、动态脚本、object URL / 下载、剪贴板、文件输入、Worker / SharedWorker、Cache Storage、权限 / 特性检测 | ✅ | | 9 | `WebSocket` + `EventSource` 捕获 | ✅ | | 10 | 端点聚类，GraphQL/RPC/框架检测，发起者分类，生成 `summary.md` | ✅ | | 11 | 请求体大小限制，脱敏处理，错误隔离，端口保持活动 | ✅ | 根据规范 §30，以下功能已推迟至 v0.2（HAR、多标签页、IDB 记录导出、source maps、Worker 内部流量、Postman/OpenAPI 导出、配置生成、通过 `webRequest` 实现的完整 CSP）。 ## 验证 两个生产级 Web 应用已通过端到端验证。测试包保存在 [`golden-tests/`](golden-tests/) 中，并作为未来版本的回归基准锁定。 ### Google Sheets 125 秒的会话。[`golden-tests/sheets-125s-v0.1.0/`](golden-tests/sheets-125s-v0.1.0/) - **768 KB ZIP**（比规范的 100 MB 验收上限低 130 倍） - **353 条网络记录**（18 个 fetch + 335 个 XHR — 首次 XHR 容量验证） - **快照包含 6 个框架**，其中包括跨域框架（`accounts.google.com`、`contacts.google.com`、`ogs.google.com`） - `_docs_flag_initialData` (85 KB) 和 `WIZ_global_data` (19 KB) 初始化全局变量完整捕获 - **在 58 个响应中检测到 XSSI 前缀 `)]}'`**（高置信度） - **在 58 个请求中检测到 Google WIZ batchexecute**（高置信度） - **在 56 个请求中检测到 form-urlencoded RPC** - **在 8 个响应中检测到类 protobuf 二进制响应** - 33 个请求头值 + 43 个 Cookie 值已脱敏 - 未触及请求体上限（在 50 MB 的预算内捕获了 1.78 MB 的请求体） - **未观察到页面破坏**（Sheets 保持完全交互状态，同一页面上运行的其他扩展未受干扰） ### GitHub (已登录的浏览会话) 119 秒的会话，跨越 dashboard → repo → issues → notifications。[`golden-tests/github-repo-120s-v0.1.2/`](golden-tests/github-repo-120s-v0.1.2/) - **1.3 MB ZIP**（比 100 MB 上限低 75 倍） - **232 条网络记录**（226 个 fetch + 6 个 XHR — 以 fetch 为主的 SPA） - **313 次 `sendBeacon` 调用**（GitHub 的遥测数据流） - **1 次 form_submit 捕获**（首次表单捕获验证 — `dismiss-notice`，`authenticity_token` 正确脱敏为仅保留类型） - **捕获了 6 次 Worker 构造** - **1857 次动态脚本/资源添加**（Turbo 懒加载） - **79 次导航事件**（密集的 SPA 路由流量） - **933 个请求体字段**通过标准正则表达式脱敏 - 端点聚类已正确规范化：`/{owner}/{repo}/issues`、`/notifications/{id}/watch_subscription` 等。 - 模式检测器如实报告 — GitHub 在此会话中不使用 GraphQL/WIZ/XSSI，因此报告如实说明（无假阳性） - **未观察到页面破坏** 综合覆盖范围：重 XHR 的 SPA、重 fetch 的 SPA、表单提交、多框架会话、跨域框架、Trusted Types 环境以及大量动态脚本注入 — 所有这些都不会破坏宿主页面。 ## 分析测试包 (v0.2.0+) 要获取面向操作员的结构化报告，请使用配套分析器： ``` python3 analyzer/webrecon_analyze.py recon-yourdomain-XXX.zip # 写入 .report.md (人工) # 写入 .report.json (机器) ``` 在记录器生成的 `summary.md` 基础上，您还将获得以下内容： - **认证面** — 聚合整个会话中所有标记为认证的请求头、认证 Cookie、CSRF 表单字段、bearer-token 存在情况以及标记为认证的查询参数。 - **按分类划分的端点聚类** — `data_fetch` / `data_write` / `rpc` / `auth` / `telemetry` / `asset` / `unknown`，包含必需与可选的查询键、状态码分布以及请求/响应结构。 - **可能的数据端点 + 提取策略** — 每个聚类的分页、认证、速率限制、base64 字段说明，以及可运行的 `jq` 命令和 `curl` 骨架代码。 - **解析器警告** — XSSI 前缀、base64 字段、二进制/protobuf 响应、NDJSON 流、WIZ batchexecute。每项都包含操作员应采取的明确*操作*指示。 - **初始化全局变量清单** — `__NEXT_DATA__`、`_docs_flag_initialData`、`WIZ_global_data`、`__APOLLO_STATE__` 等，附带大小和结构形状。 完整详情和示例输出请参见 [`analyzer/README.md`](analyzer/README.md)。 ## 读取测试包 按以下顺序检查 ZIP 内容： 1. **`summary.md`** — 从这里开始。包含顶级端点（已聚类并规范化）、检测到的模式（GraphQL/RPC/XSSI/等）、发起者分类、脱敏报告、建议的下一步操作。 2. **`network.jsonl`** — 核心数据。每个请求对应一条 JSON 记录。包含请求头、请求体（已限制大小并尽可能解码为 JSON）、耗时、发起者调用栈、框架 URL。使用 [jq](https://jqlang.github.io/jq/) 进行过滤： jq -c 'select(.method=="POST")' network.jsonl jq -c 'select(.url|test("graphql"))' network.jsonl jq -c 'select(.responseBody.decoded != null) | {url, decoded: .responseBody.decoded}' network.jsonl | head -3 3. **`timeline.jsonl`** — 统一的按时间排序的事件流。用于关联用户点击、导航事件和网络调用： jq -c '{t,kind,summary}' timeline.jsonl | head -30 4. **`globals.json`** — 引导状态对象（`__INITIAL_STATE__`、`__NEXT_DATA__`、`__APOLLO_STATE__` 等，如果存在）。这是 SPA 隐藏其服务端渲染初始状态的地方。 5. **`storage.json``** — 每个框架的 localStorage / sessionStorage / cookies（已脱敏），以及 IndexedDB 元数据和 Cache Storage URL。 6. **`runtime.json`** — userAgent、语言、CSP meta 标签、Trusted Types 存在情况、Service Worker 注册、权限状态、特性检测（WebRTC、WebAuthn、FileSystemAccess 等）。 7. **`navigation.jsonl`** — `pushState` / `replaceState` / `popstate` / `hashchange` / `beforeunload` / `pagehide` / `visibilitychange`。SPA 路由追踪。 8. **`user-events.jsonl`** — 点击、focus/blur、滚动（已限流）、按键（默认不包含键值）、更改。每条记录都包含一个带有选择器、角色、aria-label、文本片段的 `target` 描述符。 9. **`scripts.jsonl`** — 记录期间添加的每个动态 `