Getting Started

Name: WSHawk
Author: Regaan

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

This document provides a step-by-step guide for installing WSHawk, running your first WebSocket security scan, and understanding the available operational modes. It covers installation prerequisites, package distribution options, and basic usage patterns for all four CLI entrypoints.

For detailed installation options and environment-specific setup, see Installation Methods. For comprehensive CLI flag documentation, see CLI Command Reference. For advanced scanning features and Python API integration, see Advanced Usage.

Prerequisites

WSHawk requires the following system prerequisites before installation:

| Requirement | Version | Purpose | |-------------|---------|---------| | Python | 3.8+ | Core runtime (tested through 3.13) | | pip | Latest | Package installation | | Operating System | Linux/macOS/Windows | Cross-platform support | | Docker (optional) | 20.10+ | Containerized deployment |

Sources: pyproject.toml:13, pyproject.toml:21-26

Installation Decision Tree

graph TD
    Start["Choose Installation Method"]
    
    Start --> Q1{"Container or<br/>Native?"}
    
    Q1 -->|"Container"| Q2{"Which<br/>Registry?"}
    Q1 -->|"Native"| Q3{"Install via<br/>pip or source?"}
    
    Q2 -->|"Docker Hub"| DH["docker pull rothackers/wshawk:latest"]
    Q2 -->|"GitHub Registry"| GH["docker pull ghcr.io/regaan/wshawk:latest"]
    
    Q3 -->|"pip"| PIP["pip install wshawk"]
    Q3 -->|"Source"| SRC["git clone + pip install -e ."]
    
    DH --> BrowserOpt{"Need XSS<br/>verification?"}
    GH --> BrowserOpt
    PIP --> BrowserOpt
    SRC --> BrowserOpt
    
    BrowserOpt -->|"Yes"| Browser["playwright install chromium"]
    BrowserOpt -->|"No"| Ready["Ready to Scan"]
    Browser --> Ready
    
    Ready --> FirstScan["wshawk ws://target.com"]

Diagram: Installation Path Selection

The Docker images (rothackers/wshawk and ghcr.io/regaan/wshawk) include all dependencies and Playwright browsers pre-installed. Native installations via pip install wshawk require manual Playwright installation for browser-based XSS verification features.

Sources: README.md:54-80, pyproject.toml:29-35

Package Distribution Channels

WSHawk is distributed through three official channels, each targeting different deployment scenarios:

| Channel | Command | Use Case | Auto-Update | |---------|---------|----------|-------------| | PyPI | pip install wshawk | Native Python environments, CI/CD scripts | pip install --upgrade wshawk | | Docker Hub | docker pull rothackers/wshawk | Production servers, isolated environments | Pull latest tag | | GitHub Container Registry | docker pull ghcr.io/regaan/wshawk | GitHub Actions, enterprise registries | GHCR integration |

All three channels distribute the same codebase version (e.g., 3.0.0) with semantic versioning tags.

Sources: README.md:55-71, .github/workflows/ghcr-publish.yml:12-13

CLI Entrypoint Architecture

graph TB
    User["Security Professional"]
    
    subgraph "CLI Entrypoints [pyproject.toml:42-46]"
        EP1["wshawk"]
        EP2["wshawk-interactive"]
        EP3["wshawk-advanced"]
        EP4["wshawk-defensive"]
    end
    
    subgraph "Python Module Mapping"
        M1["wshawk.__main__:cli"]
        M2["wshawk.interactive:cli"]
        M3["wshawk.advanced_cli:cli"]
        M4["wshawk.defensive_cli:cli"]
    end
    
    subgraph "Core Scanner"
        Scanner["wshawk.scanner_v2.WSHawkV2"]
        Legacy["wshawk.__main__ (legacy)"]
    end
    
    subgraph "Web Interface"
        WebFlag["wshawk --web"]
        Flask["wshawk.web_dashboard (Flask)"]
        DB["scans.db (SQLite)"]
    end
    
    User --> EP1
    User --> EP2
    User --> EP3
    User --> EP4
    User --> WebFlag
    
    EP1 --> M1
    EP2 --> M2
    EP3 --> M3
    EP4 --> M4
    WebFlag --> Flask
    
    M1 --> Legacy
    M2 --> Scanner
    M3 --> Scanner
    M4 --> Scanner
    
    Legacy -.->|"delegates to"| Scanner
    
    Flask --> Scanner
    Flask --> DB
    Scanner --> DB

Diagram: CLI Entrypoint to Code Module Mapping

The four CLI commands defined in pyproject.toml:42-46 map to specific Python module entrypoints. All modern commands converge on the scanner_v2.WSHawkV2 class, which implements the core scanning engine. The --web flag launches a Flask-based dashboard that persists scan results to scans.db.

Sources: pyproject.toml:42-46, README.md:86-109

First Scan Execution Flow

The simplest way to perform a WebSocket security assessment is using the wshawk command with a target URL:

# Basic scan with automatic vulnerability detection
wshawk ws://target.com

# Docker equivalent
docker run --rm rothackers/wshawk ws://target.com

Execution Phases

graph LR
    CMD["wshawk ws://target.com"]
    
    CMD --> Init["wshawk.__main__:cli()"]
    Init --> Parse["Argument Parsing"]
    Parse --> Create["WSHawkV2 instantiation"]
    
    Create --> Phase1["Connection Phase"]
    Phase1 --> Phase2["Learning Phase<br/>(5-10s sample)"]
    Phase2 --> Phase3["Injection Phase<br/>(22,000+ payloads)"]
    Phase3 --> Phase4["Verification Phase<br/>(VulnerabilityVerifier)"]
    Phase4 --> Phase5["Reporting Phase"]
    
    Phase5 --> HTML["wshawk_report_YYYYMMDD_HHMMSS.html"]
    Phase5 --> Console["Console Summary"]

Diagram: Basic Scan Execution Pipeline

The wshawk command instantiates a WSHawkV2 object with the target URL, then executes a five-phase scanning workflow. The learning phase collects sample messages to understand the protocol structure before injection begins. Results are written to a timestamped HTML report file.

Sources: README.md:86-89, README.md:163-183

CLI Command Comparison Matrix

WSHawk provides four distinct CLI commands, each optimized for different use cases and user personas:

| Command | Module | Learning Curve | Output Persistence | Best For | |---------|--------|----------------|-------------------|----------| | wshawk | __main__:cli | Low | File-based HTML | One-off scans, automation | | wshawk-interactive | interactive:cli | Lowest | File-based HTML | Learning WebSocket security | | wshawk-advanced | advanced_cli:cli | Medium | File-based HTML | Power users, full feature access | | wshawk-defensive | defensive_cli:cli | Medium | File-based HTML | Blue team validation | | wshawk --web | web_dashboard | Low | SQLite + HTML | Team collaboration, SOC ops |

Usage Examples:

# Quick automated scan
wshawk ws://echo.websocket.org

# Interactive menu-driven interface
wshawk-interactive

# Advanced scan with smart payloads and browser verification
wshawk-advanced ws://target.com --smart-payloads --playwright --full

# Defensive security control validation
wshawk-defensive ws://your-server.com

# Launch persistent web dashboard (port 5000)
wshawk --web --port 5000 --host 0.0.0.0

Sources: pyproject.toml:42-46, README.md:84-110, README.md:152-160

Web Dashboard Quick Start

For team environments requiring scan history and centralized reporting, WSHawk provides a Flask-based web dashboard:

# Set authentication password
export WSHAWK_WEB_PASSWORD='your-secure-password'

# Launch dashboard
wshawk --web --port 5000 --host 0.0.0.0

Access the dashboard at http://localhost:5000. The web interface persists all scan results to scans.db (SQLite with WAL mode) and provides:

Real-time scan progress tracking
Historical scan management
Interactive HTML report viewing
REST API for programmatic access (/api/scans)
SHA-256 password authentication

Authentication: If WSHAWK_WEB_PASSWORD is not set, the dashboard runs in open mode (local testing only). For production deployments, always configure authentication.

Sources: README.md:112-136, README.md:152-160

Verifying Installation

After installation, verify WSHawk is correctly installed and all entrypoints are accessible:

# Check version
wshawk --version

# Verify all CLI entrypoints
which wshawk
which wshawk-interactive
which wshawk-advanced
which wshawk-defensive

# Test basic connectivity (safe echo server)
wshawk ws://echo.websocket.org

# Docker verification
docker run --rm rothackers/wshawk --version

Expected output includes version 3.0.0 and successful command execution without import errors.

Sources: pyproject.toml:7, README.md:1

Optional: Playwright Browser Setup

For advanced XSS verification using real browser execution (Playwright integration), install Chromium after pip installation:

# Install Playwright browsers
playwright install chromium

# Verify installation
python3 -c "from playwright.sync_api import sync_playwright; print('Playwright OK')"

Docker images include Playwright browsers pre-installed. This step is only required for native pip installations.

Enable browser verification in scans:

# CLI flag
wshawk-advanced ws://target.com --playwright

# Python API
from wshawk.scanner_v2 import WSHawkV2
scanner = WSHawkV2("ws://target.com")
scanner.use_headless_browser = True

Sources: README.md:60-62, README.md:101-102, pyproject.toml:31

Configuration File Setup (Optional)

WSHawk supports hierarchical configuration via wshawk.yaml for enterprise integrations and persistent settings:

# Generate configuration template
python3 -m wshawk.config --generate

# Rename template
mv wshawk.yaml.example wshawk.yaml

# Edit configuration
# Configure Jira, DefectDojo, webhooks, rate limits, etc.

Configuration precedence: CLI arguments > Environment variables > wshawk.yaml > defaults

For detailed configuration options and secret resolution, see Configuration System.

Sources: README.md:137-150

Minimal Working Example

The shortest path from installation to first scan:

# Install
pip install wshawk

# Scan
wshawk ws://echo.websocket.org

# View report
# Opens wshawk_report_<timestamp>.html in browser

This executes a complete security assessment with:

22,000+ payload injection attempts
Real vulnerability verification (not just pattern matching)
CVSS v3.1 risk scoring
Professional HTML report generation

Sources: README.md:55-89

Docker Volume Mounts for Reports

When running WSHawk in Docker, mount a volume to persist reports and scan data:

# Create output directory
mkdir -p wshawk-reports

# Run with volume mount
docker run --rm \
  -v $(pwd)/wshawk-reports:/app/reports \
  rothackers/wshawk ws://target.com

# Reports available in ./wshawk-reports/

For persistent web dashboard data:

docker run --rm \
  -v $(pwd)/wshawk-data:/app/data \
  -p 5000:5000 \
  -e WSHAWK_WEB_PASSWORD='secure-pass' \
  rothackers/wshawk wshawk --web --host 0.0.0.0

This mounts wshawk-data directory to persist scans.db across container restarts.

Sources: README.md:66-78

Next Steps

After completing basic installation and your first scan, explore these advanced capabilities:

| Topic | Wiki Page | Description | |-------|-----------|-------------| | Full CLI Options | CLI Command Reference | Detailed flag documentation for all commands | | Advanced Scanning | Advanced CLI Options | Smart payloads, browser verification, custom rates | | Python Integration | Python API | Programmatic scanning in custom scripts | | Team Deployments | Web Management Dashboard | Multi-user scanning with history | | Security Validation | Defensive Mode Overview | Blue team control validation | | CI/CD Integration | CI/CD Integration | GitHub Actions, GitLab CI with SARIF export |

For immediate hands-on learning, start with wshawk-interactive for a menu-driven experience, or review Quick Start Examples for common scanning scenarios.

Sources: README.md:242-265