WSHawk v3.0.0 - Professional WebSocket Security Scanner

SECURITY WARNING: FAKE VERSIONS CIRCULATING

PLEASE READ CAREFULLY:
Fake versions of WSHawk are being distributed on third-party download sites and linked in social media posts (e.g., LinkedIn). These versions may contain MALWARE.

OFFICIAL SOURCES ONLY:

• Official Website: https://wshawk.rothackers.com
• GitHub: https://github.com/noobforanonymous/wshawk
• PyPI: pip install wshawk
• Docker: docker pull rothackers/wshawk or ghcr.io/noobforanonymous/wshawk

DO NOT DOWNLOAD from any other website. If you see "WSHawk" on a "software download" site, it is likely fake/malicious.

WSHawk v3.0.0 is a production-grade WebSocket security scanner with advanced features including real vulnerability verification, dynamic mutation, and comprehensive session security testing. It also includes a Persistent Web GUI for dashboarding and history.

Why WSHawk?

WSHawk is the only open-source WebSocket scanner that provides:

• Smart Payload Evolution - Adaptive feedback-driven mutation engine
• Hierarchical Configuration - wshawk.yaml with env var secret resolution
• Persistent Web GUI - Dashboard with SQLite history and password auth
• Enterprise Integrations - Auto-push to Jira, DefectDojo, and Webhooks
• Real browser XSS verification (Playwright) - Not just pattern matching
• Blind vulnerability detection via OAST - Finds XXE, SSRF that others miss
• Session hijacking analysis - 6 advanced session security tests
• WAF-aware payload mutation - Dynamic evasion techniques
• CVSS-based professional reporting - Industry-standard risk assessment

Features

• 22,000+ Attack Payloads - Comprehensive vulnerability coverage
• Real Vulnerability Verification - Confirms exploitability, not just reflection
• Playwright XSS Verification - Actual browser-based script execution testing
• OAST Integration - Detects blind vulnerabilities (XXE, SSRF)
• Session Hijacking Tests - Token reuse, impersonation, privilege escalation
• Advanced Mutation Engine - WAF bypass with 8+ evasion strategies
• CVSS v3.1 Scoring - Automatic vulnerability risk assessment
• Professional HTML Reports - Screenshots, replay sequences, traffic logs
• Adaptive Rate Limiting - Server-friendly scanning

Vulnerability Detection

SQL Injection • XSS • Command Injection • XXE • SSRF • NoSQL Injection • Path Traversal • LDAP Injection • SSTI • Open Redirect • Session Security Issues

Installation

Option 1: pip (Recommended)

pip install wshawk

# Optional: For browser-based XSS verification
playwright install chromium

Option 2: Docker

# From Docker Hub
docker pull rothackers/wshawk:latest

# Or from GitHub Container Registry
docker pull ghcr.io/noobforanonymous/wshawk:latest

# Run WSHawk
docker run --rm rothackers/wshawk ws://target.com

# Defensive validation
docker run --rm rothackers/wshawk wshawk-defensive ws://target.com

See Docker Guide for detailed usage.

Quick Start

WSHawk provides 4 easy ways to scan WebSocket applications:

Method 1: Quick Scan (Fastest)

wshawk ws://target.com

Method 2: Interactive Menu (User-Friendly)

wshawk-interactive

Method 3: Advanced CLI (Full Control)

# Basic scan
wshawk-advanced ws://target.com

# With Smart Payloads and Playwright verification
wshawk-advanced ws://target.com --smart-payloads --playwright --full

Method 4: Web Management Dashboard (GUI)

# Launch the persistent web dashboard
wshawk --web

Best for teams requiring scan history, visual progress tracking, and professional report management.

Web Management Dashboard

WSHawk v3.0.0 introduces a persistent, secure web-based dashboard for managing all your WebSocket security assessments.

Launching the GUI

wshawk --web --port 5000 --host 0.0.0.0

Authentication

For production security, the Web GUI is protected by a password. Set it using an environment variable:

export WSHAWK_WEB_PASSWORD='your-strong-password'
wshawk --web

Note: If no password is set, the dashboard will run in open mode (only recommended for local testing).

Features

Feature	Description
Persistent History	All scans are saved to a local SQLite database (scans.db).
Visual Progress	Real-time scan status and vulnerability counters.
Interactive Reports	View, delete, and manage comprehensive HTML reports in-browser.
API Key Support	Programmatic access via --api-key or WSHAWK_API_KEY.

Hierarchical Configuration (wshawk.yaml)

WSHawk now supports a professional configuration system. Generate a template to get started:

python3 -m wshawk.config --generate

Rename wshawk.yaml.example to wshawk.yaml. You can resolve secrets from environment variables or files:

integrations:
  jira:
    api_token: "env:JIRA_TOKEN"  # Fetched from environment
    project: "SEC"

Command Comparison

Feature	wshawk	wshawk-interactive	wshawk-advanced	wshawk --web
Ease of Use	High	High	Medium	Highest
Persistence	No	No	No	Yes (SQLite)
Auth Support	No	No	No	Yes (SHA-256)
Best For	Automation	Learning	Power Users	Teams / SOC

What You Get

All methods include:

• Real vulnerability verification (not just pattern matching)
• 22,000+ attack payloads
• Advanced mutation engine with WAF bypass
• CVSS v3.1 scoring for all findings
• Session hijacking tests (6 security tests)
• Professional HTML reports
• Adaptive rate limiting
• OAST integration for blind vulnerabilities
• Optional Playwright for browser-based XSS verification

Output

WSHawk generates comprehensive HTML reports with:

• CVSS v3.1 scores for all vulnerabilities
• Screenshots (for XSS browser verification)
• Message replay sequences
• Raw WebSocket traffic logs
• Server fingerprints
• Actionable remediation recommendations

Reports saved as: wshawk_report_YYYYMMDD_HHMMSS.html

Advanced Options

wshawk-advanced --help

Options:
  --playwright     Enable browser-based XSS verification
  --rate N         Set max requests per second (default: 10)
  --full           Enable ALL features
  --no-oast        Disable OAST testing

Defensive Validation (NEW in v3.0.0)

WSHawk now includes a Defensive Validation Module designed for blue teams to validate their security controls.

# Run defensive validation tests
wshawk-defensive ws://your-server.com

What It Tests

1. DNS Exfiltration Prevention

• Validates if DNS-based data exfiltration is blocked
• Tests egress filtering effectiveness
• Detects potential APT-style attack vectors

2. Bot Detection Effectiveness

• Tests if anti-bot measures detect headless browsers
• Validates resistance to evasion techniques
• Identifies gaps in bot protection

3. CSWSH (Cross-Site WebSocket Hijacking)

• Tests Origin header validation (216+ malicious origins)
• Validates CSRF token requirements
• Critical for preventing session hijacking

4. WSS Protocol Security Validation

• TLS version validation (detects deprecated SSLv2/v3, TLS 1.0/1.1)
• Weak cipher suite detection (RC4, DES, 3DES)
• Certificate validation (expiration, self-signed, chain integrity)
• Forward secrecy verification (ECDHE, DHE)
• Prevents MITM and protocol downgrade attacks

Use Cases

• Validate security controls before production deployment
• Regular security posture assessment
• Compliance and audit requirements
• Blue team defensive capability testing

See Defensive Validation Documentation for detailed usage and remediation guidance.

Documentation

• Getting Started Guide
• Advanced Usage
• Vulnerability Details
• Session Security Tests
• Mutation Engine
• Architecture

Python API

For integration into custom scripts:

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())

See Advanced Usage for more examples.

Responsible Disclosure

WSHawk is designed for:

• Authorized penetration testing
• Bug bounty programs
• Security research
• Educational purposes

Always obtain proper authorization before testing.

License

MIT License - see LICENSE file

Author

Regaan (@noobforanonymous)

Contributing

Contributions welcome! See CONTRIBUTING.md

Legal Disclaimer

WSHawk is designed for security professionals, researchers, and developers for authorized testing only.

• Usage: You must have explicit permission from the system owner before scanning.
• Liability: The author (Regaan) is NOT responsible for any damage caused by the misuse of this tool.
• Malware: WSHawk is a security scanner, NOT malware. Any repackaged version found on third-party sites containing malicious code is NOT associated with this project.

By using WSHawk, you agree to these terms and use it at your own risk.

Support

• Issues: GitHub Issues
• Documentation: docs/
• Examples: examples/
• Email: support@rothackers.com

---

WSHawk v3.0.0 - Professional WebSocket Security Scanner

Built for the security community