ytkachuk95-collab/websocket-frame-inspector

# WebSocket 帧检查器 一个用于逆向工程实时 Web API 的协议无关工具。它会附加到页面打开的每个 WebSocket，按结构对每一帧进行分类，并构建一个目录，准确记录网站通过其 socket 发送的具体内容——包括已命名的 Socket.IO / Engine.IO 事件、原始 JSON 数组和对象、二进制帧以及控制帧。 当一个网站**没有公开 API**，且你需要在构建数据管道之前了解其未公开的实时协议时，这个工具非常有用。 该仓库还包含一个**流式 SQLite 收集器**（`collector.py`）骨架，展示了此类管道的存储层：批量写入、WAL 模式、schema 迁移和事件路由。 ## 为什么开发它 许多实时 Web 应用通过 Socket.IO 进行通信，混合使用文本和二进制帧、未公开的事件名称以及不明显的分帧（例如，一个文本“公告”帧后紧跟一个单独的二进制 payload）。在能够可靠地收集这些数据之前，你必须**看清**完整的协议。该工具会生成： - `catalog.json` —— 一个结构化的摘要：包含每种帧类型的计数、频率、平均大小以及一些去重后的样本。 - `raw.jsonl` —— 一个包含每一帧的只追加日志，用于实现完全的可复现性。 你可以根据该目录设计规范化的 schema 并构建收集器——`collector.py` 骨架展示了具体做法。 ## 工作原理 `inspector.py` 在对每一帧进行分类时，**不会假设任何特定网站的事件名称**。它仅判断结构： | 类别 | 含义 | |---|---| | `control` | Engine.IO 控制帧（ping/pong/open），无 payload | | `event` | 命名的 Socket.IO 事件：`["name", ...]` | | `binary_announce` | Socket.IO 二进制事件占位符（`451-[...]`） | | `binary` | 二进制数据帧 | | `array` / `object` | 没有事件名称的原始 JSON | | `scalar` / `empty` / `unparsed` | 其他所有内容 | 帧通过方向 + 类别 + 事件名称作为键进行索引，因此你可以获得一个清晰的协议清单，并根据每条消息的实际内容进行分组。 ## 用法 ``` pip install -r requirements.txt playwright install chromium # 检查站点的 WebSocket 流量 python inspector.py --url https://example.com # 已认证页面：提供导出的 cookies python inspector.py --url https://example.com --cookies cookies.json # Headless python inspector.py --url https://example.com --headless ``` 在运行期间与页面进行交互以触发不同的事件，然后按 `Ctrl+C`。目录和原始日志将在退出时（以及运行期间的定期）写入。 ### 流式收集器演示 ``` python collector.py # writes 1000 synthetic events into demo_stream.db ``` 这演示了 SQLite sink：批量插入、WAL、迁移，以及位于类型化表旁边的原始事件日志。 ## 文件 | 文件 | 用途 | |---|---| | `inspector.py` | WebSocket 帧捕获 + 结构分类 | | `collector.py` | 流式 SQLite sink 骨架（批量处理、WAL、迁移） | ## 技术栈 Python · Playwright · asyncio · SQLite ## 许可证 MIT — 查看 [LICENSE](LICENSE)。

标签：Socket.IO, SOC Prime, SQLite, URL抓取, Web API, 云资产清单, 开发工具, 数据抓取, 特征检测, 网络流量分析, 计算机取证, 逆向工具, 逆向工程