Quick Start Examples

Quick Start Examples

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

Purpose and Scope

This page provides practical, ready-to-run examples for common WSHawk scanning scenarios. It demonstrates how to execute basic scans, perform defensive validation, integrate with Docker and CI/CD pipelines, and use the Python API. These examples assume WSHawk is already installed (see Installation Methods for setup instructions). For a comprehensive reference of all CLI options and flags, see CLI Command Reference.

Overview of Execution Modes

WSHawk provides four distinct CLI entry points and a Python API, each optimized for different use cases:

graph TB
    subgraph "CLI Entry Points"
        CLI1["wshawk<br/>(Basic CLI)"]
        CLI2["wshawk-interactive<br/>(Menu-driven)"]
        CLI3["wshawk-advanced<br/>(Full control)"]
        CLI4["wshawk-defensive<br/>(Blue team)"]
    end
    
    subgraph "Core Classes"
        Scanner["WSHawkV2<br/>scanner_v2.py"]
        DefVal["DefensiveValidation<br/>defensive_validation.py"]
    end
    
    subgraph "Modules"
        Intel["MessageIntelligence<br/>ServerFingerprinter"]
        Vuln["VulnerabilityTesters<br/>SQL/XSS/XXE/etc"]
        DefTests["DNSExfiltrationTest<br/>BotDetectionValidator<br/>CSWSHValidator<br/>WSSSecurityValidator"]
    end
    
    CLI1 --> Scanner
    CLI2 --> Scanner
    CLI3 --> Scanner
    CLI4 --> DefVal
    
    Scanner --> Intel
    Scanner --> Vuln
    DefVal --> DefTests
    
    style CLI1 fill:#f9f9f9
    style CLI2 fill:#f9f9f9
    style CLI3 fill:#f9f9f9
    style CLI4 fill:#f9f9f9

Sources: README.md:64-93, README.md:147-183

Basic Scanning Examples

Example 1: Quick Security Assessment

The wshawk command provides the fastest path to scanning a WebSocket endpoint with all features enabled by default:

# Scan a WebSocket endpoint
wshawk ws://echo.websocket.org

# Scan a secure WebSocket
wshawk wss://secure-server.com/socket

# Scan with custom port
wshawk ws://192.168.1.100:8765

What This Does:

  • Initiates a 5-second learning phase to understand message formats
  • Tests all 7 vulnerability types (SQL injection, XSS, XXE, SSRF, NoSQL, path traversal, command injection)
  • Applies intelligent payload mutation for WAF bypass
  • Executes 6 session hijacking security tests
  • Generates an HTML report with CVSS v3.1 scoring

Output:

wshawk_report_20240115_143022.html

The report includes vulnerability findings, server fingerprints, request/response logs, and remediation guidance.

Sources: README.md:68-72

Example 2: Interactive Testing Workflow

The wshawk-interactive command provides a menu-driven interface for manual testing:

wshawk-interactive

Interactive Menu Flow:

flowchart TD
    Start["wshawk-interactive<br/>execution"]
    Prompt["Prompt for target URL<br/>ws:// or wss://"]
    Menu["Display Test Menu<br/>1. SQL Injection<br/>2. XSS Detection<br/>3. XXE Testing<br/>4. Session Security<br/>5. All Tests<br/>6. Exit"]
    Select["User selects option<br/>1-6"]
    Execute["Execute selected tests<br/>via WSHawkV2"]
    Results["Display results<br/>Real-time feedback"]
    Loop["Return to menu"]
    Exit["Generate report<br/>and exit"]
    
    Start --> Prompt
    Prompt --> Menu
    Menu --> Select
    Select --> Execute
    Execute --> Results
    Results --> Loop
    Loop --> Menu
    Select -->|Option 6| Exit

Use Cases:

  • Learning WSHawk's capabilities step-by-step
  • Focusing on specific vulnerability types
  • Manual verification of findings
  • Educational security training

Sources: README.md:74-78

Example 3: Advanced Mode with Full Control

The wshawk-advanced command exposes granular configuration options:

# Basic advanced scan
wshawk-advanced ws://target.com

# Enable Playwright browser verification for XSS
wshawk-advanced ws://target.com --playwright

# Custom rate limiting (5 requests per second)
wshawk-advanced ws://target.com --rate 5

# Enable all features including OAST
wshawk-advanced ws://target.com --full

# Disable OAST testing
wshawk-advanced ws://target.com --no-oast

# Combine multiple options
wshawk-advanced ws://target.com --playwright --rate 3 --full

Command Options Mapping:

| CLI Flag | WSHawkV2 Property | Purpose | |----------|------------------|---------| | --playwright | use_headless_browser = True | Enables browser-based XSS verification via Playwright | | --rate N | rate_limit = N | Sets maximum requests per second | | --full | All features enabled | Activates all detection modules and verification methods | | --no-oast | use_oast = False | Disables out-of-band testing for blind vulnerabilities |

Sources: README.md:81-93, README.md:134-141

Defensive Validation Examples

The wshawk-defensive command targets blue team security control validation:

Example 4: Complete Defensive Assessment

# Run all defensive tests
wshawk-defensive ws://production-server.com

# Test secure WebSocket endpoint
wshawk-defensive wss://secure-api.company.com/socket

Test Execution Flow:

flowchart LR
    Start["wshawk-defensive<br/>command"]
    
    subgraph "Defensive Tests"
        DNS["DNSExfiltrationTest<br/>XXE/SSRF vectors<br/>OAST callbacks"]
        Bot["BotDetectionValidator<br/>Playwright headless<br/>Evasion techniques"]
        CSWSH["CSWSHValidator<br/>216+ malicious origins<br/>Origin validation"]
        WSS["WSSSecurityValidator<br/>TLS/cipher checks<br/>Certificate validation"]
    end
    
    Output["Findings with CVSS<br/>Remediation guidance<br/>HTML report"]
    
    Start --> DNS
    Start --> Bot
    Start --> CSWSH
    Start --> WSS
    
    DNS --> Output
    Bot --> Output
    CSWSH --> Output
    WSS --> Output

Expected Output:

======================================================================
WSHawk Defensive Validation Suite
======================================================================

[*] Testing DNS Exfiltration Prevention...
[*] Validating Bot Detection Effectiveness...
[*] Testing CSWSH Prevention...
[*] Validating WSS Protocol Security...

======================================================================
DEFENSIVE VALIDATION SUMMARY
======================================================================

Findings:
  CRITICAL: 1
  HIGH: 2
  MEDIUM: 1

[CRITICAL] CSWSH - Origin Header Validation
  CVSS: 9.1
  Description: Server accepts 216 untrusted origins
  Recommendation: Implement Origin header validation immediately

Sources: README.md:143-183, docs/DEFENSIVE_VALIDATION.md:140-147

Example 5: Individual Defensive Tests

# Python API for granular control
from wshawk.defensive_validation import (
    DNSExfiltrationTest,
    BotDetectionValidator,
    CSWSHValidator,
    WSSSecurityValidator
)

# Test DNS exfiltration prevention only
import asyncio
import websockets

async def test_dns():
    async with websockets.connect("ws://target.com") as ws:
        test = DNSExfiltrationTest("ws://target.com")
        results = await test.run_all_tests(ws)
        print(test.findings)

asyncio.run(test_dns())

Module Mappings:

| Module Class | Test Focus | CVSS Range | |--------------|-----------|------------| | DNSExfiltrationTest | DNS-based data exfiltration via XXE/SSRF | 7.5-8.2 | | BotDetectionValidator | Anti-bot measure effectiveness | 5.3-7.8 | | CSWSHValidator | Origin header and CSRF token validation | 7.5-9.1 | | WSSSecurityValidator | TLS version, cipher strength, certificate validity | 5.3-9.8 |

Sources: docs/DEFENSIVE_VALIDATION.md:160-189

Docker-Based Scanning

Example 6: Docker Hub Deployment

# Pull from Docker Hub
docker pull rothackers/wshawk:latest

# Basic scan
docker run --rm rothackers/wshawk ws://target.com

# Defensive validation
docker run --rm rothackers/wshawk wshawk-defensive ws://target.com

# Interactive mode
docker run --rm -it rothackers/wshawk wshawk-interactive

# Save reports to host filesystem
mkdir -p reports
docker run --rm -v $(pwd)/reports:/app/reports rothackers/wshawk ws://target.com

Sources: README.md:47-60, docs/DOCKER.md:5-25

Example 7: GitHub Container Registry

# Pull from GHCR
docker pull ghcr.io/regaan/wshawk:latest

# Run scan
docker run --rm ghcr.io/regaan/wshawk wshawk-advanced ws://target.com --full

Docker Image Details:

  • Base Image: python:3.11-slim
  • Size: ~150MB (multi-stage build)
  • User: Non-root (wshawk:1000)
  • Platforms: linux/amd64, linux/arm64

Sources: docs/DOCKER.md:1-25, RELEASE_SUMMARY.md:117-123

Example 8: Scanning Local Services

# Access host network for localhost testing
docker run --rm --network host rothackers/wshawk ws://localhost:8765

# Using docker-compose for multi-container setup
docker-compose up -d
docker-compose exec wshawk wshawk ws://vulnerable-server:8765
docker-compose down

Sources: docs/DOCKER.md:66-98, docker-compose.yml:1-36

Python API Examples

Example 9: Programmatic Scanning

import asyncio
from wshawk.scanner_v2 import WSHawkV2

async def scan_target():
    # Initialize scanner
    scanner = WSHawkV2("ws://target.com")
    
    # Configure options
    scanner.use_headless_browser = True
    scanner.use_oast = True
    scanner.rate_limit = 5
    
    # Execute scan
    await scanner.run_intelligent_scan()
    
    # Access results
    for vuln in scanner.vulnerabilities:
        print(f"{vuln['type']}: {vuln['severity']} (CVSS: {vuln['cvss']})")
        print(f"  Evidence: {vuln['evidence']}")
        print(f"  Recommendation: {vuln['recommendation']}")

# Run scan
asyncio.run(scan_target())

Key WSHawkV2 Properties:

classDiagram
    class WSHawkV2 {
        +str target_url
        +bool use_headless_browser
        +bool use_oast
        +int rate_limit
        +list vulnerabilities
        +dict server_info
        +run_intelligent_scan() async
        +generate_report() void
    }
    
    class MessageIntelligence {
        +detect_format() dict
        +find_injectable_fields() list
    }
    
    class ServerFingerprinter {
        +detect_technology() dict
        +identify_database() str
    }
    
    WSHawkV2 --> MessageIntelligence
    WSHawkV2 --> ServerFingerprinter

Sources: README.md:196-209

Example 10: Custom Authentication

import asyncio
from wshawk.scanner_v2 import WSHawkV2

async def scan_with_auth():
    scanner = WSHawkV2("ws://authenticated-app.com/socket")
    
    # Configure authentication sequence
    scanner.auth_sequence = [
        {
            "type": "send",
            "payload": {"action": "login", "username": "test", "password": "test123"}
        },
        {
            "type": "receive",
            "expected": {"status": "authenticated"}
        }
    ]
    
    await scanner.run_intelligent_scan()

asyncio.run(scan_with_auth())

Sources: Referenced from scanner architecture patterns

CI/CD Integration Examples

Example 11: GitHub Actions Workflow

# .github/workflows/websocket-security.yml
name: WebSocket Security Scan

on:
  push:
    branches: [main, develop]
  pull_request:
  schedule:
    - cron: '0 2 * * 1'  # Weekly Monday 2 AM

jobs:
  security-scan:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install WSHawk
        run: pip install wshawk==2.0.5
      
      - name: Run offensive scan
        run: wshawk ws://staging.myapp.com/socket
      
      - name: Run defensive validation
        run: wshawk-defensive ws://staging.myapp.com/socket
      
      - name: Upload reports
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: wshawk-reports
          path: wshawk_report_*.html

Sources: docs/DEFENSIVE_VALIDATION.md:376-411

Example 12: Docker-Based CI/CD

# .gitlab-ci.yml
websocket_security:
  stage: test
  image: rothackers/wshawk:latest
  script:
    - wshawk ws://$CI_ENVIRONMENT_URL/socket
    - wshawk-defensive ws://$CI_ENVIRONMENT_URL/socket
  artifacts:
    paths:
      - wshawk_report_*.html
    expire_in: 30 days
  only:
    - main
    - staging

# Jenkins Pipeline
pipeline {
    agent {
        docker {
            image 'rothackers/wshawk:latest'
        }
    }
    stages {
        stage('WebSocket Scan') {
            steps {
                sh 'wshawk ws://staging-server:8765'
            }
        }
        stage('Defensive Validation') {
            steps {
                sh 'wshawk-defensive ws://staging-server:8765'
            }
        }
    }
    post {
        always {
            archiveArtifacts artifacts: 'wshawk_report_*.html'
        }
    }
}

Sources: docs/DOCKER.md:145-163

Report Output Examples

Example 13: Understanding Report Structure

All scanning modes generate timestamped HTML reports:

wshawk_report_20240115_143022.html

Report Contents:

graph TB
    Report["HTML Report<br/>wshawk_report_*.html"]
    
    subgraph "Report Sections"
        Summary["Executive Summary<br/>Total findings by severity<br/>CVSS score distribution"]
        Vulns["Vulnerability Details<br/>Type, CVSS, evidence<br/>Reproduction steps"]
        Server["Server Intelligence<br/>Technology fingerprint<br/>Message format analysis"]
        Traffic["Traffic Logs<br/>Request/response pairs<br/>WebSocket frames"]
        Screenshots["Screenshots<br/>Playwright captures<br/>XSS execution proof"]
        Remediation["Remediation Guidance<br/>Fix recommendations<br/>Code examples"]
    end
    
    Report --> Summary
    Report --> Vulns
    Report --> Server
    Report --> Traffic
    Report --> Screenshots
    Report --> Remediation

CVSS Severity Levels:

| Severity | CVSS Score | Color Code | Action Required | |----------|-----------|------------|-----------------| | CRITICAL | 9.0-10.0 | Red | Immediate patching | | HIGH | 7.0-8.9 | Orange | Urgent remediation | | MEDIUM | 4.0-6.9 | Yellow | Schedule fix | | LOW | 0.1-3.9 | Blue | Monitor | | INFO | 0.0 | Green | No action |

Sources: README.md:119-129

Common Scanning Patterns

Pattern 1: Full Security Assessment

# Step 1: Quick scan to identify issues
wshawk ws://target.com

# Step 2: Deep dive with browser verification
wshawk-advanced ws://target.com --playwright --full

# Step 3: Validate defensive controls
wshawk-defensive ws://target.com

# Step 4: Review all generated reports
ls -lh wshawk_report_*.html

Pattern 2: Rate-Limited Production Scan

# Gentle scan for production environments
wshawk-advanced ws://production.com/socket --rate 1 --no-oast

Pattern 3: Comprehensive Docker-Based Testing

# Create isolated testing environment
docker network create wshawk-testing
docker run -d --name target --network wshawk-testing vulnerable-ws-app

# Run scan within same network
docker run --rm --network wshawk-testing \
    -v $(pwd)/reports:/app/reports \
    rothackers/wshawk ws://target:8765

# Cleanup
docker stop target
docker network rm wshawk-testing

Sources: README.md:64-141, docs/DOCKER.md:42-83

Troubleshooting Common Issues

Connection Failures

# Verify WebSocket connectivity first
wscat -c ws://target.com

# Check network accessibility
ping target.com

# Use Docker host network if scanning localhost
docker run --rm --network host rothackers/wshawk ws://localhost:8765

Permission Issues

# Run Docker as current user
docker run --rm --user $(id -u):$(id -g) \
    rothackers/wshawk ws://target.com

# Fix report directory permissions
sudo chown -R $USER:$USER reports/

Playwright Installation

# Install Chromium for XSS verification
playwright install chromium

# Verify installation
playwright --version

Sources: docs/DOCKER.md:167-192