WebSocket Engine

Article 3: Real-time WebSocket Interceptor (MitM) Design

Source File: wshawk/wshawk-bridge.spec (Desktop Build)

3.1 Protocol Opacity and the Need for Interception

Offensive security engineers rely heavily on interception proxies (like Burp Suite or OWASP ZAP) to pause, edit, and forward traffic. While HTTP interception is standard, manipulating WebSocket frames in real-time presents significant challenges due to binary masking and long-lived connection persistence.

Automated fuzzing is excellent for finding injection flaws (SQLi, XSS), but it is generally terrible at finding complex business logic flaws. If an application allows a user to submit a bid via WebSocket {"action": "bid", "amount": 100}, an automated fuzzer will inject ' OR 1=1, but it won’t know to inject -5000 to test for integer underflow logic flaws. A human engineer needs to manually edit that frame.

3.2 The MitM Architecture

WSHawk Desktop integrates a custom Man-in-the-Middle (MitM) interceptor built specifically for full-duplex streams.

3.2.1 TLS Termination: The Python bridge generates a dynamic Root Certificate Authority (CA) and signs per-host certificates on the fly. This terminates the wss:// (WebSocket Secure) TLS connection locally, allowing WSHawk to read the plaintext traffic.

3.2.2 Unmasking Frames (RFC 6455): RFC 6455 requires all client-to-server WebSocket frames to be masked via a 32-bit masking key to prevent cache poisoning attacks against intermediary proxies. The MitM proxy intercepts the raw TCP stream, extracts the 32-bit key, XOR-unmasks the payload, and exposes the plaintext text or binary JSON to the user interface.

3.2.3 Frame-by-Frame Control: The interceptor pauses the event loop, displaying the unmasked frame in the GUI. The engineer can modify parameters and click “Forward”. The proxy re-masks the modified frame, calculates the new payload length, and injects it into the upstream TCP socket.