WSHawk - WebSocket Security Testing & Web Penetration Testing Toolkit

WSHawk is an open-source toolkit for WebSocket security testing, web application penetration testing, and stateful attack validation. It combines a CLI scanner, web dashboard, Electron desktop app, browser companion, and project-backed workflows for authorized security assessments.

As of v4.0.4, WSHawk ships under the AGPL-3.0 license and includes two separately packaged desktop editions, project-backed HTTP and WebSocket workflows, identity-aware replay and authorization matrices, race testing, Playwright-assisted browser evidence collection, and local validation labs for realtime application scenarios.

Research Paper

Regaan, R. (2026). WSHawk: Stateful Security Assessment of WebSocket Applications through Adaptive Payload Mutation and Browser-Assisted Validation.

• Zenodo preprint: 10.5281/zenodo.21290858
• Figshare preprint: 10.6084/m9.figshare.32955467.v1

[!IMPORTANT]

Full Documentation:

- 🦅 WSHawk v4: Complete Guide — Architecture, workflows, configuration, validation, and integrations

- 💻 WSHawk Desktop v4: Full Feature Guide — Desktop setup, projects, replay, interception, evidence, and web pentest workflows

- ⚙️ Electron + Go Desktop Guide — Bridge-free architecture, installation, authorization matrices, findings, lab use, and native packages

Why WSHawk — WebSocket and Web App Security Features

• Stateful WebSocket testing — persistent connections, asynchronous response handling, replay, and protocol-aware attack execution
• Smart Payload Evolution — context-aware payload generation and mutation based on target behavior, timing, and blocking signals
• Browser-assisted XSS evidence collection via Playwright for reflected and DOM-style payload testing
• Blind vulnerability detection via OAST callbacks for XXE, SSRF, and related out-of-band flows
• Full-duplex WebSocket interceptor — local proxy with frame-by-frame forward, drop, and edit controls
• Identity-aware replay and diffing for HTTP and WebSocket traffic across captured sessions and stored identities
• Desktop web pentest workspace with crawler, fuzzer, directory scan, header analysis, CORS, redirect, SSRF, TLS, and prototype-pollution tooling
• Project-backed evidence — local identities, notes, traffic, findings, and export bundles tied to a reusable project record
• CVSS v3.1 scoring for scanner findings and generated reports
• Integrations — Jira, DefectDojo, and webhook notifications
• Reporting and exports — HTML, JSON, Markdown, PDF, CSV, and SARIF outputs across the platform
• Two cross-platform desktop editions — the established Electron + Python application and the separate Electron + Go application for Linux, Windows, and macOS

⚡ Performance & Adoption Benchmarks

• Current release: v4.0.4
• Interfaces: CLI, web dashboard, desktop app, and browser companion
• Validation coverage: fullstackrealtimesaas, socketiosaas, and graphqlsubscriptionslab
• Primary focus: authenticated, stateful, and asynchronous web application testing rather than passive HTTP-only scanning

Desktop Editions

WSHawk 4.0.4 publishes two independent desktop releases from the same source revision:

| Edition | Backend | GitHub release tag | Documentation | | --- | --- | --- | --- | | WSHawk | Electron with the Python sidecar | v4.0.4 | Classic desktop guide | | WSHawk Electron + Go | Electron with a private Go worker over stdio IPC | electron-go-v4.0.4 | Electron + Go guide |

The applications have separate IDs and data directories. Installing the Electron + Go edition does not replace the classic desktop.

WebSocket Vulnerability Scanner

WSHawk's core engine focuses on stateful, bidirectional WebSocket security testing. Unlike HTTP-only scanners, it keeps live connections open, captures handshake context, and evaluates asynchronous behavior that may appear well after a payload is sent. This fits chat systems, collaboration platforms, internal dashboards, trading interfaces, and other realtime SaaS targets.

Vulnerability Detection

| Category | Technique | |---|---| | SQL Injection | Error-based, time-based (SLEEP/WAITFOR), boolean-based blind | | Cross-Site Scripting (XSS) | Reflection analysis, context detection, DOM sink identification, browser evidence collection | | Command Injection | Timing attacks, command chaining (&&, \|, ;), out-of-band detection | | XML External Entity (XXE) | Entity expansion, OAST callback detection, parameter entities | | Server-Side Request Forgery (SSRF) | Internal IP probing, cloud metadata access, DNS rebinding | | NoSQL Injection | MongoDB operator injection ($gt, $ne, $regex, $where) | | Path Traversal / LFI | File content markers (/etc/passwd, win.ini), encoding bypass |

Smart Payload Engine

The SPE system adapts attack payloads in real-time:

• Context Generator — Detects message format (JSON, XML, plaintext) and generates payloads matching the target's protocol schema
• Feedback Loop — Analyzes server signals (errors, reflections, timing anomalies, WAF blocks) and adjusts strategy dynamically
• Payload Evolver — Genetic algorithm that crossovers and mutates successful payloads to discover novel WAF bypasses

Web Application Penetration Testing Toolkit (Enhanced in v4.0.0)

The WSHawk desktop workspace also includes HTTP security tools organized into six phases so WebSocket and web application assessments can share the same project, identities, notes, and evidence trail.

Reconnaissance & Discovery Tools

| Tool | Description | |---|---| | Web Crawler | BFS spider with form extraction, API endpoint discovery, robots.txt and sitemap.xml parsing | | Subdomain Finder | Passive enumeration via crt.sh (Certificate Transparency) and AlienVault OTX, plus active DNS brute-forcing with resolution validation | | Technology Fingerprinter | Identifies 35+ technologies (Nginx, Apache, WordPress, React, Cloudflare, etc.) from headers, cookies, and page content | | DNS / WHOIS Lookup | Full record enumeration (A, AAAA, MX, NS, TXT, CNAME, SOA, SRV, CAA) with WHOIS registration data | | TCP Port Scanner | Async connect scanner with service identification, banner grabbing, and preset port lists (top-100, web, database, full) |

Vulnerability Scanning Tools

| Tool | Description | |---|---| | HTTP Fuzzer | Parameter fuzzing with §FUZZ§ markers, built-in wordlists, encoding options (URL/Base64/Hex), and heuristic vuln detection | | Directory Scanner | Path brute-forcing with extension permutation, recursive scanning, custom wordlists (up to 50K entries), and WAF-evasion throttling | | Automated Vulnerability Scanner | Multi-phase orchestrator: Crawl → Header Analysis → Directory Scan → Fuzz → Sensitive Data Scan, with auto-escalation (SQLi → LFI chaining) | | Security Header Analyzer | Evaluates HSTS, CSP, X-Frame-Options, X-Content-Type-Options, CORS, Server, and X-Powered-By with risk ratings | | Sensitive Data Finder | Regex detection for 30+ secret types — AWS keys, Google API keys, JWTs, GitHub tokens, database connection strings, internal IPs |

Offensive Security Tools

| Tool | Description | |---|---| | WAF Detector | Passive and active fingerprinting of 15+ WAFs (Cloudflare, AWS WAF, Akamai, Imperva, Sucuri, ModSecurity, F5 BIG-IP) | | CORS Misconfiguration Tester | Probes 6 attack patterns — wildcard origin, null origin, subdomain suffix attack, domain prefix injection, HTTP downgrade | | SSL/TLS Analyzer | Certificate inspection, protocol version testing (TLS 1.0–1.3), weak cipher detection, expiry and self-signed checks | | SSRF Prober | 40+ payloads targeting AWS/GCP/Azure metadata endpoints, internal services, DNS rebinding, and URL parser confusion | | Open Redirect Scanner | 25+ bypass techniques with auto-detection of 20+ common redirect parameter names | | Prototype Pollution Tester | proto and constructor.prototype injection via query params and JSON bodies with escalation detection |

Exploit Generation & Attack Chaining

| Tool | Description | |---|---| | CSRF Exploit Forge | Generates proof-of-concept HTML pages — auto-submitting forms, Fetch API XHR, multipart — with CSRF token detection | | Attack Chainer | Multi-step HTTP attack sequencing with regex-based value extraction and {{variable}} templating across requests | | Proxy CA Generator | Root Certificate Authority (RSA 4096-bit, 10-year validity) for HTTPS interception with per-host certificate issuance | | HTTP Request Forge | Manual HTTP request builder (GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS) routed through Python to bypass browser CORS | | Report Generator | Professional HTML reports with executive summary, severity charts, and remediation guidance. Also exports JSON, PDF, CSV, SARIF |

WSHawk Desktop — Native Security Testing Application

A native Electron + Python desktop application with three operating modes:

| Mode | What You Get | |---|---| | Standard | WebSocket scanner dashboard, request forge, findings panel, traffic history, system log | | Advanced | + Payload blaster, real-time WebSocket interceptor, endpoint map, auth builder, mutation lab, scheduler, codec, comparer, notes | | Web Pentest | + All 22 HTTP security tools with real-time streaming results |

Desktop-Exclusive Features

• Real-Time WebSocket Interceptor — Full-duplex MitM proxy with frame-by-frame forward, drop, and edit controls
• Payload Blaster — High-speed WebSocket fuzzer with 11 payload categories and Smart Payload Evolution toggle
• WebSocket Endpoint Map — Automated discovery via HTTP Upgrade probing, HTML crawling, and JavaScript source analysis
• Auth Builder — Multi-step authentication sequence with regex token extraction and variable substitution
• Exploit PoC Generator — Standalone Python proof-of-concept export for selected findings
• Project Files — Save and reopen sanitized local .wshawk project files
• Project Evidence — Local project database for identities, traffic, findings, notes, and export bundles
• Tamper-Evident Exports — Provenance and integrity metadata for exported project bundles
• HawkSearch — Ctrl+K command palette for instant navigation to any tool

Full Desktop Documentation →

WSHawk Electron + Go Desktop

The Electron + Go edition replaces the localhost bridge with a private, versioned stdio JSON-RPC worker. It includes encrypted project storage, componentized HTTP and WebSocket workspaces, Playwright auth recording, multi-identity authorization matrices, safe write rollback, a dedicated Findings workspace, reports, and the repository-owned security lab.

Builds for: Linux (AppImage, .deb, .tar.gz) · Windows (.exe NSIS installer) · macOS (.dmg, .zip)

Electron + Go Desktop Documentation →

Installation

Prebuilt Windows, Linux, and macOS packages are available on the GitHub Releases page.

Install via pip

pip install wshawk
Optional: Browser-based XSS verification
pip install "wshawk[browser]"
playwright install chromium
Optional: Scientific/binary analysis helpers
pip install "wshawk[analysis]"

Install on macOS (Homebrew)

Method 1: Direct Cask URL

brew install --cask https://raw.githubusercontent.com/regaan/homebrew-tap/main/Casks/wshawk.rb

Method 2: Via Tap

# Register the WSHawk tap brew tap regaan/tap

Install the cask
brew install --cask wshawk

Install on Kali Linux / Debian

If you use the published Debian/Kali package feed:

# Add the WSHawk GPG key
curl -sSL https://regaan.github.io/wshawk-repo/wshawk_repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/wshawk-archive-keyring.gpg
Add the WSHawk APT repository
echo "deb [signed-by=/usr/share/keyrings/wshawk-archive-keyring.gpg] https://regaan.github.io/wshawk-repo stable main" | sudo tee /etc/apt/sources.list.d/wshawk.list
Install WSHawk
sudo apt update && sudo apt install wshawk

Install on Arch Linux

If you use the published Arch User Repository (AUR) package:

# Install WSHawk via yay
yay -S wshawk

Install via Docker

docker pull rothackers/wshawk:latest
docker run --rm rothackers/wshawk ws://target.com

See Docker Guide for detailed usage.

Build Desktop Application

git clone https://github.com/regaan/wshawk
cd wshawk
Build Python sidecar binary
python -m pip install -e ".[browser]" pyinstaller
pyinstaller wshawk-bridge.spec
Build desktop installer
mkdir -p desktop/bin && cp dist/wshawk-bridge desktop/bin/
cd desktop && npm ci && npm run dist

Quick Start Guide

WebSocket Scan (CLI)

wshawk ws://target.com

Interactive Mode

wshawk-interactive

Advanced Scan with All Features

wshawk-advanced ws://target.com --smart-payloads --playwright --full

Web Dashboard

export WSHAWKWEBPASSWORD='your-password'
wshawk --web --port 5000

Desktop Application

cd desktop && npm start

Python API

import asyncio
from wshawk.scanner_v2 import WSHawkV2
scanner = WSHawkV2("ws://target.com") scanner.useheadlessbrowser = True scanner.use_oast = True asyncio.run(scanner.runheuristicscan())

Interface Comparison

| Capability | CLI | Web Dashboard | Desktop App | |---|---|---|---| | WebSocket Scanner | ✅ | ✅ | ✅ | | Web Pentest Toolkit (22 tools) | — | — | ✅ | | WebSocket Interceptor (MitM) | — | — | ✅ | | Payload Blaster / Fuzzer | — | — | ✅ | | Endpoint Discovery Map | — | — | ✅ | | Scan Persistence | — | SQLite | SQLite + Projects | | Exploit PoC Export | — | — | ✅ | | Report Formats | HTML / JSON / CSV / SARIF | HTML / PDF | HTML / JSON / Markdown | | Best For | Automation, CI/CD, scripted runs | Shared browser access and review | Manual pentesting, interception, replay, and red-team workflows |

Configuration

wshawk.yaml

python3 -m wshawk.config --generate

integrations:
  jira:
    apitoken: "env:JIRATOKEN"
    project: "SEC"
  defectdojo:
    apikey: "env:DDAPI_KEY"
    url: "https://defectdojo.your-org.com"

| Environment Variable | Description | |---|---| | WSHAWKBRIDGEPORT | Local bridge port (default: 8080) | | WSHAWKWEBPASSWORD | Web dashboard authentication password | | WSHAWKAPIKEY | Legacy web API key used by the older Flask dashboard path |

Defensive Validation Module

Blue team module for validating your WebSocket security controls:

wshawk-defensive ws://your-server.com

• DNS Exfiltration Prevention — Validates egress filtering effectiveness
• Bot Detection — Tests anti-bot measures against headless browser evasion
• CSWSH Protection — Origin header validation with 216+ malicious origins
• WSS Protocol Security — TLS versions, cipher suites, certificate chain, forward secrecy

Security Warning — Use Official Sources

Download WSHawk only from the official project sources or a package mirror you control.

Preferred sources:

- GitHub: https://github.com/regaan/wshawk

- PyPI: pip install wshawk

- Docker: docker pull rothackers/wshawk

Documentation

| Guide | Description | |---|---| | Electron + Go Desktop Guide | Bridge-free desktop installation, workspaces, authorization testing, local lab, and packages | | 💻 Desktop v4 Full Feature Guide | Current desktop guide for projects, replay, interception, web pentest workflows, and evidence | | 🦅 WSHawk v4 Complete Guide | Current v4 architecture, workflows, configuration, validation, and integrations | | Getting Started | First scan, output format, common use cases | | Advanced Usage | Current Python API, scanner automation, and module-level examples | | Validation Checklist | Local validation lab workflow and expected outcomes | | Defensive Validation | Blue team security control testing | | Vulnerability Details | Full vulnerability coverage reference | | Session Security Tests | WebSocket session hijacking tests | | Docker Deployment | Container deployment guide |

Responsible Use

WSHawk is designed for authorized penetration testing, bug bounty programs, security research, and education. Always obtain explicit permission before scanning any target.

The author is not responsible for misuse of this tool. If you use packaged builds, prefer the official project sources or mirrors you control.

License

AGPL-3.0 License — see LICENSE

Author

Regaan | Lead Researcher at ROT Independent Security Research Lab

Contributing

Contributions welcome — see CONTRIBUTING.md

Support

| Channel | Link | |---|---| | Issues | GitHub Issues | | Documentation | docs/ | | Email | support@rothackers.com |

WSHawk v4.0.4 — WebSocket Security Testing, Interception, and Web Pentest Toolkit

Latest Updates (v4.0.4)

• Electron + Go edition: separate Windows, Linux, and macOS packages with a private Go worker and no localhost bridge.
• Authorization workspace: anonymous and multi-identity matrices, object discovery, explicit policies, GraphQL and WebSocket authorization, semantic response analysis, and multi-object confirmation.
• Safe write validation: dry-run, confirmation, bounded execution, before/after evidence, cleanup, and verified rollback.
• Protected evidence: AES-256-GCM project storage, OS-protected key handoff, redaction, hash-only retention, reproducible requests, and controlled reveal/copy.
• Findings lifecycle: duplicate consolidation, severity and confidence editing, selected export, and five automated retest outcomes.
• Owned lab: 34 secure/vulnerable authorization scenarios covering multi-tenancy, UUIDs, nested objects, query and JSON identifiers, GraphQL, WebSocket rooms/subscriptions, mass assignment, and state-changing IDOR.
• Reliable Linux CI startup: Electron test harnesses use an ephemeral encryption key when a headless runner has no desktop keyring and preserve production fail-closed behavior.
• Dual GitHub releases: one v4.0.4 push publishes the classic WSHawk release and the separate electron-go-v4.0.4 release.