Reference

Name: WSHawk
Author: Regaan

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

Purpose and Scope

This section provides technical reference material for WSHawk's implementation. It serves as a bridge between conceptual understanding and actual code entities, documenting system constants, module dependencies, and core abstractions.

For detailed information on specific subsystems, see:

CVSS Scoring System - CVSS v3.1 calculation implementation
Logging System - Centralized logging architecture
Version History and Changelog - Release notes and migration guides
Dependency Reference - External library documentation

Sources: README.md, CHANGELOG.md

System-Wide Constants

WSHawk defines several key constants that control scanner behavior across all modules:

| Constant | Value | Location | Purpose | |----------|-------|----------|---------| | DEFAULT_RATE_LIMIT | 10 req/sec | CLI entry points | Maximum requests per second during scanning | | OBSERVATION_PERIOD | 5 seconds | scanner_v2.py learning phase | Duration for observing legitimate WebSocket traffic | | OAST_POLL_INTERVAL | 2 seconds | OAST integration | Frequency for checking interact.sh callbacks | | OAST_TOTAL_WAIT | 10 seconds | OAST integration | Maximum wait time for blind vulnerability callbacks | | DEFAULT_TIMEOUT | 30 seconds | WebSocket connections | Connection and response timeout | | MAX_RETRIES | 3 | scanner_v2.py | Connection retry attempts | | MALICIOUS_ORIGINS_COUNT | 216+ | malicious_origins.txt | Test cases for CSWSH validation | | TOTAL_PAYLOADS | 22,000+ | payloads/ directory | Combined payload count across all files |

Sources: README.md:36-47, CHANGELOG.md:42

Core Module Architecture

The following diagram maps WSHawk's conceptual systems to their actual Python module implementations:

graph TB
    subgraph "Entry Points"
        EP1["wshawk<br/>wshawk/__main__.py:main_quick()"]
        EP2["wshawk-interactive<br/>wshawk/__main__.py:main_interactive()"]
        EP3["wshawk-advanced<br/>wshawk/__main__.py:main_advanced()"]
        EP4["wshawk-defensive<br/>wshawk/defensive_validation.py:main()"]
    end
    
    subgraph "Scanner Core"
        Scanner["WSHawkV2<br/>wshawk/scanner_v2.py"]
        DefVal["DefensiveValidationModule<br/>wshawk/defensive_validation.py"]
    end
    
    subgraph "Analysis Layer"
        MA["MessageAnalyzer<br/>wshawk/message_analyzer.py"]
        VV["VulnerabilityVerifier<br/>wshawk/vulnerability_verifier.py"]
        SF["ServerFingerprinter<br/>wshawk/server_fingerprinter.py"]
    end
    
    subgraph "Testing Layer"
        PM["PayloadMutator<br/>wshawk/payload_mutator.py"]
        SHT["SessionHijackingTester<br/>wshawk/session_hijacking_tester.py"]
        WAF["WAFDetector<br/>wshawk/waf_detector.py"]
    end
    
    subgraph "Verification Layer"
        PW["PlaywrightXSSVerifier<br/>wshawk/playwright_xss_verifier.py"]
        OAST["OASTProvider<br/>wshawk/oast_integration.py"]
    end
    
    subgraph "Utility Layer"
        RL["TokenBucketRateLimiter<br/>wshawk/rate_limiter.py"]
        Log["setup_logger()<br/>wshawk/logger.py"]
        CVSS["calculate_cvss_score()<br/>wshawk/cvss_calculator.py"]
        Payloads["WSPayloads<br/>wshawk/payloads.py"]
    end
    
    EP1 --> Scanner
    EP2 --> Scanner
    EP3 --> Scanner
    EP4 --> DefVal
    
    Scanner --> MA
    Scanner --> VV
    Scanner --> SF
    Scanner --> PM
    Scanner --> SHT
    Scanner --> WAF
    Scanner --> PW
    Scanner --> OAST
    
    DefVal --> MA
    
    Scanner --> RL
    Scanner --> Log
    Scanner --> CVSS
    PM --> Payloads
    DefVal --> Log
    DefVal --> CVSS

Sources: README.md:79-156, CHANGELOG.md:8-20

Package Distribution Architecture

This diagram shows how WSHawk source code is transformed into distributable artifacts:

graph LR
    subgraph "Source"
        SRC["wshawk/<br/>Python Package"]
        Setup["setup.py<br/>pyproject.toml"]
        Docker["Dockerfile"]
    end
    
    subgraph "Build Artifacts"
        Wheel["wshawk-2.0.6-py3-none-any.whl"]
        Tarball["wshawk-2.0.6.tar.gz"]
        Image["Docker Image<br/>rothackers/wshawk:2.0.6"]
    end
    
    subgraph "Registries"
        PyPI["PyPI<br/>pypi.org/project/wshawk"]
        DH["Docker Hub<br/>hub.docker.com/r/rothackers/wshawk"]
        GHCR["GHCR<br/>ghcr.io/regaan/wshawk"]
    end
    
    subgraph "Version Scheme"
        Major["2.0.x<br/>Major releases"]
        Minor["2.x.x<br/>Feature releases"]
        Patch["x.x.6<br/>Bug fixes"]
    end
    
    SRC --> Setup
    Setup --> Wheel
    Setup --> Tarball
    
    SRC --> Docker
    Docker --> Image
    
    Wheel --> PyPI
    Tarball --> PyPI
    Image --> DH
    Image --> GHCR
    
    Major --> PyPI
    Minor --> PyPI
    Patch --> PyPI
    
    Major --> DH
    Minor --> DH
    Patch --> DH

Sources: README.md:49-76, CHANGELOG.md:1-20

CLI Entry Point Reference

WSHawk provides four distinct command-line entry points, each mapped to specific functions:

| Command | Function | File | Purpose | Target Users | |---------|----------|------|---------|--------------| | wshawk | main_quick() | wshawk/__main__.py | Quick scan with all features enabled | CI/CD pipelines, automation | | wshawk-interactive | main_interactive() | wshawk/__main__.py | Menu-driven test selection | Manual testers, learners | | wshawk-advanced | main_advanced() | wshawk/__main__.py | Full CLI flag control | Power users, custom workflows | | wshawk-defensive | main() | wshawk/defensive_validation.py | Blue team validation tests | Defenders, compliance auditors |

All entry points are registered in setup.py and pyproject.toml using the console_scripts entry point mechanism.

Sources: README.md:79-118, CHANGELOG.md:41

Core Class Hierarchy

classDiagram
    class WSHawkV2 {
        +target_url: str
        +use_headless_browser: bool
        +use_oast: bool
        +rate_limiter: TokenBucketRateLimiter
        +run_heuristic_scan()
        +generate_html_report()
    }
    
    class DefensiveValidationModule {
        +target_url: str
        +test_dns_exfiltration()
        +test_bot_detection()
        +test_cswsh()
        +test_wss_security()
    }
    
    class MessageAnalyzer {
        +detect_format()
        +analyze_structure()
        +extract_injection_points()
    }
    
    class VulnerabilityVerifier {
        +verify_sqli()
        +verify_xss()
        +verify_rce()
        +verify_xxe()
    }
    
    class PayloadMutator {
        +mutate_case_variation()
        +mutate_encoding()
        +mutate_comment_insertion()
        +mutate_null_byte()
    }
    
    class SessionHijackingTester {
        +test_token_reuse()
        +test_subscription_spoofing()
        +test_impersonation()
        +test_channel_violation()
    }
    
    class TokenBucketRateLimiter {
        +rate: float
        +burst: int
        +acquire()
    }
    
    class PlaywrightXSSVerifier {
        +verify_xss_execution()
        +capture_screenshot()
    }
    
    class OASTProvider {
        +register()
        +poll_interactions()
        +cleanup()
    }
    
    WSHawkV2 --> MessageAnalyzer
    WSHawkV2 --> VulnerabilityVerifier
    WSHawkV2 --> PayloadMutator
    WSHawkV2 --> SessionHijackingTester
    WSHawkV2 --> TokenBucketRateLimiter
    WSHawkV2 --> PlaywrightXSSVerifier
    WSHawkV2 --> OASTProvider
    
    DefensiveValidationModule --> MessageAnalyzer

Sources: README.md:209-223, CHANGELOG.md:79-93

Data File Structure

WSHawk's payload and configuration data is organized in a structured directory hierarchy:

| Path | Format | Count | Purpose | |------|--------|-------|---------| | payloads/sqli/*.txt | Plain text | Multiple files | SQL injection payloads | | payloads/xss/*.txt | Plain text | Multiple files | Cross-site scripting vectors | | payloads/xxe/*.json | JSON | Multiple files | XML external entity attacks | | payloads/ssrf/*.json | JSON | Multiple files | Server-side request forgery | | payloads/rce/*.txt | Plain text | Multiple files | Remote code execution | | payloads/nosql/*.txt | Plain text | Multiple files | NoSQL injection | | payloads/traversal/*.txt | Plain text | Multiple files | Path traversal vectors | | payloads/ldap/*.txt | Plain text | Multiple files | LDAP injection | | payloads/ssti/*.txt | Plain text | Multiple files | Server-side template injection | | payloads/redirect/*.txt | Plain text | Multiple files | Open redirect URLs | | payloads/malicious_origins.txt | Plain text | 216+ lines | CSWSH test origins |

The WSPayloads class in wshawk/payloads.py loads these files on demand using lazy loading to minimize memory usage.

Sources: README.md:36-37, CHANGELOG.md:42-47

Version Number Scheme

WSHawk follows semantic versioning with the following structure:

graph LR
    V["2.0.6"]
    
    Major["2<br/>Major Version<br/>Breaking changes"]
    Minor["0<br/>Minor Version<br/>New features"]
    Patch["6<br/>Patch Version<br/>Bug fixes"]
    
    V --> Major
    V --> Minor
    V --> Patch
    
    Major --> BC["setup.py<br/>pyproject.toml<br/>__init__.py"]
    Minor --> BC
    Patch --> BC

Version information is maintained in three synchronized locations:

wshawk/__init__.py:__version__
setup.py:version
pyproject.toml:[project].version

Sources: CHANGELOG.md:5-16, CHANGELOG.md:54-55

Feature Matrix by Version

| Version | Key Features | Breaking Changes | |---------|-------------|------------------| | 2.0.6 | 90+ test suite, full OAST integration, 12 WAF signatures | None | | 2.0.5 | CSWSH compatibility fix for websockets library | None | | 2.0.4 | Defensive validation module, WSS security tests | New CLI: wshawk-defensive | | 2.0.3 | Centralized logging, configurable auth, PyYAML dependency | Fixed entry points | | 2.0.1 | Documentation cleanup | None | | 2.0.0 | Complete rewrite, Playwright, OAST, CVSS scoring | API incompatible with 1.x | | 1.0.6 | Basic scanning, reflection detection | N/A |

Sources: CHANGELOG.md:1-100

Configuration File Locations

WSHawk accepts configuration via multiple mechanisms:

| Method | Syntax | Example | Priority | |--------|--------|---------|----------| | CLI Arguments | --flag value | --rate 5 | Highest | | YAML Config | key: value | rate_limit: 5 | Medium | | Environment Vars | WSHAWK_* | WSHAWK_RATE=5 | Lowest |

YAML configuration files are loaded using the PyYAML library and parsed in scanner_v2.py.

Sources: README.md:145-156, CHANGELOG.md:55-56

Report Output Format

All WSHawk scans generate timestamped HTML reports:

| Component | Implementation | Content | |-----------|----------------|---------| | Filename | wshawk_report_YYYYMMDD_HHMMSS.html | Timestamp-based naming | | CVSS Scores | cvss_calculator.py:calculate_cvss_score() | CVSS v3.1 severity ratings | | Screenshots | playwright_xss_verifier.py:capture_screenshot() | PNG images for XSS verification | | Traffic Logs | Raw WebSocket message capture | Request/response pairs | | Replay Sequences | Message ordering with timestamps | Step-by-step attack reproduction |

Reports are generated by scanner_v2.py:generate_html_report() and defensive_validation.py:generate_html_report() using HTML template strings.

Sources: README.md:133-143, CHANGELOG.md:44

Official Distribution Channels

To avoid malicious repackaging, WSHawk is distributed exclusively through:

| Channel | URL | Verification Method | |---------|-----|---------------------| | GitHub | github.com/regaan/wshawk | GPG signatures, release checksums | | PyPI | pypi.org/project/wshawk | Package hashes, trusted publishing | | Docker Hub | hub.docker.com/r/rothackers/wshawk | Image digests, official tags | | GHCR | ghcr.io/regaan/wshawk | GitHub attestations | | Official Site | wshawk.rothackers.com | SSL certificate verification |

Warning: Third-party download sites may distribute malware. Only use official sources listed above.

Sources: README.md:3-14, README.md:247-255

Related Reference Pages

For detailed documentation on specific reference topics:

CVSS Scoring System - CVSS v3.1 calculation algorithms, severity thresholds, and base metric definitions
Logging System - Logger configuration, output formatting, log levels, and file rotation
Version History and Changelog - Complete release notes, migration guides, and deprecation warnings
Dependency Reference - External library documentation, version requirements, and optional dependencies

Sources: CHANGELOG.md, README.md:200-208