Advanced CLI Options

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

Purpose and Scope

This document provides comprehensive reference documentation for the wshawk-advanced command-line interface, which offers full control over all WSHawk v3.0.0 scanning capabilities through command-line flags. The wshawk-advanced CLI is designed for power users and automated security workflows requiring fine-grained configuration.

For quick scanning without options, see Quick Start Examples. For interactive guided usage, see CLI Command Reference. For programmatic control via Python, see Python API. For hierarchical configuration files, see Configuration System.

Sources: wshawk/advanced_cli.py:1-300, README.md:96-103, pyproject.toml:45

Command Syntax

wshawk-advanced <url> [options]

The wshawk-advanced command requires a target URL or the --web flag to launch the web GUI. URLs can be WebSocket protocols (ws://, wss://) or HTTP protocols (http://, https://) when used with --discover.

Entry Point: The command is registered in pyproject.toml:45 as wshawk-advanced = "wshawk.advanced_cli:cli", which invokes wshawk/advanced_cli.py:286-296.

Sources: wshawk/advanced_cli.py:37-38, pyproject.toml:45

CLI Architecture Overview

The following diagram illustrates how command-line arguments flow through the advanced CLI system to configure the scanner engine.

graph TB
    CLI["wshawk-advanced CLI<br/>Entry Point: cli()"]
    Parser["argparse ArgumentParser<br/>Line 14-84"]
    ConfigLoader["WSHawkConfig.load()<br/>Line 87-88"]
    
    subgraph "Argument Groups"
        CoreArgs["Core Arguments<br/>url, playwright, no-oast<br/>rate, full, discover"]
        ReportArgs["Report Arguments<br/>format, output, binary"]
        IntegArgs["Integration Arguments<br/>defectdojo, jira, webhook"]
        SmartArgs["Smart Payload Arguments<br/>smart-payloads"]
        WebArgs["Web GUI Arguments<br/>web, host, port"]
    end
    
    subgraph "Configuration Merge"
        ConfigOverride["Config Override Logic<br/>Lines 90-97"]
        MergedConfig["Merged Configuration<br/>CLI flags > config file"]
    end
    
    subgraph "Execution Paths"
        WebMode["Web GUI Mode<br/>run_web()<br/>Lines 100-124"]
        DiscoveryMode["Discovery Mode<br/>WSEndpointDiscovery<br/>Lines 133-158"]
        ScanMode["Scan Mode<br/>WSHawkV2<br/>Lines 171-210"]
    end
    
    CLI --> Parser
    Parser --> CoreArgs
    Parser --> ReportArgs
    Parser --> IntegArgs
    Parser --> SmartArgs
    Parser --> WebArgs
    
    ConfigLoader --> MergedConfig
    CoreArgs --> ConfigOverride
    ReportArgs --> ConfigOverride
    IntegArgs --> ConfigOverride
    SmartArgs --> ConfigOverride
    WebArgs --> ConfigOverride
    
    ConfigOverride --> MergedConfig
    
    MergedConfig --> WebMode
    MergedConfig --> DiscoveryMode
    MergedConfig --> ScanMode
    
    WebMode --> FlaskApp["Flask Web Dashboard"]
    DiscoveryMode --> ScanMode
    ScanMode --> WSHawkV2Engine["WSHawkV2 Scanner Engine"]

Sources: wshawk/advanced_cli.py:12-210, wshawk/scanner_v2.py:35-100

Core Scanning Options

Target URL

wshawk-advanced ws://target.com
wshawk-advanced wss://secure-target.com

The positional url argument wshawk/advanced_cli.py:37-38 accepts WebSocket (ws://, wss://) or HTTP (http://, https://) protocols. HTTP URLs trigger automatic endpoint discovery when used with --discover.

| Protocol | Description | Use Case | |----------|-------------|----------| | ws:// | Unencrypted WebSocket | Testing, development environments | | wss:// | TLS-encrypted WebSocket | Production servers | | http:// | HTTP (with --discover) | Automatic endpoint discovery | | https:// | HTTPS (with --discover) | Secure endpoint discovery |

Sources: wshawk/advanced_cli.py:37-38, wshawk/advanced_cli.py:162-164

`--playwright`: Browser-Based XSS Verification

wshawk-advanced ws://target.com --playwright

Enables the HeadlessBrowserXSSVerifier module wshawk/scanner_v2.py:78-79 to verify XSS payloads using a real Chromium browser instance via Playwright. This eliminates false positives by confirming actual JavaScript execution.

Behavior:

When XSS is detected with HIGH confidence, the payload is rendered in a headless browser wshawk/scanner_v2.py:294-309
If JavaScript executes, confidence is upgraded to CRITICAL
Screenshots and execution evidence are captured
Requires playwright install chromium to be run first

Configuration Override: Sets config.scanner.features.playwright = True wshawk/advanced_cli.py:94

Sources: wshawk/advanced_cli.py:39-40, wshawk/scanner_v2.py:78-79, wshawk/scanner_v2.py:294-309

`--no-oast`: Disable Out-of-Band Testing

wshawk-advanced ws://target.com --no-oast

Disables the OASTProvider module that detects blind vulnerabilities (XXE, SSRF, blind RCE) via callback detection. By default, OAST is enabled using interact.sh or a local server.

Configuration Override: Sets config.scanner.features.oast = False wshawk/advanced_cli.py:95

Sources: wshawk/advanced_cli.py:41-42, wshawk/scanner_v2.py:81-83

`--rate N`: Request Rate Limiting

wshawk-advanced ws://target.com --rate 5

Sets the maximum requests per second to prevent overwhelming the target server. Default is 10 req/s wshawk/advanced_cli.py:43-44. This configures the TokenBucketRateLimiter wshawk/scanner_v2.py:62-66.

| Rate | Use Case | |------|----------| | 1-5 | Stealth mode, production servers | | 10 | Default, balanced scanning | | 20-50 | Aggressive scanning, testing environments |

Configuration Override: Sets config.scanner.rate_limit = N wshawk/advanced_cli.py:93

Sources: wshawk/advanced_cli.py:43-44, wshawk/scanner_v2.py:62-66

`--full`: Enable All Features

wshawk-advanced ws://target.com --full

Activates all advanced capabilities wshawk/advanced_cli.py:174-178:

use_headless_browser = True: Playwright XSS verification
use_oast = True: Blind vulnerability detection
use_smart_payloads = True: Adaptive payload generation

Equivalent to: --playwright --smart-payloads without --no-oast.

Sources: wshawk/advanced_cli.py:45-46, wshawk/advanced_cli.py:174-178

`--binary`: Binary Message Analysis

wshawk-advanced ws://target.com --binary

Enables the BinaryMessageHandler wshawk/scanner_v2.py:69 for analyzing binary WebSocket frames (MessagePack, CBOR, Protobuf).

Configuration Override: Sets config.scanner.features.binary_analysis = True wshawk/advanced_cli.py:96

Sources: wshawk/advanced_cli.py:53-54, wshawk/scanner_v2.py:69

Discovery Mode

wshawk-advanced https://target.com --discover
wshawk-advanced http://target.com/app --discover

When --discover is specified or the URL uses HTTP(S) protocol, the WSEndpointDiscovery module wshawk/advanced_cli.py:137-157 scans for WebSocket endpoints before initiating the security scan.

Discovery Process:

Wordlist-based path enumeration (/ws/, /socket.io/, /websocket/, etc.)
JavaScript source analysis for WebSocket URLs
Confidence scoring for each discovered endpoint
Automatic selection of highest-confidence endpoint for scanning

Example Output:

[*] Running WebSocket Endpoint Discovery...
[+] Using discovered endpoint: wss://target.com/api/ws [HIGH]
[*] Other endpoints found (2 more):
  - ws://target.com/socket.io/ [MEDIUM]
  - wss://target.com/notifications [LOW]

Sources: wshawk/advanced_cli.py:47-48, wshawk/advanced_cli.py:133-157

Report Format Options

`--format`: Export Formats

wshawk-advanced ws://target.com --format json
wshawk-advanced ws://target.com --format csv
wshawk-advanced ws://target.com --format sarif
wshawk-advanced ws://target.com --format all

Exports scan results in additional formats beyond the default HTML report wshawk/advanced_cli.py:49-50.

| Format | Description | Use Case | |--------|-------------|----------| | json | JSON structured data | API integration, custom tooling | | csv | CSV spreadsheet | Excel, data analysis | | sarif | SARIF 2.1.0 | GitHub Security, CI/CD integration | | all | All three formats | Comprehensive export |

The ReportExporter class wshawk/advanced_cli.py:221-229 handles format conversion. SARIF export is particularly useful for GitHub Actions integration (see CI/CD Integration).

Sources: wshawk/advanced_cli.py:49-50, wshawk/advanced_cli.py:220-229

`--output`: Custom Output Path

wshawk-advanced ws://target.com --format json --output /tmp/scan.json

Specifies a custom output file path wshawk/advanced_cli.py:51-52. When combined with --format all, only the first format uses this path; others generate automatic filenames.

Sources: wshawk/advanced_cli.py:51-52, wshawk/advanced_cli.py:227-228

Smart Payload Options

`--smart-payloads`: Adaptive Payload Generation

wshawk-advanced ws://target.com --smart-payloads

Activates the Smart Payload Evolution system wshawk/advanced_cli.py:73-74, which includes:

ContextAwareGenerator wshawk/scanner_v2.py:72: Learns message structure during the learning phase and generates context-specific payloads
PayloadEvolver wshawk/scanner_v2.py:74: Uses genetic algorithms to breed successful payloads
FeedbackLoop wshawk/scanner_v2.py:73: Analyzes responses to guide payload evolution

Evolution Phase: After standard scanning, the scanner runs an evolution phase wshawk/scanner_v2.py:638-703 where:

Top-performing payloads are crossed over and mutated
Context-aware variants are generated for high-priority vulnerability categories
Evolved payloads are tested and fitness scores are updated

Configuration Override: Sets config.scanner.features.smart_payloads = True wshawk/advanced_cli.py:97

Sources: wshawk/advanced_cli.py:73-74, wshawk/scanner_v2.py:72-76, wshawk/scanner_v2.py:638-703

Integration Options

The following diagram maps CLI integration flags to their corresponding integration modules:

graph LR
    subgraph "CLI Integration Flags"
        DefectDojoFlag["--defectdojo URL<br/>--dd-product ID"]
        JiraFlag["--jira URL<br/>--jira-project KEY"]
        WebhookFlag["--webhook URL<br/>--webhook-platform TYPE"]
    end
    
    subgraph "Environment Variables"
        DDEnv["DEFECTDOJO_API_KEY"]
        JiraEnv["JIRA_EMAIL<br/>JIRA_API_TOKEN"]
    end
    
    subgraph "Integration Modules"
        DDModule["DefectDojoIntegration<br/>wshawk/integrations/defectdojo.py"]
        JiraModule["JiraIntegration<br/>wshawk/integrations/jira_connector.py"]
        WebhookModule["WebhookNotifier<br/>wshawk/integrations/webhook.py"]
    end
    
    subgraph "Actions"
        DDAction["push_results()<br/>Create Engagement<br/>Import Findings"]
        JiraAction["create_tickets()<br/>Auto-assign Severity<br/>Add CVSS Vectors"]
        WebhookAction["notify()<br/>Platform Detection<br/>Rich Formatting"]
    end
    
    DefectDojoFlag --> DDModule
    DDEnv --> DDModule
    DDModule --> DDAction
    
    JiraFlag --> JiraModule
    JiraEnv --> JiraModule
    JiraModule --> JiraAction
    
    WebhookFlag --> WebhookModule
    WebhookModule --> WebhookAction
    
    WebhookAction --> Slack["Slack Webhook"]
    WebhookAction --> Discord["Discord Webhook"]
    WebhookAction --> Teams["MS Teams Webhook"]

Sources: wshawk/advanced_cli.py:56-69, wshawk/advanced_cli.py:234-281

`--defectdojo`: DefectDojo Integration

export DEFECTDOJO_API_KEY='your-api-key'
wshawk-advanced ws://target.com --defectdojo https://defectdojo.company.com --dd-product 42

Automatically pushes vulnerability findings to DefectDojo wshawk/advanced_cli.py:234-249.

Requirements:

DEFECTDOJO_API_KEY environment variable wshawk/advanced_cli.py:235-236
Product ID via --dd-product (optional; can be inferred)

Behavior: The DefectDojoIntegration.push_results() method creates an engagement and imports findings with CVSS scores and remediation steps.

Sources: wshawk/advanced_cli.py:58-60, wshawk/advanced_cli.py:234-249

`--jira`: Jira Ticket Creation

export JIRA_EMAIL='security@company.com'
export JIRA_API_TOKEN='your-api-token'
wshawk-advanced ws://target.com --jira https://company.atlassian.net --jira-project SEC

Automatically creates Jira tickets for CRITICAL and HIGH severity findings wshawk/advanced_cli.py:251-265.

Requirements:

JIRA_EMAIL environment variable
JIRA_API_TOKEN environment variable wshawk/advanced_cli.py:252-254
Project key via --jira-project (default: SEC) wshawk/advanced_cli.py:64-65

Behavior: Each ticket includes:

Vulnerability type and CVSS score
Reproduction steps with payload
Response evidence
Remediation recommendations

Sources: wshawk/advanced_cli.py:62-65, wshawk/advanced_cli.py:251-265

`--webhook`: Webhook Notifications

wshawk-advanced ws://target.com --webhook https://hooks.slack.com/services/...
wshawk-advanced ws://target.com --webhook https://discord.com/api/webhooks/...
wshawk-advanced ws://target.com --webhook https://outlook.office.com/webhook/...

Sends scan results to a webhook endpoint wshawk/advanced_cli.py:267-281.

Platform Auto-Detection: The CLI automatically detects the webhook platform based on URL patterns wshawk/advanced_cli.py:270-278:

slack.com or hooks.slack → Slack
discord.com or discordapp.com → Discord
office.com or webhook.office → Microsoft Teams

Manual Override:

wshawk-advanced ws://target.com --webhook URL --webhook-platform slack

Sources: wshawk/advanced_cli.py:66-69, wshawk/advanced_cli.py:267-281

Web GUI Launch Options

wshawk-advanced --web
wshawk-advanced --web --port 8080 --host 0.0.0.0

The --web flag launches the Flask-based web management dashboard instead of running a CLI scan wshawk/advanced_cli.py:100-124.

Web GUI Arguments

| Flag | Default | Description | |------|---------|-------------| | --web | — | Launch web GUI mode | | --host | 0.0.0.0 | Bind address (0.0.0.0 for all interfaces) | | --port | 5000 | TCP port for the dashboard |

Authentication: The dashboard uses password authentication configured via WSHAWK_WEB_PASSWORD environment variable wshawk/advanced_cli.py:109. If not set, runs in open mode (local testing only).

Configuration Integration: Web GUI settings can also be specified in wshawk.yaml wshawk/advanced_cli.py:106-111:

web:
  host: 0.0.0.0
  port: 5000
  auth:
    enabled: true
    password: "env:WSHAWK_WEB_PASSWORD"

Database Path: The SQLite database path is read from configuration wshawk/advanced_cli.py:110-122. Default is scans.db in the current directory.

Sources: wshawk/advanced_cli.py:77-83, wshawk/advanced_cli.py:100-124

Configuration System Integration

The advanced CLI integrates with the hierarchical configuration system wshawk/advanced_cli.py:86-97:

graph TB
    ConfigFile["wshawk.yaml<br/>Hierarchical Config"]
    EnvVars["Environment Variables<br/>WSHAWK_* prefix"]
    CLIFlags["CLI Flags<br/>--playwright, --rate, etc."]
    
    ConfigLoad["WSHawkConfig.load()<br/>Line 87-88"]
    
    ConfigFile --> ConfigLoad
    EnvVars --> ConfigLoad
    
    ConfigLoad --> BaseConfig["Base Configuration"]
    
    CLIFlags --> Override["config.set() overrides<br/>Lines 90-97"]
    BaseConfig --> Override
    
    Override --> MergedConfig["Merged Configuration<br/>CLI > env > file"]
    
    MergedConfig --> Scanner["WSHawkV2(config=config)<br/>Line 171"]
    
    MergedConfig --> Features["Feature Flags<br/>playwright, oast, smart_payloads"]
    MergedConfig --> RateLimit["Rate Limiter Config<br/>scanner.rate_limit"]
    MergedConfig --> WebConfig["Web GUI Config<br/>web.host, web.port"]

Precedence Order: CLI flags override environment variables, which override configuration file values wshawk/advanced_cli.py:90-97.

Configuration Override Examples:

if args.rate: config.set('scanner.rate_limit', args.rate)
if args.playwright: config.set('scanner.features.playwright', True)
if args.no_oast: config.set('scanner.features.oast', False)
if args.smart_payloads: config.set('scanner.features.smart_payloads', True)

Sources: wshawk/advanced_cli.py:86-97, wshawk/scanner_v2.py:40-66

Usage Examples

Basic Scan with Browser Verification

wshawk-advanced ws://target.com --playwright --rate 5

Scans at 5 req/s with real browser XSS verification enabled.

Full-Featured Scan with All Integrations

export DEFECTDOJO_API_KEY='...'
export JIRA_EMAIL='security@company.com'
export JIRA_API_TOKEN='...'

wshawk-advanced ws://target.com \
  --full \
  --format all \
  --defectdojo https://dd.company.com \
  --dd-product 42 \
  --jira https://company.atlassian.net \
  --jira-project SEC \
  --webhook https://hooks.slack.com/services/...

Runs a comprehensive scan with:

All features enabled (--full)
All export formats (HTML, JSON, CSV, SARIF)
DefectDojo findings import
Jira ticket creation
Slack notifications

HTTP Discovery with Smart Payloads

wshawk-advanced https://target.com/app --discover --smart-payloads --rate 10

Discovers WebSocket endpoints from the HTTP URL
Selects the highest-confidence endpoint
Runs scan with adaptive payload generation

Binary Protocol Analysis

wshawk-advanced wss://binary-service.com --binary --format json --output scan.json

Analyzes binary WebSocket messages (MessagePack, CBOR, Protobuf) and exports results as JSON.

Sources: wshawk/advanced_cli.py:18-34, README.md:98-103

Option Reference Table

| Category | Flag | Type | Default | Description | |----------|------|------|---------|-------------| | Target | url | positional | — | Target WebSocket or HTTP URL | | Core | --playwright | boolean | False | Enable browser XSS verification | | Core | --no-oast | boolean | False | Disable OAST blind testing | | Core | --rate | integer | 10 | Max requests per second | | Core | --full | boolean | False | Enable all features | | Core | --binary | boolean | False | Binary message analysis | | Discovery | --discover | boolean | False | Discover WebSocket endpoints | | Payloads | --smart-payloads | boolean | False | Adaptive payload generation | | Reporting | --format | choice | — | Export format: json, csv, sarif, all | | Reporting | --output | string | — | Custom output file path | | DefectDojo | --defectdojo | string | — | DefectDojo URL | | DefectDojo | --dd-product | integer | — | Product ID | | Jira | --jira | string | — | Jira URL | | Jira | --jira-project | string | SEC | Project key | | Webhook | --webhook | string | — | Webhook URL | | Webhook | --webhook-platform | choice | generic | Platform: slack, discord, teams | | Web GUI | --web | boolean | False | Launch web dashboard | | Web GUI | --host | string | 0.0.0.0 | Dashboard bind address | | Web GUI | --port | integer | 5000 | Dashboard TCP port |

Sources: wshawk/advanced_cli.py:37-84

Error Handling and Validation

The CLI performs validation before executing scans wshawk/advanced_cli.py:126-164:

Web Mode Validation: If --web is specified, URL is not required wshawk/advanced_cli.py:126-128
URL Validation: For scan modes, URL is mandatory wshawk/advanced_cli.py:126-128
Protocol Validation: WebSocket URLs must start with ws:// or wss:// wshawk/advanced_cli.py:162-164
Integration Validation: Required environment variables are checked before integration wshawk/advanced_cli.py:235-256

Example Error:

wshawk-advanced --defectdojo https://dd.company.com
# Error: Set DEFECTDOJO_API_KEY environment variable

Sources: wshawk/advanced_cli.py:126-164, wshawk/advanced_cli.py:235-256