Smart Payload Evolution System

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

• .github/workflows/ghcr-publish.yml
• README.md
• RELEASE_3.0.0.md
• RELEASE_SUMMARY.md
• docs/V3_COMPLETE_GUIDE.md
• requirements.txt
• wshawk/advanced_cli.py
• wshawk/scanner_v2.py

Purpose and Scope

The Smart Payload Evolution System is WSHawk's adaptive payload generation engine that transforms static vulnerability testing into a feedback-driven, intelligent attack process. Unlike traditional scanners that simply iterate through predetermined payload lists, this system learns from the target application's behavior and evolves attack payloads that are contextually optimized for the specific WebSocket implementation being tested.

This document covers the three core modules that comprise the system: ContextAwareGenerator, FeedbackLoop, and PayloadEvolver. For information about the static payload collections (22,000+ vectors) used as the foundation, see Payload Management System. For details on how vulnerabilities are verified after payload testing, see Analysis and Verification Modules.

Sources: README.md:28, RELEASE_SUMMARY.md:25-28, docs/V3_COMPLETE_GUIDE.md:176-201

---

System Overview

The Smart Payload Evolution System operates as a three-phase cognitive security engine integrated into the WSHawkV2 scanner. It consists of three specialized modules that work collaboratively to adapt attack strategies based on real-time server feedback.

Architecture Diagram: Component Relationships

graph TB
    subgraph "Learning Phase"
        SampleMessages["Sample WebSocket<br/>Messages"]
        CAG["ContextAwareGenerator<br/>context_generator.py"]
        FLBaseline["FeedbackLoop<br/>establish_baseline()"]
    end
    
    subgraph "Active Scanning Phase"
        StaticPayloads["WSPayloads<br/>Static Collection"]
        InjectedPayloads["Contextually<br/>Injected Payloads"]
        ServerResponses["Server Responses"]
        FLAnalyze["FeedbackLoop<br/>analyze_response()"]
        ResponseSignals["ResponseSignal<br/>Classification"]
    end
    
    subgraph "Evolution Phase"
        PE["PayloadEvolver<br/>payload_evolver.py"]
        Population["Payload Population<br/>population_size=100"]
        Fitness["Fitness Scoring<br/>update_fitness()"]
        Evolved["Evolved Payloads<br/>evolve(count)"]
        ContextPayloads["Context Payloads<br/>generate_payloads()"]
    end
    
    SampleMessages --> CAG
    SampleMessages --> FLBaseline
    
    CAG --> |"learn_from_message()"| InjectedPayloads
    StaticPayloads --> InjectedPayloads
    
    InjectedPayloads --> ServerResponses
    ServerResponses --> FLAnalyze
    FLAnalyze --> ResponseSignals
    
    ResponseSignals --> |"Successful payloads"| PE
    ResponseSignals --> |"seed()"| Population
    
    PE --> Fitness
    Fitness --> Evolved
    
    FLAnalyze --> |"get_priority_categories()"| ContextPayloads
    CAG --> ContextPayloads
    
    Evolved --> InjectedPayloads
    ContextPayloads --> InjectedPayloads
    
    style CAG fill:#f9f9f9
    style FLAnalyze fill:#f9f9f9
    style PE fill:#f9f9f9

Sources: wshawk/scanner_v2.py:27-30, wshawk/scanner_v2.py:72-75, wshawk/scanner_v2.py:637-703

---

Architecture Components

ContextAwareGenerator

The ContextAwareGenerator is responsible for understanding the structure and format of WebSocket messages exchanged with the target application. It performs heuristic analysis to identify message formats (JSON, XML, protobuf, binary) and extracts injectable field locations.

Core Functionality

| Method | Purpose | Phase Used | |--------|---------|------------| | learn_from_message(msg) | Analyzes sample messages to detect structure | Learning | | generate_payloads(category, count) | Generates contextually appropriate payloads | Evolution | | analysis_complete | Boolean flag indicating sufficient learning | Learning → Scanning | | context | Dictionary containing learned structural information | All phases |

The generator identifies injectable fields within message structures and tailors payloads to fit naturally into the application's expected input format. For example, if the target uses JSON messages with a {"action": "...", "data": "..."} structure, the generator creates payloads that preserve this structure rather than sending malformed JSON that would be rejected before reaching vulnerable code paths.

Sources: wshawk/scanner_v2.py:28, wshawk/scanner_v2.py:72, wshawk/scanner_v2.py:156-163

Integration with MessageAnalyzer

The ContextAwareGenerator works in tandem with the MessageAnalyzer module to perform deep structural analysis:

graph LR
    MA["MessageAnalyzer<br/>message_intelligence.py"]
    CAG["ContextAwareGenerator"]
    MF["MessageFormat<br/>JSON/XML/PROTOBUF"]
    Fields["Injectable Fields<br/>List"]
    
    MA --> |"detected_format"| MF
    MA --> |"injectable_fields"| Fields
    
    MF --> CAG
    Fields --> CAG
    
    CAG --> |"generate_payloads()"| ContextPayloads["Contextually<br/>Structured Payloads"]

Sources: wshawk/scanner_v2.py:58, wshawk/scanner_v2.py:146-173

FeedbackLoop

The FeedbackLoop module implements real-time response analysis and attack category prioritization. It classifies server responses into signal types and maintains performance metrics to guide subsequent payload selection.

Response Signal Classification

The feedback loop categorizes server responses using the ResponseSignal enumeration:

| Signal Type | Meaning | Fitness Impact | |-------------|---------|----------------| | ERROR | Server error detected (stack trace, exception) | High priority | | TIMEOUT | Response delayed significantly | Medium priority | | REFLECTION | Payload reflected in response | Medium-High priority | | ANOMALY | Response differs from baseline | Medium priority | | NORMAL | Response matches baseline | Low priority (discard) |

Key Methods

| Method | Parameters | Purpose | |--------|------------|---------| | establish_baseline(message, time) | Sample message, response time | Sets normal behavior baseline | | analyze_response(payload, response, time, category) | Attack payload, server response, timing, vuln category | Classifies response signal and confidence | | get_priority_categories() | None | Returns sorted list of most promising attack categories |

Sources: wshawk/scanner_v2.py:29, wshawk/scanner_v2.py:161, wshawk/scanner_v2.py:222-234, wshawk/scanner_v2.py:670-672

Baseline Establishment

During the learning phase, the feedback loop observes normal server behavior to establish a baseline. This enables accurate anomaly detection during active scanning:

graph TB
    SampleMsg["Sample Messages<br/>5-10 seconds observation"]
    NormalTime["Normal Response Time<br/>Baseline Average"]
    NormalPatterns["Normal Response Patterns<br/>Content/Structure"]
    
    SampleMsg --> NormalTime
    SampleMsg --> NormalPatterns
    
    NormalTime --> Baseline["Baseline Profile"]
    NormalPatterns --> Baseline
    
    Baseline --> |"Compare during scan"| AttackResponse["Attack Response"]
    
    AttackResponse --> TimeAnomaly["Response time > baseline + 2σ"]
    AttackResponse --> ContentAnomaly["Response structure differs"]
    AttackResponse --> ErrorDetection["Error strings present"]
    
    TimeAnomaly --> Signal["ResponseSignal<br/>Classification"]
    ContentAnomaly --> Signal
    ErrorDetection --> Signal

Sources: wshawk/scanner_v2.py:161, docs/V3_COMPLETE_GUIDE.md:180-186

PayloadEvolver

The PayloadEvolver implements a genetic algorithm for evolving attack payloads. It maintains a population of payloads, applies mutation and crossover operations, and tracks fitness scores based on successful exploitation attempts.

Genetic Algorithm Parameters

| Parameter | Default Value | Configuration Location | Purpose | |-----------|---------------|------------------------|---------| | population_size | 100 | wshawk/scanner_v2.py:74 | Number of payloads in gene pool | | generation | 0 (incremented) | Internal counter | Tracks evolution iterations | | population | Empty list | Internal state | Current payload population |

Core Operations

Seeding: Successful payloads from the initial heuristic scan are added to the population as high-fitness specimens:

# Conceptual flow from scanner_v2.py
if is_vuln and confidence != ConfidenceLevel.LOW:
    self.payload_evolver.seed([payload])
    self.payload_evolver.update_fitness(payload, 1.0)

Evolution: The evolve(count) method generates new payload variants through genetic operations:

1. Selection: High-fitness payloads are selected as parents
2. Crossover: Parent payloads are combined to create offspring
3. Mutation: Random modifications are applied to offspring
4. Fitness Evaluation: New payloads are tested and scored

Sources: wshawk/scanner_v2.py:30, wshawk/scanner_v2.py:74, wshawk/scanner_v2.py:232-234, wshawk/scanner_v2.py:638-640, wshawk/scanner_v2.py:683

Mutation Strategies

The evolver applies multiple mutation strategies to create payload variants optimized for WAF bypass and exploitation:

graph TB
    Parent["Parent Payload<br/>High Fitness Score"]
    
    Parent --> Encode["Encoding Mutations<br/>URL/Double-URL/Unicode"]
    Parent --> Case["Case Mutations<br/>Mixed Case Variations"]
    Parent --> Null["Null Byte Injection<br/>%00 insertions"]
    Parent --> Comment["Comment Injection<br/>/**/ and --"]
    Parent --> Polyglot["Polyglot Generation<br/>Multi-context payloads"]
    
    Encode --> Offspring["Offspring<br/>Generation N+1"]
    Case --> Offspring
    Null --> Offspring
    Comment --> Offspring
    Polyglot --> Offspring
    
    Offspring --> Test["Test Against Target"]
    Test --> Fitness["Fitness Scoring<br/>0.0 to 1.0"]
    
    Fitness --> |"High fitness"| NextGen["Next Generation<br/>Seed"]
    Fitness --> |"Low fitness"| Discard["Discard"]

Sources: docs/V3_COMPLETE_GUIDE.md:189-201

---

Lifecycle and Integration

The Smart Payload Evolution System operates across three distinct phases during a WSHawk scan, with each phase building upon the intelligence gathered in the previous phase.

Phase 1: Learning Phase (5-10 seconds)

During connection establishment, the scanner enters a passive observation mode to collect baseline data:

sequenceDiagram
    participant Scanner as WSHawkV2
    participant WS as WebSocket<br/>Connection
    participant CA as ContextAwareGenerator
    participant FL as FeedbackLoop
    participant MA as MessageAnalyzer
    
    Scanner->>WS: Connect & Authenticate
    Scanner->>WS: Listen for messages (5s)
    
    loop Sample Collection
        WS->>Scanner: Sample Message
        Scanner->>MA: learn_from_messages([samples])
        Scanner->>CA: learn_from_message(msg)
        Scanner->>FL: establish_baseline(msg, time)
    end
    
    MA->>Scanner: Format: JSON/XML/etc
    MA->>Scanner: Injectable Fields: [field1, field2, ...]
    CA->>Scanner: analysis_complete = True
    FL->>Scanner: Baseline established
    
    Scanner->>Scanner: learning_complete = True

Sources: wshawk/scanner_v2.py:112-175

Phase 2: Active Scanning Phase

During vulnerability testing, the feedback loop continuously analyzes server responses to identify promising attack vectors:

sequenceDiagram
    participant Scanner as WSHawkV2
    participant Payloads as WSPayloads
    participant CA as ContextAwareGenerator
    participant WS as WebSocket
    participant FL as FeedbackLoop
    participant PE as PayloadEvolver
    
    Scanner->>Payloads: get_sql_injection()
    Payloads->>Scanner: Static Payloads
    
    loop For each payload
        Scanner->>CA: Context-aware injection
        CA->>Scanner: Structured message
        Scanner->>WS: Send payload
        WS->>Scanner: Response + timing
        
        Scanner->>FL: analyze_response(payload, response, time)
        FL->>Scanner: (signal, confidence)
        
        alt Signal = ERROR or HIGH confidence
            Scanner->>PE: seed([payload])
            Scanner->>PE: update_fitness(payload, 1.0)
        end
    end
    
    Note over PE: Population grows with<br/>successful payloads

Sources: wshawk/scanner_v2.py:177-256, wshawk/scanner_v2.py:258-341

Phase 3: Evolution Phase (Post-Scan)

After the initial heuristic scan completes, the evolver generates and tests novel payload variants:

sequenceDiagram
    participant Scanner as WSHawkV2
    participant PE as PayloadEvolver
    participant FL as FeedbackLoop
    participant CA as ContextAwareGenerator
    participant WS as WebSocket
    participant Verify as VulnerabilityVerifier
    
    Scanner->>PE: Check population size
    
    alt Population > 0
        Scanner->>PE: evolve(count=30)
        PE->>PE: Genetic crossover & mutation
        PE->>Scanner: Evolved payloads
        
        Scanner->>FL: get_priority_categories()
        FL->>Scanner: Top 3 categories by signal
        
        loop For each priority category
            Scanner->>CA: generate_payloads(category, 10)
            CA->>Scanner: Context-aware payloads
        end
        
        loop For each evolved/context payload
            Scanner->>WS: Send payload
            WS->>Scanner: Response
            
            Scanner->>FL: analyze_response()
            Scanner->>Verify: verify_sql_injection()<br/>verify_xss()<br/>verify_command_injection()
            
            alt Vulnerability confirmed
                Scanner->>PE: update_fitness(payload, 1.0)
                Scanner->>Scanner: Record as "Evolved" finding
            end
        end
        
        PE->>PE: generation++
    end

Sources: wshawk/scanner_v2.py:637-703

---

Operational Flow: Complete System Integration

The following diagram illustrates how the Smart Payload Evolution System integrates into the complete WSHawkV2 scanning workflow:

graph TB
    Start["Scan Start<br/>WSHawkV2.run_heuristic_scan()"]
    Connect["WebSocket Connect"]
    
    subgraph "Phase 1: Learning"
        Listen["Passive Listening<br/>5 seconds"]
        LearnMsg["MessageAnalyzer<br/>learn_from_messages()"]
        LearnCtx["ContextAwareGenerator<br/>learn_from_message()"]
        LearnBase["FeedbackLoop<br/>establish_baseline()"]
        FormatDetect["Format Detection<br/>JSON/XML/Protobuf"]
        FieldExtract["Injectable Fields<br/>Extraction"]
    end
    
    subgraph "Phase 2: Active Scanning"
        LoadPayloads["WSPayloads.get_*()"]
        ContextInject["Context-Aware<br/>Injection"]
        SendPayload["Rate-Limited<br/>Send"]
        ReceiveResp["Receive Response"]
        FeedbackAnalysis["FeedbackLoop<br/>analyze_response()"]
        VerifyVuln["VulnerabilityVerifier"]
        
        SeedSuccess["PayloadEvolver.seed()<br/>update_fitness(1.0)"]
    end
    
    subgraph "Phase 3: Evolution"
        CheckPop{"Population > 0?"}
        Evolve["PayloadEvolver.evolve(30)"]
        GetPriority["FeedbackLoop<br/>get_priority_categories()"]
        GenContext["ContextAwareGenerator<br/>generate_payloads()"]
        TestEvolved["Test Evolved Payloads"]
        UpdateFitness["Update Fitness Scores"]
    end
    
    Report["Generate Report<br/>Include 'Evolved' Findings"]
    
    Start --> Connect
    Connect --> Listen
    
    Listen --> LearnMsg
    Listen --> LearnCtx
    Listen --> LearnBase
    
    LearnMsg --> FormatDetect
    FormatDetect --> FieldExtract
    FieldExtract --> LoadPayloads
    
    LoadPayloads --> ContextInject
    ContextInject --> SendPayload
    SendPayload --> ReceiveResp
    ReceiveResp --> FeedbackAnalysis
    FeedbackAnalysis --> VerifyVuln
    
    VerifyVuln --> |"Confirmed"| SeedSuccess
    VerifyVuln --> |"Continue"| LoadPayloads
    
    SeedSuccess --> CheckPop
    
    CheckPop --> |"Yes"| Evolve
    CheckPop --> |"No"| Report
    
    Evolve --> GetPriority
    GetPriority --> GenContext
    GenContext --> TestEvolved
    TestEvolved --> UpdateFitness
    UpdateFitness --> Report

Sources: wshawk/scanner_v2.py:593-806

---

Configuration and Usage

Enabling Smart Payloads

The Smart Payload Evolution System is an opt-in feature that can be enabled through multiple interfaces:

CLI Flag

# Advanced CLI with smart payloads enabled
wshawk-advanced ws://target.com --smart-payloads

# Full mode (includes smart payloads)
wshawk-advanced ws://target.com --full

Sources: wshawk/advanced_cli.py:28, wshawk/advanced_cli.py:73-74, wshawk/advanced_cli.py:97

Python API

from wshawk.scanner_v2 import WSHawkV2

scanner = WSHawkV2("ws://target.com")
scanner.use_smart_payloads = True  # Enable evolution engine
scanner.use_headless_browser = True
scanner.use_oast = True

await scanner.run_heuristic_scan()

Sources: wshawk/scanner_v2.py:75, README.md:255-263

Configuration File

Smart payloads can be enabled in wshawk.yaml:

scanner:
  features:
    smart_payloads: true
    playwright: true
    oast: true
  rate_limit: 10

Sources: wshawk/advanced_cli.py:97, README.md:137-150

Performance Characteristics

| Metric | Without Smart Payloads | With Smart Payloads | |--------|------------------------|---------------------| | Scan Duration | Baseline | +15-30% | | Payload Count | 22,000+ static | +30-50 evolved payloads | | WAF Bypass Rate | Standard | Significantly improved | | Novel Findings | Standard | May discover 0-day variants | | Memory Usage | ~50MB | ~75MB (population storage) |

Sources: wshawk/scanner_v2.py:74, wshawk/scanner_v2.py:640

---

Output and Reporting

Vulnerabilities discovered through the Smart Payload Evolution System are clearly marked in reports with an "Evolved" designation to distinguish them from findings made with static payloads.

Report Differentiation

# Example vulnerability object for evolved findings
{
    'type': 'SQL Injection (Evolved)',
    'severity': 'HIGH',
    'confidence': 'HIGH',
    'description': '[Smart Payload] Novel payload discovered by evolutionary mutation',
    'payload': '...evolved_payload...',
    'response_snippet': '...server_response...',
    'recommendation': 'Novel payload discovered by evolutionary mutation'
}

Sources: wshawk/scanner_v2.py:684-692

Console Output

During the evolution phase, the scanner provides real-time feedback:

[*] Running evolved payload phase...
[*] Testing 37 evolved/context payloads...
[!] [EVOLVED] SQL Injection [HIGH]: Time-based blind injection confirmed
[+] Evolution phase complete (gen 1)

Sources: wshawk/scanner_v2.py:639, wshawk/scanner_v2.py:649, wshawk/scanner_v2.py:682, wshawk/scanner_v2.py:702

---

Technical Implementation Details

Module File Locations

| Module | File Path | Primary Classes | |--------|-----------|-----------------| | Context Generator | wshawk/smart_payloads/context_generator.py | ContextAwareGenerator | | Feedback Loop | wshawk/smart_payloads/feedback_loop.py | FeedbackLoop, ResponseSignal | | Payload Evolver | wshawk/smart_payloads/payload_evolver.py | PayloadEvolver |

Sources: wshawk/scanner_v2.py:28-30

Dependencies

The Smart Payload Evolution System requires the following Python packages for genetic algorithm operations:

• numpy>=1.26.0 - Matrix operations for fitness scoring
• scipy>=1.11.0 - Statistical analysis for baseline comparison

Sources: requirements.txt:19-21

State Management

The evolution system maintains state across scan phases using instance variables on the WSHawkV2 scanner object:

| Variable | Type | Purpose | |----------|------|---------| | scanner.use_smart_payloads | bool | Feature flag | | scanner.context_generator | ContextAwareGenerator | Context analysis instance | | scanner.feedback_loop | FeedbackLoop | Response analysis instance | | scanner.payload_evolver | PayloadEvolver | Evolution engine instance | | scanner.learning_complete | bool | Phase transition flag |

Sources: wshawk/scanner_v2.py:72-75, wshawk/scanner_v2.py:96

---

Relationship to Other Systems

The Smart Payload Evolution System is a component of the broader Red Team Execution Plane and interacts with several other WSHawk subsystems:

• WSHawkV2 Scanner Engine: The evolution system is integrated into the scanner's heuristic scan lifecycle
• Payload Management System: Static payloads from WSPayloads serve as the initial gene pool
• Analysis and Verification Modules: The VulnerabilityVerifier confirms exploitability of evolved payloads
• Rate Limiting and Session State: Evolution phase testing respects rate limits to avoid detection

Sources: wshawk/scanner_v2.py:593-806