Reference

Reference

Relevant source files

This page provides technical reference documentation for WSHawk's configuration options, output formats, CVSS scoring methodology, and version history. It serves as a comprehensive lookup resource for developers and security engineers integrating or extending WSHawk.

For step-by-step configuration guidance, see Configuration and Authentication. For understanding scan results and reports, see Report Format and Output. For deployment-specific configuration, see Docker Deployment and CI/CD Integration.

Configuration Overview

WSHawk accepts configuration through multiple channels: command-line arguments, Python API parameters, YAML configuration files, and environment variables. The configuration system follows a hierarchical precedence model where explicit parameters override file-based configuration.

WSHawkV2 Initialization Parameters

The core scanner class WSHawkV2 accepts the following initialization parameters:

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | url | str | Required | Target WebSocket URL (ws:// or wss://) | | headers | Dict[str, str] | {} | Custom headers for WebSocket connection | | auth_sequence | str | None | Path to YAML authentication sequence file | | max_rps | int | 10 | Maximum requests per second (rate limiting) |

Sources: wshawk/scanner_v2.py L28-L35

Scanner Configuration Diagram

Sources: wshawk/scanner_v2.py L28-L76

Rate Limiting Configuration

WSHawk implements adaptive token bucket rate limiting through the TokenBucketRateLimiter class. The rate limiter prevents server overload and implements intelligent backoff based on server response patterns.

Rate Limiter Parameters

CLI Rate Configuration

| Command | Option | Default | Range | | --- | --- | --- | --- | | wshawk-advanced | --rate N | 10 | 1-100 | | Python API | max_rps=N | 10 | 1-100 |

The adaptive rate limiter monitors server response times and automatically adjusts request rates. When server responses slow down (>2s average), the limiter reduces the rate by 50%. When responses normalize (<1s average), the rate increases by 20%.

Sources: wshawk/scanner_v2.py L45-L49

README.md L88-L89

Authentication Configuration

WSHawk supports complex authentication sequences through YAML configuration files. Authentication sequences define multi-step message exchanges required to establish authenticated sessions.

YAML Authentication Format

Authentication Sequence Loading

The SessionStateMachine class processes authentication sequences:

Session State Transitions:

Sources: wshawk/scanner_v2.py L60-L62

wshawk/scanner_v2.py L81

Advanced Verification Configuration

WSHawk provides optional advanced verification modules that can be enabled or disabled based on testing requirements.

Playwright Browser Verification

Browser-based XSS verification uses Playwright to execute payloads in a real browser context:

Prerequisites:

CLI Usage:

Sources: wshawk/scanner_v2.py L52-L55

wshawk/scanner_v2.py L250-L266

OAST (Out-of-Band Application Security Testing)

OAST integration enables detection of blind vulnerabilities (XXE, SSRF) through DNS/HTTP callbacks:

OAST Payload Generation:

CLI Usage:

Sources: wshawk/scanner_v2.py L56-L59

wshawk/scanner_v2.py L410-L417

CVSS v3.1 Scoring System

WSHawk implements CVSS (Common Vulnerability Scoring System) v3.1 for standardized vulnerability risk assessment. Each detected vulnerability receives a CVSS base score (0.0-10.0) and severity classification.

CVSS Severity Levels

| Severity | Score Range | Color Code | Interpretation | | --- | --- | --- | --- | | CRITICAL | 9.0 - 10.0 | Red | Immediate action required | | HIGH | 7.0 - 8.9 | Orange | Urgent remediation needed | | MEDIUM | 4.0 - 6.9 | Yellow | Remediate when possible | | LOW | 0.1 - 3.9 | Blue | Informational | | NONE | 0.0 | Green | No vulnerability |

Confidence Level Mapping

WSHawk uses a confidence-based verification system that influences CVSS scores:

Confidence to CVSS Mapping:

| Vulnerability Type | Critical Confidence | High Confidence | Medium Confidence | | --- | --- | --- | --- | | SQL Injection | 9.8 | 8.5 | 6.5 | | XSS (Browser Verified) | 9.6 | - | - | | XSS (Pattern Match) | - | 7.8 | 5.5 | | Command Injection | 9.9 | 8.8 | 6.8 | | XXE | - | 8.2 | 6.0 | | SSRF | - | 8.6 | 6.2 | | Path Traversal | - | 7.5 | 5.8 | | NoSQL Injection | - | 8.3 | 6.3 |

Sources: wshawk/scanner_v2.py L185-L202

CHANGELOG.md L27

CVSS Vector Strings

Each vulnerability includes a CVSS vector string encoding the attack characteristics:

Example SQL Injection:

CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H

Vector Components:

  • AV:N - Attack Vector: Network
  • AC:L - Attack Complexity: Low
  • PR:N - Privileges Required: None
  • UI:N - User Interaction: None
  • S:C - Scope: Changed
  • C:H - Confidentiality Impact: High
  • I:H - Integrity Impact: High
  • A:H - Availability Impact: High

Sources: README.md L18

README.md L28

Vulnerability Finding Structure

Each detected vulnerability is stored as a dictionary with standardized fields:

Example Vulnerability Records

SQL Injection Finding:

XSS Finding (Browser Verified):

Sources: wshawk/scanner_v2.py L193-L202

wshawk/scanner_v2.py L273-L283

HTML Report Format

WSHawk generates comprehensive HTML reports through the EnhancedHTMLReporter class. Reports include vulnerability details, screenshots, traffic logs, and remediation guidance.

Report Filename Convention

wshawk_report_YYYYMMDD_HHMMSS.html

Example: wshawk_report_20250115_143022.html

The timestamp ensures unique filenames for multiple scans and enables historical tracking.

Sources: wshawk/scanner_v2.py L669

README.md L129

Report Generation Flow

Sources: wshawk/scanner_v2.py L651-L673

Report Components

The HTML report includes the following sections:

  1. Executive Summary * Total vulnerabilities found * CVSS score distribution * Critical/High/Medium/Low breakdown * Scan duration and target information
  2. Vulnerability Details * Type and severity classification * CVSS score with vector string * Confidence level * Detailed description * Attack payload used * Response evidence (first 200 characters) * Browser verification status (for XSS) * Remediation recommendations
  3. Server Fingerprint * Detected language/framework * Database type * Technology stack indicators
  4. Traffic Logs * Request/response pairs * Timestamps * Message sizes
  5. Screenshots (Optional) * Browser execution evidence for XSS * Captured during Playwright verification

Sources: wshawk/scanner_v2.py L651-L673

Report Persistence in Docker

When running WSHawk in Docker, reports persist through volume mounts:

Docker Compose Configuration:

Sources: Deployment documentation

Logging System

WSHawk implements centralized logging through the Logger class with color-coded output and file logging support.

Log Levels and Colors

| Level | Method | Color | Use Case | | --- | --- | --- | --- | | Banner | Logger.banner() | Cyan | ASCII art banner | | Success | Logger.success() | Green | Operation completed | | Info | Logger.info() | Blue | Status information | | Warning | Logger.warning() | Yellow | Non-critical issues | | Error | Logger.error() | Red | Errors and failures | | Vulnerability | Logger.vuln() | Magenta | Vulnerability findings |

Log Output Example

[SUCCESS] Connected!
[INFO] Starting learning phase (5s)...
[INFO] Sample message 1: {"type":"ping","timestamp":1234567890}...
[SUCCESS] Detected format: JSON
[INFO] Injectable fields: type, data, user
[VULN] SQL Injection [HIGH]: Database error message detected
[VULN] Payload: ' OR '1'='1

Sources: wshawk/main.py

(Logger class)

Version Information

Current Version

The current WSHawk version is defined in multiple locations for distribution:

  • Package Version: wshawk/init.py L8 - __version__ = "2.0.3"
  • PyPI Version: Latest published version
  • Docker Tags: latest, 2.0.5, 2.0, 2

Version Checking

Sources: wshawk/init.py L8

Version History Summary

v2.0.5 (2025-12-08)

Defensive Validation Module:

  • DNS Exfiltration Prevention Test
  • Bot Detection Validation Test
  • CSWSH (Cross-Site WebSocket Hijacking) Test
  • WSS Protocol Security Validation (TLS/SSL)
  • 216+ malicious origin payloads
  • CVSS scoring for defensive findings

Fixes:

  • CSWSH test compatibility with newer websockets library
  • Origin header vulnerability detection in defensive validation

Sources: CHANGELOG.md L5-L32

v2.0.4 (2025-12-08)

Added:

  • Initial defensive validation module
  • wshawk-defensive CLI command
  • Comprehensive documentation in DEFENSIVE_VALIDATION.md

Sources: CHANGELOG.md L11-L32

v2.0.3 (2025-12-07)

Fixes:

  • Version mismatch between __init__.py and package files
  • Changed time.time() to time.monotonic() for system-time-change safety
  • Added missing PyYAML dependency

Improvements:

  • Centralized logging system (wshawk/logger.py)
  • Configurable authentication in SessionHijackingTester
  • Better error handling

Sources: CHANGELOG.md L34-L50

v2.0.0 (2025-12-07)

Major Rewrite:

  • Real vulnerability verification with Playwright
  • OAST integration for blind vulnerabilities
  • Session hijacking tests (6 security tests)
  • Intelligent mutation engine with WAF bypass
  • CVSS v3.1 scoring
  • Professional HTML reporting
  • Adaptive rate limiting
  • Plugin system
  • Three CLI modes (quick, interactive, advanced)

Sources: CHANGELOG.md L58-L76

CLI Command Reference Quick Lookup

| Command | Purpose | Best For | Configuration Options | | --- | --- | --- | --- | | wshawk | Quick scan | CI/CD automation | Target URL only | | wshawk-interactive | Guided testing | Learning, manual testing | Interactive menu | | wshawk-advanced | Full control | Advanced users | --playwright, --rate, --full, --no-oast | | wshawk-defensive | Security validation | Blue teams | Target URL only |

Full command documentation: See CLI Command Reference

Sources: README.md L66-L104

Configuration File Locations

Default Search Paths

WSHawk searches for configuration files in the following order:

  1. Current working directory: ./auth_sequence.yaml
  2. User config directory: ~/.config/wshawk/auth_sequence.yaml
  3. System config directory: /etc/wshawk/auth_sequence.yaml
  4. Explicit path via --auth parameter

Environment Variables

| Variable | Purpose | Default | | --- | --- | --- | | WSHAWK_OAST_DOMAIN | Custom OAST server domain | None | | WSHAWK_RATE_LIMIT | Override default rate limit | 10 | | WSHAWK_LOG_LEVEL | Logging verbosity | INFO |

Sources: Inferred from codebase architecture

Output File Locations

Local Execution

./
├── wshawk_report_20250115_143022.html
├── wshawk_report_20250115_150431.html
└── wshawk.log (if file logging enabled)

Docker Execution

./reports/
├── wshawk_report_20250115_143022.html
├── wshawk_report_20250115_150431.html
└── wshawk.log

CI/CD Execution

Reports are typically uploaded as workflow artifacts:

Sources: Deployment patterns from DOCKER.md

RELEASE_SUMMARY.md