Version History and Changelog

Relevant source files

CHANGELOG.md

README.md

RELEASE_SUMMARY.md

pyproject.toml

Purpose and Scope

This document provides a comprehensive version history of WSHawk, tracking all changes across releases from the initial 1.0.6 release through the current 2.0.5 version. Each version entry includes new features, bug fixes, breaking changes, and dependency updates. For configuration of the current version, see Configuration and Authentication. For understanding CVSS scoring methodology introduced in v2.0.0, see CVSS Scoring System.

This page serves as a reference for:

Understanding what changed between versions
Planning upgrades and identifying breaking changes
Tracking feature additions and deprecations
Reviewing bug fixes and security patches
Identifying migration paths for major version updates

Sources: CHANGELOG.md L1-L84

pyproject.toml L6-L7

Current Version and Versioning Scheme

WSHawk currently uses semantic versioning (MAJOR.MINOR.PATCH) as defined in pyproject.toml L7

Current Version: 2.0.5

Version Components:

MAJOR (2): Incompatible API changes, complete rewrites
MINOR (0): New features in backward-compatible manner
PATCH (5): Backward-compatible bug fixes

Version Definition Locations:

Package version: pyproject.toml L7
PyPI metadata: pyproject.toml L6-L7
Distribution tags: Docker images use semantic tags (2.0.5, 2.0, 2, latest)

Sources: pyproject.toml L7

CHANGELOG.md L5

Version Timeline

#mermaid-el0ls0ytk17{font-family:ui-sans-serif,-apple-system,system-ui,Segoe UI,Helvetica;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-el0ls0ytk17 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-el0ls0ytk17 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-el0ls0ytk17 .error-icon{fill:#dddddd;}#mermaid-el0ls0ytk17 .error-text{fill:#222222;stroke:#222222;}#mermaid-el0ls0ytk17 .edge-thickness-normal{stroke-width:1px;}#mermaid-el0ls0ytk17 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-el0ls0ytk17 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-el0ls0ytk17 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-el0ls0ytk17 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-el0ls0ytk17 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-el0ls0ytk17 .marker{fill:#999;stroke:#999;}#mermaid-el0ls0ytk17 .marker.cross{stroke:#999;}#mermaid-el0ls0ytk17 svg{font-family:ui-sans-serif,-apple-system,system-ui,Segoe UI,Helvetica;font-size:16px;}#mermaid-el0ls0ytk17 p{margin:0;}#mermaid-el0ls0ytk17 .edge{stroke-width:3;}#mermaid-el0ls0ytk17 .section--1 rect,#mermaid-el0ls0ytk17 .section--1 path,#mermaid-el0ls0ytk17 .section--1 circle,#mermaid-el0ls0ytk17 .section--1 path{fill:hsl(0, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .section--1 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon--1{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge--1{stroke:hsl(0, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .edge-depth--1{stroke-width:17;}#mermaid-el0ls0ytk17 .section--1 line{stroke:rgb(84.7499999999, 84.7499999999, 84.7499999999);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-0 rect,#mermaid-el0ls0ytk17 .section-0 path,#mermaid-el0ls0ytk17 .section-0 circle,#mermaid-el0ls0ytk17 .section-0 path{fill:hsl(-120, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .section-0 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon-0{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge-0{stroke:hsl(-120, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .edge-depth-0{stroke-width:14;}#mermaid-el0ls0ytk17 .section-0 line{stroke:rgb(84.7499999999, 84.7499999999, 84.7499999999);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-1 rect,#mermaid-el0ls0ytk17 .section-1 path,#mermaid-el0ls0ytk17 .section-1 circle,#mermaid-el0ls0ytk17 .section-1 path{fill:hsl(0, 0%, 61.6666666667%);}#mermaid-el0ls0ytk17 .section-1 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon-1{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge-1{stroke:hsl(0, 0%, 61.6666666667%);}#mermaid-el0ls0ytk17 .edge-depth-1{stroke-width:11;}#mermaid-el0ls0ytk17 .section-1 line{stroke:rgb(97.7499999999, 97.7499999999, 97.7499999999);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-2 rect,#mermaid-el0ls0ytk17 .section-2 path,#mermaid-el0ls0ytk17 .section-2 circle,#mermaid-el0ls0ytk17 .section-2 path{fill:hsl(30, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .section-2 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon-2{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge-2{stroke:hsl(30, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .edge-depth-2{stroke-width:8;}#mermaid-el0ls0ytk17 .section-2 line{stroke:rgb(84.7499999999, 84.7499999999, 84.7499999999);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-3 rect,#mermaid-el0ls0ytk17 .section-3 path,#mermaid-el0ls0ytk17 .section-3 circle,#mermaid-el0ls0ytk17 .section-3 path{fill:hsl(60, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .section-3 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon-3{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge-3{stroke:hsl(60, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .edge-depth-3{stroke-width:5;}#mermaid-el0ls0ytk17 .section-3 line{stroke:rgb(84.7499999999, 84.7499999999, 84.7499999999);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-4 rect,#mermaid-el0ls0ytk17 .section-4 path,#mermaid-el0ls0ytk17 .section-4 circle,#mermaid-el0ls0ytk17 .section-4 path{fill:hsl(90, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .section-4 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon-4{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge-4{stroke:hsl(90, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .edge-depth-4{stroke-width:2;}#mermaid-el0ls0ytk17 .section-4 line{stroke:rgb(84.7499999999, 84.7499999999, 84.7499999999);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-5 rect,#mermaid-el0ls0ytk17 .section-5 path,#mermaid-el0ls0ytk17 .section-5 circle,#mermaid-el0ls0ytk17 .section-5 path{fill:hsl(120, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .section-5 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon-5{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge-5{stroke:hsl(120, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .edge-depth-5{stroke-width:-1;}#mermaid-el0ls0ytk17 .section-5 line{stroke:rgb(84.7499999999, 84.7499999999, 84.7499999999);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-6 rect,#mermaid-el0ls0ytk17 .section-6 path,#mermaid-el0ls0ytk17 .section-6 circle,#mermaid-el0ls0ytk17 .section-6 path{fill:hsl(150, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .section-6 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon-6{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge-6{stroke:hsl(150, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .edge-depth-6{stroke-width:-4;}#mermaid-el0ls0ytk17 .section-6 line{stroke:rgb(84.7499999999, 84.7499999999, 84.7499999999);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-7 rect,#mermaid-el0ls0ytk17 .section-7 path,#mermaid-el0ls0ytk17 .section-7 circle,#mermaid-el0ls0ytk17 .section-7 path{fill:hsl(210, 0%, 75%);}#mermaid-el0ls0ytk17 .section-7 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon-7{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge-7{stroke:hsl(210, 0%, 75%);}#mermaid-el0ls0ytk17 .edge-depth-7{stroke-width:-7;}#mermaid-el0ls0ytk17 .section-7 line{stroke:rgb(63.75, 63.75, 63.75);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-8 rect,#mermaid-el0ls0ytk17 .section-8 path,#mermaid-el0ls0ytk17 .section-8 circle,#mermaid-el0ls0ytk17 .section-8 path{fill:hsl(270, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .section-8 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon-8{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge-8{stroke:hsl(270, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .edge-depth-8{stroke-width:-10;}#mermaid-el0ls0ytk17 .section-8 line{stroke:rgb(84.7499999999, 84.7499999999, 84.7499999999);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-9 rect,#mermaid-el0ls0ytk17 .section-9 path,#mermaid-el0ls0ytk17 .section-9 circle,#mermaid-el0ls0ytk17 .section-9 path{fill:hsl(300, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .section-9 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon-9{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge-9{stroke:hsl(300, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .edge-depth-9{stroke-width:-13;}#mermaid-el0ls0ytk17 .section-9 line{stroke:rgb(84.7499999999, 84.7499999999, 84.7499999999);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-10 rect,#mermaid-el0ls0ytk17 .section-10 path,#mermaid-el0ls0ytk17 .section-10 circle,#mermaid-el0ls0ytk17 .section-10 path{fill:hsl(330, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .section-10 text{fill:#333;}#mermaid-el0ls0ytk17 .node-icon-10{font-size:40px;color:#333;}#mermaid-el0ls0ytk17 .section-edge-10{stroke:hsl(330, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .edge-depth-10{stroke-width:-16;}#mermaid-el0ls0ytk17 .section-10 line{stroke:rgb(84.7499999999, 84.7499999999, 84.7499999999);stroke-width:3;}#mermaid-el0ls0ytk17 .lineWrapper line{stroke:#333;}#mermaid-el0ls0ytk17 .disabled,#mermaid-el0ls0ytk17 .disabled circle,#mermaid-el0ls0ytk17 .disabled text{fill:lightgray;}#mermaid-el0ls0ytk17 .disabled text{fill:#efefef;}#mermaid-el0ls0ytk17 .section-root rect,#mermaid-el0ls0ytk17 .section-root path,#mermaid-el0ls0ytk17 .section-root circle{fill:hsl(0, 0%, 66.7647058824%);}#mermaid-el0ls0ytk17 .section-root text{fill:#333;}#mermaid-el0ls0ytk17 .icon-container{height:100%;display:flex;justify-content:center;align-items:center;}#mermaid-el0ls0ytk17 .edge{fill:none;}#mermaid-el0ls0ytk17 .eventWrapper{filter:brightness(120%);}#mermaid-el0ls0ytk17 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}1.x   Seriesv1.0.6Basic   scanning22k+   payloadsReflectiondetection2.0   Major   Rewrite2025-12-07   v2.0.0Complete   rewritePlaywrightverificationOAST   integrationSession   hijackingtestsCVSS   scoring2025-12-07   v2.0.1Documentationcleanup2025-12-07   v2.0.3Version   sync   fixesCentralized   loggingAuth   configuration2025-12-08   v2.0.4DefensivevalidationWSS   security   tests4   blue   teammodules2025-12-08   v2.0.5CSWSHcompatibilityOrigin   header   fixes"WSHawk Version Release Timeline"

Sources: CHANGELOG.md L1-L84

Version 2.0.5 (2025-12-08)

Summary

Patch release fixing compatibility issues with newer websockets library versions and improving defensive validation reliability.

Fixed

CSWSH Test Compatibility: Updated CSWSH module to use additional_headers parameter instead of deprecated extra_headers in websockets library
Origin Header Detection: Fixed defensive validation to correctly identify Origin header vulnerabilities

Code Changes

The primary fix involved updating the CSWSH test implementation to support websockets library v12.0+:

Impact:

No breaking changes
Existing scans continue to work
Defensive validation (wshawk-defensive) now more reliable

Migration Path: None required - drop-in replacement for 2.0.4.

Sources: CHANGELOG.md L5-L9

Version 2.0.4 (2025-12-08)

Summary

Major feature release introducing the Defensive Validation Module for blue team security control testing.

Added: Defensive Validation Module

New CLI command and four specialized security validation tests:

flowchart TD

CLI["wshawk-defensive CLI<br>(New Entry Point)"]
DNS["DNS Exfiltration Test<br>Egress filtering validation"]
Bot["Bot Detection Test<br>Anti-bot measure testing"]
CSWSH["CSWSH Test<br>216+ malicious origins<br>Origin header validation"]
WSS["WSS Security Test<br>TLS/cipher/cert validation"]
Payloads["malicious_origins.txt<br>216+ origin payloads"]
Docs["DEFENSIVE_VALIDATION.md<br>Blue team guide"]
CVSS["CVSS Scoring<br>(Extended for defensive)"]

CLI -.-> DNS
CLI -.-> Bot
CLI -.-> CSWSH
CLI -.-> WSS
Payloads -.-> CSWSH
DNS -.-> CVSS
Bot -.-> CVSS
CSWSH -.-> CVSS
WSS -.-> CVSS
CLI -.-> Docs

subgraph subGraph1 ["New Assets"]
    Payloads
    Docs
end

subgraph subGraph0 ["New Modules"]
    DNS
    Bot
    CSWSH
    WSS
end

New Entry Point:

CLI command: wshawk-defensive defined in pyproject.toml L45

New Payload Collection:

File: payloads/malicious_origins.txt with 216+ malicious origin test cases
Package data inclusion: pyproject.toml L51

WSS Protocol Security Validation Details:

TLS version validation (detects SSLv2/v3, TLS 1.0/1.1)
Weak cipher detection (RC4, DES, 3DES)
Certificate validation (expiration, self-signed, chain integrity)
Forward secrecy verification (ECDHE, DHE)
TLS renegotiation security

Improved

Payload Management: Centralized origin payload loading from text files
Architecture: Clear separation between offensive (red team) and defensive (blue team) capabilities
Documentation: Comprehensive blue team guide in docs/DEFENSIVE_VALIDATION.md

CVSS Scoring Ranges

| Test | Minimum CVSS | Maximum CVSS | Severity Range | | --- | --- | --- | --- | | DNS Exfiltration Prevention | 7.5 | 8.2 | HIGH | | Bot Detection Validation | 5.3 | 7.8 | MEDIUM-HIGH | | CSWSH Test | 7.5 | 9.1 | HIGH-CRITICAL | | WSS Security | 5.3 | 9.8 | MEDIUM-CRITICAL |

Migration Path:

No breaking changes to existing wshawk, wshawk-interactive, or wshawk-advanced commands
New functionality accessed via separate wshawk-defensive command
Existing offensive scans unaffected

Sources: CHANGELOG.md L11-L32

pyproject.toml L45

README.md L143-L183

Version 2.0.3 (2025-12-07)

Summary

Critical bug fix release addressing version inconsistencies, timing issues, and missing dependencies.

Fixed

1. Version Mismatch

Synchronized version numbers across __init__.py and package files to 2.0.2
Location: Package version definitions

2. Time Function Consistency

Issue: Usage of time.time() vulnerable to system clock changes
Fix: Migrated to time.monotonic() in scanner_v2.py for monotonic time measurements
Impact: Prevents timing issues during scans if system clock is adjusted

3. Missing PyYAML Dependency

Added PyYAML to dependencies list in pyproject.toml L33
Required for authentication configuration parsing

4. Entry Point Fix

Fixed wshawk command entry point in pyproject.toml L42
Command now correctly invokes wshawk.__main__:cli

Added

Centralized Logging System

New module: wshawk/logger.py
Features: * Colored console output * File logging support * Module-specific loggers * Consistent formatting across all modules

Configurable Authentication

SessionHijackingTester now accepts auth_config parameter
Removed hardcoded credentials (user1/pass1)
Enables custom authentication flows

Improved

Better error handling with specific exception types
All CLI commands verified working: * wshawk * wshawk-interactive * wshawk-advanced

Migration Path

Code Changes Required:

# Before (v2.0.0 - v2.0.1)
tester = SessionHijackingTester(target)
# Credentials were hardcoded to user1/pass1

# After (v2.0.3+)
auth_config = {
    "sequence": [
        {"send": '{"auth": "user1:pass1"}'}
    ]
}
tester = SessionHijackingTester(target, auth_config=auth_config)

Dependencies: Ensure PyYAML is installed (automatically handled by pip):

pip install wshawk>=2.0.3

Sources: CHANGELOG.md L34-L50

pyproject.toml L33

pyproject.toml L42

Version 2.0.1 (2025-12-07)

Summary

Minor documentation-only release.

Changed

Cleaned up documentation formatting
Removed attribution text from README

Migration Path: None - documentation changes only.

Sources: CHANGELOG.md L52-L56

Version 2.0.0 (2025-12-07) - Major Rewrite

Summary

Complete architectural rewrite of WSHawk with professional-grade features, moving from basic reflection-based scanning to comprehensive vulnerability verification.

Architecture Comparison

flowchart TD

V2Input["WebSocket Target"]
V2Scanner["WSHawkV2 Scanner"]
V2Intel["Intelligence Modules<br>MessageIntelligence<br>ServerFingerprinter"]
V2Payloads["22k+ Payloads<br>Intelligent Mutation"]
V2Tests["Vulnerability Tests"]
V2Verify["Multi-Layer Verification"]
V2Playwright["Playwright Browser"]
V2OAST["OAST Provider"]
V2Session["Session Tests"]
V2CVSS["CVSS v3.1 Scoring"]
V2Report["HTML Report<br>Screenshots<br>Logs"]
V1Input["WebSocket Target"]
V1Scan["Basic Scanner"]
V1Payloads["22k+ Payloads"]
V1Detect["Reflection Detection"]
V1Output["Basic Report"]

subgraph subGraph1 ["v2.0.0 Architecture"]
    V2Input
    V2Scanner
    V2Intel
    V2Payloads
    V2Tests
    V2Verify
    V2Playwright
    V2OAST
    V2Session
    V2CVSS
    V2Report
    V2Input -.-> V2Scanner
    V2Scanner -.-> V2Intel
    V2Intel -.-> V2Payloads
    V2Payloads -.-> V2Tests
    V2Tests -.-> V2Verify
    V2Verify -.-> V2Playwright
    V2Verify -.-> V2OAST
    V2Scanner -.-> V2Session
    V2Playwright -.-> V2CVSS
    V2OAST -.-> V2CVSS
    V2Session -.-> V2CVSS
    V2Tests -.-> V2CVSS
    V2CVSS -.-> V2Report
end

subgraph subGraph0 ["v1.0.6 Architecture"]
    V1Input
    V1Scan
    V1Payloads
    V1Detect
    V1Output
    V1Input -.-> V1Scan
    V1Payloads -.-> V1Scan
    V1Scan -.-> V1Detect
    V1Detect -.-> V1Output
end

Added Features

1. Real Vulnerability Verification

Multi-layered verification system
Pattern matching + execution verification
False positive reduction

2. Playwright Integration

Browser-based XSS verification
Real JavaScript execution testing
Screenshot capture for evidence
Module: Playwright browser automation

3. OAST Integration

Out-of-band testing for blind vulnerabilities
DNS/HTTP callback verification
XXE and SSRF detection
Module: OAST provider integration

4. Session Hijacking Tests Six specialized session security tests:

Token reuse attacks
Subscription spoofing
User impersonation
Channel isolation violations
Session fixation
Privilege escalation

5. Intelligent Mutation Engine

8+ WAF bypass strategies
Context-aware payload modification
Encoding variations
Case manipulation

6. CVSS v3.1 Scoring

Automatic vulnerability risk assessment
Industry-standard severity ratings
Vector string generation
Severity levels: CRITICAL, HIGH, MEDIUM, LOW

7. Professional HTML Reporting

Screenshot evidence
Message replay sequences
Raw WebSocket traffic logs
Server fingerprints
Remediation recommendations
Filename format: wshawk_report_YYYYMMDD_HHMMSS.html

8. Adaptive Rate Limiting

Server-friendly scanning
Configurable request rates
Automatic backoff

9. Plugin System

Extensible architecture
Custom vulnerability modules
Custom mutation strategies

10. Three CLI Modes New entry points in pyproject.toml L42-L44

wshawk: Quick scan mode
wshawk-interactive: Guided menu-driven testing
wshawk-advanced: Full CLI control

Changed

API Completely Rewritten

Old scanner class deprecated
New WSHawkV2 class with async/await
Location: wshawk/scanner_v2.py

CLI Interface Redesigned

Multiple command modes
Enhanced argument parsing
Better user experience

Python Version Requirement

Old: Python 3.6+
New: Python 3.8+ (required for async improvements)

Dependencies New dependencies added in pyproject.toml L30-L34

websockets>=12.0
playwright>=1.40.0
aiohttp>=3.9.0
PyYAML>=6.0

Breaking Changes

| Change | v1.0.6 | v2.0.0 | Migration | | --- | --- | --- | --- | | Scanner Class | WSHawk | WSHawkV2 | Update imports to from wshawk.scanner_v2 import WSHawkV2 | | Python Version | 3.6+ | 3.8+ | Upgrade Python interpreter | | CLI Command | wshawk (basic) | wshawk (quick)wshawk-interactive``wshawk-advanced | Use appropriate CLI mode | | Sync/Async | Synchronous | Asynchronous | Wrap calls in asyncio.run() | | Dependencies | Minimal | playwright, aiohttp, PyYAML | Install new dependencies |

Migration Guide: v1.0.6 → v2.0.0

Step 1: Update Python

# Ensure Python 3.8 or higher
python --version  # Should be 3.8+

Step 2: Update Package

pip install --upgrade wshawk

Step 3: Install Browser (for Playwright)

playwright install chromium

Step 4: Update Code

# v1.0.6 Code
from wshawk import WSHawk

scanner = WSHawk("ws://target.com")
scanner.scan()

# v2.0.0 Code
import asyncio
from wshawk.scanner_v2 import WSHawkV2

scanner = WSHawkV2("ws://target.com")
asyncio.run(scanner.run_intelligent_scan())

Step 5: Update CLI Usage

# v1.0.6
wshawk ws://target.com

# v2.0.0 - Choose appropriate mode
wshawk ws://target.com                    # Quick scan
wshawk-interactive                        # Interactive menu
wshawk-advanced ws://target.com --full    # Advanced options

Sources: CHANGELOG.md L58-L77

pyproject.toml L13

pyproject.toml L30-L34

pyproject.toml L42-L44

Version 1.0.6 (Previous)

Summary

Original WSHawk implementation with basic WebSocket security scanning capabilities.

Features

Basic WebSocket connection and message scanning
Reflection-based vulnerability detection
22,000+ attack payloads
Simple text-based output

Limitations:

No execution verification (pattern matching only)
No browser-based testing
No OAST integration
No session security testing
No CVSS scoring
No HTML reporting

Sources: CHANGELOG.md L78-L83

Feature Evolution Matrix

flowchart TD

V1["v1.0.6<br>Basic Scanning"]
V200["v2.0.0<br>Major Rewrite"]
V203["v2.0.3<br>Bug Fixes"]
V204["v2.0.4<br>Defensive Module"]
V205["v2.0.5<br>Compatibility"]
F1["22k+ Payloads"]
F2["Reflection Detection"]
F3["Playwright Verification"]
F4["OAST Integration"]
F5["Session Tests"]
F6["Mutation Engine"]
F7["CVSS Scoring"]
F8["HTML Reports"]
F9["Centralized Logging"]
F10["Auth Config"]
F11["DNS Exfiltration Test"]
F12["Bot Detection Test"]
F13["CSWSH Test"]
F14["WSS Security Test"]

V1 -.-> F1
V1 -.-> F2
V200 -.-> F3
V200 -.-> F4
V200 -.-> F5
V200 -.-> F6
V200 -.-> F7
V200 -.-> F8
V203 -.-> F9
V203 -.-> F10
V204 -.-> F11
V204 -.-> F12
V204 -.-> F13
V204 -.-> F14

subgraph subGraph1 ["Feature Additions"]
    F1
    F2
    F3
    F4
    F5
    F6
    F7
    F8
    F9
    F10
    F11
    F12
    F13
    F14
end

subgraph subGraph0 ["Core Features Timeline"]
    V1
    V200
    V203
    V204
    V205
    V1 -.-> V200
    V200 -.-> V203
    V203 -.-> V204
    V204 -.-> V205
end

| Feature | v1.0.6 | v2.0.0 | v2.0.3 | v2.0.4 | v2.0.5 | | --- | --- | --- | --- | --- | --- | | Scanning | | | | | | | 22k+ Payloads | ✓ | ✓ | ✓ | ✓ | ✓ | | Reflection Detection | ✓ | ✓ | ✓ | ✓ | ✓ | | Verification | | | | | | | Playwright XSS | ✗ | ✓ | ✓ | ✓ | ✓ | | OAST Integration | ✗ | ✓ | ✓ | ✓ | ✓ | | Advanced Testing | | | | | | | Session Hijacking | ✗ | ✓ | ✓ | ✓ | ✓ | | Mutation Engine | ✗ | ✓ | ✓ | ✓ | ✓ | | Defensive Validation | | | | | | | DNS Exfiltration | ✗ | ✗ | ✗ | ✓ | ✓ | | Bot Detection | ✗ | ✗ | ✗ | ✓ | ✓ | | CSWSH Test | ✗ | ✗ | ✗ | ✓ | ✓ | | WSS Security | ✗ | ✗ | ✗ | ✓ | ✓ | | Output | | | | | | | CVSS Scoring | ✗ | ✓ | ✓ | ✓ | ✓ | | HTML Reports | ✗ | ✓ | ✓ | ✓ | ✓ | | Centralized Logging | ✗ | ✗ | ✓ | ✓ | ✓ | | Configuration | | | | | | | Auth Config | ✗ | ✗ | ✓ | ✓ | ✓ | | CLI Modes | | | | | | | Quick Scan | ✗ | ✓ | ✓ | ✓ | ✓ | | Interactive | ✗ | ✓ | ✓ | ✓ | ✓ | | Advanced | ✗ | ✓ | ✓ | ✓ | ✓ | | Defensive | ✗ | ✗ | ✗ | ✓ | ✓ |

Sources: CHANGELOG.md L1-L84

Dependency Evolution

Dependency Changes by Version

flowchart TD

V1WS["websockets<br>(basic)"]
V2WS["websockets>=12.0"]
V2PW["playwright>=1.40.0"]
V2HTTP["aiohttp>=3.9.0"]
V3WS["websockets>=12.0"]
V3PW["playwright>=1.40.0"]
V3HTTP["aiohttp>=3.9.0"]
V3YAML["PyYAML>=6.0"]

V1WS -.->|"upgrade"| V2WS
V2WS -.-> V3WS
V2PW -.-> V3PW
V2HTTP -.-> V3HTTP

subgraph subGraph2 ["v2.0.3 Dependencies"]
    V3WS
    V3PW
    V3HTTP
    V3YAML
end

subgraph subGraph1 ["v2.0.0 Dependencies"]
    V2WS
    V2PW
    V2HTTP
end

subgraph subGraph0 ["v1.0.6 Dependencies"]
    V1WS
end

| Dependency | v1.0.6 | v2.0.0 | v2.0.3+ | Purpose | | --- | --- | --- | --- | --- | | websockets | Any | >=12.0 | >=12.0 | WebSocket client | | playwright | ✗ | >=1.40.0 | >=1.40.0 | Browser automation | | aiohttp | ✗ | >=3.9.0 | >=3.9.0 | OAST HTTP callbacks | | PyYAML | ✗ | ✗ | >=6.0 | Auth config parsing |

Version Pinning Guidance:

Recommended: Use version constraints as defined in pyproject.toml L30-L34
Production: Pin exact versions for reproducibility
Development: Use >= constraints for latest features

Sources: pyproject.toml L30-L34

CHANGELOG.md L39

Distribution Channel History

Package Distribution Evolution

| Channel | Added Version | Status | Location | | --- | --- | --- | --- | | PyPI | v1.0.6 | Active | https://pypi.org/project/wshawk/ | | Docker Hub | v2.0.5 | Active | docker.io/rothackers/wshawk | | GitHub Container Registry | v2.0.5 | Active | ghcr.io/noobforanonymous/wshawk | | GitHub Releases | All versions | Active | https://github.com/noobforanonymous/wshawk/releases |

Docker Image Tags

Starting with v2.0.5, Docker images use semantic versioning tags:

# Specific version
docker pull rothackers/wshawk:2.0.5

# Minor version (receives patches)
docker pull rothackers/wshawk:2.0

# Major version (receives minor updates and patches)
docker pull rothackers/wshawk:2

# Latest (always points to newest release)
docker pull rothackers/wshawk:latest

Multi-Platform Support (v2.0.5+):

linux/amd64
linux/arm64

Sources: RELEASE_SUMMARY.md L23-L38

README.md L47-L60

Python Version Compatibility

| WSHawk Version | Minimum Python | Maximum Python | Notes | | --- | --- | --- | --- | | v1.0.6 | 3.6 | 3.13 | Basic async support | | v2.0.0+ | 3.8 | 3.13 | Advanced async/await features |

Supported Python Versions (Current): As defined in pyproject.toml L21-L26

Python 3.8
Python 3.9
Python 3.10
Python 3.11
Python 3.12
Python 3.13

Sources: pyproject.toml L13

pyproject.toml L21-L26

Breaking Changes Summary

v2.0.0 Breaking Changes

API Change: Scanner class renamed from WSHawk to WSHawkV2
Async Required: All scan methods now async (require asyncio.run())
Python Version: Minimum Python increased from 3.6 to 3.8
Dependencies: New required dependencies (playwright, aiohttp)
CLI Commands: New command structure with multiple modes

Migration Checklist

flowchart TD

Start["Upgrading from v1.x"]
Check1["Python >= 3.8?"]
Upgrade1["Upgrade Python"]
Check2["Install new deps?"]
Install["pip install wshawk>=2.0<br>playwright install chromium"]
Check3["Update imports?"]
UpdateCode["from wshawk.scanner_v2 import WSHawkV2"]
Check4["Async code?"]
AsyncWrap["Wrap in asyncio.run()"]
Check5["CLI usage?"]
UpdateCLI["Choose CLI mode:<br>wshawk/interactive/advanced"]
Done["Migration Complete"]

Start -.-> Check1
Check1 -.->|"No"| Upgrade1
Check1 -.->|"Yes"| Check2
Upgrade1 -.->|"No"| Check2
Check2 -.->|"Yes"| Install
Check2 -.->|"No"| Check3
Install -.->|"Yes"| Check3
Check3 -.->|"No"| UpdateCode
Check3 -.->|"Yes"| Check4
UpdateCode -.-> Check4
Check4 -.->|"No"| AsyncWrap
Check4 -.->|"Yes"| Check5
AsyncWrap -.-> Check5
Check5 -.-> UpdateCLI
Check5 -.-> Done
UpdateCLI -.-> Done

Sources: CHANGELOG.md L58-L77

Semantic Version Tag Strategy

WSHawk uses a comprehensive Docker tag strategy for maximum flexibility:

| Tag Format | Example | Updates With | Use Case | | --- | --- | --- | --- | | Full version | 2.0.5 | Never | Production pinning | | Major.Minor | 2.0 | Patch releases | Receive bug fixes | | Major | 2 | Minor + patches | Receive features | | Latest | latest | All releases | Development |

Implementation: Docker tags are automatically generated by GitHub Actions workflow for each version published.

Sources: RELEASE_SUMMARY.md L29-L32

Changelog File Format

The changelog follows Keep a Changelog format with sections:

Added: New features
Changed: Changes in existing functionality
Deprecated: Soon-to-be removed features
Removed: Removed features
Fixed: Bug fixes
Security: Vulnerability fixes

Each version entry includes:

Version number in square brackets
Release date in YYYY-MM-DD format
Categorized changes
Impact and migration notes where applicable

Location: CHANGELOG.md L1-L84

Sources: CHANGELOG.md L1-L84