Offensive Testing

Offensive Testing

Relevant source files

Purpose and Scope

This document provides an overview of WSHawk's offensive security testing capabilities, including vulnerability detection modules, intelligent verification methods, and the testing workflow pipeline. Offensive testing focuses on discovering exploitable vulnerabilities in WebSocket applications through active penetration testing techniques.

For detailed information about individual vulnerability modules and their implementation, see Vulnerability Detection Modules. For browser-based verification and out-of-band testing techniques, see Advanced Verification: Playwright and OAST. For session security testing, see Session Hijacking Tests. For blue team security validation, see Defensive Validation.

Sources: README.md L1-L245

scanner_v2.py L1-L681

Vulnerability Testing Workflow

WSHawk implements a five-phase intelligence-driven testing workflow that distinguishes it from basic pattern-matching scanners. The process begins with a passive learning phase, followed by context-aware payload injection, multi-layered verification, and comprehensive reporting.

End-to-End Testing Pipeline

Sources: scanner_v2.py L87-L141

scanner_v2.py L545-L680

Vulnerability Detection Modules

WSHawk tests for seven primary vulnerability categories, each implemented as a dedicated method in the WSHawkV2 class. All tests leverage the learning phase intelligence to perform context-aware payload injection.

| Vulnerability Type | Test Method | Payload Count | OAST Support | Primary Verification | | --- | --- | --- | --- | --- | | SQL Injection | test_sql_injection_v2() | 22,000+ | No | Error-based detection | | Cross-Site Scripting | test_xss_v2() | 22,000+ | No | Browser execution | | Command Injection | test_command_injection_v2() | 22,000+ | No | Output detection | | Path Traversal | test_path_traversal_v2() | ~5,000 | No | File content detection | | XML External Entity | test_xxe_v2() | ~3,000 | Yes | Entity processing | | NoSQL Injection | test_nosql_injection_v2() | ~5,000 | No | Query error detection | | SSRF | test_ssrf_v2() | Internal targets | Yes | Metadata access |

Sources: scanner_v2.py L143-L543

README.md L32-L34

Vulnerability Type Details

SQL Injection Testing

The test_sql_injection_v2() method implements database-aware testing using server fingerprinting. When ServerFingerprinter identifies the backend database (MySQL, PostgreSQL, MSSQL, Oracle), the scanner prioritizes database-specific payloads for improved detection accuracy.

Key Features:

  • Intelligent payload injection into detected message fields
  • Database-specific payload selection based on fingerprinting
  • Error-based and blind detection techniques
  • Integration with VulnerabilityVerifier for confidence scoring

Sources: scanner_v2.py L143-L213

Cross-Site Scripting Testing

The test_xss_v2() method implements context-aware XSS detection with optional browser-based verification. Unlike basic reflection scanners, WSHawk analyzes the injection context (HTML attribute, JavaScript string, etc.) and verifies actual script execution using Playwright.

Verification Levels:

  1. Pattern-based (MEDIUM confidence): Payload appears in response with dangerous context
  2. Browser-verified (CRITICAL confidence): Payload executes in Chromium via HeadlessBrowserXSSVerifier

Sources: scanner_v2.py L215-L293

Command Injection Testing

The test_command_injection_v2() method uses language-specific payloads when the server programming language is identified. It detects both in-band (output-based) and blind command execution.

Detection Methods:

  • Command output in WebSocket responses
  • Timing-based blind detection
  • System file access confirmation

Sources: scanner_v2.py L295-L359

XML External Entity (XXE) Testing

The test_xxe_v2() method integrates with the OAST provider for blind XXE detection. When use_oast is enabled, payloads include DNS/HTTP callbacks to detect out-of-band entity resolution.

Sources: scanner_v2.py L402-L456

NoSQL Injection Testing

The test_nosql_injection_v2() method tests MongoDB and other NoSQL query manipulation through operator injection ($ne, $gt, etc.) and JavaScript execution contexts.

Sources: scanner_v2.py L458-L496

Server-Side Request Forgery Testing

The test_ssrf_v2() method attempts to access internal endpoints, cloud metadata services, and localhost resources. Detection relies on server responses indicating successful internal network access.

Internal Targets:

  • http://localhost / http://127.0.0.1
  • http://169.254.169.254/latest/meta-data/ (AWS metadata)
  • http://metadata.google.internal (GCP metadata)

Sources: scanner_v2.py L498-L543

Intelligence-Driven Testing Architecture

WSHawk employs three intelligence modules that transform generic payload spraying into context-aware security testing. These modules analyze server behavior during the learning phase and adapt testing strategies accordingly.

Intelligence Module Integration

Sources: scanner_v2.py L87-L141

scanner_v2.py L15-L19

MessageIntelligence: Format Detection and Smart Injection

The MessageIntelligence class analyzes message structure to determine format (JSON, XML, binary, plain text) and identifies injectable fields. This enables the scanner to inject payloads into the correct locations rather than blindly replacing entire messages.

Key Method:

  • inject_payload_into_message(base_message, payload) - Returns list of intelligently-crafted messages with payload injected into each detected field

Usage in Scanner:

Sources: scanner_v2.py L15

scanner_v2.py L166-L172

ServerFingerprinter: Technology Stack Detection

The ServerFingerprinter class identifies server technologies by analyzing error messages, stack traces, and response patterns collected during testing. It recommends database-specific SQL payloads, language-specific command injection vectors, and framework-specific attack techniques.

Key Methods:

  • add_response(message) - Accumulates response data for analysis
  • fingerprint() - Returns detected language, framework, and database
  • get_recommended_payloads(fingerprint) - Returns technology-specific payloads

Usage in Scanner:

Sources: scanner_v2.py L17

scanner_v2.py L105-L106

scanner_v2.py L153-L158

VulnerabilityVerifier: Confidence-Based Detection

The VulnerabilityVerifier class provides multi-layered verification logic that goes beyond simple pattern matching. It analyzes response characteristics to assign confidence levels (LOW, MEDIUM, HIGH, CRITICAL) and reduce false positives.

Verification Methods:

  • verify_sql_injection(response, payload) - Detects error messages, syntax patterns
  • verify_xss(response, payload) - Context analysis, dangerous insertion points
  • verify_command_injection(response, payload) - Output patterns, execution indicators
  • verify_path_traversal(response, payload) - File content signatures

Return Format: (is_vulnerable: bool, confidence: ConfidenceLevel, description: str)

Sources: scanner_v2.py L16

scanner_v2.py L185-L201

Verification Methods

WSHawk implements three verification layers that progressively confirm exploitability, reducing false positives and providing actionable evidence.

Three-Layer Verification Architecture

Sources: scanner_v2.py L250-L271

scanner_v2.py L52-L58

Layer 1: Pattern-Based Verification (Standard)

All vulnerability tests use the VulnerabilityVerifier class to analyze responses for exploit indicators. This layer provides immediate feedback without external dependencies.

Indicators by Vulnerability Type:

| Type | Detection Indicators | | --- | --- | | SQL Injection | Database error messages, ODBC warnings, SQL syntax errors | | XSS | Payload in dangerous contexts, unescaped script tags | | Command Injection | Command output patterns, system file contents | | Path Traversal | /etc/passwd contents, Windows system files | | XXE | Entity processing errors, external entity references | | NoSQL | MongoDB errors, BSON warnings, query operator syntax | | SSRF | Metadata endpoints, connection refused messages |

Sources: scanner_v2.py L185-L191

scanner_v2.py L244-L248

Layer 2: Browser-Based Verification (XSS Only)

When use_headless_browser is enabled, XSS findings with HIGH confidence trigger browser-based verification using the HeadlessBrowserXSSVerifier class. This verifies that the payload actually executes JavaScript in a real browser environment.

Workflow:

  1. Pattern-based detection finds potential XSS (MEDIUM/HIGH confidence)
  2. For HIGH confidence findings, spawn headless Chromium via Playwright
  3. Inject response into browser DOM
  4. Monitor for alert() calls, console messages, or DOM manipulation
  5. If execution confirmed, upgrade to CRITICAL confidence and capture screenshot

Key Code:

Sources: scanner_v2.py L21

scanner_v2.py L250-L272

Layer 3: Out-of-Band Verification (XXE/SSRF)

For blind vulnerabilities like XXE and SSRF, the OASTProvider generates unique callback URLs that include DNS subdomains or HTTP endpoints. When the server processes the payload, it makes external requests that the OAST server logs as proof of exploitation.

OAST Workflow:

  1. Scanner starts OASTProvider (either custom server or Interactsh)
  2. For XXE payloads, generate XML with external entity referencing OAST domain
  3. For SSRF payloads, inject OAST HTTP URL
  4. Monitor OAST server for incoming DNS queries or HTTP requests
  5. Match callback identifiers to specific payloads

Key Code:

Sources: scanner_v2.py L22

scanner_v2.py L409-L426

WSHawkV2 Scanner Class Architecture

The WSHawkV2 class serves as the main orchestrator, coordinating intelligence modules, rate limiting, verification layers, and reporting.

Class Structure and Dependencies

Sources: scanner_v2.py L28-L76

scanner_v2.py L143-L680

Initialization and Configuration

The WSHawkV2.__init__() method instantiates all intelligence and verification modules. Key configuration flags control advanced features:

Configuration Options:

  • use_headless_browser (default: True) - Enable Playwright browser verification for XSS
  • use_oast (default: True) - Enable out-of-band testing for XXE/SSRF
  • max_rps (default: 10) - Maximum requests per second for rate limiting
  • auth_sequence (optional) - YAML file path for authentication flow

Sources: scanner_v2.py L33-L75

Scan Execution Flow

The run_intelligent_scan() method implements the complete testing workflow:

Execution Steps:

  1. Connect to WebSocket target via connect()
  2. Learn for 5 seconds via learning_phase()
  3. Execute 7 vulnerability tests sequentially
  4. Test session security via SessionHijackingTester
  5. Cleanup browser and OAST resources
  6. Generate HTML report via EnhancedHTMLReporter
  7. Display summary statistics

Rate Limiting: Each test respects the TokenBucketRateLimiter with adaptive rate adjustment based on server response times.

Sources: scanner_v2.py L545-L680

Payload Management and Mutation

WSHawk's payload system combines a large static payload library (22,000+ vectors) with intelligent mutation strategies for WAF bypass. For mutation engine details, see the separate Mutation Engine documentation.

Payload Loading

The WSPayloads class provides static methods to load payloads from text files in the payloads/ directory:

Payload Methods:

  • get_sql_injection() - SQL injection payloads from multiple databases
  • get_xss() - XSS payloads across multiple contexts
  • get_command_injection() - OS command execution vectors
  • get_path_traversal() - File system access payloads
  • get_xxe() - XML external entity payloads
  • get_nosql_injection() - NoSQL operator injection payloads

Sources: scanner_v2.py L26

Intelligent Payload Selection

Rather than testing all 22,000+ payloads (which would take hours), WSHawk intelligently selects payloads based on:

  1. Server fingerprinting - Use database-specific SQL payloads if MySQL/PostgreSQL/etc. detected
  2. Language detection - Use language-specific command payloads if Python/PHP/Node.js detected
  3. Subset sampling - Test representative subset (100-200 payloads per type) for speed
  4. Confidence-based stopping - Stop testing once HIGH/CRITICAL confidence finding confirmed

Example from SQL Testing:

Sources: scanner_v2.py L150-L158

scanner_v2.py L305-L310

Traffic Logging and Evidence Collection

Throughout testing, WSHawk maintains detailed logs of all WebSocket traffic for inclusion in the final report. This provides auditable evidence of each vulnerability finding.

Logging Infrastructure

Message Counters:

  • messages_sent - Total payloads transmitted
  • messages_received - Total responses received
  • Per-test timing and statistics

Traffic Logs:

  • Request/response pairs stored in traffic_logs list
  • Timestamps for each interaction
  • Response snippets included in vulnerability records

Sources: scanner_v2.py L65-L76

scanner_v2.py L637-L640

Report Generation

After all tests complete, WSHawk generates a professional HTML report using the EnhancedHTMLReporter class. The report includes:

Report Sections:

  • Executive summary with vulnerability counts by severity
  • CVSS v3.1 scores for each finding
  • Detailed vulnerability descriptions with evidence
  • Screenshots from browser-based XSS verification
  • Raw WebSocket traffic logs
  • Server fingerprint information
  • Remediation recommendations

Report Filename: wshawk_report_YYYYMMDD_HHMMSS.html

Sources: scanner_v2.py L50

scanner_v2.py L652-L673

Summary: Offensive Testing Capabilities

WSHawk's offensive testing architecture implements three key innovations:

  1. Intelligence-Driven Testing - 5-second learning phase enables context-aware payload injection and technology-specific attack selection
  2. Multi-Layer Verification - Pattern detection, browser execution, and out-of-band callbacks progressively confirm exploitability
  3. Confidence-Based Reporting - Four-level confidence scoring (LOW/MEDIUM/HIGH/CRITICAL) with CVSS 3.1 risk assessment

This approach transforms WebSocket security testing from blind fuzzing to targeted, evidence-based vulnerability assessment suitable for professional penetration testing engagements.

Sources: README.md L9-L34

CHANGELOG.md L57-L71

scanner_v2.py L1-L681