Core Architecture

Relevant source files

CHANGELOG.md

pyproject.toml

wshawk/init.py

wshawk/scanner_v2.py

Purpose and Scope

This document provides a comprehensive technical overview of WSHawk's internal architecture, focusing on the core scanning engine, intelligence modules, and processing pipeline. It describes how major components interact to enable intelligent, context-aware WebSocket security testing.

For detailed information about:

Scanner initialization, learning phase, and test orchestration → see Scanner Engine (WSHawkV2)
Message intelligence, server fingerprinting, and vulnerability verification → see Intelligence Modules
Payload loading, mutation strategies, and WAF bypass techniques → see Payload Management System
CLI usage and entry points → see CLI Command Reference
Specific vulnerability testing implementations → see Vulnerability Detection Modules

Architectural Overview

WSHawk implements a five-stage intelligence-driven testing pipeline orchestrated by the WSHawkV2 scanner class. The architecture separates concerns into distinct layers: orchestration, intelligence, testing, verification, and reporting.

Core Design Principles

| Principle | Implementation | | --- | --- | | Intelligence-Driven Testing | Learning phase precedes payload injection; context analysis informs attack strategy | | Multi-Layered Verification | Pattern matching → context analysis → browser execution → out-of-band confirmation | | Separation of Concerns | Distinct modules for message parsing, fingerprinting, verification, rate limiting, reporting | | Optional Advanced Features | Playwright and OAST can be disabled for lightweight deployment | | Adaptive Behavior | Rate limiter adjusts based on server responses; payloads selected based on fingerprint | | Standardized Output | CVSS v3.1 scoring and HTML reporting across all vulnerability types |

Sources: wshawk/scanner_v2.py L1-L681

pyproject.toml L1-L52

System Components

The following diagram maps WSHawk's architectural components to their concrete implementations in code:

flowchart TD

WSHawkV2["WSHawkV2<br>(scanner_v2.py:28-681)"]
init["init()<br>lines 33-75"]
connect["connect()<br>lines 77-85"]
learning["learning_phase()<br>lines 87-141"]
intelligent_scan["run_intelligent_scan()<br>lines 545-680"]
MessageIntel["MessageIntelligence<br>(message_intelligence.py)<br>Format detection"]
ServerFP["ServerFingerprinter<br>(server_fingerprint.py)<br>Tech stack detection"]
VulnVerifier["VulnerabilityVerifier<br>(vulnerability_verifier.py)<br>Confidence scoring"]
StateMachine["SessionStateMachine<br>(state_machine.py)<br>Auth sequence"]
RateLimiter["TokenBucketRateLimiter<br>(rate_limiter.py)<br>Adaptive throttling"]
WSPayloads["WSPayloads<br>(main.py)<br>Static loader"]
PayloadFiles["Payload Files<br>payloads/.txtpayloads/**/.json"]
Mutators["Mutation Engine<br>(mutators/)<br>WAF bypass"]
HeadlessBrowser["HeadlessBrowserXSSVerifier<br>(headless_xss_verifier.py)<br>Playwright execution"]
OAST["OASTProvider<br>(oast_provider.py)<br>Blind vuln detection"]
SessionTester["SessionHijackingTester<br>(session_hijacking_tester.py)<br>6 session tests"]
SQLTest["test_sql_injection_v2()<br>lines 143-213"]
XSSTest["test_xss_v2()<br>lines 215-293"]
CMDTest["test_command_injection_v2()<br>lines 295-359"]
PathTest["test_path_traversal_v2()<br>lines 361-400"]
XXETest["test_xxe_v2()<br>lines 402-456"]
NoSQLTest["test_nosql_injection_v2()<br>lines 458-496"]
SSRFTest["test_ssrf_v2()<br>lines 498-543"]
Reporter["EnhancedHTMLReporter<br>(enhanced_reporter.py)<br>HTML generation"]
Logger["Logger<br>(main.py / logger.py)<br>Colored output"]
Vulnerabilities["self.vulnerabilities[]<br>Findings list"]

init -.-> MessageIntel
init -.-> ServerFP
init -.-> VulnVerifier
init -.-> StateMachine
init -.-> RateLimiter
init -.-> Reporter
init -.-> HeadlessBrowser
init -.-> OAST
learning -.-> MessageIntel
learning -.-> ServerFP
SQLTest -.-> WSPayloads
XSSTest -.-> WSPayloads
CMDTest -.-> WSPayloads
SQLTest -.-> VulnVerifier
XSSTest -.-> VulnVerifier
XSSTest -.-> HeadlessBrowser
XXETest -.-> OAST
SQLTest -.-> RateLimiter
XSSTest -.-> RateLimiter
SQLTest -.-> Vulnerabilities
XSSTest -.-> Vulnerabilities
CMDTest -.-> Vulnerabilities
SessionTester -.-> Vulnerabilities

subgraph subGraph6 ["Output Generation"]
    Reporter
    Logger
    Vulnerabilities
    Vulnerabilities -.-> Reporter
    Reporter -.-> Logger
end

subgraph subGraph5 ["Testing Modules"]
    SQLTest
    XSSTest
    CMDTest
    PathTest
    XXETest
    NoSQLTest
    SSRFTest
end

subgraph subGraph4 ["Verification Layer"]
    HeadlessBrowser
    OAST
    SessionTester
end

subgraph subGraph3 ["Payload Management"]
    WSPayloads
    PayloadFiles
    Mutators
    WSPayloads -.-> PayloadFiles
    WSPayloads -.-> Mutators
end

subgraph subGraph2 ["Rate Limiting & Control"]
    RateLimiter
end

subgraph subGraph1 ["Intelligence Layer"]
    MessageIntel
    ServerFP
    VulnVerifier
    StateMachine
end

subgraph subGraph0 ["Scanner Orchestrator"]
    WSHawkV2
    init
    connect
    learning
    intelligent_scan
    WSHawkV2 -.-> init
end

Sources: wshawk/scanner_v2.py L28-L681

wshawk/main.py

pyproject.toml L29-L34

Scanner Orchestrator (WSHawkV2)

The WSHawkV2 class wshawk/scanner_v2.py L28-L681

serves as the central orchestrator. Its responsibilities include:

Connection management - WebSocket connection lifecycle [lines 77-85](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 77-85)
Module initialization - Instantiates all intelligence and verification modules [lines 33-75](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 33-75)
Test sequencing - Executes vulnerability tests in order [lines 545-680](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 545-680)
Result aggregation - Maintains self.vulnerabilities[] list [line 38](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 38)
Report generation - Triggers HTML report creation [lines 652-673](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 652-673)

Key attributes:

url: str                          # Target WebSocket URL
headers: Dict                     # Connection headers
vulnerabilities: List[Dict]       # Aggregated findings
message_intel: MessageIntelligence
verifier: VulnerabilityVerifier
fingerprinter: ServerFingerprinter
state_machine: SessionStateMachine
rate_limiter: TokenBucketRateLimiter
reporter: EnhancedHTMLReporter
headless_verifier: HeadlessBrowserXSSVerifier (optional)
oast_provider: OASTProvider (optional)

Sources: wshawk/scanner_v2.py L28-L75

Intelligence Layer

Four modules provide context-aware testing capabilities:

| Module | Class | Purpose | Key Methods | | --- | --- | --- | --- | | Message Analysis | MessageIntelligence | Detects message format (JSON/XML/Binary), identifies injectable fields | learn_from_messages(), inject_payload_into_message() | | Server Fingerprinting | ServerFingerprinter | Identifies language, framework, database from responses | fingerprint(), get_recommended_payloads() | | Verification | VulnerabilityVerifier | Analyzes responses to determine vulnerability confidence | verify_sql_injection(), verify_xss(), verify_command_injection() | | Session State | SessionStateMachine | Tracks authentication state, loads auth sequences | load_sequence_from_yaml(), _update_state() |

The intelligence layer is initialized during WSHawkV2.__init__() [lines 41-44](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 41-44)

and used throughout testing phases.

Sources: wshawk/scanner_v2.py L14-L18

wshawk/scanner_v2.py L41-L44

Verification Layer

Advanced verification modules provide multi-layered confirmation:

HeadlessBrowserXSSVerifier wshawk/headless_xss_verifier.py

Uses Playwright to execute JavaScript in real browser
Captures screenshots as evidence
Invoked for HIGH confidence XSS findings [lines 251-266](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 251-266)
Elevates confidence to CRITICAL upon execution [line 263](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 263)

OASTProvider wshawk/oast_provider.py

Provides out-of-band callback detection
Used for blind XXE and SSRF testing [lines 409-417](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 409-417)
Generates unique payload identifiers [line 423](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 423)
Monitors DNS/HTTP callbacks for confirmation

SessionHijackingTester wshawk/session_hijacking_tester.py

Runs 6 distinct session security tests
Executes independently after main scan [lines 592-616](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 592-616)
Results merged into main vulnerabilities list [lines 601-612](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 601-612)

Sources: wshawk/scanner_v2.py L52-L59

wshawk/scanner_v2.py L251-L266

wshawk/scanner_v2.py L409-L417

wshawk/scanner_v2.py L592-L616

Payload System

Payloads are managed through a multi-tiered system:

Static Loading - WSPayloads class wshawk/main.py

provides static methods (get_sql_injection(), get_xss(), etc.) that load payloads from text files

File Storage - Payloads stored in payloads/*.txt and payloads/**/*.json pyproject.toml L51

bundled with the package

Intelligent Selection - Scanner uses fingerprint data to select database-specific or language-specific payloads [lines 152-158](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 152-158)

[lines 304-310](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 304-310)

Mutation Engine - Located in wshawk/mutators/ directory, provides WAF bypass strategies (covered in detail in Payload Management System)

Sources: wshawk/scanner_v2.py L26

wshawk/scanner_v2.py L150

wshawk/scanner_v2.py L152-L158

pyproject.toml L50-L51

Reporting System

EnhancedHTMLReporter wshawk/enhanced_reporter.py

Generates professional HTML reports with embedded CSS/JavaScript
Includes vulnerability summary, CVSS scores, remediation guidance
Invoked at end of scan [lines 662-666](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 662-666)
Output filename: wshawk_report_YYYYMMDD_HHMMSS.html [line 669](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 669)

Logger [wshawk/main.py or wshawk/logger.py](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/wshawk/main.py or wshawk/logger.py)

Provides colored terminal output (Logger.info(), Logger.success(), Logger.vuln(), Logger.error())
Centralized logging with file output support
Used throughout scanner for progress updates

Sources: wshawk/scanner_v2.py L20

wshawk/scanner_v2.py L50

wshawk/scanner_v2.py L652-L673

wshawk/scanner_v2.py L26

Processing Pipeline

WSHawk implements a five-stage sequential pipeline orchestrated by the run_intelligent_scan() method wshawk/scanner_v2.py L545-L680

flowchart TD

Start["run_intelligent_scan called"]
Init1["Set start_time<br>line 549"]
Init2["Display banner<br>Logger.banner() line 550"]
Init3["Call connect()<br>lines 556-558"]
ConnWS["Establish WebSocket<br>websockets.connect() line 80"]
StateUpdate["Update state machine<br>line 81"]
Learn1["Call learning_phase(ws, 5)<br>line 564"]
Learn2["Collect sample messages<br>5 second window lines 94-114"]
Learn3["message_intel.learn_from_messages()<br>line 121"]
Learn4["fingerprinter.fingerprint()<br>line 132"]
Learn5["Set learning_complete flag<br>line 138"]
Test1["test_sql_injection_v2(ws)<br>line 568"]
Test2["test_xss_v2(ws)<br>line 571"]
Test3["test_command_injection_v2(ws)<br>line 574"]
Test4["test_path_traversal_v2(ws)<br>line 577"]
Test5["test_xxe_v2(ws)<br>line 580"]
Test6["test_nosql_injection_v2(ws)<br>line 583"]
Test7["test_ssrf_v2(ws)<br>line 586"]
Session1["SessionHijackingTester<br>instantiate line 597"]
Session2["run_all_tests()<br>line 598"]
Session3["Merge results into<br>self.vulnerabilities<br>lines 601-612"]
Cleanup1["Stop headless_verifier<br>lines 619-624"]
Cleanup2["Stop oast_provider<br>lines 626-631"]
Summary1["Calculate scan duration<br>lines 634-635"]
Summary2["Display statistics<br>lines 637-649"]
Summary3["reporter.generate_report()<br>lines 662-666"]
Summary4["Write HTML file<br>lines 669-671"]
Summary5["Display rate limiter stats<br>lines 676-678"]
End["Return vulnerabilities"]

Start -.-> Init1
StateUpdate -.-> Learn1
Learn5 -.-> Test1
Test7 -.-> Session1
Cleanup2 -.-> Summary1
Summary5 -.-> End

subgraph subGraph4 ["Stage 5: Report Generation"]
    Summary1
    Summary2
    Summary3
    Summary4
    Summary5
    Summary1 -.-> Summary2
    Summary2 -.-> Summary3
    Summary3 -.-> Summary4
    Summary4 -.-> Summary5
end

subgraph subGraph3 ["Stage 4: Advanced Verification"]
    Session1
    Session2
    Session3
    Cleanup1
    Cleanup2
    Session1 -.-> Session2
    Session2 -.-> Session3
    Session3 -.-> Cleanup1
    Cleanup1 -.-> Cleanup2
end

subgraph subGraph2 ["Stage 3: Vulnerability Testing"]
    Test1
    Test2
    Test3
    Test4
    Test5
    Test6
    Test7
    Test1 -.-> Test2
    Test2 -.-> Test3
    Test3 -.-> Test4
    Test4 -.-> Test5
    Test5 -.-> Test6
    Test6 -.-> Test7
end

subgraph subGraph1 ["Stage 2: Learning Phase"]
    Learn1
    Learn2
    Learn3
    Learn4
    Learn5
    Learn1 -.-> Learn2
    Learn2 -.-> Learn3
    Learn3 -.-> Learn4
    Learn4 -.-> Learn5
end

subgraph subGraph0 ["Stage 1: Initialization"]
    Init1
    Init2
    Init3
    ConnWS
    StateUpdate
    Init1 -.-> Init2
    Init2 -.-> Init3
    Init3 -.-> ConnWS
    ConnWS -.-> StateUpdate
end

Sources: wshawk/scanner_v2.py L545-L680

Stage 1: Initialization

The scanner initializes all required components during __init__() [lines 33-75](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 33-75)

Core attributes - Store URL, headers, empty vulnerabilities list
Intelligence modules - Instantiate MessageIntelligence, VulnerabilityVerifier, ServerFingerprinter, SessionStateMachine [lines 41-44](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 41-44)
Rate limiter - TokenBucketRateLimiter with adaptive enabled [lines 45-49](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 45-49)
Reporter - EnhancedHTMLReporter for HTML generation [line 50](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 50)
Optional verifiers - HeadlessBrowserXSSVerifier and OASTProvider (instantiated lazily) [lines 52-58](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 52-58)
Auth sequence - Load YAML auth config if provided [lines 61-62](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 61-62)

The run_intelligent_scan() method then establishes the WebSocket connection via connect() [lines 556-558](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 556-558)

which calls websockets.connect() [line 80](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 80)

and updates the session state machine [line 81](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 81)

Sources: wshawk/scanner_v2.py L33-L75

wshawk/scanner_v2.py L77-L85

wshawk/scanner_v2.py L545-L558

Stage 2: Learning Phase

The learning phase wshawk/scanner_v2.py L87-L141

is critical for context-aware testing:

Duration: 5 seconds (configurable) [line 564](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 564)

Process:

Passively collect WebSocket messages [lines 94-114](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 94-114)
Feed samples to MessageIntelligence.learn_from_messages() [line 121](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 121)
Feed responses to ServerFingerprinter.add_response() [line 106](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 106)
Extract format information (JSON/XML/Binary) [lines 125-129](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 125-129)
Generate server fingerprint (language/framework/database) [lines 132-136](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 132-136)
Set learning_complete flag [line 138](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 138)

Outputs:

self.sample_messages[] - Sample messages for base templates
message_intel.detected_format - MessageFormat enum value
message_intel.injectable_fields - List of field names that can receive payloads
fingerprinter state - Contains technology stack detection results

The learning phase enables intelligent payload injection where payloads are inserted into the actual message structure rather than sent as raw strings [lines 166-169](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 166-169)

[lines 228-231](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 228-231)

Sources: wshawk/scanner_v2.py L87-L141

wshawk/scanner_v2.py L564

Stage 3: Vulnerability Testing

Seven vulnerability test methods execute sequentially [lines 568-587](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 568-587)

Each test method follows a common pattern:

1. Load base payloads from WSPayloads
2. Get recommended payloads from fingerprinter (if available)
3. For each payload:
   a. Inject into message structure using message_intel
   b. Send via WebSocket (ws.send)
   c. Receive response with timeout (asyncio.wait_for)
   d. Verify vulnerability using VulnVerifier
   e. If vulnerable and confidence >= MEDIUM:
      - Log finding
      - Append to self.vulnerabilities[]
   f. Apply rate limiting (asyncio.sleep)

Example: SQL Injection [lines 143-213](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 143-213)

Base payloads: WSPayloads.get_sql_injection()[:100] [line 150](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 150)
Database-specific: fingerprinter.get_recommended_payloads() [lines 154-158](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 154-158)
Injection: message_intel.inject_payload_into_message() [lines 167-169](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 167-169)
Verification: verifier.verify_sql_injection() [lines 185-187](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 185-187)
Confidence filtering: Only MEDIUM/HIGH/CRITICAL logged [line 189](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 189)

Example: XSS [lines 215-293](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 215-293)

Additional browser verification for HIGH confidence [lines 251-266](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 251-266)
Playwright execution confirmation elevates to CRITICAL [line 263](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 263)
Screenshot evidence captured [line 258](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 258)

Sources: wshawk/scanner_v2.py L143-L213

wshawk/scanner_v2.py L215-L293

wshawk/scanner_v2.py L295-L359

wshawk/scanner_v2.py L361-L400

wshawk/scanner_v2.py L402-L456

wshawk/scanner_v2.py L458-L496

wshawk/scanner_v2.py L498-L543

Stage 4: Advanced Verification

After core vulnerability tests, advanced verification modules execute:

Session Hijacking Tests [lines 592-616](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 592-616)

session_tester = SessionHijackingTester(self.url)
session_results = await session_tester.run_all_tests()

for result in session_results:
    if result.is_vulnerable:
        self.vulnerabilities.append({
            'type': f'Session Security: {result.vuln_type.value}',
            'cvss_score': result.cvss_score,
            # ... other fields
        })

These tests run independently and include:

Token reuse attacks
Subscription spoofing
User impersonation
Channel access violations
Session fixation
Privilege escalation

Resource Cleanup [lines 619-631](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 619-631)

Stop Playwright browser if active
Stop OAST provider if active
Log cleanup status

Sources: wshawk/scanner_v2.py L592-L631

Stage 5: Report Generation

Final stage aggregates results and generates artifacts:

Calculate metrics - Scan duration, message counts [lines 634-640](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 634-640)
Display summary - Log vulnerability counts by confidence level [lines 642-649](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 642-649)
Generate HTML - Call reporter.generate_report() with vulnerabilities, scan info, and fingerprint data [lines 652-666](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 652-666)
Save report - Write to timestamped file wshawk_report_YYYYMMDD_HHMMSS.html [lines 669-671](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 669-671)
Display stats - Rate limiter performance metrics [lines 676-678](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 676-678)
Return - Return vulnerabilities list for programmatic access [line 680](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 680)

Report contains:

Vulnerability summary with CVSS scores
Server fingerprint information
Screenshot evidence (if browser verification used)
Request/response logs
Remediation guidance

Sources: wshawk/scanner_v2.py L634-L680

Component Integration

The following diagram illustrates how components interact during a typical SQL injection test:

sequenceDiagram
  participant p1 as WSHawkV2<br/>(Orchestrator)
  participant p2 as MessageIntelligence
  participant p3 as ServerFingerprinter
  participant p4 as WSPayloads
  participant p5 as WebSocket Connection
  participant p6 as VulnerabilityVerifier
  participant p7 as TokenBucketRateLimiter
  participant p8 as self.vulnerabilities[]

  note over p1: test_sql_injection_v2() called
  p1->>p4: get_sql_injection()
  p4-->>p1: base_payloads[100 items]
  p1->>p3: fingerprint()
  p3-->>p1: fingerprint.database = "MySQL"
  p1->>p3: get_recommended_payloads(fingerprint)
  p3-->>p1: recommended['sql'] = MySQL-specific payloads
  loop For each payload
    p1->>p2: inject_payload_into_message(base_msg, payload)
    p2-->>p1: injected_messages[] (JSON fields filled)
  loop For each injected_message
    p1->>p7: acquire() [rate limit]
    p7-->>p1: Token acquired
    p1->>p5: send(injected_message)
    note over p5: Payload delivered
    p1->>p5: recv(timeout=2.0)
    p5-->>p1: response
    p1->>p3: add_response(response)
    note over p3: Update fingerprint
    p1->>p6: verify_sql_injection(response, payload)
    p6-->>p1: is_vuln=True, confidence=HIGH, description
  alt confidence >= MEDIUM
    p1->>p8: append(vulnerability_dict)
    note over p1: Log finding with Logger.vuln()
  end
  end
  end

Sources: wshawk/scanner_v2.py L143-L213

Key Integration Points

Intelligence → Payload Injection

MessageIntelligence.inject_payload_into_message() uses learned message structure [lines 167-169](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 167-169)
If learning_complete flag is False, falls back to raw payload [lines 170-171](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 170-171)

Fingerprinting → Payload Selection

ServerFingerprinter.get_recommended_payloads() provides tech-specific vectors [lines 154-158](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 154-158)
Database-specific SQL payloads for MySQL/PostgreSQL/MSSQL
Language-specific command injection payloads for Python/Node.js/PHP

Verification → Confidence Scoring

VulnerabilityVerifier analyzes responses using multiple techniques [lines 185-187](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 185-187)
Returns (is_vulnerable, confidence_level, description) tuple
Only MEDIUM/HIGH/CRITICAL vulnerabilities logged [line 189](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 189)

Rate Limiting → Request Throttling

TokenBucketRateLimiter.acquire() enforces rate limits [line 512](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 512)
Adaptive adjustments based on server errors
Stats tracked: total_requests, total_waits, adaptive_adjustments [lines 676-678](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 676-678)

Browser Verification → XSS Confirmation

Triggered for HIGH confidence XSS findings [line 251](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 251)
HeadlessBrowserXSSVerifier.verify_xss_execution() tests actual execution [lines 257-259](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 257-259)
Elevates confidence to CRITICAL if successful [line 263](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 263)
Captures screenshot evidence [line 258](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 258)

OAST → Blind Vulnerability Detection

OASTProvider.generate_payload() creates unique callback URLs [line 423](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/line 423)
Used for XXE and SSRF blind testing [lines 409-424](https://github.com/noobforanonymous/wshawk/blob/0eebedf4/lines 409-424)
Provider monitors callbacks to confirm exploitation

Sources: wshawk/scanner_v2.py L143-L213

wshawk/scanner_v2.py L215-L293

wshawk/scanner_v2.py L295-L359

wshawk/scanner_v2.py L402-L456

Module Dependencies

The scanner's dependency tree:

flowchart TD

scanner_v2["scanner_v2.py<br>WSHawkV2"]
asyncio["asyncio"]
json["json"]
time["time"]
datetime["datetime"]
websockets["websockets>=12.0"]
playwright["playwright>=1.40.0"]
aiohttp["aiohttp>=3.9.0"]
yaml["PyYAML>=6.0"]
msg_intel["message_intelligence.py<br>MessageIntelligence"]
vuln_verifier["vulnerability_verifier.py<br>VulnerabilityVerifier"]
server_fp["server_fingerprint.py<br>ServerFingerprinter"]
state_machine["state_machine.py<br>SessionStateMachine"]
headless["headless_xss_verifier.py<br>HeadlessBrowserXSSVerifier"]
oast["oast_provider.py<br>OASTProvider / SimpleOASTServer"]
session["session_hijacking_tester.py<br>SessionHijackingTester"]
rate_limiter["rate_limiter.py<br>TokenBucketRateLimiter"]
reporter["enhanced_reporter.py<br>EnhancedHTMLReporter"]
logger["main.py / logger.py<br>Logger"]
payloads["main.py<br>WSPayloads"]

headless -.-> playwright
oast -.-> aiohttp
session -.-> websockets

subgraph subGraph4 ["Utility Modules"]
    rate_limiter
    reporter
    logger
    payloads
end

subgraph subGraph3 ["Verification Modules"]
    headless
    oast
    session
end

subgraph subGraph2 ["Intelligence Modules"]
    msg_intel
    vuln_verifier
    server_fp
    state_machine
end

subgraph subGraph1 ["External Dependencies"]
    websockets
    playwright
    aiohttp
    yaml
end

subgraph subGraph0 ["Python Standard Library"]
    asyncio
    json
    time
    datetime
end

Sources: wshawk/scanner_v2.py L1-L26

pyproject.toml L29-L34

Import Structure wshawk/scanner_v2.py L1-L26

Lines 7-12: Python standard library
Lines 14-23: Intelligence and verification modules
Line 26: Payload and logging utilities from __main__.py

External Dependencies pyproject.toml L29-L34

websockets>=12.0 - WebSocket client protocol
playwright>=1.40.0 - Browser automation for XSS verification
aiohttp>=3.9.0 - HTTP client for OAST callbacks
PyYAML>=6.0 - YAML parsing for auth sequences

Entry Points and CLI Integration

The scanner is accessible through four CLI commands and one Python API:

| Entry Point | Module | Function | Purpose | | --- | --- | --- | --- | | wshawk | wshawk.__main__ | cli() | Quick scan with all features | | wshawk-interactive | wshawk.interactive | cli() | Menu-driven testing | | wshawk-advanced | wshawk.advanced_cli | cli() | Granular control | | wshawk-defensive | wshawk.defensive_cli | cli() | Blue team validation | | Python API | wshawk.scanner_v2 | WSHawkV2 class | Programmatic usage |

Sources: pyproject.toml L41-L45

All CLI commands eventually instantiate WSHawkV2 and call run_intelligent_scan(), with differences in:

Command-line argument parsing
Default option values
User interaction flow
Feature enablement flags

For details on CLI usage patterns, see CLI Command Reference. For Python API usage, see Python API Usage.