torusguard 1.0.0 → 1.3.1

package/skills/torusguard/payload/rules/csrf/TG-CSRF-002-unsafe-credentialed-cross-origin-request.md

@@ -0,0 +1,37 @@
+# TG-CSRF-002: Unsafe Credentialed Cross-Origin Request
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/skills/torusguard/payload/rules/custom/.gitkeep

@@ -0,0 +1 @@
+# Retain custom rules directory

package/skills/torusguard/payload/rules/custom/README.md

@@ -0,0 +1,30 @@
+# TorusGuard Custom Rules Directory
+
+Place your custom organization-specific, framework-specific, or proprietary library rules here.
+Any markdown files (`*.md`) or JSON files (`*.json`) placed in this directory will be automatically indexed during `/torusguard-audit` and finding scoring.
+
+---
+
+## Example Custom Rule: `TG-CUSTOM-001.md`
+
+```markdown
+# TG-CUSTOM-001: Require Organization UUID on All Multi-Tenant Queries
+
+**Rule ID:** TG-CUSTOM-001
+**Severity:** High
+**Category:** database-safety
+**Confidence Base:** 85
+
+### Description
+Ensure all database operations on multi-tenant tables enforce explicit `org_id` or `tenant_id` boundaries.
+
+### Unsafe Pattern
+```python
+db.execute("SELECT * FROM invoices WHERE status = 'paid'")
+```
+
+### Safe Remediation
+```python
+db.execute("SELECT * FROM invoices WHERE status = 'paid' AND org_id = %s", [current_org_id])
+```
+```

package/skills/torusguard/payload/rules/edge/TG-EDGE-001-serverless-global-state-leak.md

@@ -0,0 +1,83 @@
+# TG-EDGE-001: Serverless & Edge Global State Memory Leakage
+
+## Severity
+High. Global state persistence across warm container or edge worker invocations can lead to cross-request tenant pollution and unauthorized credential disclosure.
+
+## Applies To
+- Cloudflare Workers
+- Vercel Edge Functions (Next.js Edge Runtime)
+- AWS Lambda / Netlify Functions
+
+## Why It Matters
+In serverless and edge computing architectures:
+1. **Container / Isolate Reuse:** Serverless instances (V8 isolates or MicroVMs) stay warm across sequential invocations to optimize startup latency.
+2. **State Leakage Hazard:** Global variables, module-scoped arrays, singletons, or uncleaned caches persist between subsequent client requests handled by the same warm worker.
+3. **Cross-Tenant Contamination:** If User A's authentication token, tenant ID, or profile data is assigned to a module-level variable, a subsequent request from User B can accidentally read User A's data without authenticating.
+
+## What TorusGuard Looks For
+1. Module-scoped or global mutable variables (`let`, `var`, global `Map`, `dict`) storing user-specific context, request headers, or auth tokens.
+2. Singleton database connection pools or client sessions retaining user-specific session state across handler calls.
+3. Lack of explicit request-scoped context initialization.
+
+## Unsafe Example
+```typescript
+// UNSAFE: Module-scoped state persists across warm Cloudflare Worker invocations
+let currentSessionUser: { id: string; role: string } | null = null;
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const token = request.headers.get("Authorization");
+    if (token) {
+      // Leaks to subsequent requests if not explicitly cleared on every path!
+      currentSessionUser = await verifyUser(token);
+    }
+    
+    // Danger: If next request lacks Authorization header, currentSessionUser remains set!
+    return new Response(JSON.stringify({ user: currentSessionUser }));
+  }
+};
+```
+
+## Safe Example
+```typescript
+// SAFE: Strictly request-scoped context; zero mutable global state
+interface RequestContext {
+  user: { id: string; role: string } | null;
+  requestId: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    // Context is created fresh per invocation inside the handler scope
+    const reqContext: RequestContext = {
+      user: null,
+      requestId: crypto.randomUUID(),
+    };
+
+    const token = request.headers.get("Authorization");
+    if (token) {
+      reqContext.user = await verifyUser(token, env.JWT_SECRET);
+    }
+
+    if (!reqContext.user) {
+      return new Response(JSON.stringify({ error: "Unauthorized" }), { status: 401 });
+    }
+
+    return new Response(JSON.stringify({ user: reqContext.user }));
+  }
+};
+```
+
+## Remediation
+1. **Enforce Request-Scoped State:** Always declare mutable variables, session holders, and tenant identifiers inside the handler function scope.
+2. **Treat Global Scope as Immutable:** Limit module-level variables strictly to immutable configuration constants, static schemas, or stateless utility functions.
+3. **Isolate Database Clients:** Ensure database connections or ORM instances created globally do not cache user-specific transaction boundaries or credentials.
+
+## Verification
+- Unit test sequential simulated requests against the worker ensuring User A's context never appears in an unauthenticated User B invocation.
+- Assert that static linters flag module-scoped mutable assignments in edge handler files.
+
+## Related Rules
+- `TG-EDGE-003`: AWS Lambda Ephemeral Execution & Cold Start Security
+- `TG-AUTH-002`: Client-Side Only Authorization
+- `TG-DB-004`: Missing Tenant Query Isolation

package/skills/torusguard/payload/rules/edge/TG-EDGE-003-aws-lambda-ephemeral-cold-start.md

@@ -0,0 +1,76 @@
+# TG-EDGE-003: AWS Lambda Ephemeral Execution & Cold Start Security
+
+## Severity
+Medium by default. Escalate to High if IAM credentials or temporary execution tokens are leaked or indefinitely reused across invocations.
+
+## Applies To
+- AWS Lambda (Python, Node.js)
+- Serverless Framework / AWS SAM / AWS CDK
+
+## Why It Matters
+AWS Lambda execution environments are frequently reused across invocations. While initializing heavy clients (such as AWS SDK or database pools) outside the handler improves cold start latency:
+1. **Stale Credentials & Leaked Tokens:** Temporary STS session tokens or database auth credentials initialized during cold start can expire or persist between distinct tenants.
+2. **Ephemeral Disk Residue (`/tmp`):** The `/tmp` storage directory is preserved across warm invocations of the same execution environment. Writing unencrypted sensitive files, tokens, or customer exports to `/tmp` can expose data to subsequent requests.
+3. **Execution Timeouts:** Unbounded subrequests without client-side timeouts can consume maximum execution seconds, triggering Denial-of-Wallet.
+
+## What TorusGuard Looks For
+1. Writing unencrypted sensitive data or credentials directly to `/tmp` without explicit deletion in a `finally` block.
+2. Global caching of dynamic, tenant-specific STS or database credentials outside the handler.
+3. Outbound network calls inside Lambda handlers lacking explicit connection and read timeouts.
+
+## Unsafe Example
+```python
+# UNSAFE: Writing sensitive customer export to /tmp without cleanup
+import os
+import boto3
+
+def lambda_handler(event, context):
+    user_id = event["userId"]
+    temp_path = f"/tmp/export_{user_id}.json"
+    
+    # Writes sensitive data to /tmp; persists across warm invocations!
+    with open(temp_path, "w") as f:
+        f.write(event["sensitiveUserData"])
+        
+    upload_to_s3(temp_path)
+    # Missing cleanup: subsequent invocations can access this file!
+    return {"status": "ok"}
+```
+
+## Safe Example
+```python
+# SAFE: Ephemeral cleanup guaranteed via try/finally and unique temp storage
+import os
+import tempfile
+import boto3
+
+def lambda_handler(event, context):
+    user_id = event.get("userId")
+    if not user_id:
+        return {"statusCode": 400, "body": "Missing userId"}
+
+    # Use secure tempfile with guaranteed cleanup
+    with tempfile.NamedTemporaryFile(mode="w+", delete=False) as temp_file:
+        try:
+            temp_file.write(event["sensitiveUserData"])
+            temp_file.flush()
+            upload_to_s3(temp_file.name)
+        finally:
+            if os.path.exists(temp_file.name):
+                os.remove(temp_file.name)
+
+    return {"statusCode": 200, "body": "Export completed safely"}
+```
+
+## Remediation
+1. **Always clean up `/tmp` files:** Use `tempfile.NamedTemporaryFile` with a `finally` block or context manager that guarantees file removal.
+2. **Avoid Global Caching of Tenant Context:** Initialize IAM STS assume-role credentials per request within the handler.
+3. **Configure Timeouts:** Set client connection and read timeouts on all outbound HTTP and AWS SDK clients.
+
+## Verification
+- Assert that all `/tmp` file writes are wrapped in cleanup blocks.
+- Test that consecutive invocations with different tenant payloads do not find pre-existing files in `/tmp`.
+
+## Related Rules
+- `TG-EDGE-001`: Serverless & Edge Global State Memory Leakage
+- `TG-SEC-001`: Hardcoded Secrets

package/skills/torusguard/payload/rules/graphql/TG-GQL-001-missing-query-depth-or-complexity-limits.md

@@ -0,0 +1,64 @@
+# TG-GQL-001: Missing Query Depth or Complexity Limits
+
+## Severity
+High. Unbounded GraphQL queries allow nested recursive queries (e.g., author $\rightarrow$ books $\rightarrow$ author) that trigger server denial-of-service, CPU saturation, and exponential database query loads.
+
+## Applies To
+- Apollo Server, Yoga, GraphQL.js, Strawberry, Graphene (Python), TypeGraphQL
+
+## Why It Matters
+GraphQL allows client-controlled response structures. Without depth limiting or cost analysis:
+1. An attacker can submit deeply nested circular queries ($> 100$ levels) that monopolize Node.js or Python event loops.
+2. Batching multiple expensive queries in a single HTTP request bypasses naive rate limiters.
+3. Automated scanners can trigger denial-of-service unless runtime introspection probes are bounded to harmless depth thresholds.
+
+## What TorusGuard Looks For
+1. GraphQL server setup lacking query depth validation rules (e.g., `graphql-depth-limit`).
+2. Missing complexity/cost calculation plugins (`graphql-query-complexity`).
+3. Runtime probe: Executing a harmless 3-level bounded query canary; flagging if queries deeper than allowed thresholds execute without validation errors.
+
+## Unsafe Example
+```typescript
+// UNSAFE: Apollo Server without query depth or complexity validation
+import { ApolloServer } from "@apollo/server";
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  // No depth limit or complexity plugins configured!
+});
+```
+
+## Safe Example
+```typescript
+// SAFE: Query depth validation capped at 6 levels and complexity cost limits
+import { ApolloServer } from "@apollo/server";
+import depthLimit from "graphql-depth-limit";
+import { createComplexityLimitRule } from "graphql-validation-complexity";
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  validationRules: [
+    depthLimit(6), // Maximum query nesting depth
+    createComplexityLimitRule(1000, {
+      onCost: (cost) => console.log(`GraphQL Query Cost: ${cost}`),
+    }),
+  ],
+});
+```
+
+## Bounded Runtime Probe Protocol
+When probing GraphQL endpoints under `/torusguard web-validate`:
+1. Submit a **bounded 3-level canary query** (e.g., `{ __typename, schema: __schema { types { name } } }`).
+2. Submit a single test query exceeding max depth (e.g., 7 levels) with a strict request budget of 1 request.
+3. Assert that the server responds with an HTTP 400 or GraphQL `GRAPHQL_VALIDATION_FAILED` error rather than evaluating resolvers.
+
+## Remediation
+1. **Enforce Depth Limiting:** Install `graphql-depth-limit` and cap maximum depth (typically 5–7 levels).
+2. **Implement Query Cost Analysis:** Assign complexity points per field and reject queries exceeding cost thresholds.
+3. **Disable Production Introspection:** Set `introspection: false` in production environments.
+
+## Related Rules
+- `TG-GQL-004`: Unnecessary Production Introspection
+- `TG-RATE-003`: Unbounded Resource Consumption

package/skills/torusguard/payload/rules/graphql/TG-GQL-002-resolver-missing-authorization.md

@@ -0,0 +1,37 @@
+# TG-GQL-002: Resolver Missing Authorization
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/skills/torusguard/payload/rules/graphql/TG-GQL-003-unbounded-graphql-pagination-or-batching.md

@@ -0,0 +1,37 @@
+# TG-GQL-003: Unbounded GraphQL Pagination or Batching
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/skills/torusguard/payload/rules/graphql/TG-GQL-004-unnecessary-production-introspection.md

@@ -0,0 +1,37 @@
+# TG-GQL-004: Unnecessary Production Introspection
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/skills/torusguard/payload/rules/secrets/TG-SEC-005-secret-in-git-history.md

@@ -0,0 +1,37 @@
+# TG-SEC-005: Secret in Git History
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/skills/torusguard/payload/rules/secrets/TG-SEC-006-secret-in-build-artifact.md

@@ -0,0 +1,37 @@
+# TG-SEC-006: Secret in Build Artifact
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/skills/torusguard/payload/rules/secrets/TG-SEC-007-secret-in-test-or-example-fixture.md

@@ -0,0 +1,37 @@
+# TG-SEC-007: Secret in Test or Example Fixture
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/skills/torusguard/payload/rules/ssrf/TG-SSRF-001-user-controlled-server-side-url-fetch.md

@@ -0,0 +1,68 @@
+# TG-SSRF-001: User-Controlled Server-Side URL Fetch
+
+## Severity
+High by default. Raise to Critical when the request can reach internal administrative services, cloud metadata services, or sensitive network assets.
+
+## Applies To
+- URL preview APIs
+- Remote image/file importers
+- Webhook testers
+- PDF generation services
+- Server-side integrations
+- Any endpoint that fetches a URL supplied by a user
+
+## Why It Matters
+A server that fetches an attacker-controlled URL may be used to access internal systems or send requests from a trusted network location.
+
+## What TorusGuard Looks For
+- fetch(), axios, requests, HttpClient, OkHttp, or equivalent calls
+- URL values derived from request body, query, or path parameters
+- Redirect-following enabled without destination validation
+- No domain or IP allowlist
+- No timeout or response-size limit
+
+## Unsafe Example
+```javascript
+const response = await fetch(req.body.url);
+```
+
+## Safe Example
+```javascript
+const target = new URL(req.body.url);
+if (target.protocol !== "https:") {
+  throw new Error("Only HTTPS URLs are allowed");
+}
+if (!ALLOWED_HOSTS.has(target.hostname)) {
+  throw new Error("Destination is not allowed");
+}
+const response = await fetch(target, {
+  redirect: "error",
+  signal: AbortSignal.timeout(5000)
+});
+```
+
+## Remediation
+1. Parse the URL using a maintained URL parser.
+2. Allow only required schemes.
+3. Prefer an explicit hostname allowlist.
+4. Block private, loopback, link-local, and metadata destinations.
+5. Disable or revalidate redirects.
+6. Apply timeout and response-size limits.
+7. Do not return raw upstream responses.
+
+## Verification
+- Test allowed domains.
+- Test localhost and loopback addresses.
+- Test private IP ranges.
+- Test metadata-service addresses.
+- Test file:// and other unsupported schemes.
+- Test redirects to an untrusted or internal destination.
+- Verify timeout and response-size behavior.
+
+## False Positives and Exceptions
+An exception requires a documented fixed allowlist, network isolation, timeout, response limit, and review owner.
+
+## Related Rules
+- TG-SSRF-002
+- TG-SSRF-003
+- TG-RATE-003

package/skills/torusguard/payload/rules/ssrf/TG-SSRF-002-missing-internal-network-protection.md

@@ -0,0 +1,37 @@
+# TG-SSRF-002: Missing Internal Network Protection
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001

package/skills/torusguard/payload/rules/ssrf/TG-SSRF-003-unsafe-redirect-following.md

@@ -0,0 +1,37 @@
+# TG-SSRF-003: Unsafe Redirect Following
+
+## Severity
+High by default. Raise to Critical when applicable.
+
+## Applies To
+- Relevant endpoints and services
+
+## Why It Matters
+Explaining the risk of this vulnerability.
+
+## What TorusGuard Looks For
+- Specific code patterns or configurations
+
+## Unsafe Example
+```javascript
+// Unsafe code example
+```
+
+## Safe Example
+```javascript
+// Safe code example
+```
+
+## Remediation
+1. Step one
+2. Step two
+
+## Verification
+- Test case 1
+- Test case 2
+
+## False Positives and Exceptions
+An exception requires documented review.
+
+## Related Rules
+- TG-OTHER-001