Skip to content

README.zh-CN.md

Latest commit

 

History

History
262 lines (176 loc) · 7.67 KB

README.zh-CN.md

File metadata and controls

262 lines (176 loc) · 7.67 KB

ProtoDecodeX

License

English | 简体中文 | 在线体验

ProtoDecodeX 是一个跑在浏览器里的 Protobuf 线格式解码工具。

它主要是拿来处理那些不太舒服的场景：手里只有一段原始字节，也许没有 .proto，也许只有日志里的十六进制、代理里拷出来的 payload，或者一串看起来不太友好的 Java 字节数组，但你还是得先搞清楚里面到底装了什么。

ProtoDecodeX 截图

这个工具是干什么的

这个工具想解决的是一些很具体的问题：

  • 这段 Protobuf 二进制里到底有哪些字段？
  • 这份输入是十六进制、Base64、Java 字节数组，还是 Java 转义字符串？
  • 这是不是一段 varint 长度分隔的多消息流？
  • 我能不能贴一点 .proto 片段，把字段号映射成字段名？
  • 某个 bytes 字段是不是被 XOR 过，能不能继续往下解？

它不是那种大而全的 Protobuf 工具，更像一个顺手、直接、够用的检查台。你可以粘贴原始数据、上传本地文件、看字段结构、字节范围和原始 bytes，需要的时候再补一小段 schema，让结果更好读一点。

适用场景

  • 逆向分析未知 Protobuf 消息
  • 检查从日志、抓包或代理里拿到的二进制载荷
  • 检查 gRPC 消息体
  • 处理 Java 代码或日志中的字节数组/转义字符串
  • 分析嵌套 bytes 字段，一层层往下定位真实结构

为什么会有这个工具

很多 Protobuf 工具默认你已经知道 schema。可真实排查问题的时候，经常不是这样。

你手上可能只有：

  • 日志里的一段 hex
  • API trace 里的 Base64
  • Java 打印出来的一串字节
  • 带着 gRPC framing 的消息体

ProtoDecodeX 就是从这种原始条件出发。先把线格式看清楚，再一点点补上下文，而不是一开始就假设环境完整。

功能

  • 支持 Hex、Base64、Java 十进制字节数组、Java 转义字符串、文件上传
  • 自动识别输入格式，并规范化成可读的 Hex
  • 以表格形式展示 Protobuf 线格式解析结果
  • 支持 varint 长度分隔的多消息流解析
  • 检测到 gRPC 帧头时会尝试跳过
  • 支持粘贴 message 定义，做 schema 感知展示
  • 内置 Smart Decode，支持条件 XOR 和手动 XOR
  • XOR 后的结果可以直接作为新的主输入继续分析
  • 常用状态会保存到 localStorage
  • 仓库里也带了测试、CI、Docker 和部署配置

支持的输入格式

格式 示例
十六进制字节流 08 96 01
Base64 CJYB
Java 十进制字节数组 8, 150, 1
Java 转义字符串 \010\226\001
本地文件上传 浏览器中读取任意本地二进制文件

快速开始

环境要求

  • 建议使用 Node.js 20，和 CI 保持一致
  • npm

本地开发

npm install
npm start

启动后访问 http://localhost:3000。

生产构建

npm run build

构建产物会输出到 build/。

运行测试

npm test

使用方式

  1. 粘贴原始数据，或上传本地文件。
  2. 工具自动识别输入格式，并生成规范化 Hex。
  3. 点击 Decode 开始解析。
  4. 在结果表格中查看字段号、Wire Type、字节范围与原始值。
  5. 如有需要，继续使用高级功能中的 Schema 展示或 Smart Decode。

细看一下

线格式可视化

解码结果会把这些最有用的信息直接摊开：

  • 字段号
  • Wire Type
  • 字节范围
  • 原始 bytes
  • 可展开的大字段内容

就算没有 .proto 文件，也能先把消息的大致轮廓看出来。

规范化 Hex 视图

不管输入原来是什么格式，最后都会统一成一个只读的 Hex 视图。这个设计其实很朴素，但很好用，尤其是当你要对照日志、复制片段、或者继续手工分析的时候。

多消息流解析

如果输入里串着多条 Protobuf 消息，而且每条前面都有 varint 长度前缀，可以勾选 parse varint length delimited input，让它按消息边界拆开显示。

这种情况在流式传输、批量消息和一些协议封装里挺常见的。

gRPC 帧头处理

如果输入看起来带着 gRPC 帧头，解码器会先试着把那层头部跳过去，再继续做 Protobuf 解析。省掉一点小但烦人的手工处理。

基于 Schema 的展示

在高级面板里，你可以直接贴一小段 message 定义，把字段号映射成字段名和类型。

示例：

message User {
  string name = 1;
  uint32 age = 2;
  repeated string tags = 3;
}

补上 schema 之后，界面能多给你一些上下文：

  • 字段名
  • 基础类型感知渲染，例如 string、bool、float、double
  • optional / repeated 等提示

这个 parser 是轻量实现，适合快速辅助阅读，不打算替代完整的 .proto 编译。

Smart Decode / XOR 工作流

有些业务载荷会把真正有用的内容塞在一个 bytes 字段里，再顺手做一层 XOR。Smart Decode 就是拿来处理这种情况的，支持两种方式：

  • 条件 XOR：以一个字段的值作为 XOR key，对另一个字段做解码，并可设置前置条件
  • 手动 XOR：手动输入数据和 XOR 值，快速验证结果

如果 XOR 后的结果本身还是一段有效的 Protobuf，可以直接把它切回主解码输入，继续往下看。

隐私与数据存储

ProtoDecodeX 是本地优先的：

  • 解码逻辑在浏览器内执行
  • 不依赖远程解码接口
  • 本地文件由浏览器读取，不需要上传到服务端

为了省得你每次重新贴数据，应用会把一部分状态写到 localStorage，包括：

  • 输入文本
  • 检测到的输入格式
  • parseDelimited 开关状态
  • 粘贴的 schema 内容
  • 当前选择的 message
  • 是否已有解码结果

如果你在共享设备或敏感场景中使用，建议在结束后清空状态，或使用隐私窗口。

当前边界与限制

ProtoDecodeX 更偏排查和分析，不是完整的 protoc 替代品。

  • 重点是 wire-format 解码，而不是完整的 .proto 编译与语义校验
  • Schema 解析器是轻量实现，只支持部分 .proto 语法
  • packed repeated 的识别基于启发式逻辑
  • 对损坏或不完整数据，可能只解析出部分结果，并留下 leftOver 字节
  • 当前没有内置文件导出或 URL 分享能力
  • 不提供后端存储、团队协作或远程会话能力

常用脚本

命令 说明
npm start 启动 Vite 开发服务器，端口为 3000
npm run build 生成生产构建，输出到 build/
npm test 使用 Vitest 运行测试
npm run test:watch 以 watch/UI 模式运行测试

仓库中还提供了辅助脚本：

  • scripts/local-build.sh
  • scripts/docker-build.sh

Docker 与部署

仓库里已经带了这些东西：

  • 多阶段 Dockerfile
  • docker-compose.yml
  • nginx.conf

拿来做容器化开发和部署都比较顺手。

开发容器

docker compose --profile dev up --build protobuf-decoder-dev

生产容器

docker compose --profile prod up --build protobuf-decoder-prod

技术栈

  • React 18
  • Vite 5
  • Semantic UI React
  • buffer
  • jsbi
  • Vitest
  • Testing Library
  • jsdom

贡献

欢迎提 Issue 和 Pull Request。这个项目里更有价值的改动，通常也都比较具体：

  • 提升解码正确性
  • 扩展 schema 解析覆盖范围
  • 增强类型感知展示能力
  • 优化大数据量场景下的交互体验
  • 补充真实案例和文档

提交 PR 前，建议先执行：

npm test
npm run build

许可证

MIT