Intelligence Modules

Intelligence Modules

Relevant source files

Purpose and Scope

This document describes the three intelligence modules that enable WSHawk's context-aware testing capabilities: MessageIntelligence, ServerFingerprinter, and VulnerabilityVerifier. These modules form the intelligence layer that transforms WSHawk from a simple payload injector into an adaptive security scanner that understands message structure, server technology, and vulnerability verification.

For information about how these modules are orchestrated by the scanner, see Scanner Engine (WSHawkV2). For details on the payload collections these modules consume, see Payload Management System. For the mutation strategies that leverage message intelligence, see the mutation engine documentation in Payload Management System.

Sources: wshawk/scanner_v2.py L1-L681

Intelligence Layer Architecture

The intelligence modules operate during distinct phases of the scanning lifecycle: learning, fingerprinting, payload adaptation, and verification. The scanner initializes all three modules during construction and orchestrates their use throughout testing.

Intelligence Module Initialization

Sources: wshawk/scanner_v2.py L28-L50

MessageIntelligence Module

The MessageIntelligence class analyzes WebSocket message patterns during the learning phase to understand protocol structure. It detects message format (JSON, XML, binary, plaintext) and identifies injectable fields, enabling context-aware payload injection that maintains protocol validity.

Message Format Detection

Learning Phase Integration

During the 5-second learning phase, the scanner collects sample messages and passes them to MessageIntelligence.learn_from_messages(). The module analyzes these samples to determine the dominant message format and extract field names.

Sources: wshawk/scanner_v2.py L87-L141

Context-Aware Payload Injection

When learning_complete is True and the detected format is JSON, the scanner uses inject_payload_into_message() instead of raw payload strings. This method generates multiple message variants by injecting the payload into each detected injectable field.

| Injection Strategy | Format Type | Example | | --- | --- | --- | | Field injection | JSON | {"user": "admin", "action": "' OR 1=1--"} | | Attribute injection | XML | <user id="' OR 1=1--">admin</user> | | Raw payload | TEXT/BINARY | ' OR 1=1-- (no structure) |

Sources: wshawk/scanner_v2.py L165-L171

wshawk/scanner_v2.py L228-L234

wshawk/scanner_v2.py L316-L321

ServerFingerprinter Module

The ServerFingerprinter class identifies the server technology stack by analyzing response patterns, error messages, and behavioral characteristics. It builds a fingerprint containing detected language, framework, database, and other server properties.

Fingerprinting Process

Server Detection Integration

The scanner calls add_response() for every message received during both the learning phase and active testing. This continuous analysis improves fingerprint accuracy as more data is collected.

Sources: wshawk/scanner_v2.py L106

wshawk/scanner_v2.py L182

Technology-Specific Payload Selection

When a database or language is fingerprinted, the scanner retrieves recommended payloads via get_recommended_payloads() and prepends them to the standard payload list. This prioritizes payloads likely to succeed against the identified technology.

SQL Injection with Fingerprinting

Sources: wshawk/scanner_v2.py L152-L158

Command Injection with Fingerprinting

Sources: wshawk/scanner_v2.py L305-L310

VulnerabilityVerifier Module

The VulnerabilityVerifier class performs evidence-based vulnerability verification to distinguish between actual security flaws and benign payload reflection. Each verification method returns a tuple: (is_vulnerable: bool, confidence: ConfidenceLevel, description: str).

Confidence Level Enumeration

The ConfidenceLevel enum defines four severity levels used for vulnerability classification:

| Level | Meaning | Usage | | --- | --- | --- | | LOW | Weak indicator | Payload reflection only, no execution evidence | | MEDIUM | Moderate evidence | Error messages, partial execution indicators | | HIGH | Strong evidence | Clear execution signs, error details, timing anomalies | | CRITICAL | Confirmed exploitation | Browser-verified XSS, OAST callback received |

Sources: wshawk/scanner_v2.py L16

SQL Injection Verification

The verify_sql_injection() method analyzes server responses for database error signatures, timing anomalies, and data extraction indicators rather than simple payload reflection.

Sources: wshawk/scanner_v2.py L184-L189

XSS Verification with Context Analysis

The verify_xss() method performs context-aware analysis, detecting whether payloads appear in executable contexts (script tags, event handlers) versus safe contexts (HTML-encoded, inside comments).

After pattern-based verification, HIGH confidence XSS findings trigger browser-based verification via the HeadlessBrowserXSSVerifier (if enabled). Successfully executed payloads are upgraded to CRITICAL confidence.

Sources: wshawk/scanner_v2.py L244-L271

Command Injection Verification

The verify_command_injection() method detects command execution evidence through output patterns, timing analysis, and error signatures.

Sources: wshawk/scanner_v2.py L332-L338

Path Traversal Verification

The verify_path_traversal() method detects successful file access by searching for file content patterns (e.g., /etc/passwd entries, Windows system files).

Sources: wshawk/scanner_v2.py L378-L381

Intelligence Module Integration Workflow

The following diagram illustrates how the three intelligence modules interact during a complete test cycle:

Sources: wshawk/scanner_v2.py L87-L141

wshawk/scanner_v2.py L143-L213

Module Data Flow

The intelligence modules maintain state throughout the scan lifecycle, continuously refining their understanding of the target application.

Sources: wshawk/scanner_v2.py L28-L76

wshawk/scanner_v2.py L545-L680

Code Entity Reference

The following table maps intelligence module classes and methods to their usage locations in the scanner:

| Module | Class/Method | Purpose | Called From | | --- | --- | --- | --- | | MessageIntelligence | learn_from_messages() | Analyze message format | scanner_v2.py L121 | | MessageIntelligence | get_format_info() | Retrieve format details | scanner_v2.py L125 | | MessageIntelligence | inject_payload_into_message() | Context-aware injection | scanner_v2.py L167-L169 | | ServerFingerprinter | add_response() | Collect response data | scanner_v2.py L106 scanner_v2.py L182 | | ServerFingerprinter | fingerprint() | Get server technology | scanner_v2.py L132 scanner_v2.py L153 | | ServerFingerprinter | get_recommended_payloads() | Technology-specific payloads | scanner_v2.py L155-L158 | | ServerFingerprinter | get_info() | Fingerprint details for report | scanner_v2.py L660 | | VulnerabilityVerifier | verify_sql_injection() | Verify SQL vulnerability | scanner_v2.py L185-L187 | | VulnerabilityVerifier | verify_xss() | Verify XSS vulnerability | scanner_v2.py L244-L246 | | VulnerabilityVerifier | verify_command_injection() | Verify command injection | scanner_v2.py L332-L334 | | VulnerabilityVerifier | verify_path_traversal() | Verify path traversal | scanner_v2.py L378 |

Sources: wshawk/scanner_v2.py L1-L681

Intelligence Module State Variables

Each module maintains internal state that accumulates throughout the scan:

MessageIntelligence State

ServerFingerprinter State

VulnerabilityVerifier State

The VulnerabilityVerifier is stateless—each verification method analyzes the provided response independently without maintaining historical context.

Sources: wshawk/scanner_v2.py L41-L43

Intelligence Output in Reports

The intelligence gathered by these modules enhances the HTML reports with contextual information:

| Intelligence Source | Report Section | Content | | --- | --- | --- | | MessageIntelligence | Scan Information | Detected message format (JSON/XML/etc) | | MessageIntelligence | Scan Information | Number of injectable fields identified | | ServerFingerprinter | Server Fingerprint | Technology stack (language/framework/database) | | ServerFingerprinter | Server Fingerprint | Confidence score for fingerprint | | VulnerabilityVerifier | Vulnerability Details | Confidence level (LOW/MEDIUM/HIGH/CRITICAL) | | VulnerabilityVerifier | Vulnerability Details | Evidence-based description |

The report generation code at scanner_v2.py L660-L666

passes fingerprint_info from self.fingerprinter.get_info() to the EnhancedHTMLReporter for inclusion in the final report.

Sources: wshawk/scanner_v2.py L652-L673

Extension Points

To add new intelligence capabilities:

  1. New Message Formats: Extend MessageFormat enum and add detection logic to MessageIntelligence.learn_from_messages()
  2. New Fingerprinting Signatures: Add patterns to ServerFingerprinter detection logic
  3. New Verification Methods: Add verify_<vuln_type>() methods to VulnerabilityVerifier following the signature: (response: str, payload: str) -> Tuple[bool, ConfidenceLevel, str]

Each new verification method should be integrated into the corresponding test method in scanner_v2.py following the pattern established in scanner_v2.py L184-L202

Sources: wshawk/scanner_v2.py L143-L213