websocket_skill

Overview

This skill provides practical guidance and secure implementation patterns for real-time bidirectional WebSocket systems with a focus on preventing Cross-Site WebSocket Hijacking (CSWSH), enforcing strong authentication, and validating messages. It prioritizes explicit origin checks, token-based authentication, per-message authorization, and resource limits to reduce attack surface and operational risks. The guidance is actionable and test-driven to ensure security is verified before deployment.

How this skill works

The skill inspects WebSocket connection lifecycle and message flows to enforce security gates: validate the Origin header against an explicit allowlist, require token-based authentication (avoid cookie-only auth), accept connections only after checks, and perform per-message validation and authorization. It also monitors resource usage with rate limiting, idle timeouts, and connection limits per IP, and recommends performance patterns like connection pooling and batching to maintain low latency.

When to use it

• Building or hardening WebSocket endpoints that must be exposed to browsers
• Protecting applications at risk of CSWSH or session hijacking
• Implementing per-action access control for persistent connections
• Scaling real-time systems while preserving security and performance
• Designing test-driven security workflows for connection lifecycle

Best practices

• Always validate the Origin header against an explicit allowlist; never use "*"
• Authenticate with explicit tokens carried in query params or headers, not cookies
• Authorize every message action; a connected client is not implicitly trusted
• Validate all incoming messages with a schema (e.g., Pydantic) before acting
• Rate-limit messages and limit connections per IP; enforce idle timeouts
• Implement backpressure (bounded queues, timeouts) and connection pooling

Example use cases

• A single-page app that opens a WSS connection for live updates and must block cross-site injection
• A collaboration tool where per-message authorization prevents unauthorized actions like delete or admin commands
• A high-frequency telemetry stream that uses binary protocols and batching to reduce payload size
• A service requiring strict connection limits per IP to mitigate DoS from excessive websockets
• A system integrating tests that fail first for origin/auth/rate-limit behaviors to prevent regressions