Dashboard Overview and Launch

Dashboard Overview and Launch

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

Purpose and Scope

This page documents the WSHawk Web Management Dashboard: its architecture, launch mechanisms, and configuration options. The dashboard provides a persistent, SQLite-backed web interface for managing WebSocket security scans, offering features such as scan history, real-time progress tracking, and report management.

For authentication and API key configuration, see Authentication and API Keys. For REST API endpoint details, see REST API Reference. For database schema and scan persistence internals, see Scan History and Persistence.

Sources: README.md:105-136, RELEASE_SUMMARY.md:15-19

What is the Web Management Dashboard?

The Web Management Dashboard is a Flask-based web application introduced in WSHawk v3.0.0 as the Infrastructure Persistence Plane component. Unlike the ephemeral CLI modes (wshawk, wshawk-interactive, wshawk-advanced), the dashboard provides persistent storage of all scan data in a SQLite database located at ~/.wshawk/scans.db.

The dashboard serves as the central interface for:

  • Team Collaboration: Multiple security professionals can access shared scan history
  • Historical Analysis: Compare vulnerabilities across multiple scans of the same target
  • Professional Reporting: Generate and manage HTML reports with CVSS scoring
  • Programmatic Access: REST API for CI/CD integration and automation

Key Differentiator: The dashboard is the only WSHawk interface that maintains state across multiple executions. CLI modes are stateless and generate standalone reports.

Sources: README.md:112-136, RELEASE_SUMMARY.md:15-19, docs/V3_COMPLETE_GUIDE.md:289-306

Dashboard Architecture

Component Overview

graph TB
    subgraph "Entry Point"
        CLI["wshawk CLI<br/>wshawk.__main__:cli<br/>pyproject.toml:43"]
    end
    
    subgraph "Flask Application Layer"
        WebModule["wshawk/web/<br/>Flask App Module"]
        Templates["wshawk/web/templates/*.html<br/>Jinja2 Templates<br/>pyproject.toml:55"]
        Static["wshawk/web/static/*<br/>CSS/JS Assets<br/>pyproject.toml:56"]
    end
    
    subgraph "Data Persistence Layer"
        SQLite["~/.wshawk/scans.db<br/>SQLite Database<br/>WAL Mode"]
        Reports["File System<br/>wshawk_report_*.html<br/>Screenshots"]
    end
    
    subgraph "Scanner Integration"
        ScannerV2["wshawk.scanner_v2.WSHawkV2<br/>Core Scanning Engine"]
    end
    
    subgraph "Authentication Layer"
        Auth["SHA-256 Password Hash<br/>WSHAWK_WEB_PASSWORD env var"]
        APIKey["API Key Support<br/>WSHAWK_API_KEY env var"]
    end
    
    CLI -->|"--web flag"| WebModule
    WebModule --> Templates
    WebModule --> Static
    WebModule --> SQLite
    WebModule --> Reports
    WebModule --> ScannerV2
    WebModule --> Auth
    WebModule --> APIKey
    
    SQLite -->|"scan metadata<br/>vulnerabilities<br/>traffic logs"| WebModule

Diagram: Web Dashboard Architecture and Code Entity Mapping

This diagram maps the dashboard's architectural components to their concrete file locations and code entities in the codebase.

Sources: pyproject.toml:43-56, README.md:112-119, RELEASE_SUMMARY.md:15-19

Launching the Dashboard

Basic Launch Command

The dashboard is launched using the --web flag on the wshawk CLI entrypoint:

wshawk --web

This starts the Flask application on the default port 5000 and binds to localhost (127.0.0.1).

Entry Point Flow:

  1. User executes wshawk --web
  2. Python invokes wshawk.main:cli function (defined in pyproject.toml:43)
  3. Argument parser detects --web flag
  4. Flask application is initialized and starts listening

Sources: README.md:108, pyproject.toml:43

Launch Process Sequence

sequenceDiagram
    participant User
    participant CLI as "wshawk.__main__:cli"
    participant Flask as "Flask App (wshawk/web/)"
    participant DB as "SQLite (scans.db)"
    participant Browser
    
    User->>CLI: "wshawk --web --port 5000 --host 0.0.0.0"
    CLI->>CLI: "Parse arguments"
    CLI->>DB: "Initialize ~/.wshawk/scans.db"
    CLI->>Flask: "Start Flask app"
    Flask->>Flask: "Load templates from wshawk/web/templates/"
    Flask->>Flask: "Load static assets from wshawk/web/static/"
    Flask->>Browser: "Server listening on 0.0.0.0:5000"
    Note over Flask: "Dashboard is now accessible"
    User->>Browser: "Navigate to http://host:5000"
    Browser->>Flask: "HTTP GET /"
    Flask->>DB: "Query scan history"
    DB-->>Flask: "Return scan records"
    Flask->>Browser: "Render dashboard HTML"

Diagram: Dashboard Launch Sequence

Sources: README.md:117-119, pyproject.toml:52-56

Configuration Options

Command-Line Flags

The dashboard launch supports the following configuration flags:

| Flag | Type | Default | Description | Example | |------|------|---------|-------------|---------| | --web | boolean | N/A | Enable web dashboard mode | wshawk --web | | --port | integer | 5000 | TCP port for Flask server | wshawk --web --port 8080 | | --host | string | 127.0.0.1 | Network interface to bind | wshawk --web --host 0.0.0.0 |

Sources: README.md:118

Network Binding Configuration

Local Development (Default)

wshawk --web
# Binds to: http://127.0.0.1:5000
# Accessible: Local machine only

Team/Production Environment

wshawk --web --port 5000 --host 0.0.0.0
# Binds to: http://0.0.0.0:5000
# Accessible: All network interfaces (LAN/WAN)

Security Note: When binding to 0.0.0.0, the dashboard is exposed to all network interfaces. Production deployments must set WSHAWK_WEB_PASSWORD (see Authentication and API Keys).

Sources: README.md:118-127

Environment Variable Configuration

The dashboard reads configuration from environment variables for sensitive data:

| Variable | Purpose | Required | Default Behavior | |----------|---------|----------|------------------| | WSHAWK_WEB_PASSWORD | SHA-256 authentication password | Recommended | Open mode (no authentication) | | WSHAWK_API_KEY | Programmatic API access token | Optional | API key support disabled |

Setting a Password

export WSHAWK_WEB_PASSWORD='your-strong-password'
wshawk --web

Authentication Flow: The password is hashed using SHA-256 with salt and stored in the database. Login sessions are managed via Flask session cookies.

Security Warning: The README explicitly states that running without a password is "only recommended for local testing" (README.md:127).

Sources: README.md:122-127, RELEASE_SUMMARY.md:18, docs/V3_COMPLETE_GUIDE.md:300-301

Dashboard Feature Overview

Persistent Scan History

All scans executed via the dashboard are stored in ~/.wshawk/scans.db using SQLite with WAL (Write-Ahead Logging) mode. This ensures:

  • Zero-loss persistence: Crashes do not corrupt the database
  • Concurrent read access: Multiple users can query scan history simultaneously
  • Transaction safety: Partial scan data is safely committed

Database Location: ~/.wshawk/scans.db (documented in README.md:132)

Storage Schema: Scan metadata, vulnerabilities, traffic logs (detailed in Scan History and Persistence)

Sources: README.md:132, RELEASE_SUMMARY.md:17, docs/V3_COMPLETE_GUIDE.md:293-297

Visual Progress Tracking

The dashboard provides real-time visibility into active scans:

graph LR
    subgraph "Real-Time Metrics"
        Status["Scan Status<br/>(Running/Complete/Failed)"]
        Progress["Progress Percentage"]
        Vulns["Vulnerability Counters<br/>(Critical/High/Medium/Low)"]
        RPS["Requests Per Second"]
    end
    
    subgraph "Data Source"
        DB["SQLite scans.db"]
    end
    
    subgraph "Display Layer"
        Dashboard["Web Dashboard UI<br/>wshawk/web/templates/"]
    end
    
    DB -->|"Query scan state"| Status
    DB -->|"Calculate completion"| Progress
    DB -->|"Aggregate findings"| Vulns
    DB -->|"Track message rate"| RPS
    
    Status --> Dashboard
    Progress --> Dashboard
    Vulns --> Dashboard
    RPS --> Dashboard

Diagram: Real-Time Progress Tracking Architecture

The dashboard queries the SQLite database periodically to display live scan metrics without blocking the scanning engine.

Sources: README.md:133, docs/V3_COMPLETE_GUIDE.md:304-305

Interactive Report Management

The dashboard provides a web-based interface for managing generated HTML reports:

| Feature | Description | Location | |---------|-------------|----------| | View Reports | Render HTML reports in-browser with CVSS scoring | Dashboard UI | | Download Reports | Export HTML files for offline review | File system | | Delete Reports | Remove old scan data and associated reports | Database + File system | | Report History | Browse all historical reports by date/target | SQLite query interface |

Report Format: Professional HTML with screenshots (Playwright XSS verification), message replay sequences, traffic logs, and actionable remediation guidance (README.md:177-185).

Sources: README.md:134, README.md:177-185

API Key Support for Programmatic Access

The dashboard includes a REST API for automation and CI/CD integration. API keys provide authentication for headless access:

export WSHAWK_API_KEY='your-api-key-here'
curl -H "X-API-Key: $WSHAWK_API_KEY" http://localhost:5000/api/scans

Full API Documentation: See REST API Reference for endpoint details, request/response formats, and authentication mechanisms.

Sources: README.md:135, RELEASE_SUMMARY.md:19

Comparison: Dashboard vs CLI Modes

The following table contrasts the dashboard with the three CLI execution modes:

| Feature | wshawk | wshawk-interactive | wshawk-advanced | wshawk --web | |---------|----------|----------------------|-------------------|----------------| | Ease of Use | High | High | Medium | Highest | | Persistence | No (single report) | No (single report) | No (single report) | Yes (SQLite) | | Authentication | N/A | N/A | N/A | Yes (SHA-256) | | Multi-User Access | No | No | No | Yes | | Real-Time Progress | Terminal logs | Menu updates | Terminal logs | Web UI | | Historical Analysis | Manual file comparison | Manual file comparison | Manual file comparison | Database queries | | REST API | No | No | No | Yes | | Best For | Automation scripts | Learning/Training | Power users | Teams / SOC / DevSecOps |

Key Insight: The dashboard is the only stateful interface. CLI modes generate ephemeral reports and exit. For continuous monitoring or team collaboration, the dashboard is the recommended deployment.

Sources: README.md:153-159

Use Cases and Deployment Patterns

Use Case 1: Local Development Testing

# No authentication, localhost only
wshawk --web
# Access: http://127.0.0.1:5000

Scenario: Individual security researcher testing on local machine.

Use Case 2: Team SOC Environment

# Password-protected, LAN-accessible
export WSHAWK_WEB_PASSWORD='SecureTeamPassword123!'
wshawk --web --port 5000 --host 0.0.0.0
# Access: http://team-server:5000

Scenario: Security Operations Center with multiple analysts sharing scan history.

Use Case 3: CI/CD Integration

# API-driven headless mode
export WSHAWK_API_KEY='ci-automation-key'
export WSHAWK_WEB_PASSWORD='SecurePassword'
wshawk --web --host 0.0.0.0 &
# REST API calls from GitHub Actions / GitLab CI
curl -X POST http://localhost:5000/api/scans \
  -H "X-API-Key: $WSHAWK_API_KEY" \
  -d '{"target": "ws://staging.app.com"}'

Scenario: Automated WebSocket security testing in deployment pipelines. See CI/CD Integration for full implementation.

Use Case 4: Kubernetes Multi-Service Scanning

# Dashboard as K8s Service
kubectl create deployment wshawk-dashboard \
  --image=rothackers/wshawk:latest \
  -- wshawk --web --host 0.0.0.0 --port 5000
kubectl expose deployment wshawk-dashboard --type=LoadBalancer

Scenario: Centralized dashboard for scanning multiple WebSocket services in a Kubernetes cluster. See Kubernetes Deployment for manifest examples.

Sources: README.md:117-127, docs/V3_COMPLETE_GUIDE.md:352-376

Data Persistence Location

The dashboard stores all data in a user-specific directory:

~/.wshawk/
├── scans.db          # SQLite database (WAL mode)
├── scans.db-wal      # Write-Ahead Log
└── scans.db-shm      # Shared Memory

Database Path: ~/.wshawk/scans.db (README.md:132, RELEASE_SUMMARY.md:17)

WAL Mode Benefits:

  • Crash Recovery: Uncommitted transactions are preserved in the WAL file
  • Concurrent Readers: Multiple dashboard users can query simultaneously
  • Write Performance: Asynchronous writes improve scan throughput

Sources: README.md:132, RELEASE_SUMMARY.md:17, docs/V3_COMPLETE_GUIDE.md:123-124

Next Steps

Sources: README.md:153-159