hunt-websocket
Teaches your AI agent to protect apps against attacks.
What it does
This tool helps find security flaws in internet connections called WebSockets. It checks if these connections can be used to steal information or perform unauthorized actions.
When to use it
- ✓When testing the security of a website or application.
- ✓To check if sensitive data can be exposed through real-time connections.
- ✓When investigating how an attacker could manipulate transactions or messages.
Example of what to ask your AI
“Check WebSocket security on example.com”
Want more? Open the sections below.
How to use
The easiest way: copy the message below and paste it into Claude, ChatGPT, Cursor or any AI. It reads the skill and follows the instructions.
Skill link
Ready-to-paste message
How it works
The tool analyzes how a website establishes real-time internet connections. It looks for ways to trick these connections into revealing information or allowing unauthorized actions, as if it were a legitimate user.
Installation
Easiest way: copy the skill link and paste it into Claude, ChatGPT or Cursor asking it to follow the instructions.
In the terminal (Claude Code, Codex, Cursor), in your project folder:
npx skills add sickn33/agentic-awesome-skills --skill hunt-websocketOr download just the file:
curl -L https://raw.githubusercontent.com/sickn33/agentic-awesome-skills/main/plugins/agentic-awesome-skills-claude/skills/hunt-websocket/SKILL.md -o SKILL.mdTechnical content (original SKILL.md)
Original text by the author, straight from GitHub.
⚠️ AUTHORIZED USE ONLY This skill is for educational purposes or authorized security assessments only. You must have explicit, written permission from the system owner before using this tool. Misuse of this tool is illegal and strictly prohibited.
Mandatory confirmation gate Before running any command that probes, exploits, changes, persists on, extracts data from, or attempts credential access against a target:
- Ask the user to state the exact target URL, IP, account, or resource.
- Ask the user to confirm written authorization and the permitted scope.
- Show the exact command(s) and explain their expected effect.
- Wait for explicit confirmation in the current conversation.
Without that confirmation, remain read-only and provide defensive guidance only. Prefer a sandbox, disposable VM, or controlled lab.
HUNT-WEBSOCKET — WebSocket Security
Crown Jewel Targets
CSWSH (Cross-Site WebSocket Hijacking) with a cookie-authenticated handshake and no CSRF/per-connection token = High–Critical (real-time exfil of any logged-in victim's data).
Highest-value chains:
- CSWSH → data exfil / ATO — handshake authenticates via ambient cookie, no CSRF token, Origin not enforced → attacker page opens WS as the victim and streams their messages/PII/tokens. If the stream carries a session/refresh/CSRF token, this escalates to ATO.
- No per-message auth — HTTP/handshake auth present but individual WS frames are not re-authorized → privileged messages accepted (
deleteUser,getSecretConfig). - Message tampering — modify in-flight frames (price, qty, userId, amount) in trading/game/checkout apps → financial fraud.
- socket.io namespace / room authz bypass — connect to a privileged namespace or join another user's room without a permission check → cross-tenant real-time exfil.
- Handshake-layer Upgrade smuggling — a malformed
Upgrade/Connection/Sec-WebSocket-*handshake makes the front proxy and origin disagree on whether an upgrade occurred → request-smuggling tunnel.
Grounding — Reference Cases (read before hunting)
These are public, verifiable references. Use them to calibrate what a real WS finding looks like and how it was proven. Do not invent additional report IDs or payouts.
| # | Source / ID | Class | Lesson |
|---|---|---|---|
| 1 | PortSwigger Web Security Academy — "Cross-site WebSocket hijacking" (research + labs) | CSWSH | Canonical CSWSH model: cookie-auth handshake + no CSRF token + missing Origin check → attacker reads/sends as victim. The authoritative methodology. |
| 2 | Christian Schneider — "Cross-Site WebSocket Hijacking (CSWSH)" (original disclosure/write-up, 2013) | CSWSH | First public CSWSH technique: cookie-auth handshake + no Origin enforcement; PoC must prove victim-data receipt in the attacker browser, not just a 101. |
| 3 | Coda CSWSH (referenced in this repo's hunt-csrf set) | CSWSH | Real-time collab apps commonly authenticate the socket purely via cookie; Origin allow-listing was the missing control. |
| 4 | CVE-2020-7662 — websocket-extensions (Node) ReDoS |
DoS | A crafted Sec-WebSocket-Extensions header triggers catastrophic backtracking — handshake header is an attack surface, not just frames. |
| 5 | CVE-2024-37890 — ws (Node) DoS |
DoS | Many handshake request headers exhaust the server; confirms the handshake itself is parser-attackable pre-frames. |
| 6 | Outdated socket.io / Engine.IO stacks |
socket.io | Motivates the version-fingerprint step in Phase 7 — fingerprint the version, then check that release's known advisories. |
Only the four CVEs above are asserted with exact IDs because they are verifiable. For any case where you are not certain of the exact identifier, describe the technique with no citation — a wrong CVE is worse than none.
Phase 1 — Discover WebSocket Endpoints
# Grep JS for WS connections (handshake URLs, socket.io clients)
grep -rE "new WebSocket|io\(|io\.connect|socket\.io|new SockJS|signalr|Phoenix\.Socket|wss?://" \
recon/$TARGET/ --include="*.js" 2>/dev/null | \
grep -oE "(wss?://[^'\"]+|/[a-zA-Z0-9/_.-]*socket[^'\"]*|/signalr[^'\"]*|/cable\b)" | sort -u
# Crawl URLs for realtime hints
grep -iE "socket|/ws\b|websocket|stream|realtime|live|chat|events|/cable|/signalr|notifications" \
recon/$TARGET/urls.txt | sort -u
# Probe handshake (101 = upgrade supported)
curl -sI -o /dev/null -w "%{http_code}\n" \
…
FAQ
What is a WebSocket?
It's a way for your browser (or app) and a web server to exchange data in real-time, like in online chats or games.
What is CSWSH?
It's a type of attack (Cross-Site WebSocket Hijacking) where an attacker tries to steal user data through a WebSocket connection by exploiting authentication flaws.
Do I need permission to use this tool?
Yes, it is crucial to have explicit, written permission from the system owner before using this tool. Misuse is illegal.
Details
Original description by the author
Hunt WebSocket vulnerabilities
Popularity
- GitHub stars
- 48k
- Ranking position
- #3295
- License
- MIT
- Updated
- 10/15/2026
Comments
- …
More skills from this repository
00-andruia-consultant
Helps your agent start or improve AI projects. It analyzes code, suggests tools, and creates action plans in Spanish.
sickn33/agentic-awesome-skills
007
Lets your agent perform security audits and threat modeling. It's useful for protecting projects against attacks and vulnerabilities.
sickn33/agentic-awesome-skills
10-andruia-skill-smith
Helps your agent create or improve AI tools. It defines how tools work, writes documentation, and validates the structure.
sickn33/agentic-awesome-skills
20-andruia-niche-intelligence
Lets your agent create a summary about a specific industry. It's useful for understanding the context, rules, usage patterns, and risks of a project, using reliable sources.
sickn33/agentic-awesome-skills
Similar skills
django-security
Helps your agent implement security practices in Django applications. It focuses on authentication, authorization, and prevention against common attacks, ensuring more secure code.
affaan-m/ECC
laravel-security
Helps your agent secure Laravel applications against threats. Implements security practices for authentication, authorization, and common attack prevention.
affaan-m/ECC
module-regression
Helps your agent manage changes in large projects. Ensures code changes in one part don't break other parts.
affaan-m/ECC