whistle.ws-inspector

English | 简体中文

一个业务无关、被动读取的 Whistle WebSocket 帧检查插件。它读取 Whistle 已经捕获的帧，并在插件 Option 页面中展示 JSON、MessagePack、UTF-8 文本、压缩内容或 可无损还原的二进制摘要。

插件只负责检查：不会主动建立上游 WebSocket 连接，不会转发或修改帧，也不会安装拦截规则。

主要功能

• 自动识别 JSON、MessagePack 和 UTF-8 文本
• 递归解码 gzip、deflate 和 Brotli
• 未知二进制格式以可无损还原的 hex 和 Base64 展示
• 展示方向、字节数、编码和时间戳元数据
• 支持按正则表达式过滤会话和解码后的帧内容
• 三栏宽度可调、会话表格可排序、支持明暗主题和解码资源限制
• 不硬编码站点、接口或业务字段
• 提供仅本地导入的独立模式，用于查看已保存或合成的帧

环境要求

• Node.js 18 或更高版本
• 被动检查浏览器流量时需要 Whistle 2.x

配合 Whistle 快速开始

安装 Whistle 和插件：

npm install -g whistle
w2 start -p 8899
npm install -g whistle.ws-inspector

将浏览器或操作系统的 HTTP/HTTPS 代理配置为 127.0.0.1:8899。需要检查 HTTPS 时，安装并 信任 Whistle 根证书。然后：

1. 打开 http://local.whistlejs.com/ 或 http://127.0.0.1:8899/。
2. 进入 Plugins，启用 ws-inspector，点击 Option。
3. 保持 Whistle 录制状态，访问或操作一个使用 WebSocket 的页面。
4. 选择一个状态为 101 的会话，再选择具体帧查看解码结果。

Whistle 原生 Frames 面板仍可能显示二进制摘要，这是预期行为；可读结果以插件的 Option 页面为准。

证书安装、代理排障、界面操作和安全截图指南见中文使用指南。

从源码安装

git clone https://github.com/derek-sz/whistle.ws-inspector.git
cd whistle.ws-inspector
npm install
npm test
w2 install .
w2 restart -p 8899

独立检查模式

Whistle 不可用或帧由其他工具导出时，可以使用独立模式。服务只监听本机回环地址，导入数据只 保存在内存中，也不会连接远程 WebSocket 服务。

npm start

复制进程输出的随机 URL 和 bearer token，然后导入一个合成帧：

curl -X POST http://127.0.0.1:8898/api/v1/import \
  -H "Authorization: Bearer <printed-token>" \
  -H "Content-Type: application/json" \
  --data '{"session":{"url":"wss://stream.example.test/market"},"frames":[{"base64":"eyJzeW1ib2wiOiJCVEMiLCJwcmljZSI6NjAwMDB9"}]}'

打开进程输出的本地地址，依次选择导入的会话和帧。二进制 fallback、压缩内容等示例见 示例文档。

隐私与安全

Option 页面会按原样展示完整 WebSocket URL 和帧内容。数据只在本机 Whistle/插件进程中处理， 本插件不会上传或持久化这些内容，但被捕获的数据可能包含密钥或个人信息。

• 只检查你有权访问的流量。
• 发布截图、日志或 Issue 附件前先检查并脱敏。
• 不得公开 Cookie、Authorization、Token、私有域名或生产环境完整载荷。
• Bug 报告和示例优先使用合成帧。

漏洞报告和完整数据边界见 SECURITY.md。

工作原理

1. Whistle 使用原生解析器捕获 WebSocket 连接和帧。
2. Option 页面通过 Whistle 本地 API 读取会话和帧副本。
3. 原始帧副本发送到插件本地解码接口。
4. UI 展示结构化内容或可无损还原的二进制 fallback。

组件边界和扩展契约见架构文档。

开发

npm test
npm run check
npm pack --dry-run

提交修改前请阅读 CONTRIBUTING.md。

许可证

MIT