WSHawk: Stateful Security Assessment of WebSocket Applications through Adaptive Payload Mutation and Browser-Assisted Validation

WSHawk is an open-source (AGPL-3.0) toolkit designed for the stateful security assessment of WebSocket and realtime web applications. Unlike traditional stateless HTTP scanners, WSHawk models WebSocket connections as long-lived sessions, separating passive schema learning from active vulnerability probing.

This implementation study details the toolkit's core architecture and subsystems:

Adaptive Payload Subsystem: A dual-layer engine that combines strategy-scored payload mutation with genetic algorithms (Smart Payload Evolution) to iteratively adapt attack strings based on observed server responses.

Browser-Assisted Oracles: A Playwright-backed browser pool that transitions heuristic cross-site scripting (XSS) findings into confirmed, sandboxed execution evidence.

Protocol Inference: A protocol-graph subsystem that fingerprints underlying realtime framework families (e.g., GraphQL-WS, SignalR, Socket.IO, ActionCable) and automatically recommends context-aware attack playbooks. 

Unified Attack Framework: An asyncio-bound workflow engine that executes parallel HTTP and WebSocket attack services, including session replay, authorization diffing, race condition testing, and subscription abuse.

Evidence Integrity: A persistence layer that generates tamper-evident, Ed25519-signed, and hash-chained export bundles for verifiable vulnerability reporting.

The repository includes a Python-based scanning engine, a loopback daemon, an Electron desktop interface, and a suite of local validation labs for reproducible security testing.