CLI Command Reference v3.0.0

CLI Command Reference v3.0.0

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

Purpose and Scope

This document provides a comprehensive reference for all command-line interface (CLI) commands provided by WSHawk v3.0. It covers command syntax, available options, execution modes, and output artifacts for each CLI entry point.

For installation instructions, see Installation Methods. For practical usage examples and workflows, see Quick Start Examples. For programmatic usage via the Python API, see Python API Usage.

Sources: README.md:1-245, pyproject.toml:41-45

CLI Command Architecture

WSHawk exposes four distinct command-line interfaces, each serving different use cases and user expertise levels. All commands are registered as console script entry points and invoke specific Python modules.

graph TB
    subgraph "Console Script Entry Points"
        wshawk["wshawk<br/>Quick Scan"]
        interactive["wshawk-interactive<br/>Guided Testing"]
        advanced["wshawk-advanced<br/>Full Control"]
        defensive["wshawk-defensive<br/>Blue Team"]
    end
    
    subgraph "Python Module Entry Points"
        main_cli["wshawk.__main__:cli"]
        interactive_cli["wshawk.interactive:cli"]
        advanced_cli["wshawk.advanced_cli:cli"]
        defensive_cli["wshawk.defensive_cli:cli"]
    end
    
    subgraph "Core Scanner Integration"
        scanner["WSHawkV2<br/>scanner_v2.py"]
        defensive_module["DefensiveValidation<br/>defensive_validation.py"]
    end
    
    subgraph "Output Artifacts"
        report["wshawk_report_YYYYMMDD_HHMMSS.html"]
        logs["Console Logs<br/>Colored Output"]
    end
    
    wshawk --> main_cli
    interactive --> interactive_cli
    advanced --> advanced_cli
    defensive --> defensive_cli
    
    main_cli --> scanner
    interactive_cli --> scanner
    advanced_cli --> scanner
    defensive_cli --> defensive_module
    
    scanner --> report
    scanner --> logs
    defensive_module --> report
    defensive_module --> logs

Sources: pyproject.toml:41-45, setup.py:41-47

Command Overview Table

| Command | Entry Point Module | Target Audience | Complexity | Configuration Style | |---------|-------------------|-----------------|------------|---------------------| | wshawk | wshawk.__main__:cli | CI/CD, Automation | Low | Zero-config, all features enabled | | wshawk-interactive | wshawk.interactive:cli | Manual testers, Learners | Low | Menu-driven selection | | wshawk-advanced | wshawk.advanced_cli:cli | Advanced users | High | CLI flags and options | | wshawk-defensive | wshawk.defensive_cli:cli | Blue teams | Medium | Defensive-specific tests |

Sources: pyproject.toml:41-45, README.md:95-105

wshawk - Quick Scan Command

Entry Point

Module: wshawk.__main__:cli
Defined in: pyproject.toml:42, setup.py:43

Purpose

The wshawk command provides zero-configuration scanning with all offensive testing features enabled by default. Designed for CI/CD integration and quick security assessments.

Syntax

wshawk <websocket_url>

Arguments

| Argument | Required | Description | |----------|----------|-------------| | websocket_url | Yes | Target WebSocket URL (ws:// or wss://) |

Features Enabled

  • 22,000+ attack payloads (SQL, XSS, XXE, SSRF, NoSQL, Path Traversal, Command Injection)
  • Intelligent mutation engine with WAF bypass strategies
  • CVSS v3.1 scoring
  • Session hijacking tests (6 security tests)
  • OAST integration for blind vulnerabilities
  • Adaptive rate limiting (default: 10 requests/second)
  • HTML report generation

Examples

# Basic scan
wshawk ws://target.com

# Scan secure WebSocket
wshawk wss://target.com/chat

# Scan with authentication
wshawk ws://target.com/api --auth-file auth_config.yml

Use Cases

  • Automated security scanning in CI/CD pipelines
  • Quick vulnerability assessments
  • Pre-production security validation
  • Regular scheduled security scans

Sources: README.md:68-72, pyproject.toml:42

wshawk-interactive - Interactive Menu Command

Entry Point

Module: wshawk.interactive:cli
Defined in: pyproject.toml:43, setup.py:44

Purpose

The wshawk-interactive command provides a menu-driven interface for selecting specific vulnerability tests and security validations. Designed for learning and manual testing workflows.

Syntax

wshawk-interactive

Arguments

This command accepts no command-line arguments. All configuration is performed through interactive menu prompts.

Interactive Menu Flow

flowchart TD
    start["Launch wshawk-interactive"]
    url["Prompt: Enter WebSocket URL"]
    menu["Display Test Selection Menu"]
    
    subgraph "Test Categories"
        sqli["SQL Injection Tests"]
        xss["XSS Tests"]
        xxe["XXE Tests"]
        ssrf["SSRF Tests"]
        nosql["NoSQL Injection Tests"]
        path["Path Traversal Tests"]
        cmd["Command Injection Tests"]
        session["Session Security Tests"]
        all["All Tests"]
    end
    
    execute["Execute Selected Tests"]
    results["Display Results"]
    report["Generate HTML Report"]
    
    start --> url
    url --> menu
    menu --> sqli & xss & xxe & ssrf & nosql & path & cmd & session & all
    sqli & xss & xxe & ssrf & nosql & path & cmd & session & all --> execute
    execute --> results
    results --> report

Features

  • Step-by-step guided testing
  • Real-time feedback during test execution
  • Selective test execution (choose specific vulnerability types)
  • Educational mode with detailed explanations
  • All features from wshawk available

Examples

# Launch interactive mode
wshawk-interactive

# Example session:
# > Enter WebSocket URL: ws://target.com
# > Select tests:
#   [1] SQL Injection
#   [2] XSS
#   [3] All Tests
# > Enter selection: 1

Use Cases

  • Learning WebSocket security testing
  • Manual penetration testing
  • Selective vulnerability testing
  • Security demonstrations and training

Sources: README.md:74-79, pyproject.toml:43

wshawk-advanced - Advanced Control Command

Entry Point

Module: wshawk.advanced_cli:cli
Defined in: pyproject.toml:44, setup.py:45

Purpose

The wshawk-advanced command provides granular control over scanning behavior through CLI flags and options. Designed for advanced users who need precise configuration.

Syntax

wshawk-advanced <websocket_url> [OPTIONS]

Command-Line Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | --playwright | Flag | Disabled | Enable browser-based XSS verification with Playwright | | --rate N | Integer | 10 | Set maximum requests per second (rate limiting) | | --full | Flag | Disabled | Enable ALL advanced features (Playwright + OAST + full payloads) | | --no-oast | Flag | Enabled | Disable OAST (Out-of-Band Application Security Testing) | | --auth-file PATH | String | None | Path to YAML authentication configuration file | | --output PATH | String | Auto-generated | Custom path for HTML report output |

Detailed Option Descriptions

--playwright

Enables browser-based XSS verification using Playwright automation framework. When enabled:

  • Spawns headless Chromium browser
  • Executes JavaScript payloads in real browser context
  • Captures screenshots of successful XSS execution
  • Confirms exploitability beyond pattern matching

Prerequisite: playwright install chromium must be executed first.

--rate N

Controls the maximum number of WebSocket messages sent per second. Useful for:

  • Avoiding server-side rate limiting
  • Preventing application crashes from excessive load
  • Compliance with responsible disclosure guidelines
  • Distributed testing across multiple targets

--full

Meta-option that enables all advanced features simultaneously:

  • --playwright (browser verification)
  • OAST integration
  • Full payload sets (all 22,000+ vectors)
  • Maximum mutation strategies

--no-oast

Disables Out-of-Band Application Security Testing. When disabled:

  • No external OAST server interactions
  • Cannot detect blind XXE vulnerabilities
  • Cannot confirm blind SSRF
  • Reduces external dependencies

Examples

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

# With Playwright XSS verification
wshawk-advanced ws://target.com --playwright

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

# All features enabled
wshawk-advanced ws://target.com --full

# Disable OAST for air-gapped environments
wshawk-advanced ws://target.com --no-oast

# Authenticated scan with custom output
wshawk-advanced ws://target.com --auth-file auth.yml --output custom_report.html

# Maximum control: rate limiting + Playwright + no OAST
wshawk-advanced ws://target.com --rate 3 --playwright --no-oast

Use Cases

  • Advanced penetration testing requiring precise control
  • Scans with strict rate limiting requirements
  • Browser-based XSS verification for high-confidence results
  • Air-gapped or restricted network environments (--no-oast)
  • Custom reporting workflows

Sources: README.md:80-93, README.md:133-141

wshawk-defensive - Defensive Validation Command

Entry Point

Module: wshawk.defensive_cli:cli
Defined in: pyproject.toml:45, setup.py:46

Purpose

The wshawk-defensive command is designed for blue teams to validate security controls and defensive measures. Unlike offensive commands, this tests the effectiveness of security implementations rather than discovering exploitable vulnerabilities.

Syntax

wshawk-defensive <websocket_url> [OPTIONS]

Defensive Test Modules

graph TB
    entry["wshawk-defensive ws://target"]
    
    subgraph "Defensive Test Suite"
        dns["DNS Exfiltration Prevention<br/>dns_exfiltration_test.py"]
        bot["Bot Detection Validation<br/>bot_detection_test.py"]
        cswsh["CSWSH Validation<br/>cswsh_test.py<br/>216+ malicious origins"]
        wss["WSS Protocol Security<br/>wss_security_test.py"]
    end
    
    subgraph "Validation Results"
        dns_pass["✓ Egress filtering active"]
        dns_fail["✗ DNS exfiltration possible"]
        
        bot_pass["✓ Headless detection working"]
        bot_fail["✗ Bot evasion successful"]
        
        cswsh_pass["✓ Origin validation enforced"]
        cswsh_fail["✗ CSWSH vulnerable"]
        
        wss_pass["✓ Strong TLS configuration"]
        wss_fail["✗ Weak ciphers/protocols"]
    end
    
    entry --> dns & bot & cswsh & wss
    
    dns --> dns_pass & dns_fail
    bot --> bot_pass & bot_fail
    cswsh --> cswsh_pass & cswsh_fail
    wss --> wss_pass & wss_fail

Test Categories

1. DNS Exfiltration Prevention Test

Purpose: Validates egress filtering effectiveness
Tests:

  • XXE-based DNS exfiltration attempts
  • SSRF-based DNS lookups
  • Detects potential APT-style attack vectors

CVSS Range: 7.5 - 8.2 (HIGH to HIGH)

2. Bot Detection Validation Test

Purpose: Validates anti-bot measures
Tests:

  • Basic headless browser detection
  • Browser fingerprinting resistance
  • Evasion technique resistance

CVSS Range: 5.3 - 7.8 (MEDIUM to HIGH)

3. CSWSH (Cross-Site WebSocket Hijacking) Test

Purpose: Validates Origin header enforcement
Tests:

  • 216+ malicious origin headers
  • CSRF token requirements
  • Session hijacking prevention

CVSS Range: 7.5 - 9.1 (HIGH to CRITICAL)

Payload Source: payloads/malicious_origins.txt

4. WSS Protocol Security Validation

Purpose: Validates TLS/SSL configuration
Tests:

  • Deprecated protocol detection (SSLv2, SSLv3, TLS 1.0, TLS 1.1)
  • Weak cipher suites (RC4, DES, 3DES)
  • Certificate validation (expiration, self-signed, chain integrity)
  • Forward secrecy (ECDHE, DHE support)

CVSS Range: 5.3 - 9.8 (MEDIUM to CRITICAL)

Arguments

| Argument | Required | Description | |----------|----------|-------------| | websocket_url | Yes | Target WebSocket URL (must use wss:// for WSS tests) |

Examples

# Run all defensive tests
wshawk-defensive wss://your-server.com

# Example output:
# [INFO] Running DNS Exfiltration Prevention Test...
# [PASS] DNS exfiltration blocked
# 
# [INFO] Running Bot Detection Validation Test...
# [FAIL] Headless browser not detected (CVSS: 7.8)
# 
# [INFO] Running CSWSH Test...
# [CRITICAL] Server accepts 216 untrusted origins (CVSS: 9.1)
# 
# [INFO] Running WSS Protocol Security Validation...
# [FAIL] TLS 1.0 supported (CVSS: 7.5)

Use Cases

  • Pre-production security control validation
  • Regular security posture assessments
  • Compliance and audit requirements
  • Blue team defensive capability testing
  • Regression testing after security patches

Output

Generates HTML report with:

  • Pass/Fail status for each test
  • CVSS v3.1 scores for failures
  • Detailed remediation guidance
  • Evidence and reproduction steps

Sources: README.md:143-183, pyproject.toml:45, RELEASE_SUMMARY.md:6-17

Common Arguments and Behavior

WebSocket URL Format

All commands accept WebSocket URLs in the following formats:

  • ws://hostname:port/path (unencrypted)
  • wss://hostname:port/path (TLS-encrypted)

Note: The wshawk-defensive WSS tests require wss:// URLs.

Authentication Configuration

Authentication can be configured via YAML file:

auth_sequence:
  - send: '{"type": "auth", "token": "SECRET"}'
  - expect: '{"status": "authenticated"}'

Specify with --auth-file option (available in wshawk-advanced).

Rate Limiting

Default rate: 10 requests/second
Configurable via --rate N in wshawk-advanced

Rate limiting applies to:

  • Payload injection messages
  • Mutation iterations
  • OAST callback attempts

Output Reports

All commands generate HTML reports with timestamp-based filenames:

wshawk_report_YYYYMMDD_HHMMSS.html

Report contents:

  • Executive summary with CVSS score distribution
  • Detailed vulnerability findings
  • Screenshots (if Playwright enabled)
  • WebSocket message logs
  • Server fingerprint information
  • Remediation recommendations

Sources: README.md:119-129

Command Comparison Matrix

| Feature | wshawk | wshawk-interactive | wshawk-advanced | wshawk-defensive | |---------|--------|-------------------|-----------------|------------------| | Ease of Use | ★★★ | ★★★ | ★★ | ★★ | | Flexibility | ★ | ★★ | ★★★ | ★★ | | Zero Configuration | ✓ | ✓ | ✗ | ✓ | | Menu Selection | ✗ | ✓ | ✗ | ✗ | | CLI Options | ✗ | ✗ | ✓ | ✗ | | Offensive Testing | ✓ | ✓ | ✓ | ✗ | | Defensive Validation | ✗ | ✗ | ✗ | ✓ | | Playwright Support | Auto | Auto | Optional (--playwright) | Auto (Bot test) | | OAST Integration | Auto | Auto | Optional (--no-oast) | Auto (DNS test) | | Rate Control | Fixed (10/sec) | Fixed (10/sec) | Configurable (--rate) | Fixed (10/sec) | | Best For | CI/CD, Automation | Learning, Manual Testing | Advanced Users | Blue Teams |

Sources: README.md:95-105

Exit Codes

All commands follow standard exit code conventions:

| Exit Code | Meaning | |-----------|---------| | 0 | Scan completed successfully (may include findings) | | 1 | Error during execution (network error, invalid arguments, etc.) | | 2 | Invalid command-line arguments or options |

Note: Exit code 0 does not mean "no vulnerabilities found" — check the HTML report for findings.

Environment Variables

WSHawk commands respect the following environment variables:

| Variable | Description | Default | |----------|-------------|---------| | WSHAWK_OAST_DOMAIN | Custom OAST callback domain | Built-in service | | WSHAWK_LOG_LEVEL | Logging verbosity (DEBUG, INFO, WARNING, ERROR) | INFO | | PLAYWRIGHT_BROWSERS_PATH | Custom path for Playwright browser binaries | System default |

Sources: Inferred from standard WSHawk architecture

Installation Verification

After installation, verify all commands are available:

# Check wshawk
wshawk --help

# Check wshawk-interactive
wshawk-interactive --help

# Check wshawk-advanced
wshawk-advanced --help

# Check wshawk-defensive
wshawk-defensive --help

Each command should display usage information without errors.

Sources: README.md:36-62, pyproject.toml:41-45