wshawk
Advanced tools
Professional WebSocket security scanner with real vulnerability verification, session hijacking tests, and CVSS scoring
-blueviolet?style=flat&logo=github){kind=icon}
WSHawk is an enterprise-grade, open-source WebSocket security scanner built for professional penetration testers and red teams. It performs automated vulnerability assessment over WebSocket connections using an adaptive Smart Payload Evolution (SPE) engine with real-time feedback loops and genetic payload mutation. Designed for high-performance environments at the ROT Independent Security Research Lab.
Starting with v3.0.6, we've transitioned to the AGPL-3.0 license to better protect the project while keeping it open for the community. This release includes the Headless DOM Invader powered by Playwright for real browser-based XSS verification and complex SSO auth flow recording/replay. Also includes a Context-Aware Heuristic Engine and WSHawk Browser Companion for seamless handshake interception.
[!IMPORTANT] Full Documentation:
- 🦅 WSHawk V3: Complete Enterprise Guide — Architecture, scanning engine, configuration
- 💻 WSHawk Desktop: Full Reference Manual — All 22 tools, API reference, build guide
WSHawk's core engine performs enterprise-grade, stateful, bidirectional WebSocket security testing. Unlike traditional DAST scanners that only handle HTTP request-response, WSHawk maintains persistent WebSocket connections and analyzes asynchronous responses that may arrive long after the attack payload is sent — critical for real-world financial, healthcare, and SaaS applications.
| 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 verification |
| 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 |
The SPE system adapts attack payloads in real-time:
The WSHawk Desktop application now ships with 22 HTTP security tools organized into six phases. We're building this out alongside the WebSocket scanner to give pentesters a single interface for both WebSocket and HTTP assessments.
| 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) |
| 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 |
| 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 |
| 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 signing |
| 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 |
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 |
~/.wshawk/sessions/Ctrl+K command palette for instant navigation to any toolBuilds for: Linux (.pacman, .AppImage, .deb) · Windows (.exe NSIS installer) · macOS (.dmg)
pip install wshawk
# Optional: Browser-based XSS verification
playwright install chromium
Method 1: One-liner (Recommended)
brew install --cask https://raw.githubusercontent.com/regaan/homebrew-tap/main/Casks/wshawk.rb
Method 2: Stay Updated (Via Tap)
# Register the WSHawk tap
brew tap regaan/tap
# Install the cask
brew install --cask wshawk
WSHawk is available via the official Regaan APT repository.
# 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
WSHawk is available in the Arch User Repository (AUR).
# Install WSHawk via yay
yay -S wshawk
docker pull rothackers/wshawk:latest
docker run --rm rothackers/wshawk ws://target.com
See Docker Guide for detailed usage.
git clone https://github.com/regaan/wshawk
cd wshawk
# Build Python sidecar binary
pip install -e . && pip install pyinstaller
pyinstaller wshawk-bridge.spec
# Build desktop installer
mkdir -p desktop/bin && cp dist/wshawk-bridge desktop/bin/
cd desktop && npm install && npm run dist
wshawk ws://target.com
wshawk-interactive
wshawk-advanced ws://target.com --smart-payloads --playwright --full
export WSHAWK_WEB_PASSWORD='your-password'
wshawk --web --port 5000
cd desktop && npm start
import asyncio
from wshawk.scanner_v2 import WSHawkV2
scanner = WSHawkV2("ws://target.com")
scanner.use_headless_browser = True
scanner.use_oast = True
asyncio.run(scanner.run_heuristic_scan())
| 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 + Sessions |
| Exploit PoC Export | — | — | ✅ |
| Report Formats | HTML | HTML | HTML / JSON / PDF |
| Best For | CI/CD pipelines | Teams, SOC | Manual pentesting, red teams |
python3 -m wshawk.config --generate
integrations:
jira:
api_token: "env:JIRA_TOKEN"
project: "SEC"
defectdojo:
api_key: "env:DD_API_KEY"
url: "https://defectdojo.your-org.com"
| Environment Variable | Description |
|---|---|
WSHAWK_BRIDGE_PORT | Backend server port (default: 8080) |
WSHAWK_WEB_PASSWORD | Web dashboard authentication password |
WSHAWK_API_KEY | API key for programmatic access |
Blue team module for validating your WebSocket security controls:
wshawk-defensive ws://your-server.com
See Defensive Validation Guide.
Repackaged versions of WSHawk containing malware have been found on third-party download sites.
Download only from official sources:
- Website:
https://wshawk.rothackers.com- GitHub:
https://github.com/regaan/wshawk- PyPI:
pip install wshawk- Docker:
docker pull rothackers/wshawk
| Guide | Description |
|---|---|
| V3.0.4 Release Guide | AGPL-3.0 Transition, DOM Invader, Auth Flow Recorder — full technical reference |
| 🦅 Complete Enterprise Guide | Architecture, scanning engine, configuration, integrations |
| 💻 Desktop Reference Manual | All 22 tools, API reference, build instructions |
| Getting Started | First scan, output format, common use cases |
| 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 |
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. Repackaged versions found on third-party download sites are not associated with this project.
AGPL-3.0 License — see LICENSE
Regaan | Lead Researcher at ROT Independent Security Research Lab
Contributions welcome — see CONTRIBUTING.md
| Channel | Link |
|---|---|
| Issues | GitHub Issues |
| Documentation | docs/ |
| support@rothackers.com |
WSHawk v3.0.6 — Professional WebSocket Security Scanner & Interception Suite
alert(), eval(), DOM mutations, and injected script tags.Built for security professionals, by Regaan.
FAQs
Professional WebSocket security scanner with real vulnerability verification, session hijacking tests, and CVSS scoring
We found that wshawk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Socket detected malicious node-ipc versions with obfuscated stealer/backdoor behavior in a developing npm supply chain attack.
Security News
TeamPCP and BreachForums are promoting a Shai-Hulud supply chain attack contest with a $1,000 prize for the biggest package compromise.
Security News
Packagist urges PHP projects to update Composer after a GitHub token format change exposed some GitHub Actions tokens in CI logs.