WebSocket security testing tool for intercepting, analyzing, fuzzing, and scripting WebSocket connections to discover authentication flaws, injection vulnerabilities, data leaks, and protocol-level weaknesses.
Status: v1.0.0 - Production Ready | 982 tests | 82%+ coverage
- MITM Proxy with TLS interception and message logging
- Security Scanner with 12 checks covering OWASP WebSocket risks
- Fuzzing Engine with mutation, payload generation, and wordlist support
- Session Recording and replay with timing control
- Script Engine with YAML-based test automation, conditionals, loops, and 12 built-in functions
- Server Fingerprinting with implementation detection and CVE matching
- Endpoint Discovery via HTML/JS crawling for WebSocket URLs
- Report Diffing to compare scan results for regression testing
- 5 Report Formats: text, JSON, HTML, SARIF, JUnit
- Socket.IO protocol support
- permessage-deflate compression support
- Config auto-discovery with environment variable substitution (
${VAR:-default})
# Clone repository
git clone https://github.com/0xsj/socketspy
cd socketspy
# Build
go build -o bin/socketspy ./cmd/socketspy
# Or use make
make build# 1. Start the vulnerable chat server (in one terminal)
go run examples/vulnerable-chat/main.go
# 2. Test SocketSpy against it (in another terminal)
./bin/socketspy scan --target ws://localhost:8888/ws
# 3. Or run the demo script
examples/vulnerable-chat/test-socketspy.shSee examples/vulnerable-chat/README.md for detailed testing scenarios.
# Show help
./bin/socketspy --help
# Generate a starter config
./bin/socketspy init --target ws://example.com/ws
# Run security scanner
./bin/socketspy scan --target ws://example.com/ws --checks auth_bypass,idor
# Record a WebSocket session
./bin/socketspy record --target ws://example.com/ws --output session.jsonl
# Fuzz messages
./bin/socketspy fuzz --target ws://example.com/ws --mutations 50
# Replay recorded session
./bin/socketspy replay --input session.jsonl --target ws://example.com/ws --speed 2.0
# Run a YAML test script
./bin/socketspy script --file auth-test.yaml --target ws://example.com/ws
# Start MITM proxy
./bin/socketspy intercept --listen 127.0.0.1:8080 --target ws://example.com/ws --show-messages
# Fingerprint a WebSocket server
./bin/socketspy fingerprint --target ws://example.com/ws
# Discover WebSocket endpoints
./bin/socketspy discover --url https://example.com
# Compare two scan reports for regressions
./bin/socketspy diff --baseline old.json --current new.json| Mode | Description | Example |
|---|---|---|
| init | Generate a starter config file | socketspy init --target ws://example.com/ws |
| intercept | MITM proxy with optional message logging | socketspy intercept --listen :8080 --show-messages |
| scan | Run security checks on a WebSocket endpoint | socketspy scan --target ws://... --checks all |
| fuzz | Fuzz messages with mutations and payloads | socketspy fuzz --target ws://... --mutations 50 |
| record | Record a session to JSONL file | socketspy record --target ws://... --output file.jsonl |
| replay | Replay a recorded session with timing control | socketspy replay --input file.jsonl --speed 2.0 |
| script | Run a YAML test script | socketspy script --file test.yaml --target ws://... |
| fingerprint | Identify server implementation and known CVEs | socketspy fingerprint --target ws://... |
| discover | Crawl a site to find WebSocket endpoints | socketspy discover --url https://example.com |
| diff | Compare two reports to find new/resolved findings | socketspy diff --baseline old.json --current new.json |
| Check | Description |
|---|---|
| auth_bypass | Test if server accepts messages without authentication |
| idor | Mutate ID fields to test access controls |
| injection | SQL, XSS, and command injection testing |
| rate_limit | Test if server enforces rate limiting on messages |
| data_leak | Detect sensitive data exposure in server responses |
| origin_bypass | Test for CSWSH by connecting with spoofed Origin headers |
| session_hijack | Test if session tokens can be reused from a different connection |
| privilege_escalation | Test for horizontal/vertical privilege escalation across sessions |
| data_exposure | Detect excessive data exposure including PII, internal IDs, verbose errors |
| dos | Test resilience against denial of service patterns |
| schema_bypass | Test if server validates message schemas (missing fields, wrong types) |
| message_tampering | Test if server validates message integrity by tampering with fields |
Run all checks with --checks all or select specific ones with --checks auth_bypass,idor,injection.
SocketSpy supports 5 output formats via the --format flag:
| Format | Flag | Use Case |
|---|---|---|
| Text | --format text |
Human-readable terminal output (default) |
| JSON | --format json |
Machine-readable, pipeline integration |
| HTML | --format html |
Shareable standalone report with styling |
| SARIF | --format sarif |
GitHub Code Scanning, IDE integration |
| JUnit | --format junit |
CI/CD test result integration |
Each finding includes CWE references (e.g., CWE-287 for auth_bypass, CWE-639 for IDOR).
The script engine runs YAML-based test sequences against WebSocket endpoints. Scripts support variables, conditionals, loops, assertions, and value extraction.
name: auth-bypass-test
target: ws://example.com/ws
vars:
user_id: 42
steps:
- name: Send without auth
send: { "action": "get_profile", "user_id": "{{ user_id }}" }
expect:
timeout_ms: 3000
assert:
- path: "$.error"
exists: true
- name: Brute force IDs
for_each: "1,2,3,4,5"
send: { "action": "get_profile", "user_id": "{{ _item }}" }
expect:
assert:
- path: "$.data"
exists: false
on_fail:
finding:
severity: high
title: "IDOR on user_id={{ _item }}"Control flow: if: conditionals, repeat: loops, for_each: iteration.
Built-in functions: base64(), base64_decode(), url_encode(), url_decode(), random_int(), timestamp(), uuid(), upper(), lower(), len(), md5(), sha256().
Assertions: equals, not_equals, contains, matches (regex), exists, gt, lt, gte, lte, plus response time constraints.
SocketSpy is designed for pipeline use:
# Quiet mode suppresses progress output, keeps the report
socketspy scan --target ws://... --quiet --format sarif --output report.sarif
# Exit code control: fail the build on high+ severity findings
socketspy scan --target ws://... --fail-on high
# JUnit output for test frameworks
socketspy scan --target ws://... --format junit --output results.xml
# Strip ANSI colors for log files
socketspy scan --target ws://... --no-color
# Regression testing with diff
socketspy scan --target ws://... --format json --output current.json
socketspy diff --baseline baseline.json --current current.jsonCreate a config file (default: ~/.socketspy/config.json or ./socketspy.json):
{
"target": {
"url": "ws://localhost:3000/ws",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
}
},
"scanner": {
"enabled_checks": ["auth_bypass", "idor", "injection"],
"max_concurrent": 5
},
"fuzzer": {
"mutation_count": 10,
"max_payload_size": 1048576
},
"timeout": {
"dial_ms": 5000,
"read_ms": 10000,
"write_ms": 5000
}
}Environment variables are expanded using ${VAR} or ${VAR:-default} syntax. Config is auto-discovered from ./socketspy.json or ~/.socketspy/config.json, or specified with --config.
See configs/socketspy.json and test/example-config.json for full examples.
See CLAUDE.md for development guidelines and architecture.
socketspy/
├── cmd/socketspy/ # CLI implementation (10 modes)
├── internal/ # Application logic
│ ├── analyzer/ # Traffic analysis and pattern detection
│ ├── client/ # WebSocket client with message handling
│ ├── config/ # Configuration with auto-discovery and env vars
│ ├── discovery/ # WebSocket endpoint discovery via HTML/JS crawling
│ ├── fingerprint/ # Server fingerprinting with CVE matching
│ ├── fuzzer/ # Mutation and payload generation engine
│ ├── models/ # Domain models (Message, Connection, Finding, Session)
│ ├── protocol/
│ │ └── socketio/ # Socket.IO protocol support
│ ├── proxy/ # MITM proxy with TLS interception
│ ├── recorder/ # Session recording and replay
│ ├── report/ # Report generation (text, JSON, HTML, SARIF, JUnit, diff)
│ ├── scanner/ # Security check orchestration
│ │ └── checks/ # 12 security checks
│ └── script/ # YAML script engine with vars, loops, conditionals
├── pkg/ # Shared libraries
│ ├── errors/ # Structured error handling
│ ├── json/ # JSON path utilities and mutation
│ ├── logger/ # Logging interface
│ ├── tls/ # TLS certificate generation
│ ├── types/ # Shared types (Severity, etc.)
│ └── ws/ # WebSocket wrapper with compression support
├── configs/ # Example config files
├── examples/ # Vulnerable demo server and test scripts
├── notes/ # Development documentation
└── test/ # Test utilities and fixtures
# Run all tests
go test ./...
# Run with coverage
go test -cover ./...
# Start test echo server
go run test/echo-server/main.go
# Test CLI modes
./bin/socketspy record --config test/example-config.json --output test.jsonlSocketSpy includes a deliberately vulnerable WebSocket chat server:
# Start vulnerable server
go run examples/vulnerable-chat/main.go
# Visit web interface
open http://localhost:8888/
# Test with SocketSpy
./bin/socketspy scan --target ws://localhost:8888/wsThe server includes 9+ intentional vulnerabilities: authentication bypass, IDOR, authorization bypass, information disclosure, missing origin validation (CSWSH), no rate limiting, broadcasting private data, and injection vulnerabilities.
See examples/vulnerable-chat/README.md for detailed testing scenarios.
SocketSpy follows a layered architecture:
- pkg/ - Reusable libraries (errors, logger, json, tls, ws with compression)
- internal/models - Domain models (Message, Connection, Finding, Session)
- internal/config - Configuration with auto-discovery and env var substitution
- internal/client - WebSocket client with message handling
- internal/proxy - MITM proxy with TLS interception
- internal/analyzer - Pattern detection and anomaly scoring
- internal/scanner - Security check orchestration with 12 checks
- internal/fuzzer - Message mutation and payload generation
- internal/recorder - Session recording and replay
- internal/script - YAML script engine with conditionals and loops
- internal/report - Multi-format report generation and diffing
- internal/fingerprint - Server implementation detection with CVE matching
- internal/discovery - WebSocket endpoint crawling
- internal/protocol - Protocol-specific support (Socket.IO)
- cmd/socketspy - CLI interface with 10 modes
See architecture diagrams in CLAUDE.md.
Contributions welcome! Please see CLAUDE.md for:
- Development guidelines
- Code organization
- Testing strategy
- Design patterns used
MIT License - see LICENSE file
Built with:
- gorilla/websocket - WebSocket implementation
- Go standard library