Defensive Mode Overview WSHawk v3.0.0

Defensive Mode Overview WSHawk v3.0.0

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

Purpose and Scope

This document introduces WSHawk's Defensive Validation Module, a specialized testing framework designed for blue teams to validate the effectiveness of security controls protecting WebSocket endpoints. Unlike the offensive scanning modes documented in Section 4, defensive mode tests whether your security infrastructure (egress filtering, bot detection, origin validation, TLS configuration) functions correctly against real-world attack vectors.

For detailed information about specific defensive tests, see:

Defensive vs Offensive Testing

WSHawk provides two fundamentally different testing paradigms:

| Aspect | Offensive Mode | Defensive Mode | |--------|---------------|----------------| | Purpose | Find vulnerabilities in target applications | Validate security controls protecting your infrastructure | | Perspective | Red team / Penetration tester | Blue team / Security operations | | CLI Command | wshawk, wshawk-advanced | wshawk-defensive | | Entry Point | wshawk/main.py, wshawk/advanced_cli.py | wshawk/defensive_cli.py:46 | | Target | Third-party WebSocket endpoints | Your own WebSocket infrastructure | | Test Types | SQL injection, XSS, XXE, SSRF, etc. | DNS exfiltration blocking, bot detection, origin validation, TLS configuration | | Success Criteria | Vulnerability found | Security control is working (attack blocked) | | Report Focus | Exploitation evidence | Control effectiveness and gaps |

Sources: README.md:199-239, CHANGELOG.md:58-78

CLI Entry Point

Defensive mode is invoked via a dedicated CLI command defined in the package configuration:

wshawk-defensive ws://your-server.com

The command is registered as a console script entry point:

[project.scripts]
wshawk-defensive = "wshawk.defensive_cli:cli"

This entry point is separate from the offensive scanning commands to ensure clear operational separation and prevent accidental testing against production systems.

Sources: pyproject.toml:46, README.md:204-206

Defensive Test Categories

WSHawk's defensive mode executes four distinct validation test categories, each addressing critical security control domains:

1. DNS Exfiltration Prevention Test

Validates whether DNS-based data exfiltration attempts are blocked by egress filtering or DNS monitoring. This test simulates Advanced Persistent Threat (APT) techniques that abuse DNS queries to leak sensitive data.

Key Validations:

  • DNS query blocking at network perimeter
  • DNS resolver monitoring effectiveness
  • Detection of suspicious TXT/CNAME record queries

2. Bot Detection Effectiveness Test

Validates anti-bot measures by attempting to connect using headless browser characteristics and automation fingerprints. Tests whether your WebSocket infrastructure can detect and block automated clients.

Key Validations:

  • Headless browser detection (Playwright/Puppeteer signatures)
  • User-Agent filtering effectiveness
  • JavaScript challenge execution
  • Browser fingerprinting evasion detection

3. CSWSH (Cross-Site WebSocket Hijacking) Test

Tests Origin header validation with 216+ malicious origin payloads sourced from wshawk/payloads/malicious_origins.txt. This validates protection against session hijacking via cross-origin WebSocket connections.

Key Validations:

  • Origin header enforcement
  • CSRF token requirement for WebSocket upgrade
  • Same-origin policy implementation
  • Wildcard origin rejection

4. WSS Protocol Security Validation

Validates TLS/SSL configuration for secure WebSocket connections (wss://). Tests for deprecated protocols, weak ciphers, certificate issues, and modern security requirements.

Key Validations:

  • TLS version restrictions (reject SSLv2, SSLv3, TLS 1.0, TLS 1.1)
  • Weak cipher suite detection (RC4, DES, 3DES, NULL ciphers)
  • Certificate validation (expiration, self-signed, chain integrity)
  • Forward secrecy support (ECDHE, DHE)
  • TLS renegotiation security

Sources: README.md:208-230, CHANGELOG.md:60-72

System Architecture

Diagram 1: Defensive Mode Integration

graph TB
    subgraph "CLI Layer"
        DefensiveCLI["wshawk-defensive<br/>(defensive_cli.py:cli)"]
    end
    
    subgraph "Defensive Test Modules"
        DNSTest["DNS Exfiltration<br/>Prevention Test"]
        BotTest["Bot Detection<br/>Validation Test"]
        CSWSHTest["CSWSH Test<br/>(Origin Validation)"]
        WSSTest["WSS Protocol<br/>Security Test"]
    end
    
    subgraph "Payload Resources"
        MaliciousOrigins["malicious_origins.txt<br/>(216+ payloads)"]
        PayloadSystem["WSPayloads Class<br/>(Static Payloads)"]
    end
    
    subgraph "Core Infrastructure"
        Scanner["WSHawkV2<br/>(scanner_v2.py)"]
        ResilientSession["ResilientSession<br/>(Network I/O)"]
        VulnVerifier["VulnerabilityVerifier<br/>(Confidence Scoring)"]
    end
    
    subgraph "Reporting Layer"
        CVSSScoring["CVSS v3.1 Scoring<br/>(Risk Assessment)"]
        ReportGen["Report Generation<br/>(HTML/JSON/CSV)"]
        Database["scans.db<br/>(SQLite WAL)"]
    end
    
    DefensiveCLI --> DNSTest
    DefensiveCLI --> BotTest
    DefensiveCLI --> CSWSHTest
    DefensiveCLI --> WSSTest
    
    CSWSHTest --> MaliciousOrigins
    DNSTest --> PayloadSystem
    
    DNSTest --> Scanner
    BotTest --> Scanner
    CSWSHTest --> Scanner
    WSSTest --> Scanner
    
    Scanner --> ResilientSession
    Scanner --> VulnVerifier
    
    DNSTest --> CVSSScoring
    BotTest --> CVSSScoring
    CSWSHTest --> CVSSScoring
    WSSTest --> CVSSScoring
    
    CVSSScoring --> ReportGen
    ReportGen --> Database

Diagram 1: Defensive Mode Architecture - This diagram illustrates how wshawk-defensive integrates with WSHawk's core scanning infrastructure while maintaining separation from offensive testing modes. Each defensive test module leverages the same underlying scanner engine, resilient networking layer, and reporting infrastructure used by offensive scans.

Sources: pyproject.toml:46, README.md:199-239, CHANGELOG.md:58-78

Diagram 2: Defensive Test Execution Pipeline

graph LR
    subgraph "Initialization"
        CLI["CLI Invocation<br/>wshawk-defensive<br/>ws://target"]
        Parse["Argument Parsing<br/>(Target URL)"]
    end
    
    subgraph "Test Orchestration"
        Orchestrator["Test Orchestrator<br/>(defensive_cli)"]
        Config["Load Config<br/>(wshawk.yaml)"]
    end
    
    subgraph "Individual Tests"
        T1["DNS Exfiltration<br/>Test Execution"]
        T2["Bot Detection<br/>Test Execution"]
        T3["CSWSH<br/>Test Execution<br/>(216+ Origins)"]
        T4["WSS Protocol<br/>Test Execution<br/>(TLS/Certs)"]
    end
    
    subgraph "Validation Logic"
        V1["DNS Query<br/>Detection"]
        V2["Bot Signature<br/>Detection"]
        V3["Origin Header<br/>Enforcement"]
        V4["TLS Config<br/>Analysis"]
    end
    
    subgraph "Result Processing"
        Score["CVSS Scoring<br/>(Control Failures)"]
        Report["Report Generation<br/>(Findings + Remediation)"]
        Store["Store to scans.db<br/>(Persistence)"]
    end
    
    CLI --> Parse
    Parse --> Orchestrator
    Orchestrator --> Config
    
    Orchestrator --> T1
    Orchestrator --> T2
    Orchestrator --> T3
    Orchestrator --> T4
    
    T1 --> V1
    T2 --> V2
    T3 --> V3
    T4 --> V4
    
    V1 --> Score
    V2 --> Score
    V3 --> Score
    V4 --> Score
    
    Score --> Report
    Report --> Store

Diagram 2: Defensive Test Execution Pipeline - Shows the sequential flow from CLI invocation through individual test execution to result persistence. Each test module performs specialized validation logic and returns findings that are scored using CVSS v3.1 methodology.

Sources: pyproject.toml:46, README.md:204-206, CHANGELOG.md:72-73

Test Execution Model

Defensive mode operates on a control validation model rather than an exploitation model:

  1. Test Initialization: The defensive_cli.py module parses the target WebSocket URL and initializes test configurations.

  2. Security Control Testing: Each test module attempts to bypass or violate a security control:

    • DNS exfiltration attempts DNS-based data leakage
    • Bot detection uses headless browser signatures
    • CSWSH sends requests with invalid Origin headers
    • WSS validation analyzes TLS handshake parameters

  3. Success Criteria Inversion: Unlike offensive mode where finding a vulnerability is "success," defensive mode considers blocking the attack as success. If an attack is not blocked, it indicates a security control gap.

  4. CVSS Scoring: Control failures are assigned CVSS v3.1 scores based on:

    • Attack Vector (AV): Network-accessible WebSocket
    • Attack Complexity (AC): Varies by test
    • Privileges Required (PR): None (unauthenticated tests)
    • User Interaction (UI): None
    • Scope (S): Changed (if control bypass affects other systems)
    • Impact (CIA): Varies by control type

  5. Remediation Guidance: Reports include specific remediation steps for each control failure, such as configuring DNS egress filtering rules or updating TLS cipher suite policies.

Sources: README.md:232-238, CHANGELOG.md:72-73

Output and Reporting

Defensive mode generates comprehensive validation reports with the following structure:

Report Sections

| Section | Content | |---------|---------| | Executive Summary | Pass/fail status for each security control test | | Control Effectiveness Score | Aggregate security posture metric (0-100) | | Individual Test Results | Detailed findings per test category with CVSS scores | | Evidence Collection | Network traffic logs, TLS handshake details, DNS queries | | Remediation Guidance | Step-by-step instructions for addressing control gaps | | Compliance Mapping | Mapping to PCI-DSS, NIST, ISO 27001 requirements |

Report Formats

  • HTML Report: Visual dashboard with color-coded pass/fail indicators
  • JSON Export: Machine-readable format for SIEM/SOAR integration
  • CSV Export: Tabular data for spreadsheet analysis
  • SARIF Export: Integration with GitHub Security and other DevSecOps platforms

Database Persistence

All defensive validation scans are stored in the SQLite database (scans.db) with WAL mode enabled for crash recovery:

Table: scans
- scan_id (PRIMARY KEY)
- scan_type (set to "defensive")
- target_url
- timestamp
- control_effectiveness_score
- findings_count
- report_path

This enables historical trending analysis to track security posture improvements over time.

Sources: README.md:177-185, README.md:132-135

Use Cases

Pre-Production Validation

Before deploying WebSocket applications to production, run defensive validation to ensure security controls are properly configured:

wshawk-defensive wss://staging.example.com/ws

This validates that DNS egress filtering, bot detection, origin validation, and TLS configuration meet security requirements before production exposure.

Continuous Security Monitoring

Integrate defensive mode into scheduled CI/CD pipelines or cron jobs to continuously validate security posture:

# Run daily defensive validation
0 2 * * * docker run rothackers/wshawk wshawk-defensive wss://prod.example.com/ws

Automated runs detect security control degradation due to configuration changes or infrastructure updates.

Compliance and Audit

Defensive validation reports provide evidence for compliance audits:

  • PCI-DSS Requirement 6.5: Protection against injection attacks (validated via Origin header enforcement)
  • NIST 800-53 SC-7: Boundary protection (validated via egress filtering)
  • ISO 27001 A.14.1: Secure development requirements (validated via TLS configuration)

The CVSS-scored findings demonstrate due diligence in security control implementation.

Blue Team Capability Testing

Security operations teams use defensive mode to validate detection and prevention capabilities:

# Test if SOC can detect bot activity
wshawk-defensive ws://internal-websocket.corp.example.com

# Review SIEM logs to confirm alerting triggered

This validates that security monitoring systems correctly identify and alert on suspicious WebSocket activity.

Sources: README.md:232-238

Integration with Web Dashboard

Defensive validation scans integrate seamlessly with WSHawk's persistent web dashboard (Section 6):

  1. Launch the dashboard:

    wshawk --web --port 5000

  2. Execute defensive scans via REST API:

    curl -X POST http://localhost:5000/api/scans \
  -H "Content-Type: application/json" \
  -d '{"url": "wss://target.com", "mode": "defensive"}'

  3. View scan history filtered by defensive mode to track security posture trends over time.

The SQLite-backed persistence layer (scans.db) stores all defensive validation results alongside offensive scan data, enabling side-by-side comparison of offensive findings vs defensive control effectiveness.

Sources: README.md:112-136

Version History

Defensive mode was introduced in WSHawk v3.0.0 (December 2025) with the following initial capabilities:

  • DNS Exfiltration Prevention Test
  • Bot Detection Validation Test
  • CSWSH Test with 216+ malicious origin payloads
  • WSS Protocol Security Validation

Subsequent releases enhanced defensive testing:

  • v3.0.0: Fixed CSWSH test compatibility with newer websockets library versions
  • v3.0.0: Production flagship release with integrated SPE engine and enterprise-grade reporting. Integrated defensive mode with unified reporting and web dashboard persistence.

Sources: CHANGELOG.md:50-78

Related Documentation

For detailed information about specific defensive tests and remediation guidance, refer to:

For comparison with offensive testing capabilities, see:

For programmatic usage of defensive mode via Python API: