WS Tester Pro

Enterprise-Grade WebSocket Security Assessment Framework

---

WS Tester Pro is an enterprise-grade WebSocket penetration testing framework with rule-based validation, multi-stage verification, and adaptive payload generation. It runs 38+ automated security tests across 22 attack modules, validated against benchmark labs (DVWA, WebGoat, Juice Shop), and generates OWASP-format reports — all from your browser or the command line.

🎯 False-Negative Reduction System

The False-Negative Reduction System is a comprehensive enhancement that transforms WS Tester Pro into an enterprise-grade security testing platform competitive with Burp Suite and OWASP ZAP.

Key Features

Feature	Description
🎯 Rule-Based Validation	Pattern-matching validation with confidence scoring across 8 attack types; sklearn ML training pipeline available for custom model training
🔍 Multi-Stage Verification	4-stage verification process (payload, response pattern, behavioral, timing)
🧬 Adaptive Payloads	Automatically generates alternative payloads to bypass WAFs and defenses
📊 Benchmark Framework	Validated against DVWA, WebGoat, and Juice Shop with comprehensive test coverage
🔐 Enterprise Security	RBAC with 3 roles, HMAC-SHA256 audit logging, AES-256 encryption
🔌 Plugin System	Dynamic loading of custom attack modules with hot-reload support
⚡ Performance Optimized	Async I/O, connection pooling, caching, and backpressure handling
📈 Advanced Monitoring	Distributed tracing, structured logging, Prometheus metrics

Detection Engine Architecture

User Request → Scanner → Detection Engine → Rule Engine / ML Validator
                                         → Multi-Stage Verifier
                                         → Adaptive Payload Generator
                                         → False Positive Validator
                                         → Confidence Scorer
                                         → Audit Logger

Documentation

• 📖 Architecture Documentation - System architecture and component design
• 🔌 API Documentation - REST API and WebSocket event reference
• 🚀 CI/CD Pipeline - Quality gates and deployment automation
• 🔒 Security Scanning - Security tools and best practices
• 🧩 Plugin Development Guide - Create custom attack modules
• 🚀 Deployment Guide - Production deployment procedures
• ⚙️ Configuration Guide - Complete configuration reference
• 🐳 Docker Guide - Container deployment and optimization

Docker is optional. If you don't have Docker installed (e.g. you see: docker : The term 'docker' is not recognized), you can still run everything with Python using the Installation / Quick Start steps below. Docker/Compose is only for easy hosting (running Dashboard + OOB server together).

---

🎬 Features

Core Capabilities

Feature	Description
🚀 Auto Scanner	Discovers WS endpoints & runs 30+ vulnerability tests across 14 modules
🔐 Authenticated Scan	Reuse login (token/cookie/headers) to scan protected WebSockets
📊 Response Diff Tool	Compare authenticated vs unauthenticated WebSocket responses to detect authorization bypass & data leaks
🔄 Auto-Diff	One-click automated dual-connection diffing — connects with & without auth, flags sensitive field leaks
🎯 Bug Bounty Mode	One-click copy of HackerOne/Bugcrowd-ready markdown reports
📄 Multi-Format Reports	PDF, HTML, JSON, and SARIF (CI/CD) export
🤖 AI Analysis	Anthropic Claude integration for attack chain analysis & prioritized remediation
🕵️ Live Interceptor / MITM Proxy	Real WebSocket man-in-the-middle proxy to capture, filter, hold, modify & replay live traffic
⚡ Turbo Intruder	High-speed message sender for race conditions, burst tests, and OTP brute-forcing
🤖 AI-Powered Fuzzer	Dynamic, context-aware payload generation via Claude API for zero-day hunting
📝 Schema Builder	Auto-infer robust API data models from live WS traffic & export to Markdown/HTML
📂 Multi-Target Scan	Bulk scan sequentially (CLI) or concurrently via Dashboard modal
🧨 WebSocket Fuzzer	Auto-detect crashes, DoS, and error leaks with malformed payloads

| 🎨 120Hz Smooth UI | GPU-accelerated animations with cubic-bezier easing & hardware compositing | | 🔎 Advanced Dropdowns | Custom dropdown elements with built-in sticky search filters for massive datasets | | 📄 WeasyPrint PDF Reports | High-fidelity, pixel-perfect OWASP format reports with 5-10x faster generation than Playwright |

✅ Validation & Confidence Scoring	Intelligent false positive reduction with response validation, confidence scoring, and sensitive pattern detection
📝 Custom Payloads System	9 built-in payload libraries (SQLi, XSS, SSTI, SSRF, CMDi, NoSQL, XXE, Path Traversal, Fuzzing) with drag-and-drop upload, deduplication, sorting & merge mode
🗑️ Auto-Drop Rules	Filter noise (heartbeats, telemetry) out of the live traffic feed silently using regex patterns
🔄 Match & Replace	On-the-fly regex payload rewriting in either direction (C2S/S2C/Both) without pausing traffic
📝 Repeater Modal	Edit & Replay captured packets to either client or server using a dedicated editing interface
🔧 Scan Profiles	Save, load, and delete scan configurations with custom in-app confirmation modals
⚡ Fast/Deep Modes	Quick scans or comprehensive audits
🖥️ CLI + Dashboard	Launch the dashboard directly with python main.py
🔄 Concurrent Scanning	Parallel endpoint testing (3/5/10 threads)
⏸ Pause & Resume	Pause scans and resume without losing progress
📊 Session History	Save, load, and compare scan sessions
🛡️ WAF Bypass Engine	10+ encoding techniques (Unicode, Double-URL, Full-width) to evade Cloudflare, AWS, and Akamai
🛰️ Dual-Mode OOB Proof	Automated Interactsh (oast.fun) or custom server for blind vulnerability (SSRF/XXE/CMDi) confirmation
🌙 Dark/Light Theme	Toggle between themes with Ctrl+Shift+T
⌨️ Keyboard Shortcuts	Fast workflow with keyboard shortcuts
🔔 Notifications	Browser notifications + sound on scan complete
📱 Responsive UI	Works on desktop, tablet, and mobile screens
🎨 120Hz Smooth UI	GPU-accelerated animations with cubic-bezier easing & hardware compositing

---

📸 Screenshots

🔍 Scan Results — Findings Tab

452 vulnerabilities discovered with severity breakdown: 128 Critical, 205 High, 98 Medium, 21 Low.

🎯 Bug Bounty Report Generator

Copy HackerOne/Bugcrowd-ready markdown reports with one click — each finding includes CVSS scores, reproduction steps, and remediation.

📡 Live Scan Log

Real-time scan activity with color-coded severity levels, timestamps, and module-by-module progress tracking.

🕵️ MITM Interceptor

WebSocket man-in-the-middle proxy with traffic capture, search, filter, hold/forward/drop, and replay capabilities.

📊 Auto-Diff — Bypass Detection

Auto-Diff detecting CRITICAL authorization bypass: 11 sensitive fields leaked including API keys, admin panel paths, database URIs, and internal IPs.

✅ Auto-Diff — Clean Comparison

Authenticated vs unauthenticated response comparison — no bypass detected when the server correctly enforces authorization.

⚡ Next-Level Turbo Intruder UI

Premium animated UI with glowing segmented buttons — testing maximum throughput via Burst Test mode.

Context-aware inputs like OTP digit configuration and templating for brute-force attacks.

Live execution results showcasing animated gradient stat cards, duplicate detection, and scrolling response timeline.

🤖 AI-Powered Dynamic Fuzzer

Claude-powered context-aware exploit generator with selectable attack categories (SQLi, NoSQLi, XSS, IDOR, CMDi). Reads live traffic schemas and smartly generates zero-day hunting payloads.

📝 Custom Payloads System

Advanced payload management with 9 built-in libraries, one-click deduplication & sorting, merge mode toggle, drag-and-drop file upload, and live payload count.

---

✅ Validation & Confidence Scoring

WS Tester Pro includes an intelligent false positive reduction system that validates findings and assigns confidence scores to help you focus on real vulnerabilities.

Key Features

Feature	Description
🎯 Response Validation	Validates server responses against expected vulnerability indicators
📊 Confidence Scoring	Assigns confidence scores (0-100) based on multiple validation signals
🔍 Sensitive Pattern Detection	Detects leaked credentials, tokens, PII, and internal paths in responses
⚡ Baseline Caching	Caches baseline responses for efficient diff-based validation
🎨 Normalization Engine	Normalizes responses to reduce noise from dynamic content
📝 Configurable Rules	Customize validation rules via config/validation.json

How It Works

1. Baseline Capture: First request establishes a baseline response
2. Attack Execution: Malicious payloads are sent to the target
3. Response Validation: Responses are validated against vulnerability-specific patterns
4. Confidence Calculation: Multiple signals combined into a confidence score:
   • Response validation results (40% weight)
   • Sensitive pattern detection (30% weight)
   • Diff analysis vs baseline (20% weight)
   • Attack-specific indicators (10% weight)
5. False Positive Filtering: Low-confidence findings can be filtered out

Confidence Score Interpretation

Score Range	Interpretation	Action
90-100	Very High Confidence	Immediate investigation required
70-89	High Confidence	Likely real vulnerability
50-69	Medium Confidence	Manual verification recommended
30-49	Low Confidence	Possible false positive
0-29	Very Low Confidence	Likely false positive

Configuration

Customize validation behavior in config/validation.json:

{
  "enabled": true,
  "confidence_threshold": 50,
  "baseline_cache_ttl": 3600,
  "normalization": {
    "remove_timestamps": true,
    "remove_session_ids": true,
    "remove_dynamic_values": true
  },
  "sensitive_patterns": {
    "credentials": ["password", "secret", "api_key"],
    "tokens": ["jwt", "bearer", "session"],
    "pii": ["ssn", "credit_card", "email"]
  }
}

See config/validation_config_README.md for complete configuration documentation.

Testing the Validation System

Use the included Vulnerable Lab Server to test validation features:

# Terminal 1: Start the vulnerable lab server
python mock_server.py

# Terminal 2: Run WS Tester Pro
python main.py --target ws://localhost:8765

The mock server implements 20+ vulnerability types with realistic responses for testing validation accuracy. See MOCK_SERVER_README.md for complete lab documentation.

---

🔒 Attack Modules (14 Modules, 30+ Tests)

Authentication & Authorization

Test	Module	Description
JWT None Algorithm	auth.py	Bypass JWT verification using alg: none
JWT Algorithm Confusion	auth.py	Switch RS256 → HS256 with public key as secret
JWT Token Manipulation	auth.py	Modify claims (role, user ID, admin flags)
JWT Secret Cracker	auth.py	High-speed dictionary attack to crack weak HMAC secrets
CSWSH (Cross-Site WS Hijacking)	auth.py	Test Origin header validation
Auth Bypass	auth.py	Attempt accessing authenticated endpoints without credentials

Injection Attacks

Test	Module	Description
SQL Injection	injection.py	Union, blind, time-based, error-based SQLi
XSS (Cross-Site Scripting)	injection.py	Reflected, stored, DOM-based XSS via WS messages
Command Injection	injection.py	OS command injection through WS payloads
NoSQL Injection	injection.py	MongoDB/CouchDB operator injection
Prototype Pollution	injection.py	JavaScript prototype chain manipulation

Server-Side Attacks

Test	Module	Description
SSRF	ssrf.py	Server-side request forgery with 8 target categories (AWS, GCP, Azure, K8s, localhost, file://, protocols, encoded)
SSTI	ssti.py	Server-side template injection (Jinja2, Twig, Freemarker, Spring)
XXE (via payloads)	Custom Payloads	XML external entity injection payloads

Protocol & Network Attacks

Test	Module	Description
WebSocket Smuggling	smuggling.py	HTTP/WS upgrade smuggling & protocol confusion
Protocol Downgrade	smuggling.py	Detect if wss:// allows unencrypted ws:// connections
GraphQL-over-WS	graphql_ws.py	Introspection, batch queries, subscription abuse via WS
Subprotocol Attacks	subprotocol.py	Protocol negotiation manipulation & downgrade
Encryption Check	network.py	Detect unencrypted ws:// connections
Information Disclosure	network.py	Detect leaked server internals, stack traces, debug info
IDOR	network.py	Insecure direct object reference via sequential IDs

Timing & Concurrency

Test	Module	Description
Timing Side Channels	timing.py	User enumeration & data extraction via response timing
Race Conditions (Turbo)	turbo_intruder.py	Concurrent request exploitation (double-spend, TOCTOU)
Burst Tests	turbo_intruder.py	High-speed concurrent message delivery
OTP Brute-Force	turbo_intruder.py	High-speed 4-6 digit token cracking

Fuzzing & Logic

Test	Module	Description
AI-Powered Fuzzer	ai_fuzzer.py	Claude-generated context-aware zero-day hunting
Payload Fuzzing	fuzzer.py	Oversized payloads, malformed JSON, null bytes, type confusion
Mass Assignment	mass_assignment.py	Unauthorized field modification (role escalation, price tampering)
Business Logic	business_logic.py	Workflow abuse, negative quantities, state manipulation

---

📁 Project Structure

ws_pro/
├── .github/
│   └── workflows/
│       └── ws-security.yml       # CI/CD pipeline
├── attacks/                      # 14 Attack Modules
│   ├── __init__.py               # Module registry
│   ├── ai_fuzzer.py              # AI-Powered Dynamic Fuzzer (Claude)
│   ├── auth.py                   # JWT attacks, CSWSH, auth bypass
│   ├── business_logic.py         # Business logic & workflow abuse
│   ├── fuzzer.py                 # WebSocket fuzzer (DoS, boundary, types)
│   ├── graphql_ws.py             # GraphQL-over-WebSocket attacks
│   ├── injection.py              # SQLi, XSS, CMDi, NoSQL, Prototype Pollution
│   ├── mass_assignment.py        # Mass-assignment exploitation
│   ├── network.py                # Encryption, info disclosure, GraphQL, IDOR
│   ├── race_condition.py         # Concurrency / race-condition tests
│   ├── smuggling.py              # WebSocket smuggling & upgrade attacks
│   ├── ssrf.py                   # SSRF with 8 target categories
│   ├── ssti.py                   # Server-side template injection
│   ├── subprotocol.py            # Subprotocol negotiation attacks
│   ├── timing.py                 # Timing side channels & enumeration
│   ├── turbo_intruder.py         # Turbo Intruder (Burst/Race/OTP)
│   └── waf_bypass.py             # WAF Bypass Engine (10 evasion tech)
├── core/
│   ├── auth_profile.py           # Authentication profile management
│   ├── cve_db.json               # CVE database for known vulnerabilities
│   ├── cve_matcher.py            # CVE fingerprint matching engine
│   ├── findings.py               # Thread-safe findings store, CVSS scoring
│   ├── oob_profile.py            # OOB (Out-of-Band) proof profile
│   ├── scanner.py                # Endpoint discovery, fingerprinting, helpers
│   ├── schema_builder.py         # Live WS traffic Schema Builder
│   ├── validation.py             # Response validation & confidence scoring engine
│   └── ws_proxy.py               # Real WebSocket MITM proxy (bridge + hold + replay)
├── config/
│   ├── validation.json           # Validation rules & thresholds
│   └── validation_config_README.md  # Validation configuration guide
├── dashboard/
│   ├── app.py                    # Flask + Socket.IO server
│   ├── templates/
│   │   └── index.html            # Dashboard UI (GPU-smooth animations)
│   └── static/
│       ├── css/app.css           # Styling (dark/light themes, 120Hz smooth)
│       └── js/
│           ├── proxy.js          # Live Interceptor, rewriting rules, and Proxy UI
│           └── scanner.js        # Core scanning logic, Vulnerability UI, and Attacks
├── docs/
│   └── screenshots/              # Documentation screenshots
├── logs/                         # Runtime logs (auto-created)
├── profiles/
│   ├── bug_bounty.json           # Bug bounty scan profile
│   ├── ci_cd.json                # CI/CD pipeline scan profile
│   ├── deep_audit.json           # Deep audit scan profile
│   └── jwt_focus.json            # JWT-focused scan profile
├── reports/
│   ├── generator.py              # HTML report generator
│   ├── pdf_generator.py          # OWASP-format PDF report generator
│   └── sarif_generator.py        # SARIF v2.1.0 for CI/CD integration
├── tests/
│   ├── test_attacks.py           # Attack module unit tests
│   ├── test_core.py              # Core module unit tests
│   └── test_integration.py       # Integration tests
├── utils/
│   ├── diff_engine.py            # Response diff engine for bypass detection & validation
│   ├── evidence.py               # Evidence data collector
│   ├── logger.py                 # File + console logging
│   └── payload_store.py          # Custom payload storage & management
├── main.py                       # CLI entry point (argparse)
├── mock_server.py                # Vulnerable Lab Server (20+ scenarios)
├── oob_server.py                 # OOB callback server for blind SSRF/XXE
├── MOCK_SERVER_README.md         # Vulnerable Lab Server documentation
├── Dockerfile                    # Docker image build
├── docker-compose.yml            # Multi-service orchestration
├── requirements.txt              # Python dependencies
├── CONTRIBUTING.md               # Contribution guide
├── LICENSE                       # AGPL v3
└── README.md                     # This file

---

🖥️ Installation

Prerequisites

• Python 3.9+ — Download Python
• pip — Comes bundled with Python
• A modern browser (Chrome, Firefox, Edge)

---

🪟 Windows

# 1. Clone the project
git clone https://github.com/palnirupam/ws_pro.git
cd ws_pro

# 2. Create virtual environment
python -m venv venv
venv\Scripts\activate

# 3. Install WeasyPrint dependencies for PDF generation (REQUIRED for PDF export)
# Download and install GTK3 Runtime:
# https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases/latest
#
# Steps:
# - Click on "gtk3-runtime-x.x.x-x-x-x-ts-win64.exe" to download
# - Run the installer (requires admin rights)
# - Use default installation path: C:\Program Files\GTK3-Runtime Win64
# - Restart your terminal after installation
#
# ⚠️ Without GTK+: HTML/JSON reports work, but PDF export will fail

# 4. Install Python dependencies
pip install -r requirements.txt

# 5. (Optional) Configure environment
copy .env.example .env

# 6. Start the dashboard
python main.py

Open your browser → http://localhost:5000

Important: WeasyPrint (our PDF rendering engine) requires GTK+ libraries on Windows for PDF generation. If you skip GTK+ installation, you can still use HTML, JSON, and SARIF export formats. WeasyPrint provides 5-10x faster PDF generation compared to the previous Playwright-based implementation.

---

🍎 macOS

# 1. Clone the project
git clone https://github.com/palnirupam/ws_pro.git
cd ws_pro

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install WeasyPrint dependencies for PDF generation (one-time setup)
brew install pango cairo gdk-pixbuf libffi

# 4. Install dependencies
pip install -r requirements.txt

# 5. (Optional) Configure environment
cp .env.example .env

# 6. Start the dashboard
python3 main.py

Open your browser → http://localhost:5000

---

🐧 Linux (Ubuntu/Debian)

# 1. Install Python if needed
sudo apt update && sudo apt install python3 python3-pip python3-venv -y

# 2. Install WeasyPrint dependencies for PDF generation (one-time setup)
sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev -y

# 3. Clone the project
git clone https://github.com/palnirupam/ws_pro.git
cd ws_pro

# 4. Create virtual environment
python3 -m venv venv
source venv/bin/activate

# 5. Install dependencies
pip install -r requirements.txt

# 6. (Optional) Configure environment
cp .env.example .env

# 7. Start the dashboard
python3 main.py

Open your browser → http://localhost:5000

---

📄 PDF Generation Performance

WS Tester Pro uses WeasyPrint for PDF report generation, delivering professional OWASP-format reports with exceptional performance:

Performance Improvements

Report Size	Generation Time	Previous (Playwright)	Improvement
1 finding	< 500ms	~5 seconds	10x faster
10 findings	< 800ms	~6 seconds	7.5x faster
50 findings	< 1 second	~8 seconds	8x faster
100 findings	< 2 seconds	~10 seconds	5x faster

Key Benefits

• No Browser Overhead: Direct HTML-to-PDF rendering without launching Chromium
• Identical Visual Output: Maintains the same professional OWASP format and styling
• Lower Resource Usage: Reduced memory and CPU consumption
• Faster CI/CD Pipelines: Significantly faster report generation in automated workflows

Migration Notes

Upgrading from Playwright-based PDF generation?

• ✅ No code changes required — PDF export button works exactly as before
• ✅ Visual output is identical — Same professional OWASP format reports
• ✅ Playwright no longer needed — You can remove playwright from your environment
• ✅ 5-10x performance improvement — Reports generate in under 2 seconds
• ⚠️ WeasyPrint dependencies required — See platform-specific installation instructions above

---

🚀 Quick Start Guide

Option A: Docker (Recommended for Production)

# Start all services with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Access dashboard at http://localhost:5000

Using Makefile (easier):

make up          # Start production services
make logs        # View logs
make health      # Check service health
make down        # Stop services

See Docker Documentation for complete guide.

Option B: Kubernetes (Enterprise Production)

# Deploy to Kubernetes cluster
cd k8s
./deploy.sh production    # Linux/macOS
.\deploy.ps1 production   # Windows

# Or manually
kubectl apply -f namespace.yaml
kubectl apply -f secret.yaml
kubectl apply -f configmap.yaml
kubectl apply -f rbac.yaml
kubectl apply -f pvc.yaml
kubectl apply -f service.yaml
kubectl apply -f deployment.yaml
kubectl apply -f ingress.yaml
kubectl apply -f hpa.yaml

# Check deployment status
kubectl get pods -n ws-tester-pro
kubectl get svc -n ws-tester-pro
kubectl get ingress -n ws-tester-pro

See Kubernetes Deployment Guide for complete guide.

Option C: Web Dashboard (Python)

# Windows
python main.py

# macOS / Linux
python3 main.py

You'll see:

╔══════════════════════════════════════╗
║     WS Tester Pro — Dashboard        ║
║     http://localhost:5000            ║
╚══════════════════════════════════════╝

Option D: Command Line

# Basic scan
python main.py --target https://example.com

# Fast scan with JSON output
python main.py --target wss://example.com/ws --fast --output report.json

# SARIF output for CI/CD
python main.py --target https://example.com --output report.sarif --format sarif

# Authenticated scans
python main.py --target https://app.com --username admin --password pass123
python main.py --target https://app.com --token eyJhbGci...
python main.py --target https://app.com --cookie "session=abc123; csrf=xyz"

# Start dashboard from CLI (Default behavior)
python main.py

---

🔐 Authenticated Scan

Most real WebSockets are behind login. Use the 🔐 Authentication card in the sidebar:

Method	Description
Username + Password	Auto-login and extract JWT token/cookies
Bearer Token	Attach Authorization: Bearer ... to every WS connect
Session Cookie	Attach Cookie: ... to every WS connect
Custom Headers	Attach arbitrary headers (one per line: Name: Value)

Use 🧪 Test Auth to validate credentials before scanning (10s timeout).

---

📝 Custom Payloads System

The 📝 Custom Payloads panel provides an advanced payload management system:

Built-in Payload Libraries (9 Categories)

Library	Payloads	Description
💉 SQLi	25	Union, blind, time-based, error-based, stacked queries
🔥 XSS	20	Reflected, stored, DOM, polyglot, filter bypass
📝 SSTI	18	Jinja2, Twig, Freemarker, Spring, EL injection
🌐 SSRF	15	AWS/GCP/Azure metadata, localhost, gopher, file://
💻 Command Injection	15	Bash, PowerShell, backtick, $() substitution
🗂 NoSQL Injection	12	MongoDB $gt, $ne, $regex, $where operators
🔗 XXE	10	External entity, billion laughs, OOB exfiltration
📁 Path Traversal	12	../, encoded, null byte, double-URL-encoded
🧨 Fuzzing	20	Null bytes, prototype pollution, boundary values, NaN

Key Features

• 📤 Upload File — Load .txt, .csv, .lst, .json payload files (multi-file support)
• 🖱️ Drag & Drop — Drop files directly onto the textarea with animated glow effect
• 🔄 Deduplicate — Automatically sanitize custom wordlists by removing identical entries to optimize scan times and prevent redundant requests.
• 🔤 Sort — Alphabetically organize large custom payload files for improved readability and easier manual review.
• ✅ Merge Mode — Combine your custom payloads with built-in checks for maximum coverage (ON), or run them exclusively for stealthy, targeted testing (OFF).
• 🟢 Count Badge — Live payload count shown on section header
• 🔗 Scan Integration — Custom payloads + template sent to backend during scans

---

⌨️ Keyboard Shortcuts

Shortcut	Action
Ctrl+Enter	Start scan
Escape	Stop scan
Ctrl+Shift+T	Toggle dark/light theme
Ctrl+Shift+S	Save current session
Ctrl+Shift+E	Export findings as JSON
Alt+1 to Alt+7	Switch between tabs

---

📊 Dashboard Tabs

Tab	Description
🔍 Findings	Real-time vulnerability feed with severity filtering & sorting
🎯 Bug Bounty	One-click HackerOne/Bugcrowd-ready markdown reports
📡 Live Log	Color-coded real-time scan activity log
🕵️ Interceptor	WebSocket MITM proxy with capture/hold/forward/drop/replay
📊 Diff Tool	Manual & Auto-Diff for authorization bypass detection
🤖 AI Analysis	Claude-powered attack chain analysis & AI Dynamic Fuzzer
⚡ Intruder	High-speed message sender for race conditions, burst tests, and OTP brute-force
📝 Schema	Auto-capture live WebSocket traffic, infer data models, and export API schemas
📂 History	Save, load, compare, and delete scan sessions

---

🎯 Bug Bounty Workflow

1. Run a comprehensive scan on your target WebSocket endpoint
2. Switch to the 🎯 Bug Bounty tab
3. Review discovered vulnerabilities
4. Click 📋 Copy next to any finding — generates a professional markdown report:
   • Vulnerability Name & Severity
   • CVSS Score and Vector
   • Target URL & Exact Endpoint
   • Detailed Description & Impact
   • Step-by-Step Reproduction
   • Evidence/Payloads
   • Remediation Advice
5. Paste directly into HackerOne, Bugcrowd, or YesWeHack

---

🕵️ Interceptor Mode Guide

WS Tester Pro includes a real WebSocket MITM proxy:

Client/App → ws://localhost:<PORT> → [WS Tester Pro Proxy] → <TARGET_WS_URL>

Setup

1. Open the Interceptor tab
2. Set Target WS URL (e.g. wss://example.com/ws)
3. Set Local Port (default: 8080)
4. Optionally enable Intercept Mode for manual hold/forward
5. Click Start Proxy
6. Point your app to ws://localhost:<PORT>

Core Capabilities

Action	Description
Capture	All messages logged with time, direction, size, and flags
Search/Filter	Narrow traffic by keyword, direction, or session
Hold	Intercept Mode pauses messages for inspection
Forward	Send held message as-is
Modify & Forward	Edit payload before forwarding
Drop	Discard message (not forwarded)
Edit & Replay	Open captured message in Repeater Modal — edit payload, choose direction (Server/Client), and send
Export	Download all captured traffic as JSON

Advanced Intercept Rules (Phase 2)

Feature	Description
🗑️ Auto-Drop Rules	Silently filter noise (heartbeats, telemetry, pings) using regex patterns — dropped messages never reach the target or clutter the feed
🔄 Match & Replace	On-the-fly regex rewriting of live payloads in either direction (C2S / S2C / Both) without pausing traffic
📝 Repeater Modal	Burp-style Edit & Replay popup — modify any captured payload and re-send it to the server or client with one click
✅ Breakpoints	Regex-based rules to auto-hold specific messages matching a pattern for manual inspection
🔁 Auto-Forward	Regex rules to automatically forward matching messages without manual intervention

---

📊 Response Diff Tool

Manual Compare

1. Open Diff Tool tab
2. Paste unauthenticated response into Response A
3. Paste authenticated response into Response B
4. Click 🔒 Compare

Auto-Diff (One-Click)

1. Enter target URL in sidebar
2. Click 🔄 Auto-Diff (connect with/without auth)
3. Tool automatically connects with & without auth, captures responses, and flags bypass

Example bypass detection:

🔓 CRITICAL — Authorization Bypass Detected
Sensitive fields: admin_panel, api_key, balance, email, role, session, token

+ admin_panel: "/admin/dashboard"
+ api_key: "sk-live-4f3a8b2c..."
+ balance: 9999
+ role: "admin"

---

🤖 AI Analysis Setup (Optional)

To enable AI-powered analysis using Anthropic Claude:

1. Get an API key from console.anthropic.com
2. Option A: Add to .env file: ANTHROPIC_API_KEY=sk-ant-api03-...
3. Option B: In the dashboard sidebar, paste your key in 🔑 AI API Key and click 💾 Save Key
4. Enable 🤖 AI analysis checkbox before scanning

AI analysis provides:

• Executive summary of all findings
• Top 3 critical risks with business impact
• Attack chain analysis (how vulnerabilities combine)
• Prioritized remediation roadmap

Keys from .env persist across restarts. Dashboard keys are session-only.

---

⚙️ Scan Options

Attack Modules

Option	Description
🤖 AI Analysis	Claude-powered attack chain analysis
🌐 Browser Discovery	Headless browser to find hidden WS endpoints
🔑 JWT Attacks	7 types of JWT vulnerabilities
⏱ Timing Attacks	Timing-based side channels & enumeration
🧨 Fuzzer	Malformed/boundary payloads for crash detection
🏎️ Race Conditions	Concurrent request exploitation
🌐 SSRF	Server-side request forgery with 8 target categories
📝 SSTI	Server-side template injection
📦 Mass Assignment	Unauthorized field modification
🧠 Business Logic	Workflow abuse & state manipulation
🔀 Smuggling	WebSocket upgrade & HTTP smuggling
📡 GraphQL-WS	GraphQL-over-WebSocket attacks
⚡ Fast Mode	Skip deep tests for quicker results

Baseline Tests

Test	Description
Encryption	Detect unencrypted ws:// connections
Injection	SQLi, XSS, CMDi, NoSQL, Prototype Pollution
WAF Evasion	Automatically run injection payloads through the WAF Bypass Engine
Blind Attacks (OOB)	Detect zero-output vulnerabilities using Out-of-Band DNS/HTTP callbacks
CSWSH	Cross-Site WebSocket Hijacking
Rate Limiting	Verify rate limit enforcement
Message Size	Test oversized payload handling
Info Disclosure	Detect leaked server internals
GraphQL	Introspection & batch query abuse
IDOR	Insecure direct object reference
Subprotocol	Protocol negotiation attacks
Auth Bypass	Unauthenticated access to protected endpoints

SSRF Target Categories

Category	Targets
☁️ Cloud	AWS, GCP, Azure metadata endpoints
🏠 Localhost	127.0.0.1, 0.0.0.0, IPv6 loopback
📁 File	file:///etc/passwd, Windows paths
🔌 Protocols	gopher://, dict://, ftp://
☁️ Azure	Azure IMDS & management endpoints
🐳 K8s/Docker	Kubernetes API, Docker socket
🔍 Elastic	Elasticsearch internal API
🔢 Encoded	URL-encoded, double-encoded, hex/octal

Concurrent Threads

Level	Threads	Use Case
Safe	3	Production testing (minimal load)
Normal	5	Standard penetration testing
Aggressive	10	Lab/CTF environments

---

⚙️ Environment Configuration

Copy .env.example to .env and configure:

# Flask secret key (auto-generated if not set)
WS_SECRET_KEY=your-secret-key-here

# Anthropic API key for AI analysis
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# CORS allowed origins (comma-separated, default: * for all)
WS_CORS_ORIGINS=http://localhost:5000,http://localhost:3000

---

📊 Export Formats

Format	Use Case
PDF	Professional OWASP-format reports for clients
HTML	Standalone viewable report in any browser
JSON	Machine-readable, import/export between sessions
SARIF	CI/CD integration (GitHub Actions, Azure DevOps)

---

🛡️ WAF Bypass Engine

WS Tester Pro features a dedicated, state-of-the-art Web Application Firewall (WAF) Evasion Engine that systematically obfuscates malicious payloads to bypass modern edge-protection systems like Cloudflare, AWS WAF, and Akamai.

10 Advanced Encoding Techniques Supported:

• URL Encoding & Double URL Encoding
• Unicode Escaping (\u003c)
• Hex Escaping (\x3c)
• HTML Entity Obfuscation (<, <)
• Keyword Case Mixing (SeLeCt)
• Null-Byte Injection (<scr%00ipt>)
• Full-Width Unicode (＜script＞)
• Comment Insertion (SEL/**/ECT)
• Tab & Newline Fragmentation

Select a WAF Profile (Generic, Cloudflare, AWS, Akamai) from the dashboard to optimize the technique priority order for the highest probability of evasion.

---

🛰️ Dual-Mode OOB (Out-of-Band) Proof System

Blind vulnerabilities (where the server returns no explicit error message or data) are notoriously difficult to detect via WebSockets. The OOB Proof System automates the detection of Blind SSRF, Blind SQLi, Blind Command Injection, and XML External Entities (XXE).

Mode 1: Interactsh (Fully Automated)

Powered by the popular Interactsh project (oast.fun).

• Generates unique polling domains automatically for every payload.
• Asynchronously polls for DNS, HTTP, and SMTP interactions.
• Provides immediate, deterministic proof of vulnerability (Zero Configuration required).

Mode 2: Custom Callback Server (Self-Hosted for Enterprise/Stealth)

For restricted networks or strictly governed red team engagements, use your own privately hosted notification server.

# Start your private server natively
export OOB_API_KEY="super-secret-key"
python3 oob_server.py

Auto-Confirm in Dashboard / CLI: Configure your callback URL and API key to have WS Tester Pro automatically verify callbacks across millions of packets in real-time.

python main.py --target wss://example.com/ws --oob https://proxy.redteam.xyz --oob-key super-secret-key

---

🐳 Docker

# Start Dashboard + OOB server
docker compose up -d --build

# View logs
docker compose logs -f

# Stop
docker compose down

• Dashboard: http://localhost:5000
• OOB health: http://localhost:7000/health

Production notes:

• Use HTTPS via reverse proxy (Nginx/Caddy/Traefik)
• Keep OOB_API_KEY secret
• Set WS_CORS_ORIGINS to your domain in production
• For correct client IPs behind proxy: OOB_TRUST_PROXY=1

---

💡 Example Penetration Testing Session

1. Discovery: Inspect target app's Network tab → filter "WS" → find wss://api.target.com/v1/chat
2. Initial Scan: Paste URL → select Fast Mode → Start Scan
3. Load Payloads: Open Custom Payloads → load SQLi + XSS libraries → re-scan for deeper injection testing
4. Deep Analysis: Disable Fast Mode → enable JWT, SSRF, SSTI modules → full scan
5. Traffic Interception: Switch to Interceptor → configure proxy → capture & modify live traffic
6. AI Analysis: Enable AI → get attack chain analysis & prioritized remediation roadmap
7. Reporting: Bug Bounty tab → Copy markdown → paste into HackerOne. Download PDF for client report.

---

🧪 Testing

# Run unit tests
pytest tests/ -v

# Run validation system tests
pytest tests/test_validation_properties.py -v
pytest tests/test_confidence_scoring.py -v

# Test with Vulnerable Lab Server
python mock_server.py    # Terminal 1
python main.py --target ws://localhost:8765    # Terminal 2

Vulnerable Lab Server Quick Test

1. Terminal 1: python mock_server.py (WS: ws://localhost:8765)
2. Terminal 2: python main.py (Dashboard: http://localhost:5000)
3. Open http://localhost:5000 → Target: ws://localhost:8765 → Start Scan

The Vulnerable Lab Server implements 20+ vulnerability types with realistic responses for testing the validation system. See MOCK_SERVER_README.md for complete documentation including:

• All vulnerability scenarios
• Test credentials
• Authentication testing
• WAF bypass scenarios
• OOB testing support

Mock Lab: Authenticated Scan

• WebSocket: ws://localhost:8765
• HTTP Login: http://localhost:8766/api/login

Test users:

Username	Password	Role
admin	admin123	Admin
alice	alice123	User
bob	bob123	User
test	test	Tester

Proxy Quick Test

1. Start mock server → Start dashboard → Open Interceptor tab
2. Target: ws://localhost:8765, Port: 8080, Intercept: OFF
3. Click Start Proxy → Click 🧪 Quick Test

Turbo Intruder Quick Test

1. Target: ws://localhost:8765 → Intruder tab
2. Burst Test: Payload {"action":"transfer","amount":100} → Count 30 → Launch Attack
3. OTP Brute-Force: Template {"action":"verify_otp","otp":"{{OTP}}"} → Digits 4 → Launch
4. Mock server correct OTP: 1337 — scanner detects no rate limiting (HIGH finding)

Port Troubleshooting (Windows)

netstat -ano | findstr ":5000"
netstat -ano | findstr ":8080"
taskkill /PID <PID> /F

---

👨‍💻 Development

Code Quality

This project uses pre-commit hooks to maintain code quality and consistency. The hooks automatically run before each commit to:

• Format code with Black
• Sort imports with isort
• Lint with flake8
• Type check with mypy
• Scan for security issues with bandit
• Validate docstrings with pydocstyle

Setup pre-commit hooks:

# Install pre-commit
pip install pre-commit

# Install git hooks
pre-commit install

# Run hooks manually on all files
pre-commit run --all-files

For detailed information about the configured hooks and how to use them, see Pre-Commit Hooks Documentation.

---

📋 VS Code Setup

1. Open ws_pro folder in VS Code
2. Open terminal (Ctrl + ~)
3. Run:

   pip install -r requirements.txt
   python main.py

4. Ctrl+Click the URL http://localhost:5000 to open in browser

---

⚠️ Legal Disclaimer

This tool is intended for educational purposes and authorized security testing only.

The developers and contributors of WS Tester Pro assume no liability and are not responsible for any misuse or damage caused by this program. It is the end user's absolute responsibility to obey all applicable local, state, and federal laws.

You may ONLY use this tool on systems, networks, and applications that you own, or for which you have explicit, written permission from the owner to conduct security assessments. Unauthorized scanning of systems or exploiting vulnerabilities without consent is illegal and may result in severe civil and criminal penalties.

By using this tool, you agree that you are using it at your own risk and that the creators will not be held accountable for your actions.

---

📄 License

Proprietary License — All Rights Reserved.

This software is the private intellectual property of the author. Unauthorized copying, distribution, or modification is strictly prohibited. See the LICENSE file for details.

---

Built with ❤️ for the security community
_{Star ⭐ the project if you find it useful!}