Quick Start Examples

Relevant source files

• README.md
• RELEASE_SUMMARY.md
• docker-compose.yml
• docs/DEFENSIVE_VALIDATION.md
• docs/DOCKER.md

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:

flowchart TD

CLI1["wshawk<br>(Basic CLI)"]
CLI2["wshawk-interactive<br>(Menu-driven)"]
CLI3["wshawk-advanced<br>(Full control)"]
CLI4["wshawk-defensive<br>(Blue team)"]
Scanner["WSHawkV2<br>scanner_v2.py"]
DefVal["DefensiveValidation<br>defensive_validation.py"]
Intel["MessageIntelligence<br>ServerFingerprinter"]
Vuln["VulnerabilityTesters<br>SQL/XSS/XXE/etc"]
DefTests["DNSExfiltrationTest<br>BotDetectionValidator<br>CSWSHValidator<br>WSSSecurityValidator"]

CLI1 -.-> Scanner
CLI2 -.-> Scanner
CLI3 -.-> Scanner
CLI4 -.-> DefVal
Scanner -.-> Intel
Scanner -.-> Vuln
DefVal -.-> DefTests

subgraph Modules ["Modules"]
    Intel
    Vuln
    DefTests
end

subgraph subGraph1 ["Core Classes"]
    Scanner
    DefVal
end

subgraph subGraph0 ["CLI Entry Points"]
    CLI1
    CLI2
    CLI3
    CLI4
end

Sources: README.md L64-L93

README.md L147-L183

---

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 L68-L72

---

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 -.->|"Option 6"| Select
Select -.-> Execute
Execute -.-> Results
Results -.-> Loop
Loop -.-> Menu
Select -.-> 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 L74-L78

---

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 L81-L93

README.md L134-L141

---

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 TD

Start["wshawk-defensive<br>command"]
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"]
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

subgraph subGraph0 ["Defensive Tests"]
    DNS
    Bot
    CSWSH
    WSS
end

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 L143-L183

docs/DEFENSIVE_VALIDATION.md L140-L147

---

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 L160-L189

---

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 L47-L60

docs/DOCKER.md L5-L25

---

Example 7: GitHub Container Registry

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

# Run scan
docker run --rm ghcr.io/noobforanonymous/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 L1-L25

RELEASE_SUMMARY.md L117-L123

---

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 L66-L98

docker-compose.yml L1-L36

---

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 L196-L209

---

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 L376-L411

---

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 L145-L163

---

Report Output Examples

Example 13: Understanding Report Structure

All scanning modes generate timestamped HTML reports:

wshawk_report_20240115_143022.html

Report Contents:

flowchart TD

Report["HTML Report<br>wshawk_report_*.html"]
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"]

Report -.-> Summary
Report -.-> Vulns
Report -.-> Server
Report -.-> Traffic
Report -.-> Screenshots
Report -.-> Remediation

subgraph subGraph0 ["Report Sections"]
    Summary
    Vulns
    Server
    Traffic
    Screenshots
    Remediation
end

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 L119-L129

---

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 L64-L141

docs/DOCKER.md L42-L83

---

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 L167-L192