Desktop Advanced Features

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

Purpose and Scope

This document covers the advanced features available in WSHawk Desktop's Advanced and Web Pentest operating modes. These features go beyond basic scanning — they provide real-time traffic interception, high-speed fuzzing, endpoint discovery, multi-step authentication, and attack sequence automation.

For the Desktop architecture and sidecar model, see Desktop Application Architecture. For the 22 web pentest tools, see Desktop Web Pentest Toolkit.

Sources: docs/DESKTOP_V3_GUIDE.md:261-430

Real-Time WebSocket Interceptor

The interceptor is a full-duplex Man-in-the-Middle proxy that sits between the Electron UI and the target WebSocket server. It allows frame-by-frame inspection, modification, and replay — similar to Burp Suite's WebSocket proxy but purpose-built for WSHawk.

Architecture

sequenceDiagram
    participant Client as Electron UI
    participant Proxy as gui_bridge.py /proxy
    participant Target as Real WebSocket Target

    Client->>Proxy: Connect ws://localhost:8080/proxy?url=target
    Proxy->>Target: Connect to real target

    Client->>Proxy: Send frame
    alt Interception ON
        Proxy-->>Client: sio.emit('intercepted_frame')
        Note over Proxy: Awaits user action...
        Client->>Proxy: POST /interceptor/action (forward/drop/edit)
        Proxy->>Target: Forward (optionally modified)
    else Interception OFF
        Proxy->>Target: Relay immediately
    end

    Target->>Proxy: Response frame
    Proxy->>Client: Relay to client

How It Works

The renderer connects to ws://127.0.0.1:8080/proxy?url=<target> instead of the target directly
The backend opens a real connection to the target WebSocket server
Two async coroutines relay frames bidirectionally (client_to_target, target_to_client)
When interception is enabled, outgoing frames are held in an asyncio.Event queue
The UI displays the intercepted frame with three action buttons:
- Forward — Send the frame unchanged to the target
- Drop — Silently discard the frame
- Edit & Forward — Modify the frame content before sending

Interceptor Controls

| Control | Description | |---|---| | Toggle Intercept | Enable/disable frame interception (passthrough when off) | | Auto-Forward Rules | Skip interception for frames matching a regex pattern | | Frame History | All intercepted frames are logged with timestamps | | Replay | Re-send any previously intercepted frame |

Route: WebSocket endpoint at /proxy, controls via POST /interceptor/action and POST /interceptor/toggle

Sources: docs/DESKTOP_V3_GUIDE.md:282-340

Payload Blaster

High-speed WebSocket fuzzing engine for bulk payload testing. Unlike the scanner which tests intelligently, the blaster fires every payload in a category and records responses.

Features

| Feature | Description | |---|---| | 11 Categories | SQLi, XSS, CMDi, XXE, SSRF, NoSQLi, LFI, SSTI, LDAP, Open Redirect, CSV Injection | | Payload Count | 22,000+ unique vectors across all categories | | Custom Payloads | Load custom wordlists from file | | Rate Control | Configurable delay between payloads (0ms = full speed) | | SPE Toggle | Enable Smart Payload Evolution for adaptive mutation | | Response Analysis | Side-by-side comparison of each payload's response vs baseline |

Execution Flow

graph LR
    A["Select Category"] --> B["Load Payloads<br/>(built-in or custom)"]
    B --> C{"SPE Enabled?"}
    C -->|Yes| D["Generate adaptive<br/>payloads via SPE"]
    C -->|No| E["Use static payloads"]
    D --> F["Inject into<br/>message template"]
    E --> F
    F --> G["Send to target<br/>WebSocket"]
    G --> H["Analyze response"]
    H --> I["Display result<br/>with diff highlighting"]

    style A fill:#16213e,stroke:#0f3460,color:#fff
    style I fill:#1a1a2e,stroke:#e94560,color:#fff

Response Analysis

For each payload, the blaster collects:

Response size (compared to baseline)
Response time (timing anomalies highlighted)
Status indicators (connection maintained/dropped/error)
Content diff (highlighted differences from baseline response)

Anomalous responses are automatically flagged with color-coded severity badges.

Route: POST /blaster/start, POST /blaster/stop

Sources: docs/DESKTOP_V3_GUIDE.md:263-282

WebSocket Endpoint Discovery

Automated discovery of WebSocket endpoints on a target domain using three techniques.

Discovery Methods

| Method | Technique | Description | |---|---|---| | HTTP Upgrade Probing | Sends Upgrade: websocket headers to common paths | Tests /ws, /socket, /feed, /live, /stream, /chat, /api/ws, etc. | | HTML Crawling | Parses HTML for WebSocket URLs | Searches for new WebSocket(, ws://, wss:// in page content | | JavaScript Analysis | Scans .js files for WebSocket references | Regex extraction of WebSocket URLs from bundled JavaScript |

Endpoint Map Display

Discovered endpoints are displayed as an interactive map showing:

Endpoint URL
Discovery method (how it was found)
Connection status (accepting connections or not)
Protocol (ws:// or wss://)
Click-to-scan button that populates the scanner target field

Route: POST /discover/endpoints Engine: Uses ws_discovery.py

Sources: docs/DESKTOP_V3_GUIDE.md:340-360

Authentication Builder

Constructs multi-step authentication sequences with token extraction and variable substitution. This is critical for testing WebSocket endpoints that require prior HTTP authentication.

How It Works

sequenceDiagram
    participant User as Auth Builder UI
    participant Builder as gui_bridge.py
    participant Target as Target Server

    User->>Builder: Define Step 1: POST /login
    User->>Builder: Define extraction: regex for Set-Cookie

    Builder->>Target: POST /login {user, pass}
    Target-->>Builder: 200 OK, Set-Cookie: session=abc123
    Builder->>Builder: Extract 'abc123' → {{session}}

    User->>Builder: Define Step 2: GET /ws-token
    User->>Builder: Use {{session}} in Cookie header

    Builder->>Target: GET /ws-token (Cookie: session=abc123)
    Target-->>Builder: {"token": "xyz789"}
    Builder->>Builder: Extract 'xyz789' → {{ws_token}}

    Builder-->>User: Auth complete: session + ws_token available
    User->>User: Use {{ws_token}} in WebSocket scan

Step Configuration

Each authentication step specifies:

HTTP method and URL
Headers (with {{variable}} substitution)
Body (with {{variable}} substitution)
Extraction rules: Regex patterns applied to the response to extract values
Variable names: Store extracted values for use in subsequent steps

The extracted variables are available to the scanner, request forge, and interceptor.

Route: POST /auth/build, POST /auth/execute

Sources: docs/DESKTOP_V3_GUIDE.md:360-380

Mutation Lab

Interactive payload mutation workspace using the WSHawk WAF-evasion mutation engine.

Mutation Strategies

| Strategy | Constant | Technique | |---|---|---| | Encoding | ENCODING | URL encode, double encode, Unicode escapes, hex encode | | Case Variation | CASE_VARIATION | Random case (sElEcT), full upper/lower, camelCase | | Comment Injection | COMMENT_INJECTION | SQL comments (/**/), HTML comments, line breaks | | Whitespace | WHITESPACE | Tab, newline, null byte, zero-width character insertion | | Concatenation | CONCATENATION | String splitting with '+', CONCAT(), CHAR() | | Bypass Filter | BYPASS_FILTER | Null bytes, Unicode normalization, alternative representations | | Tag Breaking | TAG_BREAKING | Alternative HTML tags (<img>, <svg>, <details>, <marquee>) | | Polyglot | POLYGLOT | Multi-context payloads effective in HTML, JS, and SQL simultaneously |

Adaptive Learning

The engine uses a weighted scoring system:

learn_from_response() adjusts strategy weights based on WAF blocks, timing anomalies, and successful reflections
generate_adaptive_payloads() uses these weights to select the optimal strategy mix automatically

The UI tries the backend SPE engine first; if unavailable, falls back to client-side JavaScript mutations.

Route: POST /mutate, POST /mutate/adaptive Engine: PayloadMutator — wshawk/payload_mutator.py

Sources: docs/DESKTOP_V3_GUIDE.md:344-378

Scan Scheduler

Automated recurring scan scheduler with vulnerability delta tracking.

Configuration

| Interval | Description | |---|---| | Every 1 hour | High-frequency monitoring | | Every 6 hours | Standard SOC cadence | | Every 12 hours | Daily coverage | | Every 24 hours | Nightly scan | | Weekly | Compliance scanning |

Vulnerability Deltas

The scheduler tracks changes between runs:

+N new — Vulnerabilities found that weren't in the previous scan
-N resolved — Vulnerabilities from the previous scan that are no longer detected
Unchanged — Persistent vulnerabilities across scans

Active schedules auto-resume on application restart via localStorage persistence.

Sources: docs/DESKTOP_V3_GUIDE.md:380-388

Codec (Encoder/Decoder)

Comprehensive encoding and hashing toolkit used during manual testing.

Encoding Operations

| Operation | Direction | Notes | |---|---|---| | Base64 | Encode / Decode | Standard and URL-safe variants | | URL Encoding | Encode / Decode | Percent encoding of special characters | | HTML Entities | Encode / Decode | Named and numeric entity conversion | | Hex | Encode / Decode | Hexadecimal string conversion | | Unicode Escape | Encode / Decode | \uXXXX format | | Gzip | Decompress | Accepts base64-encoded gzip input |

Hashing Operations

| Algorithm | Output | |---|---| | MD5 | 128-bit hex digest | | SHA-1 | 160-bit hex digest | | SHA-256 | 256-bit hex digest | | SHA-512 | 512-bit hex digest |

All operations run client-side in the renderer for instant results.

Sources: docs/DESKTOP_V3_GUIDE.md:389-420

Response Comparer

Side-by-side diff tool for comparing two HTTP or WebSocket responses.

Features

Character-level diff highlighting (additions in green, deletions in red)
Header-by-header comparison
Body content diff with line numbers
Size and timing comparison
Import from traffic history or paste manually

Use Case

The comparer is primarily used for:

Blind injection detection — Compare baseline response with injected response to detect subtle differences (size, timing, content)
WAF bypass verification — Compare blocked vs allowed response to confirm bypass success
Before/after analysis — Compare pre-auth vs post-auth responses to identify authorization issues

Sources: docs/DESKTOP_V3_GUIDE.md:420-435

HawkSearch (Command Palette)

Ctrl+K command palette for instant navigation to any tool or feature.

Features

Fuzzy search across all tool names, panel names, and actions
Keyboard navigation (arrow keys + Enter)
Recent items shown by default
Instant tool activation — selecting a result navigates directly to the tool panel

Searchable Items

All 22 web pentest tools
Scanner, Interceptor, Payload Blaster, Endpoint Map
Auth Builder, Mutation Lab, Codec, Comparer
Settings, Session Save/Load, History
System Log, Traffic History, Findings Panel

Sources: docs/DESKTOP_V3_GUIDE.md:435-440

Exploit PoC Generator

One-click standalone Python exploit script generation for confirmed vulnerabilities.

Generated Script Content

When a vulnerability is confirmed, clicking Export PoC generates a complete Python script that:

#!/usr/bin/env python3
"""
WSHawk Exploit PoC
Target: ws://target.com/ws
Vulnerability: SQL Injection
Severity: HIGH (CVSS 8.6)
Generated: 2026-02-24T13:00:00Z
"""

import asyncio
import websockets

async def exploit():
    uri = "ws://target.com/ws"
    async with websockets.connect(uri) as ws:
        payload = '{"query": "admin\' OR 1=1 --"}'
        await ws.send(payload)
        response = await ws.recv()
        print(f"[+] Response: {response}")

asyncio.run(exploit())

The script is self-contained — it only requires the websockets library and can be run independently from WSHawk.

Route: IPC via dialog:exportExploit

Sources: docs/DESKTOP_V3_GUIDE.md:235-242

Session Management

Save/Load Projects

Full application state can be saved to .wshawk project files:

| Saved Data | Description | |---|---| | Target URL | The WebSocket or HTTP target | | Findings | All discovered vulnerabilities with evidence | | Traffic History | WebSocket frame log | | Notes | In-app research notes | | Auth Sequences | Configured authentication steps | | Scheduled Scans | Active scan schedules | | Tool Results | Web pentest tool outputs |

File Format: JSON with .wshawk extension

Scan History Database

SQLite database at ~/.wshawk/scans.db maintains persistent scan history with:

Vulnerability regression tracking (diff between scans of the same target)
CVSS score aggregation
Exportable via the Report Generator

Sources: docs/DESKTOP_V3_GUIDE.md:435-465

Desktop Advanced Features

Purpose and Scope

Real-Time WebSocket Interceptor

Architecture

How It Works

Interceptor Controls

Payload Blaster

Features

Execution Flow

Response Analysis

WebSocket Endpoint Discovery

Discovery Methods

Endpoint Map Display

Authentication Builder

How It Works

Step Configuration

Mutation Lab

Mutation Strategies

Adaptive Learning

Scan Scheduler

Configuration

Vulnerability Deltas

Codec (Encoder/Decoder)

Encoding Operations

Hashing Operations

Response Comparer

Features

Use Case

HawkSearch (Command Palette)

Features

Searchable Items

Exploit PoC Generator

Generated Script Content

Session Management

Save/Load Projects

Scan History Database

Related Documentation