Overview WSHawk v3.0.0

Overview WSHawk v3.0.0

The following files were used as context for generating this wiki page:

This document provides a high-level introduction to WSHawk v3.0.0, a professional WebSocket security scanner built on four architectural planes: Red Team Execution, Infrastructure Persistence, Resilience Control, and Integration Collaboration. It covers the tool's dual-purpose architecture (offensive and defensive testing), core capabilities, system design principles, and deployment options.

For installation instructions, see Getting Started. For architecture details, see Core Architecture. For specific testing capabilities, see Offensive Testing and Defensive Validation.

What is WSHawk?

WSHawk v3.0.0 is a production-grade WebSocket security scanner designed for both offensive security testing (red team) and defensive validation (blue team). Unlike traditional scanners that rely solely on pattern matching, WSHawk performs real vulnerability verification using browser automation (Playwright) and out-of-band testing (OAST) techniques.

The tool is distributed as a Python package on PyPI and as Docker images on Docker Hub and GitHub Container Registry. It features 22,000+ attack payloads, adaptive WAF evasion, smart payload evolution, persistent web management dashboard, and CVSS v3.1-based risk scoring.

Key Differentiators (v3.0.0):

  • Smart Payload Evolution - Adaptive feedback-driven mutation using genetic algorithms
  • Persistent Web GUI - SQLite-backed dashboard with authentication and REST API
  • Enterprise Integrations - Auto-push to Jira, DefectDojo, and webhooks (Slack/Discord/Teams)
  • Browser-based XSS verification via Playwright (not just reflection detection)
  • OAST integration for blind vulnerability detection (XXE, SSRF via interact.sh)
  • Session security testing - 6 comprehensive attack scenarios
  • Production-grade resilience - ResilientSession with circuit breakers and exponential backoff
  • Hierarchical configuration - wshawk.yaml with environment variable secret resolution

Sources: pyproject.toml:1-52, README.md:1-311, RELEASE_SUMMARY.md:1-60

Dual-Purpose Architecture

WSHawk operates in two distinct modes, each serving different security objectives:

Offensive Testing Mode (Red Team)

Tests WebSocket applications for exploitable vulnerabilities across 11 attack categories:

| Vulnerability Type | Description | |-------------------|-------------| | SQL Injection | Database query manipulation | | Cross-Site Scripting (XSS) | Client-side script injection | | Remote Code Execution (RCE) | Server-side command injection | | XML External Entity (XXE) | XML parser exploitation | | Server-Side Request Forgery (SSRF) | Internal network access | | NoSQL Injection | NoSQL database manipulation | | Path Traversal | File system access | | LDAP Injection | Directory service exploitation | | Server-Side Template Injection (SSTI) | Template engine abuse | | Open Redirect | URL redirection attacks | | Session Security | Token reuse, hijacking, privilege escalation |

Entry Points: wshawk, wshawk-interactive, wshawk-advanced commands

Defensive Validation Mode (Blue Team)

Validates security controls and defensive measures:

| Control Category | Tests | |-----------------|-------| | DNS Exfiltration Prevention | Egress filtering, XXE/SSRF-based DNS exfiltration | | Bot Detection Effectiveness | Headless browser detection, evasion resistance | | CSWSH Protection | Origin validation (216+ malicious origins), CSRF tokens | | WSS Protocol Security | TLS version, cipher suites, certificates, renegotiation |

Entry Point: wshawk-defensive command

Sources: pyproject.toml:41-45, README.md:34-47, README.md:157-189

System Entry Points

WSHawk v3.0.0 provides five interfaces for different use cases:

CLI Entry Points and Web Dashboard

graph TB
    subgraph "User Interface Layer"
        wshawk["wshawk<br/>(Quick Scan)<br/>wshawk.__main__:cli"]
        interactive["wshawk-interactive<br/>(Menu-Driven)<br/>wshawk.interactive:cli"]
        advanced["wshawk-advanced<br/>(Full Control)<br/>wshawk.advanced_cli:cli"]
        defensive["wshawk-defensive<br/>(Blue Team)<br/>wshawk.defensive_cli:cli"]
        webgui["wshawk --web<br/>(Management Dashboard)<br/>Flask + SQLite"]
        api["Python API<br/>WSHawkV2 class<br/>scanner_v2.py"]
    end
    
    subgraph "Core Scanning Engine"
        scanner["WSHawkV2<br/>scanner_v2.py"]
        defmodule["DefensiveValidationModule<br/>defensive_validation.py"]
    end
    
    subgraph "Infrastructure Persistence"
        db[("SQLite Database<br/>scans.db<br/>WAL Mode")]
        files["File System<br/>HTML Reports<br/>Traffic Logs<br/>Screenshots"]
    end
    
    wshawk --> scanner
    interactive --> scanner
    advanced --> scanner
    defensive --> defmodule
    api --> scanner
    webgui --> scanner
    webgui --> db
    
    scanner --> db
    scanner --> files
    defmodule --> files

Entry Point Details:

| Command | Use Case | Persistence | Authentication | Best For | |---------|----------|-------------|----------------|----------| | wshawk | Quick security assessment | No | No | Automation, CI/CD | | wshawk-interactive | Manual testing, learning | No | No | Learning, exploration | | wshawk-advanced | Advanced users, custom options | No | No | Power users, custom flags | | wshawk-defensive | Blue team validation | No | No | Security control testing | | wshawk --web | Persistent dashboard | Yes (SQLite) | Yes (SHA-256) | Teams, SOC, history | | Python API | Custom integration | Configurable | No | Custom tooling, pipelines |

Sources: pyproject.toml:42-46, README.md:84-127, RELEASE_SUMMARY.md:15-19

Core System Architecture

WSHawk v3.0.0 is organized into four architectural planes that work together to provide comprehensive WebSocket security testing:

The Four Architectural Planes

graph TB
    subgraph "Red Team Execution Plane"
        Scanner["WSHawkV2 Scanner<br/>scanner_v2.py"]
        SmartPayload["Smart Payload Evolution<br/>ContextAwareGenerator<br/>PayloadEvolver<br/>FeedbackLoop"]
        Payloads["WSPayloads<br/>22,000+ Vectors<br/>payloads/*.txt"]
        Mutation["PayloadMutator<br/>8+ WAF Evasion Strategies"]
    end
    
    subgraph "Infrastructure Persistence Plane"
        DB[("SQLite Database<br/>scans.db<br/>WAL Mode")]
        WebGUI["Web Management Dashboard<br/>Flask Application<br/>REST API"]
        FileStorage["File System<br/>HTML Reports<br/>Traffic Logs<br/>Screenshots"]
    end
    
    subgraph "Resilience Control Plane"
        Resilient["ResilientSession<br/>Wraps All Network I/O"]
        CircuitBreaker["Circuit Breakers<br/>State: OPEN/HALF_OPEN/CLOSED"]
        Backoff["Exponential Backoff<br/>with Jitter"]
        RateLimit["TokenBucketRateLimiter<br/>Adaptive Rate Control"]
    end
    
    subgraph "Integration Collaboration Plane"
        Jira["Jira Integration<br/>Auto Ticket Creation"]
        DefectDojo["DefectDojo<br/>Findings Push"]
        Webhooks["Webhook Notifier<br/>Slack/Discord/Teams"]
        SARIF["SARIF Export<br/>GitHub Security"]
    end
    
    Scanner --> SmartPayload
    Scanner --> Payloads
    Scanner --> Mutation
    SmartPayload --> Payloads
    
    Scanner --> DB
    Scanner --> FileStorage
    WebGUI --> DB
    
    Scanner --> Resilient
    Resilient --> CircuitBreaker
    Resilient --> Backoff
    Resilient --> RateLimit
    
    Scanner --> Jira
    Scanner --> DefectDojo
    Scanner --> Webhooks
    Scanner --> SARIF

Architectural Plane Details:

| Plane | Purpose | Key Components | Sources | |-------|---------|----------------|---------| | Red Team Execution | Vulnerability detection and exploitation | WSHawkV2, ContextAwareGenerator, PayloadEvolver, WSPayloads | wshawk/scanner_v2.py | | Infrastructure Persistence | Data storage and management | SQLite (WAL mode), Flask dashboard, file system | wshawk/web/ | | Resilience Control | Network stability and reliability | ResilientSession, circuit breakers, rate limiting | wshawk/resilient_session.py | | Integration Collaboration | External platform connectivity | Jira, DefectDojo, webhooks, SARIF export | wshawk/integrations/ |

Component Architecture with Code Entities

graph TB
    subgraph "User Interface Layer"
        CLI["CLI Entrypoints<br/>__main__.py<br/>interactive.py<br/>advanced_cli.py<br/>defensive_cli.py"]
        WebDash["Web Dashboard<br/>web/app.py<br/>web/routes.py"]
        PyAPI["Python API<br/>WSHawkV2 class"]
    end
    
    subgraph "Core Scanning Engine"
        WSHawkV2["WSHawkV2<br/>scanner_v2.py"]
        MessageAnalyzer["MessageAnalyzer<br/>Format Detection"]
        VulnerabilityVerifier["VulnerabilityVerifier<br/>Confidence Scoring"]
        ServerFingerprinter["ServerFingerprinter<br/>Technology Stack"]
    end
    
    subgraph "Smart Payload Evolution"
        ContextGen["ContextAwareGenerator<br/>Field Injection"]
        Evolver["PayloadEvolver<br/>Genetic Algorithm"]
        Feedback["FeedbackLoop<br/>Response Analysis"]
    end
    
    subgraph "Verification Layer"
        Playwright["HeadlessBrowserXSSVerifier<br/>Playwright Integration"]
        OAST["OASTProvider<br/>interact.sh"]
        SessionTest["SessionHijackingTester<br/>6 Security Tests"]
    end
    
    subgraph "Data and Configuration"
        WSPayloads["WSPayloads<br/>Lazy Payload Loading"]
        Config["WSHawkConfig<br/>wshawk.yaml<br/>Environment Variables"]
        PluginMgr["PluginManager<br/>Lazy Loading<br/>Validation"]
    end
    
    subgraph "Resilience and Output"
        Resilient["ResilientSession<br/>Exponential Backoff<br/>Circuit Breakers"]
        CVSS["CVSSCalculator<br/>v3.1 Scoring"]
        Reports["ReportGenerator<br/>HTML/JSON/CSV/SARIF"]
    end
    
    CLI --> WSHawkV2
    WebDash --> WSHawkV2
    PyAPI --> WSHawkV2
    
    WSHawkV2 --> MessageAnalyzer
    WSHawkV2 --> VulnerabilityVerifier
    WSHawkV2 --> ServerFingerprinter
    
    WSHawkV2 --> ContextGen
    ContextGen --> Evolver
    Evolver --> Feedback
    
    WSHawkV2 --> Playwright
    WSHawkV2 --> OAST
    WSHawkV2 --> SessionTest
    
    WSHawkV2 --> WSPayloads
    WSHawkV2 --> Config
    WSHawkV2 --> PluginMgr
    
    WSHawkV2 --> Resilient
    WSHawkV2 --> CVSS
    CVSS --> Reports

Design Principles (v3.0.0):

  1. Zero-Loss Persistence - SQLite WAL mode ensures no data loss during crashes
  2. Autonomous Evolution - Smart Payload Evolution adapts to target responses
  3. Production-Grade Resilience - ResilientSession handles unstable networks
  4. Actionable Output - Automated integration with Jira, DefectDojo, webhooks
  5. Hierarchical Configuration - Unified wshawk.yaml with secret resolution
  6. Plugin Extensibility - PluginManager for custom payloads, detectors, protocols

Sources: RELEASE_SUMMARY.md:1-60, docs/V3_COMPLETE_GUIDE.md:111-131, pyproject.toml:29-35

Verification System

WSHawk distinguishes itself through multi-layer vulnerability verification:

Verification Layers

flowchart TD
    Input["Vulnerability Candidate<br/>Pattern Match or Response Analysis"]
    
    Layer1["Layer 1: Pattern Matching<br/>VulnerabilityVerifier<br/>Regex + String Analysis"]
    
    Layer2["Layer 2: Browser Verification<br/>Playwright Integration<br/>Real XSS Execution"]
    
    Layer3["Layer 3: Out-of-Band Testing<br/>OAST Provider<br/>interact.sh Callbacks"]
    
    Output["Confirmed Vulnerability<br/>CVSS Score + Evidence"]
    
    Input --> Layer1
    Layer1 -->|"XSS Candidate"| Layer2
    Layer1 -->|"XXE/SSRF Candidate"| Layer3
    Layer1 -->|"Other Vulnerabilities"| Output
    
    Layer2 -->|"Script Executed"| Output
    Layer2 -->|"Failed"| Discard1["False Positive"]
    
    Layer3 -->|"Callback Received"| Output
    Layer3 -->|"No Callback"| Discard2["False Positive"]

Verification Methods:

| Vulnerability Type | Verification Method | False Positive Rate | |-------------------|---------------------|---------------------| | SQL Injection | Error message analysis, time-based blind | Low | | XSS | Playwright browser execution + screenshot | Very Low | | XXE | OAST callback detection | Very Low | | SSRF | OAST callback detection | Very Low | | RCE | Time delays + command output detection | Low | | NoSQL Injection | Error messages + response behavior | Medium | | Others | Pattern matching + response analysis | Medium |

Sources: README.md:28-32, README.md:37-39

Key Capabilities

Red Team Execution Capabilities

  • 22,000+ Attack Payloads - WSPayloads class with lazy loading from payloads/*.txt and payloads/**/*.json
  • Smart Payload Evolution - ContextAwareGenerator, PayloadEvolver with genetic algorithms, FeedbackLoop for response analysis
  • Adaptive Mutation - PayloadMutator with 8+ WAF evasion strategies and real-time feedback
  • Intelligent Learning Phase - MessageAnalyzer observes legitimate traffic for context-aware generation
  • Session State Management - SessionStateMachine tracks authentication and context

Verification and Detection

  • Browser Verification - HeadlessBrowserXSSVerifier using Playwright Chromium for real XSS execution
  • OAST Provider - OASTProvider with interact.sh for blind XXE/SSRF detection via callbacks
  • WAF Detection - 12 WAF signatures (Cloudflare, AWS WAF, etc.) with adaptive bypass strategies
  • Server Fingerprinting - ServerFingerprinter identifies technology stack for targeted testing
  • Confidence Scoring - VulnerabilityVerifier assigns LOW/MEDIUM/HIGH confidence levels

Infrastructure and Persistence

  • Web Management Dashboard - Flask-based GUI with SQLite persistence and REST API
  • Zero-Loss Storage - SQLite WAL mode for crash-resistant scan history (scans.db)
  • Authentication - SHA-256 password hashing with WSHAWK_WEB_PASSWORD environment variable
  • Historical Analysis - Query and compare past scans through web interface or API

Resilience and Reliability

  • ResilientSession - Wraps all network I/O with error classification and retry logic
  • Circuit Breakers - State machine (OPEN/HALF_OPEN/CLOSED) prevents cascading failures
  • Exponential Backoff - Automatic retry with jitter for transient errors (429, network issues)
  • Adaptive Rate Limiting - TokenBucketRateLimiter monitors server health and adjusts speed

Integration and Collaboration

  • Jira Integration - Automatic ticket creation for CRITICAL/HIGH findings with CVSS scores
  • DefectDojo Integration - Direct push to vulnerability management platform with engagement creation
  • Webhook Notifications - Structured messages to Slack, Discord, Microsoft Teams
  • SARIF Export - Standardized format for GitHub Security tab integration

Reporting and Output

  • CVSS v3.1 Scoring - CVSSCalculator for automatic risk assessment with vector generation
  • Multi-Format Reports - HTML (human-readable), JSON/CSV (machine-readable), SARIF (CI/CD)
  • Evidence Collection - Screenshots (XSS verification), traffic logs, replay sequences
  • Remediation Guidance - Actionable recommendations for each vulnerability type

Configuration and Extensibility

  • Hierarchical Configuration - WSHawkConfig reads wshawk.yaml with environment variable resolution
  • Secret Management - env: and file: prefixes for secure credential handling
  • Plugin System - PluginManager with lazy loading for PayloadPlugin, DetectorPlugin, ProtocolPlugin
  • Plugin Validation - Metadata checks, semver validation, minimum version enforcement

Sources: README.md:28-48, RELEASE_SUMMARY.md:9-35, docs/V3_COMPLETE_GUIDE.md:100-108

Distribution and Deployment

WSHawk is distributed through multiple channels:

Installation Methods

| Method | Command | Use Case | |--------|---------|----------| | PyPI (pip) | pip install wshawk | Development, local testing | | Docker Hub | docker pull rothackers/wshawk:latest | Production, CI/CD | | GitHub Container Registry | docker pull ghcr.io/regaan/wshawk:latest | Enterprise, automated pipelines | | Source | git clone + pip install -e . | Development, contributions |

Docker Architecture

  • Multi-stage builds - Optimized image size
  • Multi-platform support - linux/amd64 and linux/arm64
  • Automated publishing - GitHub Actions on releases and tags
  • Version tagging - latest, semantic versions (v3.0.0), major.minor versions (v3.0.0)

CI/CD Integration

WSHawk can be integrated into automated security pipelines:

# Example: GitLab CI
docker run --rm rothackers/wshawk wshawk ws://staging-app.internal

# Example: GitHub Actions
- run: pip install wshawk
- run: wshawk ws://localhost:8080 --rate 5

For detailed installation instructions, see Installation Methods. For CI/CD integration examples, see CI/CD Integration.

Sources: README.md:49-76, pyproject.toml:5-7

Dependencies and Requirements

Core Dependencies

| Dependency | Version | Purpose | Component | |------------|---------|---------|-----------| | websockets | ≥12.0 | WebSocket protocol implementation | WSHawkV2, ResilientSession | | playwright | ≥1.40.0 | Browser automation for XSS verification | HeadlessBrowserXSSVerifier | | aiohttp | ≥3.9.0 | HTTP client for OAST and API integrations | OASTProvider, Jira, DefectDojo | | PyYAML | ≥6.0 | Configuration file parsing | WSHawkConfig | | flask | ≥3.0.0 | Web management dashboard | web/app.py, web/routes.py |

Python Version Support

WSHawk supports Python 3.8 through 3.13 (production status as of v3.0.0), ensuring compatibility with both legacy systems and modern environments.

Optional Components

  • Playwright browsers - Required for XSS verification: playwright install chromium
  • OAST service - Automatically uses interact.sh (no setup required)
  • SQLite - Built-in with Python (used for scans.db persistence)

Package Distribution

  • MANIFEST.in - Ensures payloads, web templates, and static files are included
  • pyproject.toml - Defines CLI entrypoints: wshawk, wshawk-interactive, wshawk-advanced, wshawk-defensive
  • setup.py - Package metadata and dependency declarations

For detailed dependency information, see Dependency Reference.

Sources: pyproject.toml:13-35, pyproject.toml:42-46, MANIFEST.in:1-7

Use Cases

Offensive Security (Red Team)

  • Penetration Testing - Identify vulnerabilities in authorized targets
  • Bug Bounty Programs - Discover and report security issues
  • Security Research - Analyze WebSocket security patterns
  • Vulnerability Assessment - Automated security scanning in CI/CD

Defensive Security (Blue Team)

  • Security Control Validation - Verify defensive measures work as intended
  • Pre-Production Testing - Validate security before deployment
  • Compliance Audits - Demonstrate security controls for regulatory requirements
  • Continuous Monitoring - Regular security posture assessment

Development and Education

  • Secure Development - Test applications during development
  • Security Training - Learn WebSocket security concepts
  • Quality Assurance - Automated security testing in QA environments

Sources: README.md:226-234, README.md:190-196

Next Steps

Sources: pyproject.toml:1-52, README.md:1-269, requirements.txt:1-19