WebSocket Scribe

A passive Burp Suite extension for capturing, inspecting, classifying, and exporting application-level WebSocket messages.

What it adds

• Captures new WebSocket connections created by any Burp tool after the extension is loaded.
• Retains text and binary message payloads without modifying messages in transit.
• Exports all or selected messages as:
  • JSONL: searchable records with lossless Base64 payloads.
  • CSV: spreadsheet-friendly metadata plus Base64 payloads.
  • ZIP evidence bundle: raw per-message .txt/.bin files, upgrade requests, connection metadata, decoded views, and a JSONL manifest.
• Analyzes each message for:
  • Shannon entropy and printable-byte ratio.
  • Valid UTF-8, JSON-like, XML-like, JWT/JWS-like, hex, and Base64 content.
  • Gzip and zlib/deflate wrappers, with a 5 MiB decompression safety cap.
  • Common file signatures.
  • Protobuf-like and MessagePack-like binary framing heuristics.
  • SHA-256 hashes, duplicate payloads, repeated sizes, and common per-direction prefixes.
• Uses a bounded background worker so analysis does not intentionally block or alter live WebSocket messages.

Important limitation

This extension does not decrypt arbitrary application-layer encryption. Entropy and pattern analysis can help distinguish text, encoding, compression, packed binary serialization, stable headers, repeated frames, and opaque/high-entropy bodies, but high entropy alone is not proof of encryption.

Actual decryption requires the relevant algorithm, key material, nonce/IV handling, and message format. For authorized testing, those details usually come from application code, client-side instrumentation, protocol documentation, or keys supplied by the application owner.

Build

Requirements: JDK 21 and internet access for the first dependency download.

Windows PowerShell

Set-ExecutionPolicy -Scope Process Bypass
.\build.ps1

Linux/macOS

chmod +x build.sh
./build.sh

The JAR is written to:

build/libs/websocket-scribe.jar

A Gradle build is also included:

gradle jar

Load in Burp

1. Open Extensions.
2. Select Installed and click Add.
3. Choose Java as the extension type.
4. Select build/libs/websocket-scribe.jar.
5. Open the WebSocket Scribe suite tab.
6. Establish or replay a new WebSocket connection; capture begins for new connections created after the extension is loaded.

Using the analysis

Select a row to view:

• Payload text: strict UTF-8 representation when valid.
• Decoded: recognized Base64/hex/JWT/gzip/zlib transformation.
• Hex and Base64: lossless inspection views.
• Analysis: message classification and connection-level pattern statistics.
• Upgrade request: the HTTP request that established the connection.

Useful interpretation signals:

• A stable prefix with a changing high-entropy tail may be a binary header plus compressed/encrypted body.
• Repeated frame sizes can reveal heartbeats, acknowledgements, or fixed message types.
• Identical SHA-256 hashes identify exact replays.
• Gzip/zlib, Base64, or hex detection often explains payloads that merely look encrypted.
• Protobuf/MessagePack labels are intentionally tentative and should be confirmed against the client or server implementation.

Data handling

Exports can contain authentication tokens, personal information, session data, and other secrets. Store and share them as assessment evidence with appropriate access controls.

Design notes

• Maximum retained table rows: 50,000. Oldest table rows are evicted after that limit.
• Background analysis queue: 5,000. If Burp produces data faster than analysis can consume it, the dropped counter increases rather than blocking traffic.
• Hex and Base64 UI views are capped at 1 MiB; exported payloads remain complete.
• Decoded/decompressed output is capped at 5 MiB to reduce decompression-bomb risk.

Validation

The source is compiled with Java 21. PayloadAnalyzerSmokeTest covers JSON, Base64, gzip, random high-entropy input, and low-entropy binary input. The included build scripts compile against PortSwigger's Montoya API 2026.7 dependency.