torusguard 1.3.4 → 1.3.6

package/.torusguard/rules/webhook/TG-WEBHOOK-003-missing-webhook-idempotency.md

@@ -1,37 +1,51 @@
 # TG-WEBHOOK-003: Missing Webhook Idempotency
 
 ## Severity
-High by default. Raise to Critical when applicable.
+High. Processing incoming webhook events without recording event IDs allows duplicate webhook delivery to trigger duplicate fulfillments, charges, or database entries.
 
 ## Applies To
-- Relevant endpoints and services
+- Webhook Event Handlers
+- Node.js, Python, Go, Java, C#
 
 ## Why It Matters
-Explaining the risk of this vulnerability.
+Webhook providers (Stripe, GitHub, PayPal) employ retry mechanisms and guarantee *at-least-once* delivery. If a network blip causes your server to respond slowly, the provider resends the webhook. Without idempotency checks, actions execute multiple times.
 
 ## What TorusGuard Looks For
-- Specific code patterns or configurations
+- Event handlers executing side-effects immediately without checking if `event.id` was already processed.
 
 ## Unsafe Example
 ```javascript
-// Unsafe code example
+// UNSAFE: Handling event without deduplicating by event ID
+app.post('/api/webhook', async (req, res) => {
+  const event = req.event;
+  await creditUserAccount(event.userId, event.amount); // Executed on every retry
+  res.sendStatus(200);
+});
 ```
 
 ## Safe Example
 ```javascript
-// Safe code example
+// SAFE: Recording processed event IDs to guarantee idempotency
+app.post('/api/webhook', async (req, res) => {
+  const event = req.event;
+  const exists = await db.processedEvent.findUnique({ where: { id: event.id } });
+  if (exists) return res.status(200).json({ status: 'already_processed' });
+  await db.$transaction([
+    db.processedEvent.create({ data: { id: event.id } }),
+    creditUserAccount(event.userId, event.amount)
+  ]);
+  res.sendStatus(200);
+});
 ```
 
-## Remediation
-1. Step one
-2. Step two
-
-## Verification
-- Test case 1
-- Test case 2
+## Ponytail Remediation Budget
+- Additions: <= 8 lines
+- Deletions: <= 3 lines
 
-## False Positives and Exceptions
-An exception requires documented review.
+## Remediation
+1. Store processed event IDs in a persistent table with unique constraints.
+2. Return 200 OK immediately if an event ID has already been recorded.
 
 ## Related Rules
-- TG-OTHER-001
+- `TG-BIZ-002`: Replayable One-Time Operation
+- `TG-WEBHOOK-001`: Missing Webhook Signature Verification

package/.torusguard/rules/webhook/TG-WEBHOOK-004-unvalidated-webhook-event-type.md

@@ -1,37 +1,46 @@
 # TG-WEBHOOK-004: Unvalidated Webhook Event Type
 
 ## Severity
-High by default. Raise to Critical when applicable.
+High. Dynamically dispatching webhook handlers using unsanitized `event.type` strings from payloads can lead to object prototype pollution, unintended method invocation, or unhandled exceptions.
 
 ## Applies To
-- Relevant endpoints and services
+- Dynamic Webhook Event Dispatchers
+- Node.js, Python, Ruby
 
 ## Why It Matters
-Explaining the risk of this vulnerability.
+Using `handlers[event.type](event)` where `event.type` is controlled by the payload allows attackers to invoke object prototype properties like `toString`, `constructor`, or `__proto__`, causing crashes or prototype pollution.
 
 ## What TorusGuard Looks For
-- Specific code patterns or configurations
+- Bracket indexing into handler objects with untrusted event type strings without allowlist validation.
 
 ## Unsafe Example
 ```javascript
-// Unsafe code example
+// UNSAFE: Dynamic object lookup using unsanitized event.type
+const handlers = { 'order.created': handleOrder };
+app.post('/webhook', (req, res) => {
+  handlers[req.body.type](req.body); // Attacker passes type: '__proto__' or 'constructor'
+});
 ```
 
 ## Safe Example
 ```javascript
-// Safe code example
+// SAFE: Explicit switch-case or Object.hasOwn allowlist validation
+const ALLOWED_TYPES = new Set(['order.created', 'order.refunded']);
+app.post('/webhook', (req, res) => {
+  const { type } = req.body;
+  if (!ALLOWED_TYPES.has(type)) return res.status(400).json({ error: 'Unsupported event type' });
+  if (type === 'order.created') handleOrder(req.body);
+});
 ```
 
-## Remediation
-1. Step one
-2. Step two
-
-## Verification
-- Test case 1
-- Test case 2
+## Ponytail Remediation Budget
+- Additions: <= 6 lines
+- Deletions: <= 2 lines
 
-## False Positives and Exceptions
-An exception requires documented review.
+## Remediation
+1. Validate event types against an explicit `Set` or `switch` statement.
+2. Never dynamically execute object methods via unvetted user-controlled keys.
 
 ## Related Rules
-- TG-OTHER-001
+- `TG-WEBHOOK-001`: Missing Webhook Signature Verification
+- `TG-INPUT-001`: Missing Server-Side Request Validation

package/.torusguard/rules/websocket/TG-WS-002-missing-channel-level-authorization.md

@@ -1,37 +1,48 @@
-# TG-WS-002: Missing Channel-Level Authorization
+# TG-WS-002: Missing Channel-Level WebSocket Authorization
 
 ## Severity
-High by default. Raise to Critical when applicable.
+Critical. Allowing WebSocket clients to subscribe to rooms, topics, or channels (`socket.join(...)`) without verifying that the client has permission to view that channel leaks real-time private messages across tenants.
 
 ## Applies To
-- Relevant endpoints and services
+- Real-Time Sockets (Socket.io, ws, ActionCable, Django Channels)
+- Node.js, Python, Go
 
 ## Why It Matters
-Explaining the risk of this vulnerability.
+In real-time chat or multi-tenant collaboration applications, joining a room grants immediate broadcast reception. If a client can emit `join_room("tenant_123_finance")` and the server joins them without verifying membership, all private room broadcasts leak.
 
 ## What TorusGuard Looks For
-- Specific code patterns or configurations
+- Socket event listeners (`socket.on('join')`) that join rooms based on client input without permissions checks.
 
 ## Unsafe Example
 ```javascript
-// Unsafe code example
+// UNSAFE: Joining channel directly from client parameter without auth check
+io.on('connection', (socket) => {
+  socket.on('join_channel', (channelId) => {
+    socket.join(channelId); // Attacker joins other tenants' private channels
+  });
+});
 ```
 
 ## Safe Example
 ```javascript
-// Safe code example
+// SAFE: Verifying tenant membership before allowing channel join
+io.on('connection', (socket) => {
+  socket.on('join_channel', async (channelId) => {
+    const isMember = await checkChannelAccess(socket.data.user.id, channelId);
+    if (!isMember) return socket.emit('error', 'Unauthorized channel access');
+    socket.join(channelId);
+  });
+});
 ```
 
-## Remediation
-1. Step one
-2. Step two
-
-## Verification
-- Test case 1
-- Test case 2
+## Ponytail Remediation Budget
+- Additions: <= 6 lines
+- Deletions: <= 2 lines
 
-## False Positives and Exceptions
-An exception requires documented review.
+## Remediation
+1. Attach authenticated user session data to the socket during handshake (`socket.data.user`).
+2. Verify user channel membership against database before calling `socket.join(channelId)`.
 
 ## Related Rules
-- TG-OTHER-001
+- `TG-WS-001`: Unauthenticated WebSocket Handshake
+- `TG-DB-004`: Missing Multi-Tenant Query Isolation

package/.torusguard/rules/websocket/TG-WS-003-unvalidated-websocket-message.md

@@ -1,37 +1,51 @@
-# TG-WS-003: Unvalidated WebSocket Message
+# TG-WS-003: Unvalidated WebSocket Message Payload
 
 ## Severity
-High by default. Raise to Critical when applicable.
+High. Ingesting and processing incoming WebSocket message frames without schema validation or input sanitization exposes real-time backend handlers to SQL injection, XSS broadcasting, and command execution.
 
 ## Applies To
-- Relevant endpoints and services
+- WebSocket Message Handlers (Socket.io, ws, native WebSockets)
+- Node.js, Python, Go
 
 ## Why It Matters
-Explaining the risk of this vulnerability.
+Unlike HTTP routes which typically have middleware validation (Zod, Joi, Pydantic), WebSocket messages frequently bypass standard middleware pipelines and pass raw client JSON directly into database queries or broadcast sinks.
 
 ## What TorusGuard Looks For
-- Specific code patterns or configurations
+- WebSocket message event handlers directly consuming message payloads without validation schemas.
 
 ## Unsafe Example
 ```javascript
-// Unsafe code example
+// UNSAFE: Consuming raw WebSocket message without schema validation
+socket.on('send_message', async (data) => {
+  await db.message.create({ data: { text: data.text, room: data.room } });
+  io.to(data.room).emit('new_message', data);
+});
 ```
 
 ## Safe Example
 ```javascript
-// Safe code example
+// SAFE: Validating WebSocket payload with Zod schema before processing
+const MessageSchema = z.object({
+  text: z.string().min(1).max(2000),
+  room: z.string().uuid()
+});
+
+socket.on('send_message', async (rawData) => {
+  const result = MessageSchema.safeParse(rawData);
+  if (!result.success) return socket.emit('error', 'Invalid payload schema');
+  await db.message.create({ data: result.data });
+  io.to(result.data.room).emit('new_message', result.data);
+});
 ```
 
-## Remediation
-1. Step one
-2. Step two
-
-## Verification
-- Test case 1
-- Test case 2
+## Ponytail Remediation Budget
+- Additions: <= 8 lines
+- Deletions: <= 2 lines
 
-## False Positives and Exceptions
-An exception requires documented review.
+## Remediation
+1. Enforce validation schemas (Zod, Pydantic) on all incoming WebSocket message handlers.
+2. Sanitize text fields before broadcasting to other connected clients.
 
 ## Related Rules
-- TG-OTHER-001
+- `TG-INPUT-001`: Missing Server-Side Request Validation
+- `TG-INPUT-003`: Unsafe Dynamic Code or HTML Execution

package/.torusguard/rules/websocket/TG-WS-004-unbounded-websocket-connections.md

@@ -1,37 +1,51 @@
-# TG-WS-004: Unbounded WebSocket Connections
+# TG-WS-004: Unbounded WebSocket Connections & Rate Limiting
 
 ## Severity
-High by default. Raise to Critical when applicable.
+Medium. Permitting unlimited concurrent WebSocket connections per IP address or user allows attackers to exhaust file descriptors, socket memory pools, and server CPU via connection flood attacks.
 
 ## Applies To
-- Relevant endpoints and services
+- WebSocket Servers (ws, Socket.io, Django Channels, Gorilla WebSocket)
+- Node.js, Python, Go
 
 ## Why It Matters
-Explaining the risk of this vulnerability.
+WebSocket connections are persistent TCP connections that remain open. Without connection throttling or message rate limits, a single client can open 10,000 idle sockets, consuming all available file descriptors and denying service to legitimate users.
 
 ## What TorusGuard Looks For
-- Specific code patterns or configurations
+- WebSocket server configurations lacking maximum connection limits, per-IP socket caps, or message throttling.
 
 ## Unsafe Example
 ```javascript
-// Unsafe code example
+// UNSAFE: Accepting unbounded WebSocket connections without rate limiting
+const wss = new WebSocketServer({ port: 8080 });
 ```
 
 ## Safe Example
 ```javascript
-// Safe code example
+// SAFE: Enforcing per-IP connection limits and message rate bounds
+const ipConnections = new Map();
+const MAX_CONNS_PER_IP = 10;
+
+server.on('upgrade', (req, socket, head) => {
+  const ip = req.socket.remoteAddress;
+  const count = ipConnections.get(ip) || 0;
+  if (count >= MAX_CONNS_PER_IP) {
+    socket.destroy();
+    return;
+  }
+  ipConnections.set(ip, count + 1);
+  socket.on('close', () => ipConnections.set(ip, Math.max(0, (ipConnections.get(ip) || 1) - 1)));
+});
 ```
 
-## Remediation
-1. Step one
-2. Step two
-
-## Verification
-- Test case 1
-- Test case 2
+## Ponytail Remediation Budget
+- Additions: <= 10 lines
+- Deletions: <= 2 lines
 
-## False Positives and Exceptions
-An exception requires documented review.
+## Remediation
+1. Enforce per-IP connection limits in the HTTP `upgrade` request listener.
+2. Implement heartbeat ping/pong timeouts to terminate dead or idle sockets.
+3. Throttle inbound message rates using token bucket or sliding window algorithms.
 
 ## Related Rules
-- TG-OTHER-001
+- `TG-RATE-003`: Unbounded Resource Consumption
+- `TG-WS-001`: Unauthenticated WebSocket Handshake