Getting Started

Getting Started

Relevant source files

Purpose and Scope: This page guides you through installing WSHawk, running your first WebSocket security scan, and understanding the four CLI execution modes. For detailed installation options and version pinning, see Installation Methods. For comprehensive command-line options, see CLI Command Reference. For practical scanning scenarios, see Quick Start Examples.

Prerequisites

WSHawk requires Python 3.8 or higher and supports multiple installation methods. The core dependencies are automatically installed during setup.

System Requirements

| Requirement | Minimum Version | Purpose | | --- | --- | --- | | Python | 3.8+ | Runtime environment | | pip | Latest | Package installation (for PyPI method) | | Docker | 20.10+ | Container runtime (for Docker method) | | Disk Space | ~150MB | Docker image or ~50MB for pip installation |

Core Dependencies

The following packages are automatically installed as dependencies:

| Package | Version | Purpose | | --- | --- | --- | | websockets | >=12.0 | WebSocket protocol implementation | | playwright | >=1.40.0 | Browser automation for XSS verification | | aiohttp | >=3.9.0 | HTTP client for OAST integration | | PyYAML | >=6.0 | Configuration file parsing |

Sources: pyproject.toml L29-L34

setup.py L9-L14

requirements.txt L4-L12

Installation Overview

WSHawk supports three installation methods, each optimized for different use cases:

flowchart TD

User["User"]
PyPI["pip install wshawk<br>pypi.org/project/wshawk"]
DockerHub["docker pull rothackers/wshawk<br>docker.io/rothackers/wshawk"]
GHCR["docker pull ghcr.io/noobforanonymous/wshawk<br>GitHub Container Registry"]
CLIScripts["CLI Entry Points<br>wshawk<br>wshawk-interactive<br>wshawk-advanced<br>wshawk-defensive"]
PythonAPI["Python Module<br>wshawk.scanner_v2.WSHawkV2"]
PayloadData["Payload Files<br>payloads/.txtpayloads/**/.json"]

User -.-> PyPI
User -.-> DockerHub
User -.-> GHCR
PyPI -.-> CLIScripts
PyPI -.-> PythonAPI
PyPI -.-> PayloadData
DockerHub -.-> CLIScripts
DockerHub -.-> PayloadData
GHCR -.-> CLIScripts
GHCR -.-> PayloadData

subgraph subGraph1 ["Runtime Artifacts"]
    CLIScripts
    PythonAPI
    PayloadData
end

subgraph subGraph0 ["Installation Methods"]
    PyPI
    DockerHub
    GHCR
end

Installation Method Comparison

| Method | Best For | Installation Command | Size | | --- | --- | --- | --- | | PyPI (pip) | Developers, CI/CD integration, Python scripting | pip install wshawk | ~50MB | | Docker Hub | DevOps teams, isolated environments, no Python setup | docker pull rothackers/wshawk | ~150MB | | GitHub Container Registry | GitHub-native workflows, GHCR authentication | docker pull ghcr.io/noobforanonymous/wshawk | ~150MB |

For detailed installation instructions including version pinning and platform-specific guidance, see Installation Methods.

Sources: README.md L36-L62

pyproject.toml L36-L39

RELEASE_SUMMARY.md L22-L38

CLI Entry Points and Code Mapping

Diagram: CLI Commands to Code Modules

flowchart TD

wshawk["wshawk"]
interactive["wshawk-interactive"]
advanced["wshawk-advanced"]
defensive["wshawk-defensive"]
main_cli["wshawk.main:cli"]
inter_cli["wshawk.interactive:cli"]
adv_cli["wshawk.advanced_cli:cli"]
def_cli["wshawk.defensive_cli:cli"]
scanner["wshawk.scanner_v2.WSHawkV2"]
defensive_module["wshawk.defensive_validation"]
payloads["wshawk.payloads.WSPayloads"]
reporter["wshawk.reporting"]

wshawk -.-> main_cli
interactive -.-> inter_cli
advanced -.-> adv_cli
defensive -.-> def_cli

subgraph subGraph2 ["Core Modules"]
    scanner
    defensive_module
    payloads
    reporter
    scanner -.-> payloads
    scanner -.-> reporter
end

subgraph subGraph1 ["Entry Point Functions[setup.py:42-47]"]
    main_cli
    inter_cli
    adv_cli
    def_cli
end

subgraph subGraph0 ["CLI Commands[pyproject.toml:41-45]"]
    wshawk
    interactive
    advanced
    defensive
end

All four CLI commands are registered as console script entry points during installation, providing direct command-line access without needing to invoke python -m.

Sources: pyproject.toml L41-L45

setup.py L41-L47

First Scan

Quick Installation and First Test

For pip users:

# Install WSHawk
pip install wshawk

# Optional: Install browser for XSS verification
playwright install chromium

# Run your first scan
wshawk ws://echo.websocket.org

For Docker users:

# Pull the image
docker pull rothackers/wshawk:latest

# Run your first scan
docker run --rm rothackers/wshawk ws://echo.websocket.org

Understanding the Output

After the scan completes, WSHawk generates an HTML report with the naming pattern wshawk_report_YYYYMMDD_HHMMSS.html. The terminal output shows:

  1. Learning Phase - 5 seconds of passive observation to understand message structure
  2. Vulnerability Testing - Progress indicators for each test category
  3. Findings Summary - CVSS severity breakdown (CRITICAL/HIGH/MEDIUM/LOW)
  4. Report Location - Filesystem path to the generated HTML report

Sources: README.md L64-L93

README.md L119-L129

Understanding CLI Execution Modes

WSHawk provides four distinct CLI commands, each optimized for different testing scenarios and user expertise levels.

Diagram: CLI Mode Selection Workflow

flowchart TD

Start["Start Security Testing"]
Question1["Need defensive<br>validation?"]
Question2["Have specific<br>configuration needs?"]
Question3["Prefer menu-driven<br>or automated?"]
DefensiveCLI["wshawk-defensive<br>wshawk.defensive_cli:cli"]
AdvancedCLI["wshawk-advanced<br>wshawk.advanced_cli:cli"]
InteractiveCLI["wshawk-interactive<br>wshawk.interactive:cli"]
QuickCLI["wshawk<br>wshawk.main:cli"]
DefensiveTests["4 Blue Team Tests<br>DNS/Bot/CSWSH/WSS"]
AdvancedConfig["Custom Flags<br>--playwright --rate N<br>--full --no-oast"]
MenuSystem["Interactive Menu<br>Test Selection<br>Step-by-step"]
AutoScan["Automated Scan<br>All Features<br>Zero Config"]

Start -.-> Question1
Question1 -.->|"Yes"| DefensiveCLI
Question1 -.->|"No"| Question2
Question2 -.->|"Yes"| AdvancedCLI
Question2 -.->|"No"| Question3
Question3 -.->|"Menu"| InteractiveCLI
Question3 -.->|"Automated"| QuickCLI
DefensiveCLI -.-> DefensiveTests
AdvancedCLI -.-> AdvancedConfig
InteractiveCLI -.-> MenuSystem
QuickCLI -.-> AutoScan

Sources: pyproject.toml L41-L45

README.md L66-L104

CLI Mode Comparison

| Command | Ease of Use | Flexibility | Configuration | Primary Audience | | --- | --- | --- | --- | --- | | wshawk | ★★★ | ★ | Zero-config | CI/CD pipelines, automation | | wshawk-interactive | ★★★ | ★★ | Menu-driven | Manual testers, learners | | wshawk-advanced | ★★ | ★★★ | CLI flags | Advanced users, custom workflows | | wshawk-defensive | ★★★ | ★ | Specialized tests | Blue teams, compliance validation |

Mode 1: wshawk - Quick Scan

Purpose: Zero-configuration scanning for automation and CI/CD integration.

Usage:

wshawk ws://target.com

Characteristics:

  • All offensive testing features enabled by default
  • No command-line configuration required
  • Optimal for scripting and automation
  • Invokes wshawk.__main__:cli entry point

Sources: README.md L68-L72

pyproject.toml L42

Mode 2: wshawk-interactive - Menu-Driven Testing

Purpose: User-friendly interface with guided test selection.

Usage:

wshawk-interactive

Characteristics:

  • Interactive menu system for test selection
  • Step-by-step guidance through testing workflow
  • Educational mode with real-time feedback
  • Invokes wshawk.interactive:cli entry point

Sources: README.md L74-L78

pyproject.toml L43

Mode 3: wshawk-advanced - Full Control

Purpose: Granular control over testing parameters via CLI flags.

Usage:

wshawk-advanced ws://target.com --playwright --rate 5 --full

Common Flags:

  • --playwright: Enable browser-based XSS verification
  • --rate N: Set maximum requests per second
  • --full: Enable all features (OAST, Playwright, session tests)
  • --no-oast: Disable out-of-band testing

Characteristics:

  • Maximum configurability
  • Suitable for advanced testing scenarios
  • Custom rate limiting for production environments
  • Invokes wshawk.advanced_cli:cli entry point

Sources: README.md L80-L93

README.md L133-L141

pyproject.toml L44

Mode 4: wshawk-defensive - Blue Team Validation

Purpose: Security control validation for defensive teams.

Usage:

wshawk-defensive ws://target.com

Test Categories:

  1. DNS Exfiltration Prevention (XXE/SSRF egress filtering)
  2. Bot Detection Validation (headless browser detection)
  3. CSWSH Testing (216+ malicious origins, Origin header validation)
  4. WSS Protocol Security (TLS/cipher/certificate validation)

Characteristics:

  • Blue team focused (validates defenses, not attacks)
  • CVSS scoring for security control gaps
  • Specialized remediation guidance
  • Invokes wshawk.defensive_cli:cli entry point

For detailed defensive testing guidance, see Defensive Validation.

Sources: README.md L143-L183

pyproject.toml L45

RELEASE_SUMMARY.md L5-L17

Verifying Installation

Check Installed Version

# For pip installations
pip show wshawk

# Expected output includes:
# Name: wshawk
# Version: 2.0.5
# Location: /path/to/site-packages

Verify CLI Commands

# Test all four CLI entry points
wshawk --help
wshawk-interactive --help
wshawk-advanced --help
wshawk-defensive --help

All commands should display help text without errors. If any command is not found, the installation may be incomplete or PATH configuration may be incorrect.

Test with Echo Server

# Test against a public WebSocket echo server
wshawk ws://echo.websocket.org

# Expected: Learning phase → Testing → Report generation
# Report saved as: wshawk_report_YYYYMMDD_HHMMSS.html

Sources: README.md L39-L44

pyproject.toml L6-L7

Package Data and Payloads

WSHawk includes embedded payload files that are automatically installed with the package:

flowchart TD

Package["wshawk Package<br>[pyproject.toml:50-51]"]
TxtPayloads["payloads/*.txt<br>SQL/XSS/NoSQL/etc"]
JsonPayloads["payloads/**/*.json<br>Structured payloads"]
Origins["payloads/malicious_origins.txt<br>216+ CSWSH origins"]
WSPayloads["wshawk.payloads.WSPayloads"]
FileLoader["External file loading"]

Package -.-> TxtPayloads
Package -.-> JsonPayloads
Package -.-> Origins
TxtPayloads -.-> WSPayloads
JsonPayloads -.-> WSPayloads
Origins -.-> WSPayloads

subgraph subGraph1 ["Payload Loader"]
    WSPayloads
    FileLoader
    WSPayloads -.-> FileLoader
end

subgraph subGraph0 ["Payload Directory Structure"]
    TxtPayloads
    JsonPayloads
    Origins
end

The payload files are registered as package data in both pyproject.toml and setup.py, ensuring they're included in all distribution formats (PyPI wheel, Docker image).

Sources: pyproject.toml L50-L51

setup.py L49-L54

Next Steps

After completing your first scan, explore these resources:

  1. Quick Start Examples - Practical scanning scenarios with command examples
  2. CLI Command Reference - Comprehensive documentation of all CLI options
  3. Offensive Testing - Deep dive into vulnerability detection capabilities
  4. Defensive Validation - Blue team security control validation
  5. Python API Usage - Programmatic integration for custom workflows
  6. Docker Deployment - Container-based deployment with volume mounting and networking

Common Next Actions

| Goal | Recommended Path | | --- | --- | | Run a comprehensive security scan | wshawk-advanced ws://target.com --full | | Learn about specific vulnerability types | See Vulnerability Detection Modules | | Validate security controls | wshawk-defensive ws://target.com | | Integrate into CI/CD pipeline | See CI/CD Integration | | Customize testing logic | See Python API Usage |

Sources: README.md L186-L209