Advanced Usage

Advanced Usage

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

This document covers power-user features and programmatic integration of WSHawk for security professionals and automation engineers. It includes the Python API, the wshawk-advanced CLI with all flags, hierarchical configuration with wshawk.yaml, smart payload evolution, browser-based verification, and multi-format report exports.

For basic scanning workflows, see Quick Start Examples. For defensive validation testing, see Defensive Mode Overview. For team-based GUI management, see Web Management Dashboard.

Python API Overview

WSHawk provides a comprehensive Python API through the WSHawkV2 class for integration into custom security tools, CI/CD pipelines, and automated testing frameworks.

Basic Usage Pattern

import asyncio
from wshawk.scanner_v2 import WSHawkV2

# Initialize scanner with target URL
scanner = WSHawkV2("ws://target.com")

# Enable advanced features
scanner.use_headless_browser = True  # Playwright XSS verification
scanner.use_oast = True              # OAST blind vulnerability detection
scanner.use_smart_payloads = True    # Genetic algorithm payload evolution

# Run full heuristic scan
asyncio.run(scanner.run_heuristic_scan())

# Access results
vulnerabilities = scanner.vulnerabilities
print(f"Found {len(vulnerabilities)} vulnerabilities")

WSHawkV2 Class Architecture

graph TB
    subgraph "Initialization [scanner_v2.py:40-100]"
        Init["WSHawkV2.__init__(url, headers, auth_sequence, max_rps, config)"]
        Config["WSHawkConfig.load()"]
        Modules["Initialize Analysis Modules"]
    end
    
    subgraph "Analysis Modules [scanner_v2.py:58-74]"
        MA["MessageAnalyzer<br/>message_intelligence"]
        VV["VulnerabilityVerifier<br/>vulnerability_verifier"]
        SF["ServerFingerprinter<br/>server_fingerprint"]
        SM["SessionStateMachine<br/>state_machine"]
        RL["TokenBucketRateLimiter<br/>rate_limiter"]
        Rep["EnhancedHTMLReporter<br/>enhanced_reporter"]
    end
    
    subgraph "Smart Payload System [scanner_v2.py:71-74]"
        CG["ContextAwareGenerator<br/>smart_payloads.context_generator"]
        FL["FeedbackLoop<br/>smart_payloads.feedback_loop"]
        PE["PayloadEvolver<br/>smart_payloads.payload_evolver"]
    end
    
    subgraph "Advanced Verification [scanner_v2.py:77-83]"
        HB["HeadlessBrowserXSSVerifier<br/>headless_xss_verifier"]
        OAST["OASTProvider<br/>oast_provider"]
        SHT["SessionHijackingTester<br/>session_hijacking_tester"]
    end
    
    subgraph "Core Methods [scanner_v2.py:102-852]"
        Connect["connect() -> WebSocket"]
        Learn["learning_phase(ws, duration=5)"]
        Scan["run_heuristic_scan()"]
        Tests["test_sql_injection_v2(ws)<br/>test_xss_v2(ws)<br/>test_command_injection_v2(ws)<br/>test_xxe_v2(ws)<br/>test_ssrf_v2(ws)"]
    end
    
    Init --> Config
    Init --> Modules
    Init --> Smart
    
    Modules --> MA
    Modules --> VV
    Modules --> SF
    Modules --> SM
    Modules --> RL
    Modules --> Rep
    
    Smart --> CG
    Smart --> FL
    Smart --> PE
    
    Scan --> Connect
    Connect --> Learn
    Learn --> Tests
    Tests --> HB
    Tests --> OAST
    Tests --> SHT
    
    style Init fill:#f9f9f9
    style Scan fill:#f9f9f9

Sources: wshawk/scanner_v2.py:35-100, wshawk/scanner_v2.py:593-852

Programmatic Configuration

The WSHawkV2 constructor accepts a config parameter for programmatic configuration:

from wshawk.config import WSHawkConfig
from wshawk.scanner_v2 import WSHawkV2

# Load configuration from wshawk.yaml
config = WSHawkConfig.load()

# Override specific settings
config.set('scanner.rate_limit', 5)
config.set('scanner.features.playwright', True)
config.set('integrations.jira.enabled', True)

# Initialize scanner with custom config
scanner = WSHawkV2("ws://target.com", config=config)

The scanner reads configuration values with fallback defaults scanner_v2.py:55-56:

  • scanner.rate_limit: Requests per second (default: 10)
  • scanner.features.playwright: Enable browser verification
  • scanner.features.oast: Enable OAST testing
  • scanner.features.smart_payloads: Enable adaptive payload generation

Sources: wshawk/scanner_v2.py:40-56, README.md:137-151

Advanced CLI Command

The wshawk-advanced command provides full control over all scanning features through command-line flags. It is designed for power users who need granular configuration without editing YAML files.

Command Syntax

wshawk-advanced ws://target.com [OPTIONS]

Core Scanning Options

| Flag | Type | Default | Description | |------|------|---------|-------------| | url | Positional | Required | Target URL (ws://, wss://, http://, https://) | | --rate N | Integer | 10 | Max requests per second | | --full | Boolean | False | Enable ALL features (Playwright + OAST + Smart Payloads) | | --playwright | Boolean | False | Enable browser-based XSS verification | | --no-oast | Boolean | False | Disable OAST (Out-of-Band) testing | | --binary | Boolean | False | Enable binary WebSocket message analysis | | --smart-payloads | Boolean | False | Enable context-aware adaptive payload generation |

Sources: wshawk/advanced_cli.py:37-98

Discovery and Export Options

| Flag | Type | Default | Description | |------|------|---------|-------------| | --discover | Boolean | False | Discover WebSocket endpoints from HTTP target before scanning | | --format FORMAT | Choice | None | Additional report format: json, csv, sarif, all | | --output PATH | String | None | Custom output file path for report |

Sources: wshawk/advanced_cli.py:47-52

Integration Options

| Flag | Environment Variable | Description | |------|---------------------|-------------| | --defectdojo URL | DEFECTDOJO_API_KEY | Push results to DefectDojo | | --dd-product ID | - | DefectDojo product ID | | --jira URL | JIRA_EMAIL, JIRA_API_TOKEN | Create Jira tickets | | --jira-project KEY | - | Jira project key (default: SEC) | | --webhook URL | - | Send results to webhook (auto-detects platform) | | --webhook-platform TYPE | - | Webhook type: slack, discord, teams, generic |

Sources: wshawk/advanced_cli.py:56-69

Web GUI Mode

| Flag | Type | Default | Description | |------|------|---------|-------------| | --web | Boolean | False | Launch Flask-based Web GUI instead of CLI scan | | --host HOST | String | 0.0.0.0 | Web GUI host binding | | --port PORT | Integer | 5000 | Web GUI port |

Sources: wshawk/advanced_cli.py:77-83

Advanced CLI Workflow

graph LR
    subgraph "CLI Argument Parsing [advanced_cli.py:12-84]"
        Args["argparse.ArgumentParser"]
        Parse["args = parser.parse_args()"]
    end
    
    subgraph "Configuration Override [advanced_cli.py:86-98]"
        LoadConfig["config = WSHawkConfig.load()"]
        Override["config.set() for each CLI flag"]
    end
    
    subgraph "Mode Selection [advanced_cli.py:100-124]"
        WebMode{"args.web?"}
        DiscoverMode{"args.discover or HTTP URL?"}
        ScanMode["Standard Scan"]
    end
    
    subgraph "Web GUI Launch [advanced_cli.py:100-124]"
        WebApp["from .web.app import run_web"]
        RunWeb["run_web(host, port, auth_enabled, auth_password, db_path)"]
    end
    
    subgraph "Discovery Phase [advanced_cli.py:133-158]"
        Discovery["WSEndpointDiscovery(url)"]
        Endpoints["await discovery.discover()"]
        SelectBest["Use highest-confidence endpoint"]
    end
    
    subgraph "Scanner Initialization [advanced_cli.py:166-209]"
        CreateScanner["scanner = WSHawkV2(scan_url, config=config)"]
        ConfigFeatures["Configure use_headless_browser<br/>use_oast<br/>use_smart_payloads"]
    end
    
    subgraph "Scan Execution [advanced_cli.py:210-283]"
        RunScan["await scanner.run_heuristic_scan()"]
        ExportFormats["ReportExporter.export(fmt) for each format"]
        Integrations["Push to DefectDojo/Jira/Webhook"]
    end
    
    Args --> Parse
    Parse --> LoadConfig
    LoadConfig --> Override
    Override --> WebMode
    
    WebMode -->|Yes| WebApp
    WebApp --> RunWeb
    
    WebMode -->|No| DiscoverMode
    DiscoverMode -->|Yes| Discovery
    Discovery --> Endpoints
    Endpoints --> SelectBest
    
    DiscoverMode -->|No| ScanMode
    SelectBest --> CreateScanner
    ScanMode --> CreateScanner
    
    CreateScanner --> ConfigFeatures
    ConfigFeatures --> RunScan
    RunScan --> ExportFormats
    ExportFormats --> Integrations
    
    style WebMode fill:#f9f9f9
    style DiscoverMode fill:#f9f9f9

Sources: wshawk/advanced_cli.py:12-283

Example Usage Patterns

Full Feature Scan with SARIF Export:

wshawk-advanced ws://target.com --full --format sarif --output security-scan.sarif

CI/CD Integration with DefectDojo:

export DEFECTDOJO_API_KEY="abc123..."
wshawk-advanced ws://target.com \
  --playwright \
  --rate 5 \
  --defectdojo https://defectdojo.company.com \
  --dd-product 42 \
  --format all

Smart Payloads with Slack Notifications:

wshawk-advanced ws://target.com \
  --smart-payloads \
  --webhook https://hooks.slack.com/services/T00/B00/XXX \
  --webhook-platform slack

Discovery and Jira Ticket Creation:

export JIRA_EMAIL="security@company.com"
export JIRA_API_TOKEN="abc123..."
wshawk-advanced https://app.company.com \
  --discover \
  --jira https://company.atlassian.net \
  --jira-project WEBSEC

Sources: README.md:189-198, wshawk/advanced_cli.py:17-33

Smart Feature Configuration

WSHawk v3.0.0 introduces three cutting-edge features for advanced vulnerability detection: Smart Payload Evolution, Real Browser Verification, and OAST Blind Detection.

Smart Payload Evolution System

The Smart Payload Evolution system uses genetic algorithms and feedback loops to adaptively generate payloads that bypass WAFs and exploit specific application contexts.

graph TB
    subgraph "Smart Payload Components [scanner_v2.py:71-74]"
        CG["ContextAwareGenerator<br/>context_generator.learn_from_message()"]
        FL["FeedbackLoop<br/>feedback_loop.analyze_response()"]
        PE["PayloadEvolver<br/>payload_evolver.evolve()"]
    end
    
    subgraph "Learning Phase [scanner_v2.py:155-165]"
        Samples["Sample Messages"]
        LearnContext["context_generator.learn_from_message(msg)"]
        Baseline["feedback_loop.establish_baseline(msg, resp_time)"]
    end
    
    subgraph "Response Analysis [scanner_v2.py:220-226]"
        Response["Server Response"]
        AnalyzeResp["signal, conf = feedback_loop.analyze_response(payload, response, resp_time, category)"]
        Signal["ResponseSignal: ERROR, ANOMALY, SLOW, NORMAL"]
    end
    
    subgraph "Payload Evolution [scanner_v2.py:638-703]"
        InitPop["Initial Population: 100 payloads"]
        Seed["payload_evolver.seed([successful_payload])"]
        Fitness["payload_evolver.update_fitness(payload, 1.0)"]
        Evolve["evolved = payload_evolver.evolve(count=30)"]
        Mutate["Genetic Operations:<br/>Crossover, Mutation, Selection"]
    end
    
    subgraph "Context-Aware Generation [scanner_v2.py:643-646]"
        Priority["priorities = feedback_loop.get_priority_categories()"]
        GenCtx["ctx_payloads = context_generator.generate_payloads(category, count=10)"]
    end
    
    Samples --> LearnContext
    Samples --> Baseline
    
    Response --> AnalyzeResp
    AnalyzeResp --> Signal
    
    Signal --> Fitness
    Fitness --> Seed
    Seed --> InitPop
    
    InitPop --> Evolve
    Evolve --> Mutate
    
    Priority --> GenCtx
    GenCtx --> Evolve
    
    style CG fill:#f9f9f9
    style FL fill:#f9f9f9
    style PE fill:#f9f9f9

Enabling Smart Payloads:

Python API:

scanner = WSHawkV2("ws://target.com")
scanner.use_smart_payloads = True

CLI:

wshawk-advanced ws://target.com --smart-payloads

Configuration:

scanner:
  features:
    smart_payloads: true

Evolution Mechanics:

  1. Learning Phase scanner_v2.py:155-165: The system learns message structure and establishes response time baselines
  2. Seeding scanner_v2.py:230-234: Successful payloads are added to the evolver's gene pool
  3. Fitness Scoring scanner_v2.py:220-226: Responses are analyzed for signals (ERROR, ANOMALY, SLOW) to calculate fitness
  4. Evolution scanner_v2.py:638-703: Genetic algorithm generates new payloads through crossover and mutation
  5. Context Generation scanner_v2.py:643-646: Priority categories drive context-aware payload creation

Sources: wshawk/scanner_v2.py:71-74, wshawk/scanner_v2.py:155-165, wshawk/scanner_v2.py:638-703

Real Browser XSS Verification

The HeadlessBrowserXSSVerifier uses Playwright to execute payloads in a real Chromium instance, confirming actual script execution rather than relying on reflection patterns.

Enabling Browser Verification:

Python API:

scanner = WSHawkV2("ws://target.com")
scanner.use_headless_browser = True

CLI:

wshawk-advanced ws://target.com --playwright

Verification Workflow scanner_v2.py:294-314:

  1. HIGH Confidence Detection: VulnerabilityVerifier identifies potential XSS
  2. Browser Initialization: HeadlessBrowserXSSVerifier starts Playwright if not running
  3. Execution Test: verify_xss_execution(response, payload) injects response into browser context
  4. Evidence Collection: Screenshots and execution confirmations are captured
  5. Confidence Upgrade: Verified payloads are promoted to ConfidenceLevel.CRITICAL

Installation Requirements requirements.txt:24:

playwright install chromium

Sources: wshawk/scanner_v2.py:294-314, README.md:60-62, requirements.txt:24

OAST Blind Vulnerability Detection

The OASTProvider integrates with interact.sh to detect blind vulnerabilities (XXE, SSRF, blind RCE) through out-of-band callbacks.

Enabling OAST:

Python API:

scanner = WSHawkV2("ws://target.com")
scanner.use_oast = True  # Enabled by default

CLI (disabled by default, enable explicitly):

# OAST is enabled unless explicitly disabled
wshawk-advanced ws://target.com  # OAST enabled
wshawk-advanced ws://target.com --no-oast  # Disable OAST

OAST Workflow scanner_v2.py:458-503:

  1. Provider Start: await oast_provider.start() registers unique subdomain
  2. Payload Generation: oast_payload = oast_provider.generate_payload('xxe', 'test1')
  3. Injection: OAST payload injected into XXE/SSRF test vectors
  4. Callback Detection: Provider polls for DNS/HTTP callbacks
  5. Blind Confirmation: Out-of-band interaction confirms blind vulnerability

XXE with OAST Example scanner_v2.py:469-477:

# Generate OAST payload for XXE detection
oast_payload = self.oast_provider.generate_payload('xxe', f'test{len(results)}')
msg = json.dumps({"action": "parse_xml", "xml": oast_payload})
await ws.send(msg)

# OAST provider will detect callback if XXE processes external entity

Sources: wshawk/scanner_v2.py:458-503, wshawk/scanner_v2.py:742-747

Hierarchical Configuration System

WSHawk v3.0.0 introduces a hierarchical configuration system via wshawk.yaml with environment variable resolution and configuration precedence.

Configuration Hierarchy

graph TB
    subgraph "Configuration Sources (Precedence Order)"
        CLI["1. CLI Flags<br/>--rate, --playwright, etc."]
        EnvVars["2. Environment Variables<br/>WSHAWK_*"]
        YAMLFile["3. wshawk.yaml<br/>Project Configuration"]
        Defaults["4. Built-in Defaults<br/>Hard-coded Fallbacks"]
    end
    
    subgraph "WSHawkConfig Class [config.py]"
        Load["WSHawkConfig.load()"]
        Merge["Hierarchical Merge"]
        Get["config.get(key, default)"]
        Set["config.set(key, value)"]
    end
    
    subgraph "Secret Resolution [config.py]"
        EnvPrefix["env:VARIABLE_NAME"]
        FilePrefix["file:/path/to/secret"]
        Resolve["Resolve at runtime"]
    end
    
    subgraph "Configuration Keys"
        Scanner["scanner.rate_limit<br/>scanner.features.*"]
        Web["web.host<br/>web.port<br/>web.auth.*"]
        Integrations["integrations.jira.*<br/>integrations.defectdojo.*<br/>integrations.webhook.*"]
        Reporting["reporting.output_dir<br/>reporting.formats"]
    end
    
    CLI --> Merge
    EnvVars --> Merge
    YAMLFile --> Merge
    Defaults --> Merge
    
    Merge --> Load
    Load --> Get
    Load --> Set
    
    YAMLFile --> EnvPrefix
    YAMLFile --> FilePrefix
    EnvPrefix --> Resolve
    FilePrefix --> Resolve
    
    Get --> Scanner
    Get --> Web
    Get --> Integrations
    Get --> Reporting
    
    style CLI fill:#f9f9f9
    style Merge fill:#f9f9f9

Sources: README.md:137-151, wshawk/advanced_cli.py:86-98

Configuration File Structure

Generate a template configuration:

python3 -m wshawk.config --generate

This creates wshawk.yaml.example. Rename to wshawk.yaml:

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

web:
  host: "0.0.0.0"
  port: 5000
  auth:
    enabled: true
    password: "env:WSHAWK_WEB_PASSWORD"
  database: "sqlite:///scans.db"

integrations:
  jira:
    enabled: false
    url: "https://company.atlassian.net"
    email: "security@company.com"
    api_token: "env:JIRA_API_TOKEN"
    project: "SEC"
  
  defectdojo:
    enabled: false
    url: "https://defectdojo.company.com"
    api_key: "env:DEFECTDOJO_API_KEY"
    product_id: 42
  
  webhook:
    enabled: false
    url: "env:SLACK_WEBHOOK_URL"
    platform: "slack"

reporting:
  output_dir: "."
  formats:
    - json
    - sarif

Secret Resolution Patterns

WSHawk supports two secret resolution patterns to avoid hardcoding credentials:

Environment Variable Resolution:

integrations:
  jira:
    api_token: "env:JIRA_API_TOKEN"  # Resolves $JIRA_API_TOKEN

File-Based Resolution:

integrations:
  defectdojo:
    api_key: "file:/run/secrets/defectdojo_key"  # Reads file content

Sources: README.md:137-151

Configuration Precedence Example

For scanner.rate_limit, the effective value is determined by:

  1. CLI Flag: wshawk-advanced ws://target.com --rate 5 → 5 req/s
  2. wshawk.yaml: scanner.rate_limit: 15 → 15 req/s (if no CLI flag)
  3. Built-in Default: 10 req/s (if no CLI flag or YAML value)

Override in Code advanced_cli.py:91-97:

config = WSHawkConfig.load()

# CLI flags override config file
if args.rate:
    config.set('scanner.rate_limit', args.rate)
if args.playwright:
    config.set('scanner.features.playwright', True)

Sources: wshawk/advanced_cli.py:86-98

Integration Configuration

WSHawk supports three external integrations for workflow automation: Jira ticket creation, DefectDojo findings push, and webhook notifications.

Jira Integration

Configuration advanced_cli.py:62-64:

integrations:
  jira:
    enabled: true
    url: "https://company.atlassian.net"
    email: "security@company.com"
    api_token: "env:JIRA_API_TOKEN"
    project: "SEC"

CLI Usage:

export JIRA_EMAIL="security@company.com"
export JIRA_API_TOKEN="abc123..."
wshawk-advanced ws://target.com --jira https://company.atlassian.net --jira-project WEBSEC

Ticket Creation Logic scanner_v2.py:823-834:

  • CRITICAL/HIGH severity vulnerabilities automatically create tickets
  • Tickets include CVSS scores, reproduction steps, and remediation guidance
  • Duplicate detection prevents ticket spam

Sources: wshawk/advanced_cli.py:251-265, wshawk/scanner_v2.py:823-834

DefectDojo Integration

Configuration advanced_cli.py:58-61:

integrations:
  defectdojo:
    enabled: true
    url: "https://defectdojo.company.com"
    api_key: "env:DEFECTDOJO_API_KEY"
    product_id: 42

CLI Usage:

export DEFECTDOJO_API_KEY="abc123..."
wshawk-advanced ws://target.com \
  --defectdojo https://defectdojo.company.com \
  --dd-product 42

Push Workflow scanner_v2.py:810-820:

  1. Scanner completes and generates vulnerability list
  2. DefectDojo engagement is created or retrieved
  3. Findings are pushed in DefectDojo's JSON format
  4. Each vulnerability becomes a finding with severity, description, and CVSS

Sources: wshawk/advanced_cli.py:234-249, wshawk/scanner_v2.py:810-820

Webhook Notifications

Configuration advanced_cli.py:66-69:

integrations:
  webhook:
    enabled: true
    url: "env:SLACK_WEBHOOK_URL"
    platform: "slack"  # slack, discord, teams, generic

CLI Usage:

wshawk-advanced ws://target.com \
  --webhook https://hooks.slack.com/services/T00/B00/XXX \
  --webhook-platform slack

Platform Auto-Detection advanced_cli.py:270-279:

# Auto-detect platform from URL
platform = args.webhook_platform
if platform == 'generic':
    if 'slack.com' in args.webhook:
        platform = 'slack'
    elif 'discord.com' in args.webhook:
        platform = 'discord'
    elif 'office.com' in args.webhook:
        platform = 'teams'

Notification Content scanner_v2.py:837-846:

  • Scan summary (target, duration, message counts)
  • Vulnerability counts by severity (CRITICAL, HIGH, MEDIUM, LOW)
  • Links to HTML reports
  • Rich formatting for Slack/Discord/Teams

Sources: wshawk/advanced_cli.py:267-281, wshawk/scanner_v2.py:837-846

Report Format and Export

WSHawk generates comprehensive reports in multiple formats for different audiences: HTML for manual review, JSON/CSV for data processing, and SARIF for CI/CD integration.

Report Generation Pipeline

graph LR
    subgraph "Scan Completion [scanner_v2.py:749-806]"
        Vulns["self.vulnerabilities<br/>List[Dict]"]
        ScanInfo["scan_info = {<br/>  target, duration,<br/>  messages_sent, messages_received<br/>}"]
        Fingerprint["fingerprint_info = fingerprinter.get_info()"]
    end
    
    subgraph "Primary HTML Report [scanner_v2.py:785-793]"
        HTMLGen["EnhancedHTMLReporter.generate_report()"]
        HTMLFile["wshawk_report_YYYYMMDD_HHMMSS.html"]
    end
    
    subgraph "Additional Formats [scanner_v2.py:796-805]"
        ConfigFormats["config.get('reporting.formats')"]
        Exporter["ReportExporter.export(vulns, scan_info, fmt)"]
        JSONFile["wshawk_report_*.json"]
        CSVFile["wshawk_report_*.csv"]
        SARIFFile["wshawk_report_*.sarif"]
    end
    
    subgraph "Output Directory [scanner_v2.py:768-773]"
        OutDir["config.get('reporting.output_dir', '.')"]
        CreateDir["os.makedirs(output_dir, exist_ok=True)"]
    end
    
    Vulns --> HTMLGen
    ScanInfo --> HTMLGen
    Fingerprint --> HTMLGen
    HTMLGen --> HTMLFile
    
    ConfigFormats --> Exporter
    Vulns --> Exporter
    ScanInfo --> Exporter
    Fingerprint --> Exporter
    
    Exporter --> JSONFile
    Exporter --> CSVFile
    Exporter --> SARIFFile
    
    OutDir --> CreateDir
    CreateDir --> HTMLFile
    CreateDir --> JSONFile
    
    style HTMLGen fill:#f9f9f9
    style Exporter fill:#f9f9f9

Sources: wshawk/scanner_v2.py:749-806

HTML Report Format

The primary report format is HTML, generated by EnhancedHTMLReporter scanner_v2.py:785-793:

Content Sections:

  1. Executive Summary: Vulnerability counts, severity breakdown, CVSS scores
  2. Scan Metadata: Target URL, duration, message statistics, timestamp
  3. Server Fingerprint: Detected language/framework/database, technology stack
  4. Vulnerability Details: Per-vulnerability cards with:
    • Type, severity, confidence level
    • CVSS v3.1 score and vector
    • Payload and response snippet
    • Evidence (screenshots for XSS, OAST callbacks)
    • Remediation recommendations
  5. Traffic Logs: Raw WebSocket message exchange
  6. Session Security Tests: Results from SessionHijackingTester

File Naming: wshawk_report_YYYYMMDD_HHMMSS.html

Sources: README.md:176-186, wshawk/scanner_v2.py:785-793

JSON Export Format

CLI Usage:

wshawk-advanced ws://target.com --format json --output scan-results.json

Configuration:

reporting:
  formats:
    - json

Structure:

{
  "scan_info": {
    "target": "ws://target.com",
    "duration": 45.23,
    "messages_sent": 1523,
    "messages_received": 1498,
    "timestamp": "2024-01-15T14:32:10"
  },
  "vulnerabilities": [
    {
      "type": "SQL Injection",
      "severity": "HIGH",
      "confidence": "HIGH",
      "cvss_score": 8.6,
      "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N",
      "description": "SQL syntax error detected in response",
      "payload": "' OR 1=1--",
      "response_snippet": "mysql_error: syntax error...",
      "recommendation": "Use parameterized queries"
    }
  ]
}

Sources: wshawk/advanced_cli.py:49-50, wshawk/scanner_v2.py:796-805

CSV Export Format

CLI Usage:

wshawk-advanced ws://target.com --format csv

Structure:

Type,Severity,Confidence,CVSS Score,Description,Payload,Recommendation
SQL Injection,HIGH,HIGH,8.6,SQL syntax error detected,' OR 1=1--,Use parameterized queries
XSS,CRITICAL,HIGH,9.3,Real browser execution,<script>alert(1)</script>,Sanitize and encode all user input

Use Cases:

  • Import into Excel/Google Sheets for tracking
  • Bulk analysis in data science tools
  • Integration with BI dashboards

Sources: wshawk/advanced_cli.py:49-50

SARIF Export Format

SARIF (Static Analysis Results Interchange Format) is designed for CI/CD integration, particularly GitHub Security.

CLI Usage:

wshawk-advanced ws://target.com --format sarif --output security-scan.sarif

GitHub Actions Integration:

- name: Run WSHawk Scan
  run: |
    wshawk-advanced ws://${{ env.TARGET_URL }} --format sarif --output wshawk.sarif

- name: Upload SARIF to GitHub Security
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: wshawk.sarif

SARIF Structure:

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "WSHawk",
          "version": "3.0.0",
          "informationUri": "https://github.com/regaan/wshawk"
        }
      },
      "results": [
        {
          "ruleId": "sql-injection",
          "level": "error",
          "message": {
            "text": "SQL Injection vulnerability detected"
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "ws://target.com"
                }
              }
            }
          ],
          "properties": {
            "cvss": "8.6",
            "confidence": "HIGH"
          }
        }
      ]
    }
  ]
}

Sources: wshawk/advanced_cli.py:49-50, README.md:47

Multi-Format Export

CLI Usage:

wshawk-advanced ws://target.com --format all

This generates:

  • wshawk_report_20240115_143210.html
  • wshawk_report_20240115_143210.json
  • wshawk_report_20240115_143210.csv
  • wshawk_report_20240115_143210.sarif

Configuration-Driven:

reporting:
  output_dir: "/var/reports"
  formats:
    - json
    - csv
    - sarif

Export Logic advanced_cli.py:220-229:

if args.format and vulns is not None:
    from .report_exporter import ReportExporter
    exporter = ReportExporter()
    
    formats = ['json', 'csv', 'sarif'] if args.format == 'all' else [args.format]
    
    for fmt in formats:
        output_file = args.output if args.output and len(formats) == 1 else None
        path = exporter.export(scanner.vulnerabilities, scan_info, fmt, output_file)
        Logger.success(f"{fmt.upper()} report saved: {path}")

Sources: wshawk/advanced_cli.py:220-229, wshawk/scanner_v2.py:796-805

Feature Matrix

| Feature | Python API | CLI Flag | Config Key | Default | |---------|-----------|----------|------------|---------| | Rate Limiting | max_rps=N | --rate N | scanner.rate_limit | 10 | | Browser XSS | use_headless_browser=True | --playwright | scanner.features.playwright | False | | OAST Detection | use_oast=True | --no-oast (disable) | scanner.features.oast | True | | Smart Payloads | use_smart_payloads=True | --smart-payloads | scanner.features.smart_payloads | False | | Binary Analysis | N/A | --binary | scanner.features.binary_analysis | False | | Full Features | All = True | --full | N/A | False | | Endpoint Discovery | N/A | --discover | N/A | False | | JSON Export | N/A | --format json | reporting.formats: [json] | None | | SARIF Export | N/A | --format sarif | reporting.formats: [sarif] | None | | Jira Integration | Via config | --jira URL | integrations.jira.enabled | False | | DefectDojo Push | Via config | --defectdojo URL | integrations.defectdojo.enabled | False | | Webhook Notify | Via config | --webhook URL | integrations.webhook.enabled | False |

Sources: wshawk/scanner_v2.py:40-98, wshawk/advanced_cli.py:37-98, README.md:137-151