wshawk - Open source toolkit for WebSocket security testing

项目说明

WSHawk - WebSocket Security Testing & Web Penetration Testing Toolkit

![Python 3.10–3.13]()
![PyPI ]()
![License: AGPL-3.0]()
![Playwright]()
![Desktop]()
![Quality Gates]()
![ Labs]()

WSHawk is an open-source toolkit for WebSocket security testing, web application penetration testing, and stateful attack . 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 e collection, and local labs for realtime application scenarios.

Research Paper

Regaan, R. (2026). _WSHawk: Stateful Security Assessment of WebSocket Applications through Adapti Mutation and Browser-Assisted ._

If WSHawk supports your research, please cite the preprint using either permanent record above.

> [!IMPORTANT]
> Full Documentation:
> - 🦅 WSHawk v4: Complete Guide — Architecture, workflows, configuration, , and integrations
> - 💻 WSHawk Desktop v4: Full Feature Guide — Desktop setup, projects, replay, interception, e, and web pentest workflows
> - ⚙️ Electron + Go Desktop Guide — Bridge-free architecture, installation, authorization matrices, findings, lab use, and nati

---

Why WSHawk — WebSocket and Web App Security Features

---

⚡ Performance & Adoption Benchmarks

---

Desktop Editions

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

| 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 o IPC | electron-go-v4.0.4 | Electron + Go guide |

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

---

WebSocket Scanner

WSHawk's core engine focuses on stateful, bidirectional WebSocket security testing. Unlike HTTP-only scanners, it keeps li open, captures handshake context, and e 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.

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 e collection |
| Command Injection | Timing attacks, command chaining (&&, \|, ;), out-of-band detection |
| XML External Entity (XXE) | Entity expansion, OAST callback detection, parameter entities |
| Ser Request Forgery (SSRF) | Internal IP probing, cloud metadata access, DNS rebinding |
| NoSQL Injection | MongoDB operator injection ($gt, $ne, $regex, $where) |
| Path Tra / LFI | File content markers (/etc/passwd, win.ini), encoding bypass |

Smart Payload Engine

The SPE system adapts attack payloads in real-time:

1. Context Generator — Detects message format (JSON, XML, plaintext) and generates payloads matching the target's protocol schema
2. Feedback Loop — Analyzes ser (errors, reflections, timing anomalies, WAF blocks) and adjusts strategy dynamically
3. Payload E — Genetic algorithm that crossovers and mutates successful payloads to disco 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 e trail.

Reconnaissance & Discovery Tools

| Tool | Description |
|---|---|
| Web Crawler | BFS spider with form extraction, API endpoint discovery, robots.txt and sitemap.xml parsing |
| Subdomain Finder | Passi via crt.sh (Certificate Transparency) and AlienVault OTX, plus active DNS brute-forcing with resolution |
| 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) |

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, recursi, custom wordlists (up to 50K entries), and WAF-e throttling |
| Automated Scanner | Multi-phase orchestrator: Crawl → Header Analysis → Directory Scan → Fuzz → Sensitive Data Scan, with auto-escalation (SQLi → LFI chaining) |
| Security Header Analyzer | E 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 |

Offensi Tools

| Tool | Description |
|---|---|
| WAF Detector | Passive and acti of 15+ WAFs (Cloudflare, AWS WAF, Akamai, Imper, 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 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 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 {{}} templating across requests |
| Proxy CA Generator | Root Certificate Authority (RSA 4096-bit, 10-year ) 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 executi, se charts, and remediation guidance. Also exports JSON, PDF, CS |

---

WSHawk Desktop — Nati Testing Application

A nati + Python desktop application with three operating modes:

| Mode | What You Get |
|---|---|
| Standard | WebSocket scanner dashboard, request forge, findings panel, traffic history, system log |
| Ad | + 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-Exclusi

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

Full Desktop Documentation →

---

WSHawk Electron + Go Desktop

The Electron + Go edition replaces the localhost bridge with a private,
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 a on the GitHub Releases page.

Install via pip

Install on macOS (Homebrew)

Method 1: Direct Cask URL

Method 2: Via Tap

Install on Kali Linux / Debian

If you use the published Debian/Kali package feed:

Install on Arch Linux

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

Install

See Docker Guide for detailed usage.

Build Desktop Application

---

Quick Start Guide

WebSocket Scan (CLI)

Interactive Mode

Ad Scan with All Features

Web Dashboard

Desktop Application

Python API

---

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 / CS | 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

| En | Description |
|---|---|
| WSHAWK_BRIDGE_PORT | Local bridge port (default: 8080) |
| WSHAWK_WEB_PASSWORD | Web dashboard authentication password |
| WSHAWK_API_KEY | Legacy web API key used by the older Flask dashboard path |

---

Defensi Module

Blue team module for your WebSocket security controls:

See Defensi Guide.

---

Security Warning — Use Official Sources

> Download WSHawk only from the official project sources or a package mirror you control.
>
> Preferred sources:
> - GitHub:
> - 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 e |
| 🦅 WSHawk v4 Complete Guide | Current v4 architecture, workflows, configuration, , and integrations |
| Getting Started | First scan, output format, common use cases |
| Ad Usage | Current Python API, scanner automation, and module-le |
| Checklist | Local lab workflow and expected outcomes |
| Defensi | Blue team security control testing |
| Details | Full co 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 | |

---

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

---

Latest Updates (v4.0.4)

*Built for security professionals, by Regaan.*

项目信息

开发语言：Python

Star 数：15

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕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.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。