CLI Command Reference

CLI Command Reference

Relevant source files

Purpose and Scope

This document provides a comprehensive reference for all four command-line interface (CLI) commands provided by WSHawk v2.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 L1-L245

pyproject.toml L41-L45

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.

flowchart TD

wshawk["wshawk<br>Quick Scan"]
interactive["wshawk-interactive<br>Guided Testing"]
advanced["wshawk-advanced<br>Full Control"]
defensive["wshawk-defensive<br>Blue Team"]
main_cli["wshawk.main:cli"]
interactive_cli["wshawk.interactive:cli"]
advanced_cli["wshawk.advanced_cli:cli"]
defensive_cli["wshawk.defensive_cli:cli"]
scanner["WSHawkV2<br>scanner_v2.py"]
defensive_module["DefensiveValidation<br>defensive_validation.py"]
report["wshawk_report_YYYYMMDD_HHMMSS.html"]
logs["Console Logs<br>Colored Output"]

wshawk -.-> main_cli
interactive -.-> interactive_cli
advanced -.-> advanced_cli
defensive -.-> defensive_cli
scanner -.-> report
scanner -.-> logs

subgraph subGraph3 ["Output Artifacts"]
    report
    logs
end

subgraph subGraph2 ["Core Scanner Integration"]
    scanner
    defensive_module
end

subgraph subGraph1 ["Python Module Entry Points"]
    main_cli
    interactive_cli
    advanced_cli
    defensive_cli
end

subgraph subGraph0 ["Console Script Entry Points"]
    wshawk
    interactive
    advanced
    defensive
end

Sources: pyproject.toml L41-L45

setup.py L41-L47

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 L41-L45

README.md L95-L105

wshawk - Quick Scan Command

Entry Point

Module: wshawk.__main__:cli Defined in: pyproject.toml L42

setup.py L43

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

pyproject.toml L42

wshawk-interactive - Interactive Menu Command

Entry Point

Module: wshawk.interactive:cli Defined in: pyproject.toml L43

setup.py L44

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"]
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"]
execute["Execute Selected Tests"]
results["Display Results"]
report["Generate HTML Report"]

start -.-> url
url -.-> menu
menu -.-> sqli
menu -.-> xss
menu -.-> xxe
menu -.-> ssrf
menu -.-> nosql
menu -.-> path
menu -.-> cmd
menu -.-> session
menu -.-> all
sqli -.-> execute
xss -.-> execute
xxe -.-> execute
ssrf -.-> execute
nosql -.-> execute
path -.-> execute
cmd -.-> execute
session -.-> execute
all -.-> execute
execute -.-> results
results -.-> report

subgraph subGraph0 ["Test Categories"]
    sqli
    xss
    xxe
    ssrf
    nosql
    path
    cmd
    session
    all
end

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 L74-L79

pyproject.toml L43

wshawk-advanced - Advanced Control Command

Entry Point

Module: wshawk.advanced_cli:cli Defined in: pyproject.toml L44

setup.py L45

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

README.md L133-L141

wshawk-defensive - Defensive Validation Command

Entry Point

Module: wshawk.defensive_cli:cli Defined in: pyproject.toml L45

setup.py L46

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

flowchart TD

entry["wshawk-defensive ws://target"]
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"]
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"]

entry -.-> dns
entry -.-> bot
entry -.-> cswsh
entry -.-> wss
dns -.-> dns_pass
dns -.-> dns_fail
bot -.-> bot_pass
bot -.-> bot_fail
cswsh -.-> cswsh_pass
cswsh -.-> cswsh_fail
wss -.-> wss_pass
wss -.-> wss_fail

subgraph subGraph1 ["Validation Results"]
    dns_pass
    dns_fail
    bot_pass
    bot_fail
    cswsh_pass
    cswsh_fail
    wss_pass
    wss_fail
end

subgraph subGraph0 ["Defensive Test Suite"]
    dns
    bot
    cswsh
    wss
end

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

pyproject.toml L45

RELEASE_SUMMARY.md L6-L17

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

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 L95-L105

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 L36-L62

pyproject.toml L41-L45