Architectural Planes Overview

Architectural Planes Overview

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

Purpose and Scope

This document explains the four architectural planes that form the foundation of WSHawk v3.0.0. These planes represent distinct functional layers that operate concurrently to provide enterprise-grade WebSocket security scanning capabilities. Each plane has specific responsibilities and interfaces with other planes through well-defined boundaries.

For implementation details of individual components within each plane, see:

Architectural Philosophy

WSHawk v3.0.0 implements a separation of concerns architecture where offensive capabilities, infrastructure management, resilience mechanisms, and external integrations operate as independent but coordinated planes. This design ensures that failures in one plane (e.g., a Jira API timeout) do not cascade to other planes (e.g., the core scanning engine).

The architecture follows three core principles documented in RELEASE_SUMMARY.md:96-98:

  1. Zero-Loss Persistence - Security data is never ephemeral
  2. Autonomous Evolution - The tool adapts to target behavior
  3. Actionable Output - Findings automatically create tickets and alerts

Sources: RELEASE_SUMMARY.md:1-60, docs/V3_COMPLETE_GUIDE.md:1-111

The Four Architectural Planes

High-Level Plane Interaction Model

graph TB
    subgraph RedTeam["Red Team Execution Plane"]
        WSHawkV2["WSHawkV2<br/>(scanner_v2.py)"]
        PayloadSys["Payload System<br/>(WSPayloads)"]
        Evolution["Smart Evolution<br/>(ContextAwareGenerator,<br/>PayloadEvolver,<br/>FeedbackLoop)"]
        Analysis["Analysis Modules<br/>(MessageAnalyzer,<br/>VulnerabilityVerifier,<br/>ServerFingerprinter)"]
    end
    
    subgraph Persistence["Infrastructure Persistence Plane"]
        SQLite["SQLite Database<br/>(scans.db)<br/>WAL Mode"]
        FileSystem["File System<br/>Reports, Logs,<br/>Screenshots"]
    end
    
    subgraph Resilience["Resilience Control Plane"]
        ResilientSession["ResilientSession<br/>(Wraps All Network I/O)"]
        CircuitBreaker["Circuit Breakers<br/>(State Machine)"]
        RateLimit["TokenBucketRateLimiter<br/>(Adaptive)"]
        Backoff["Exponential Backoff<br/>(with Jitter)"]
    end
    
    subgraph Integration["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
    
    WSHawkV2 --> PayloadSys
    WSHawkV2 --> Evolution
    WSHawkV2 --> Analysis
    Evolution --> PayloadSys
    
    WSHawkV2 --> ResilientSession
    ResilientSession --> CircuitBreaker
    ResilientSession --> RateLimit
    ResilientSession --> Backoff
    
    WSHawkV2 --> SQLite
    WSHawkV2 --> FileSystem
    
    WSHawkV2 --> Jira
    WSHawkV2 --> DefectDojo
    WSHawkV2 --> Webhooks
    WSHawkV2 --> SARIF
    
    ResilientSession -.->|"protects"| Jira
    ResilientSession -.->|"protects"| DefectDojo
    ResilientSession -.->|"protects"| Webhooks

Diagram: Four architectural planes with their primary components and interactions

Sources: RELEASE_SUMMARY.md:1-60, docs/V3_COMPLETE_GUIDE.md:111-131, README.md:1-310

1. Red Team Execution Plane

The Red Team Execution Plane contains all offensive security testing capabilities. This plane is responsible for discovering vulnerabilities, mutating payloads, and verifying exploitability.

Core Components

| Component | File Location | Responsibility | |-----------|---------------|----------------| | WSHawkV2 | wshawk/scanner_v2.py | Central orchestrator for scanning lifecycle | | WSPayloads | wshawk/payloads.py | 22,000+ static payload vectors with lazy loading | | ContextAwareGenerator | wshawk/mutation/ | Dynamic payload generation based on message structure | | PayloadEvolver | wshawk/mutation/ | Genetic algorithm for payload breeding | | FeedbackLoop | wshawk/mutation/ | Response analysis and fitness scoring | | MessageAnalyzer | wshawk/analysis/ | Message format detection (JSON/XML/protobuf) | | VulnerabilityVerifier | wshawk/verification/ | Confidence scoring for detected vulnerabilities | | ServerFingerprinter | wshawk/fingerprint/ | Technology stack identification |

Execution Flow

graph LR
    Target["Target WebSocket<br/>(ws:// or wss://)"]
    
    Connect["Connection Manager<br/>(SSL/TLS Handshake)"]
    Sample["Message Sampling<br/>(5-10 seconds)"]
    Analyze["MessageAnalyzer<br/>(Format Detection)"]
    Fingerprint["ServerFingerprinter<br/>(Tech Stack ID)"]
    
    Static["WSPayloads<br/>(22,000+ Vectors)"]
    Context["ContextAwareGenerator<br/>(Field Injection)"]
    Evolve["PayloadEvolver<br/>(Genetic Mutation)"]
    
    Inject["Payload Injection<br/>(Rate-Limited)"]
    Verify["VulnerabilityVerifier<br/>(Confidence Scoring)"]
    Feedback["FeedbackLoop<br/>(Fitness Analysis)"]
    
    Target --> Connect
    Connect --> Sample
    Sample --> Analyze
    Sample --> Fingerprint
    
    Analyze --> Context
    Fingerprint --> Context
    Static --> Context
    
    Context --> Inject
    Inject --> Verify
    Verify --> Feedback
    Feedback --> Evolve
    Evolve --> Inject

Diagram: Red Team Execution Plane component flow showing the adaptive scanning loop

Advanced Verification

The Red Team Plane includes three advanced verification subsystems:

  1. Playwright XSS Verification - HeadlessBrowserXSSVerifier executes payloads in real Chromium browser to confirm script execution, captures screenshots as evidence
  2. OAST Blind Detection - OASTProvider uses interact.sh to detect XXE, SSRF, and blind RCE through out-of-band callbacks
  3. Session Security Testing - SessionHijackingTester performs 6 authentication tests including token reuse, privilege escalation, and session fixation

Sources: README.md:38-52, RELEASE_SUMMARY.md:23-28, docs/V3_COMPLETE_GUIDE.md:115-120

2. Infrastructure Persistence Plane

The Infrastructure Persistence Plane ensures that all security data survives process termination, system crashes, and network interruptions. This implements the "Zero-Loss Persistence" design principle.

Core Components

| Component | Storage Type | Location | Purpose | |-----------|--------------|----------|---------| | SQLite Database | scans.db | ~/.wshawk/ or configurable | Scan metadata, vulnerabilities, traffic logs | | WAL Mode | Write-Ahead Logging | SQLite configuration | Crash recovery without data loss | | HTML Reports | wshawk_report_*.html | Current directory or --output | Comprehensive vulnerability reports with CVSS | | Screenshots | PNG files | Report artifacts | Browser verification evidence | | Traffic Logs | Raw WebSocket frames | Database + report | Message replay sequences |

Database Architecture

graph TB
    Scanner["WSHawkV2<br/>Scanner"]
    
    subgraph Database["SQLite Database (scans.db)"]
        ScanTable["scans table<br/>(scan_id, target, timestamp,<br/>status, config)"]
        VulnTable["vulnerabilities table<br/>(vuln_id, scan_id, type,<br/>cvss_score, payload)"]
        TrafficTable["traffic_logs table<br/>(log_id, scan_id,<br/>direction, frame_data)"]
        MetadataTable["metadata table<br/>(key, value)"]
    end
    
    subgraph FileSystem["File System"]
        Reports["HTML Reports<br/>(wshawk_report_*.html)"]
        Screenshots["Screenshots<br/>(xss_verification_*.png)"]
        Configs["Configuration<br/>(wshawk.yaml)"]
    end
    
    WebGUI["Web Management Dashboard<br/>(Flask + SQLite)"]
    
    Scanner --> ScanTable
    Scanner --> VulnTable
    Scanner --> TrafficTable
    Scanner --> Reports
    Scanner --> Screenshots
    
    WebGUI --> ScanTable
    WebGUI --> VulnTable
    WebGUI --> TrafficTable
    WebGUI --> Reports
    
    ScanTable --> VulnTable
    ScanTable --> TrafficTable

Diagram: Infrastructure Persistence Plane storage architecture with database schema

WAL Mode Implementation

WSHawk enables SQLite's Write-Ahead Logging (WAL) mode to ensure that writes are atomic and recoverable. If the scanner process is killed mid-scan, the database automatically recovers to the last committed transaction.

Configuration in wshawk/database.py or equivalent:

PRAGMA journal_mode=WAL;

This ensures "Zero-Loss Persistence" even during system crashes or Docker container terminations.

Sources: RELEASE_SUMMARY.md:15-19, docs/V3_COMPLETE_GUIDE.md:122-125, README.md:132-136

3. Resilience Control Plane

The Resilience Control Plane wraps all network I/O to handle unstable targets, rate-limited APIs, and unreliable networks. This plane prevents the scanner from overwhelming targets or cascading failures.

Core Components

| Component | Purpose | Key Features | |-----------|---------|--------------| | ResilientSession | Network I/O wrapper | Wraps all HTTP, WebSocket, and external API calls | | Circuit Breaker | Failure threshold management | 3 states: CLOSED, OPEN, HALF_OPEN with 60s cooldown | | Exponential Backoff | Retry timing | Base * 2^Attempt + Jitter, capped at max delay | | TokenBucketRateLimiter | Adaptive rate control | Server health monitoring, dynamic rate adjustment | | Error Classifier | Transient vs. permanent | Distinguishes retryable (429, network) from fatal (401, 403) |

ResilientSession State Machine

stateDiagram-v2
    [*] --> Normal
    
    Normal --> Retry: "Transient Error<br/>(429, Network Timeout)"
    Retry --> Backoff: "attempt < max_retries"
    Backoff --> Normal: "Success"
    Backoff --> Retry: "Still Failing"
    
    Retry --> CircuitOpen: "Failure Threshold<br/>Exceeded"
    CircuitOpen --> Cooldown: "60s Wait Period"
    Cooldown --> HalfOpen: "Cooldown Complete"
    
    HalfOpen --> Normal: "Canary Request<br/>Success"
    HalfOpen --> CircuitOpen: "Canary Request<br/>Failed"
    
    Normal --> FastFail: "Permanent Error<br/>(401, 403, 404)"
    FastFail --> [*]

Diagram: ResilientSession state machine showing error handling and recovery paths

Error Classification Logic

The ResilientSession classifies errors into two categories:

Transient Errors (retry with backoff):

  • HTTP 429 Too Many Requests
  • HTTP 503 Service Unavailable
  • Network timeouts
  • Connection refused (temporary)

Permanent Errors (fail fast):

  • HTTP 401 Unauthorized
  • HTTP 403 Forbidden
  • HTTP 404 Not Found
  • Invalid SSL certificates

This classification ensures that authentication failures don't trigger infinite retry loops while network hiccups are handled gracefully.

Sources: RELEASE_SUMMARY.md:9-13, docs/V3_COMPLETE_GUIDE.md:134-173, README.md:48

4. Integration Collaboration Plane

The Integration Collaboration Plane connects WSHawk to external platforms for workflow automation and team collaboration. This plane operates independently from the scanning engine to ensure failures don't impact core functionality.

Core Components

| Integration | Configuration Source | Trigger Condition | Output Format | |-------------|---------------------|-------------------|---------------| | Jira | wshawk.yaml or env vars | CRITICAL/HIGH severity findings | Jira issue with CVSS, payload, reproduction steps | | DefectDojo | wshawk.yaml or env vars | All findings | DefectDojo engagement with standardized findings | | Webhooks | wshawk.yaml | All findings or completion | JSON payload to Slack/Discord/Teams | | SARIF Export | CLI flag --sarif | Scan completion | SARIF v2.1.0 JSON for GitHub/GitLab Security |

Integration Flow

graph TB
    ScanComplete["Scan Completion<br/>(WSHawkV2)"]
    
    CVSS["CVSS v3.1 Scoring<br/>(Severity Calculation)"]
    
    Filter["Severity Filter<br/>(CRITICAL/HIGH for auto-ticket)"]
    
    JiraCheck{"Jira<br/>Enabled?"}
    JiraCreate["Jira API<br/>(Create Issue)<br/>via ResilientSession"]
    
    DDCheck{"DefectDojo<br/>Enabled?"}
    DDPush["DefectDojo API<br/>(Push Finding)<br/>via ResilientSession"]
    
    WebhookCheck{"Webhook<br/>Enabled?"}
    WebhookSend["Webhook POST<br/>(Slack/Discord/Teams)<br/>via ResilientSession"]
    
    SARIFCheck{"SARIF<br/>Requested?"}
    SARIFExport["SARIF Export<br/>(wshawk.sarif)<br/>File System"]
    
    ScanComplete --> CVSS
    CVSS --> Filter
    
    Filter --> JiraCheck
    JiraCheck -->|Yes| JiraCreate
    JiraCheck -->|No| DDCheck
    
    JiraCreate --> DDCheck
    DDCheck -->|Yes| DDPush
    DDCheck -->|No| WebhookCheck
    
    DDPush --> WebhookCheck
    WebhookCheck -->|Yes| WebhookSend
    WebhookCheck -->|No| SARIFCheck
    
    WebhookSend --> SARIFCheck
    SARIFCheck -->|Yes| SARIFExport
    SARIFCheck -->|No| Complete["Scan Complete"]
    
    SARIFExport --> Complete

Diagram: Integration Collaboration Plane workflow showing conditional external platform updates

Configuration System

All integrations are configured through the hierarchical configuration system:

Configuration Sources (in priority order):

  1. Command-line arguments
  2. Environment variables (with env: prefix resolution)
  3. wshawk.yaml configuration file
  4. Default values

Example wshawk.yaml structure:

integrations:
  jira:
    url: "env:JIRA_URL"
    api_token: "env:JIRA_API_TOKEN"
    project: "SEC"
    auto_create_issue: true
    
  defectdojo:
    url: "env:DD_URL"
    api_key: "env:DD_API_KEY"
    
  webhooks:
    - url: "env:SLACK_WEBHOOK_URL"
      format: "slack"
    - url: "env:DISCORD_WEBHOOK_URL"
      format: "discord"

Secret resolution using env: prefix prevents hardcoding credentials in configuration files.

Sources: RELEASE_SUMMARY.md:30-34, docs/V3_COMPLETE_GUIDE.md:333-349, README.md:137-151

Inter-Plane Communication

Resilience Protection for Integration Plane

The ResilientSession from the Resilience Control Plane wraps all Integration Collaboration Plane API calls. This ensures that:

  1. Circuit breakers prevent cascading failures if Jira/DefectDojo is down
  2. Exponential backoff handles rate-limited APIs gracefully
  3. Timeouts prevent hanging on slow external services
  4. Retries handle transient network failures

Persistence Support for All Planes

All planes write to the Infrastructure Persistence Plane:

  • Red Team Plane: Stores scan results, vulnerabilities, payloads
  • Resilience Control Plane: Logs retry attempts and circuit breaker state changes
  • Integration Collaboration Plane: Records successful/failed integration attempts

This unified persistence ensures complete audit trails and enables the Web Management Dashboard to provide historical views.

Sources: docs/V3_COMPLETE_GUIDE.md:126-131, RELEASE_SUMMARY.md:1-60

Entry Points and Plane Activation

CLI Entry Points

WSHawk provides multiple entry points defined in pyproject.toml that activate different plane combinations:

| Entry Point | Command | Planes Activated | Use Case | |-------------|---------|------------------|----------| | wshawk | wshawk ws://target.com | Red Team + Persistence + Resilience | Quick automated scan | | wshawk-interactive | wshawk-interactive | Red Team + Persistence + Resilience | Learning-friendly menu | | wshawk-advanced | wshawk-advanced --full | All planes + Smart Evolution + Browser | Power user scanning | | wshawk-defensive | wshawk-defensive ws://target.com | Red Team (defensive tests) + Persistence | Blue team validation | | Web GUI | wshawk --web | All planes + REST API + Dashboard | Team collaboration |

Python API Entry Point

from wshawk.scanner_v2 import WSHawkV2

scanner = WSHawkV2("ws://target.com")
scanner.use_headless_browser = True  # Red Team Plane: Browser verification
scanner.use_oast = True              # Red Team Plane: OAST detection
scanner.enable_smart_payloads = True # Red Team Plane: Smart evolution

await scanner.run_heuristic_scan()   # Activates all configured planes

This programmatic interface activates planes based on the properties set on the WSHawkV2 instance.

Sources: README.md:84-111, README.md:252-263

Design Benefits

1. Fault Isolation

Failures in the Integration Collaboration Plane (e.g., Jira API timeout) do not impact the Red Team Execution Plane. The scan continues and results are still persisted.

2. Independent Scaling

Each plane can be optimized independently:

  • Red Team Plane: Multi-threaded payload injection
  • Persistence Plane: SQLite WAL mode for write performance
  • Resilience Plane: Tunable retry counts and backoff parameters
  • Integration Plane: Parallel API calls to multiple platforms

3. Testability

Planes can be tested in isolation. Mock implementations of ResilientSession can simulate network failures without requiring real target infrastructure.

4. Configuration Granularity

Each plane has independent configuration sections in wshawk.yaml, allowing teams to enable/disable features without code changes.

Sources: docs/V3_COMPLETE_GUIDE.md:111-131, RELEASE_SUMMARY.md:1-60

Summary

WSHawk v3.0.0's four architectural planes provide:

  • Red Team Execution Plane: 22,000+ payloads, smart evolution, real verification
  • Infrastructure Persistence Plane: Zero-loss SQLite storage with WAL mode
  • Resilience Control Plane: Production-grade stability with circuit breakers
  • Integration Collaboration Plane: Automated workflow integration with external platforms

These planes operate concurrently with well-defined interfaces, ensuring that enterprise-grade features like resilience and integration do not compromise the core offensive security testing capabilities.

Sources: README.md:1-310, RELEASE_SUMMARY.md:1-60, docs/V3_COMPLETE_GUIDE.md:1-443