Overview

Overview

Relevant source files

Purpose and Scope

This document provides a high-level introduction to WSHawk, a professional WebSocket security testing framework. It covers the system's architecture, core components, feature set, and distribution model. For detailed installation instructions and first-time usage, see Getting Started. For information about specific vulnerability tests, see Offensive Testing. For blue team security control validation, see Defensive Validation.

What is WSHawk

WSHawk is a production-grade WebSocket security scanner implemented in Python that provides automated vulnerability detection and security control validation for WebSocket applications. The system operates in two distinct modes:

  1. Offensive Mode: Red team vulnerability detection across seven major attack categories (SQL injection, XSS, XXE, SSRF, NoSQL injection, path traversal, command injection)
  2. Defensive Mode: Blue team security control validation through four specialized tests (DNS exfiltration prevention, bot detection, CSWSH, WSS protocol security)

The tool is distributed through three channels (PyPI, Docker Hub, GitHub Container Registry) and provides both CLI and programmatic Python API interfaces.

Sources: README.md L1-L10

pyproject.toml L1-L52

System Architecture

WSHawk implements a layered architecture with five primary CLI interfaces, a central scanning engine, and distinct offensive/defensive testing modules. The following diagram maps the system's natural language components to their corresponding code entities:

flowchart TD

CLI_QUICK["wshawk<br>(wshawk.main:cli)"]
CLI_INTERACTIVE["wshawk-interactive<br>(wshawk.interactive:cli)"]
CLI_ADVANCED["wshawk-advanced<br>(wshawk.advanced_cli:cli)"]
CLI_DEFENSIVE["wshawk-defensive<br>(wshawk.defensive_cli:cli)"]
API["Python API<br>(WSHawkV2 class)"]
SCANNER["Scanner Engine<br>(wshawk/scanner_v2.py)<br>WSHawkV2 class"]
LOGGER["Centralized Logging<br>(wshawk/logger.py)"]
MSG_INTEL["MessageIntelligence<br>(scanner_v2.py)"]
SERVER_FING["ServerFingerprinter<br>(scanner_v2.py)"]
VULN_VERIF["VulnerabilityVerifier<br>(scanner_v2.py)"]
VULN_TESTS["Vulnerability Tests<br>(wshawk/sql_injection.py)<br>(wshawk/xss_detection.py)<br>(wshawk/xxe_tester.py)<br>(wshawk/ssrf_tester.py)<br>(wshawk/nosql_injection.py)<br>(wshawk/path_traversal.py)<br>(wshawk/cmd_injection.py)"]
SESSION_TEST["Session Hijacking<br>(wshawk/session_hijacking_tester.py)<br>SessionHijackingTester class"]
PLAYWRIGHT["Playwright Verification<br>(scanner_v2.py)<br>verify_xss_with_playwright()"]
OAST["OAST Integration<br>(scanner_v2.py)<br>OASTProvider class"]
DNS_TEST["DNS Exfiltration Test<br>(wshawk/defensive_validation.py)<br>test_dns_exfiltration()"]
BOT_TEST["Bot Detection Test<br>(wshawk/defensive_validation.py)<br>test_bot_detection()"]
CSWSH_TEST["CSWSH Test<br>(wshawk/defensive_validation.py)<br>test_cswsh()"]
WSS_TEST["WSS Security Test<br>(wshawk/defensive_validation.py)<br>test_wss_security()"]
PAYLOADS["WSPayloads class<br>(wshawk/payloads.py)<br>payloads/.txtpayloads/**/.json"]
MUTATORS["Mutation Engine<br>(wshawk/mutators/)"]
CVSS["CVSS Calculator<br>(wshawk/cvss_calculator.py)<br>calculate_cvss_score()"]
REPORTS["HTML Report Generator<br>(scanner_v2.py)<br>generate_html_report()"]

API -.-> SCANNER
SCANNER -.-> MSG_INTEL
SCANNER -.-> SERVER_FING
SCANNER -.-> VULN_VERIF
SCANNER -.-> VULN_TESTS
SCANNER -.-> SESSION_TEST
SCANNER -.-> PLAYWRIGHT
SCANNER -.-> OAST
SCANNER -.-> REPORTS

subgraph subGraph6 ["Output & Scoring"]
    CVSS
    REPORTS
    CVSS -.-> REPORTS
end

subgraph subGraph5 ["Payload System"]
    PAYLOADS
    MUTATORS
end

subgraph subGraph4 ["Defensive Testing Modules"]
    DNS_TEST
    BOT_TEST
    CSWSH_TEST
    WSS_TEST
end

subgraph subGraph3 ["Offensive Testing Modules"]
    VULN_TESTS
    SESSION_TEST
    PLAYWRIGHT
    OAST
end

subgraph subGraph2 ["Intelligence Layer"]
    MSG_INTEL
    SERVER_FING
    VULN_VERIF
end

subgraph subGraph1 ["Core Engine"]
    SCANNER
    LOGGER
    SCANNER -.-> LOGGER
end

subgraph subGraph0 ["User Interface Layer"]
    CLI_QUICK
    CLI_INTERACTIVE
    CLI_ADVANCED
    CLI_DEFENSIVE
    API
end

Component Mapping to Code Entities:

The system's entry points are defined in pyproject.toml L41-L45

as console scripts:

| CLI Command | Python Module Path | | --- | --- | | wshawk | wshawk.__main__:cli | | wshawk-interactive | wshawk.interactive:cli | | wshawk-advanced | wshawk.advanced_cli:cli | | wshawk-defensive | wshawk.defensive_cli:cli |

Sources: pyproject.toml L41-L45

README.md L66-L93

High-Level Diagram 1

Core Components

The following diagram maps WSHawk's execution flow to specific code functions and file paths:

flowchart TD

START["User Executes CLI"]
ENTRY_QUICK["wshawk.main:cli<br>Quick scan mode"]
ENTRY_INTERACTIVE["wshawk.interactive:cli<br>Menu-driven mode"]
ENTRY_ADVANCED["wshawk.advanced_cli:cli<br>Full control mode"]
ENTRY_DEFENSIVE["wshawk.defensive_cli:cli<br>Blue team mode"]
INIT["WSHawkV2.init()<br>scanner_v2.py:70-120"]
LEARNING["run_learning_phase()<br>scanner_v2.py:150-200<br>5 second passive observation"]
INTEL_FORMAT["MessageIntelligence.analyze()<br>scanner_v2.py:250-300<br>Detect JSON/XML/Binary"]
INTEL_FINGER["ServerFingerprinter.fingerprint()<br>scanner_v2.py:350-400<br>Tech stack detection"]
TEST_EXEC["run_intelligent_scan()<br>scanner_v2.py:500-600<br>Orchestrate all tests"]
VULN_SQL["SQLInjectionTester.test()<br>sql_injection.py"]
VULN_XSS["XSSDetector.test()<br>xss_detection.py"]
VULN_XXE["XXETester.test()<br>xxe_tester.py"]
VULN_SSRF["SSRFTester.test()<br>ssrf_tester.py"]
VULN_SESSION["SessionHijackingTester.run_all_tests()<br>session_hijacking_tester.py:50-100"]
VERIFY_BROWSER["verify_xss_with_playwright()<br>scanner_v2.py:700-800<br>Real browser execution"]
VERIFY_OAST["OASTProvider.check_callbacks()<br>scanner_v2.py:900-950<br>Out-of-band detection"]
SCORE["calculate_cvss_score()<br>cvss_calculator.py:20-150"]
REPORT["generate_html_report()<br>scanner_v2.py:1000-1100<br>wshawk_report_YYYYMMDD_HHMMSS.html"]
DEF_DNS["test_dns_exfiltration()<br>defensive_validation.py:50-150"]
DEF_BOT["test_bot_detection()<br>defensive_validation.py:200-300"]
DEF_CSWSH["test_cswsh()<br>defensive_validation.py:350-500"]
DEF_WSS["test_wss_security()<br>defensive_validation.py:550-750"]

START -.-> ENTRY_QUICK
START -.-> ENTRY_INTERACTIVE
START -.-> ENTRY_ADVANCED
START -.-> ENTRY_DEFENSIVE
INIT -.-> LEARNING
LEARNING -.-> INTEL_FORMAT
LEARNING -.-> INTEL_FINGER
SCORE -.-> REPORT

Primary Code Components

| Component | File Path | Primary Class/Function | Responsibility | | --- | --- | --- | --- | | Scanner Engine | wshawk/scanner_v2.py | WSHawkV2 | Central orchestration, learning phase, test coordination | | Payload Manager | wshawk/payloads.py | WSPayloads | Load and manage 22,000+ attack vectors from payloads/*.txt | | Mutation Engine | wshawk/mutators/ | BaseMutator subclasses | WAF bypass through 8+ evasion strategies | | CVSS Calculator | wshawk/cvss_calculator.py | calculate_cvss_score() | CVSS v3.1 scoring for all findings | | Session Tester | wshawk/session_hijacking_tester.py | SessionHijackingTester | 6 session security tests (token reuse, impersonation, etc.) | | Defensive Module | wshawk/defensive_validation.py | 4 test functions | Blue team security control validation | | Logging System | wshawk/logger.py | Module-level loggers | Centralized colored output and file logging |

Sources: pyproject.toml L41-L52

README.md L20-L34

CHANGELOG.md L5-L27

Distribution Channels

WSHawk is distributed through three channels, each serving different deployment scenarios:

| Channel | Installation Command | Use Case | | --- | --- | --- | | PyPI | pip install wshawk==2.0.5 | Python developers, local development | | Docker Hub | docker pull rothackers/wshawk:latest | DevOps teams, CI/CD pipelines | | GitHub Container Registry | docker pull ghcr.io/noobforanonymous/wshawk:latest | GitHub-native organizations |

Package Configuration

The Python package is configured in pyproject.toml L1-L52

with:

Docker Image Details

The Docker images are multi-architecture (linux/amd64, linux/arm64), built from a multi-stage Dockerfile with:

  • Base Image: python:3.11-slim
  • Image Size: ~150MB
  • Non-root User: wshawk:1000
  • Automated Publishing: GitHub Actions workflows trigger on push to main branch

Sources: pyproject.toml L1-L52

README.md L36-L62

RELEASE_SUMMARY.md L21-L54

Feature Matrix

Offensive Testing Capabilities

| Feature Category | Implementation | Verification Method | | --- | --- | --- | | SQL Injection | 22,000+ payloads via wshawk/sql_injection.py | Pattern matching + context analysis | | XSS Detection | wshawk/xss_detection.py | Playwright browser verification (optional) | | XXE Testing | wshawk/xxe_tester.py | OAST out-of-band callbacks | | SSRF Detection | wshawk/ssrf_tester.py | OAST out-of-band callbacks | | NoSQL Injection | wshawk/nosql_injection.py | Database-specific payload testing | | Path Traversal | wshawk/path_traversal.py | File access pattern detection | | Command Injection | wshawk/cmd_injection.py | OS command execution verification | | Session Security | wshawk/session_hijacking_tester.py | 6 specialized tests (token reuse, subscription spoofing, user impersonation, channel violations, session fixation, privilege escalation) |

Defensive Testing Capabilities

Implemented in wshawk/defensive_validation.py

:

| Test Name | Function | CVSS Range | Purpose | | --- | --- | --- | --- | | DNS Exfiltration Prevention | test_dns_exfiltration() | 7.5-8.2 | Validates egress filtering effectiveness | | Bot Detection Validation | test_bot_detection() | 5.3-7.8 | Tests anti-bot measure effectiveness | | CSWSH Test | test_cswsh() | 7.5-9.1 | Validates Origin header enforcement (216+ malicious origins) | | WSS Protocol Security | test_wss_security() | 5.3-9.8 | TLS version/cipher/certificate validation (6 checks) |

Sources: README.md L20-L34

README.md L143-L183

CHANGELOG.md L13-L27

Key Features

Intelligence-Driven Testing

WSHawk implements a learning phase scanner_v2.py L150-L200

that passively observes WebSocket traffic for 5 seconds before active testing. This phase extracts:

  1. Message Format Intelligence (MessageIntelligence class): Detects JSON, XML, Binary, or plain text structures
  2. Server Fingerprinting (ServerFingerprinter class): Identifies technology stack (language, framework, database)
  3. Session State Capture: Extracts tokens, user IDs, and authentication data

This intelligence informs context-aware payload injection and reduces false positives.

Payload Mutation System

The mutation engine wshawk/mutators/

implements 8+ WAF bypass strategies through pluggable mutator classes inheriting from BaseMutator. Payloads are loaded from external files:

  • Structured Payloads: payloads/*.txt (22,000+ vectors)
  • JSON Payloads: payloads/**/*.json
  • Malicious Origins: payloads/malicious_origins.txt (216+ origins for CSWSH testing)

Multi-Layer Verification

WSHawk uses three verification layers to reduce false positives:

  1. Pattern-Based Detection: Initial string matching for reflected payloads
  2. Browser-Based Verification: verify_xss_with_playwright() scanner_v2.py L700-L800 executes JavaScript in Chromium
  3. Out-of-Band Confirmation: OASTProvider class scanner_v2.py L900-L950 detects blind vulnerabilities via DNS/HTTP callbacks

Standardized Risk Scoring

All findings are scored using CVSS v3.1 via calculate_cvss_score() cvss_calculator.py L20-L150

Scores are categorized as:

  • CRITICAL: 9.0-10.0
  • HIGH: 7.0-8.9
  • MEDIUM: 4.0-6.9
  • LOW: 0.1-3.9

Sources: README.md L14-L30

CHANGELOG.md L60-L70

Use Cases

Red Team (Offensive Testing)

Accessible via wshawk, wshawk-interactive, or wshawk-advanced commands:

  • Penetration Testing: Comprehensive vulnerability assessment for authorized engagements
  • Bug Bounty Hunting: Automated discovery of WebSocket vulnerabilities with proof-of-concept evidence
  • CI/CD Security Gates: Automated vulnerability scanning in build pipelines
  • Security Research: Systematic evaluation of WebSocket implementations

Blue Team (Defensive Validation)

Accessible via wshawk-defensive command:

  • Security Control Validation: Verify DNS egress filtering, Origin header enforcement, TLS configuration
  • Compliance Audits: Document security control effectiveness for audit requirements
  • Pre-Production Testing: Validate security controls before deployment
  • Red Team Exercise Preparation: Identify defensive capability gaps before simulated attacks

Programmatic Integration

Accessible via Python API (from wshawk.scanner_v2 import WSHawkV2):

  • Custom Security Workflows: Integrate vulnerability scanning into proprietary security platforms
  • Automated Triage: Parse results programmatically for automated ticket creation
  • Continuous Monitoring: Scheduled vulnerability scanning with custom notification logic

Sources: README.md L212-L220

README.md L176-L182

README.md L196-L209

Technology Stack

Core Dependencies

From pyproject.toml L29-L34

:

  • websockets (>=12.0): Async WebSocket protocol implementation
  • playwright (>=1.40.0): Browser automation for XSS verification
  • aiohttp (>=3.9.0): Async HTTP client for OAST and SSRF testing
  • PyYAML (>=6.0): Configuration file parsing for authentication sequences

Supported Python Versions

WSHawk supports Python 3.8 through 3.13 pyproject.toml L13-L26

enabling deployment across legacy and modern environments.

Development Status

Classified as "Production/Stable" pyproject.toml L15

with active maintenance. Current version is 2.0.5 as of 2025-12-08 CHANGELOG.md L5

Sources: pyproject.toml L13-L34

CHANGELOG.md L1-L11

For detailed information about specific subsystems, refer to: