REGAAN RFrequently Asked Questions (FAQ)
This page answers 20 technical questions about the architecture, implementation, and security mechanics of the WSHawk toolkit.
Q1: Why does WSHawk use asyncio instead of standard threading for WebSocket fuzzing?
Source File: wshawk/scanner_v2.py
WebSockets are full-duplex protocols where servers can push messages at any time. Standard synchronous threading (like requests in HTTP) blocks execution while waiting for a response. By using Python’s asyncio and websockets libraries, WSHawk decouples the send and receive tasks. This allows the scanner to inject thousands of payloads without blocking, while a separate background coroutine asynchronously evaluates incoming frames for delayed vulnerability markers (like SQL errors).
Q2: How does the Smart Payload Evolver (SPE) bypass Web Application Firewalls?
Source File: wshawk/smart_payloads/payload_evolver.py
The PayloadEvolver treats fuzzing as a genetic algorithm. Instead of looping through a static wordlist that triggers rate-limiters, it starts with a seed population of payloads. If a payload bypasses a WAF but fails to exploit the target, it receives a fitness score. The engine mutates these successful payloads (via null_padding, char_swap, or encoding_wrap) and combines them using crossover strategies to breed novel strings that evade static regex signatures.
Q3: How does WSHawk eliminate false positives in XSS detection?
Source File: wshawk/headless_xss_verifier.py
WSHawk passes suspected XSS reflections into a sandboxed Chromium instance managed by Playwright. The HeadlessBrowserXSSVerifier overrides the native window.alert to act as a silent beacon (window.xssExecuted = true). If the injected payload successfully executes in the DOM, the beacon fires, confirming the vulnerability. If the frontend framework safely encodes the output, the payload remains inert, and the finding is discarded.
Q4: What is Cross-Site WebSocket Hijacking (CSWSH) and how is it detected?
Source File: wshawk/wss_security_validator.py
CSWSH occurs when a WebSocket server relies solely on session cookies for authentication and fails to validate the Origin header during the HTTP Upgrade handshake. WSHawk tests for this by initiating the handshake with valid cookies but injecting 216+ spoofed origin headers (e.g., https://evil.com, null). If the server returns a 101 Switching Protocols instead of a 403 Forbidden, it is vulnerable to hijacking.
Q5: How does WSHawk track blind vulnerabilities like SSRF?
Source File: wshawk/oast_provider.py
Blind vulnerabilities do not return output in the WebSocket frame. WSHawk detects them using Out-Of-Band Security Testing (OAST). It injects unique, correlation-tagged domains (e.g., http://wshawk-a1b2.oast-server.net) into payloads. It then asynchronously polls the OAST provider’s API. If a DNS resolution or HTTP GET request hits the unique subdomain, WSHawk links the out-of-band interaction to the specific payload that caused it.
Q6: Can WSHawk intercept and edit raw WebSocket frames manually?
Source File: wshawk/wshawk-bridge.spec
Yes. The Electron desktop application integrates a local Man-in-the-Middle (MitM) proxy. It terminates the TLS connection, XOR-unmasks the client frames, and exposes them in the GUI. Operators can configure rules to drop specific frames or pause execution to manually edit JSON/text payloads before forwarding them to the server, enabling deep business logic testing.
Q7: How does WSHawk test for authorization bypasses (IDOR/BOLA)?
Source File: wshawk/session_hijacking_tester.py
WSHawk features an Identity-Aware Replay mechanism. The tester records a sequence of WebSocket frames using Identity A (e.g., a low-privileged user). The engine then replays the exact same frame sequence, but dynamically swaps the HTTP Upgrade headers (like Authorization: Bearer <token>) with the credentials of Identity B. If the server processes privileged commands for the low-privileged identity, it flags a broken access control vulnerability.
Q8: How does the framework persist data during long scans without crashing?
Source File: wshawk/db_manager.py
Storing millions of fuzzed frames in RAM causes Out-Of-Memory (OOM) crashes. WSHawk writes all HTTP traffic, WebSocket frames, and identified vulnerabilities asynchronously to a local SQLite database operating in Write-Ahead Logging (WAL) mode. This project-backed architecture allows operators to pause, resume, and export scan data across multiple days.
Q9: Does WSHawk support testing WebSockets behind strict rate limiters?
Source File: wshawk/web_pentest/dir_scanner.py
Yes. WSHawk implements WAF-evasion throttling. If the engine detects connection drops or 429 Too Many Requests responses, it automatically applies randomized jitter delays between requests and rotates standard User-Agent strings. This slows down the scan but prevents the IP address from being blacklisted by Fail2Ban or Cloudflare.
Q10: How are findings exported for CI/CD pipelines?
Source File: wshawk/report_exporter.py
WSHawk exports machine-readable reports in the Static Analysis Results Format (SARIF 2.1.0). This JSON-based schema maps WSHawk vulnerabilities to standardized rule IDs and embeds the payload evidence. SARIF files can be ingested directly by GitHub Code Scanning or GitLab CI to automatically block builds containing high-severity WebSocket flaws.
Q11: What encoding mechanisms does the payload evolver support?
Source File: wshawk/smart_payloads/payload_evolver.py
The encode_char and encoding_wrap mutation strategies can obfuscate payloads using Base64, Hexadecimal, ROT13, string reversal, Leetspeak, and Unicode escape characters. This is particularly effective against naive input filters that check for plaintext keywords like SELECT or javascript:.
Q12: How does WSHawk parse binary WebSocket frames?
The Python websockets library handles frame decoding. If a frame specifies the OPCODE_BINARY flag, WSHawk attempts to deserialize it (e.g., using MessagePack or Protobuf if a schema is mapped). If the format is unknown, it logs the raw hex dump. Mutations on unknown binary blobs are limited to byte-flipping to prevent protocol corruption.
Q13: Does WSHawk support fuzzing GraphQL subscriptions over WebSockets?
Yes. WSHawk’s content generators specifically recognize GraphQL subscription envelopes (e.g., {"type": "start", "payload": {"query": "..."}}). The fuzzer targets the variables and query strings within the JSON envelope rather than corrupting the framing structure.
Q14: How does the scanner identify database injection errors?
Source File: wshawk/scanner_v2.py
The receive task continuously runs incoming frames against a compiled list of error heuristics. It checks for standard database engine complaints, such as MySQL (SQL syntax), Oracle (ORA-[0-9]{4}), PostgreSQL (PostgreSQL query failed), and MongoDB operator errors.
Q15: What is the crossover mechanism in the payload evolver?
Source File: wshawk/smart_payloads/payload_evolver.py
When two payloads perform well, the engine breeds them using crossover. The interleave strategy slices both parents into chunks and alternates them. The split strategy takes the first half of one and the second half of the other. The wrap strategy nests one payload entirely inside the other.
Q16: Can WSHawk detect Prototype Pollution over WebSockets?
Relevant Directory: wshawk/web_pentest/
Yes. The included proto_polluter.py tool targets JSON bodies and query parameters, injecting __proto__ and constructor.prototype payloads. It evaluates the response objects to see if the injected properties successfully polluted the global object scope.
Q17: Why use an Electron and Python hybrid architecture for the desktop app?
Python excels at asynchronous network fuzzing, cryptography, and logic engines, but lacks robust, cross-platform UI frameworks. Electron provides a high-performance web-based frontend (HTML/CSS/JS). WSHawk combines them by running the Python daemon in the background and communicating with the Electron GUI via local REST APIs and WebSockets.
Q18: What is required to run the local Dockerized version of WSHawk?
The official Docker image (rothackers/wshawk) packages all Python dependencies. Because the headless Playwright verifier requires Chromium binaries, the full Docker image is slightly larger but provides a zero-setup environment. Run it using docker run --rm rothackers/wshawk ws://target.com.
Q19: How are vulnerabilities scored?
Source File: wshawk/cvss_calculator.py
WSHawk integrates a CVSS v3.1 calculator. It maps discovered vulnerabilities to base vectors (e.g., SSRF mapping to High/Critical impacts on Confidentiality and Integrity) and generates standardized severity scores for the export reports.
Q20: Can I use WSHawk against arbitrary targets?
No. WSHawk generates aggressive fuzzing traffic and exploit payloads that can disrupt services or alter databases. It must only be used against applications and infrastructure where the operator has explicit, documented authorization to perform penetration testing.
Reproducibility
The commands, configuration, and methodology described above are intended to allow independent verification. Target application configurations (like WAF rules and Rate Limits) may cause varying results when reproducing tests.