| name | websocket-binary-reverse-engineering |
| description | Recover binary application protocols carried over WebSocket from PCAPs, browser traces, proxy exports, or runtime logs. Use when WebSocket opcode 2 frames are opaque, messages are fragmented, payloads use Protobuf, MessagePack, CBOR, compression, encryption, custom envelopes, heartbeats, sequence numbers, or undocumented request/response state transitions. |
WebSocket Binary Reverse Engineering
Workflow
- Preserve the HTTP upgrade request and response, negotiated subprotocol, extensions, cookies, and origin.
- Reassemble fragmented WebSocket messages. Do not treat individual TCP packets or continuation frames as application messages.
- Separate control frames from business messages: ping, pong, close, and protocol heartbeats are different layers.
- Record a timeline with direction, opcode, message length, first bytes, and the user action that caused it.
- Identify the outer envelope before the body codec: magic, version, flags, opcode, request ID, sequence, length, checksum, compression, and encryption markers.
- Test common body formats with evidence: JSON, Protobuf, MessagePack, CBOR, BSON, FlatBuffers, or a custom binary layout.
- Vary one application input at a time and compare messages across multiple sessions.
- Infer request/response pairs, unsolicited pushes, acknowledgements, retries, heartbeats, and reconnect/resume behavior.
- Validate by writing a passive decoder first. Replay or mutation requires explicit authorization and a controlled environment.
Read references/message-analysis.md for framing and state-machine checks.
Evidence Standard
Produce the upgrade metadata, reconstructed message set, codec evidence, field table, state diagram, passive decoder/dissector, and redacted examples. Mark field semantics as observed, code-backed, controlled-test-backed, or speculative.
Route Protobuf bodies to protobuf-grpc-reverse-engineering and TLS visibility problems to tls-plaintext-acquisition.
