torusguard 1.0.0 → 1.3.1

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`

package/.torusguard/rules/TG-RATE-002-unlimited-public-write-endpoint.md

@@ -0,0 +1,109 @@
+# TG-RATE-002: Unlimited Public Write Endpoint
+
+## Severity
+
+Medium
+
+## Applies To
+
+- Contact forms and feedback submission routes
+- Newsletter signup and waitlist endpoints
+- Anonymous content creation or comment endpoints
+- Webhooks that accept unauthenticated internet traffic
+- Any expensive POST/PUT/PATCH endpoint callable pre-auth
+
+## Why It Matters
+
+Public write endpoints are common abuse entry points.
+Attackers can flood storage, queues, email providers, and notification systems.
+Abuse may not be data theft, but can still create real cost and downtime.
+Spam and bot traffic can also degrade analytics and operational trust.
+Unchecked write volume becomes an easy denial-of-wallet vector.
+
+## What TorusGuard Looks For
+
+- Unauthenticated write handlers without route-level throttling
+- Missing CAPTCHA or bot challenge on high-abuse forms
+- No IP, device, or fingerprint-based submission controls
+- No duplicate submission detection for identical payloads
+- Lack of queue depth or outbound provider safeguards after intake
+- Public webhooks with no signature check plus no request limits
+
+## Unsafe Example
+
+```ts
+app.post("/api/contact", async (req, res) => {
+  await db.contactMessage.create({
+    data: {
+      email: req.body.email,
+      message: req.body.message
+    }
+  });
+
+  await mailer.send({
+    to: "support@example.com",
+    subject: "New contact request",
+    text: req.body.message
+  });
+
+  res.status(201).json({ ok: true });
+});
+```
+
+## Safe Example
+
+```ts
+import rateLimit from "express-rate-limit";
+
+const publicWriteLimiter = rateLimit({
+  windowMs: 10 * 60 * 1000,
+  max: 20,
+  message: { error: "Too many submissions. Please retry later." },
+  standardHeaders: true,
+  legacyHeaders: false
+});
+
+app.post("/api/contact", publicWriteLimiter, async (req, res) => {
+  if (!req.body.captchaToken || !(await captcha.verify(req.body.captchaToken))) {
+    return res.status(400).json({ error: "Bot challenge failed" });
+  }
+
+  await db.contactMessage.create({
+    data: { email: req.body.email, message: req.body.message }
+  });
+  res.status(201).json({ ok: true });
+});
+```
+
+## Remediation
+
+1. Inventory all anonymous or pre-auth write endpoints.
+2. Add route-specific rate limits with lower thresholds than authenticated APIs.
+3. Add anti-automation controls (CAPTCHA, proof-of-work, or managed bot defense).
+4. Deduplicate repeated payloads to reduce spam amplification.
+5. Gate downstream expensive actions (email, SMS, AI calls) with quotas.
+6. Enforce signed webhooks where feasible and rate-limit unsigned traffic heavily.
+7. Add abuse monitoring dashboards for submission spikes and block decisions.
+8. Define an incident playbook for emergency tightening of public write limits.
+
+## Verification
+
+- Send more than allowed form submissions and confirm throttling responses.
+- Confirm bot challenge is required and invalid tokens are rejected.
+- Verify normal user submission paths remain functional.
+- Test downstream providers are not called when requests are throttled.
+- Review logs to ensure abuse signals are observable and actionable.
+
+## False Positives and Exceptions
+
+- Endpoint is private behind VPN and not internet-reachable
+- Strict gateway quota exists with documented ownership and alerts
+- Endpoint is read-mostly and mislabeled as write by route naming only
+- Temporary load-test bypass with approved window and post-test rollback
+
+## Related Rules
+
+- `TG-RATE-001-unlimited-auth-endpoint.md`
+- `TG-RATE-003-unbounded-resource-consumption.md`
+- `TG-INPUT-001-missing-server-validation.md`
+- `TG-INPUT-004-unrestricted-file-upload.md`

package/.torusguard/rules/TG-RATE-003-unbounded-resource-consumption.md

@@ -0,0 +1,105 @@
+# TG-RATE-003: Unbounded Resource Consumption
+
+## Severity
+
+High
+
+## Applies To
+
+- Search and reporting endpoints with user-controlled pagination or filters
+- File generation/export endpoints (CSV, PDF, ZIP)
+- Media processing, image transforms, and AI inference routes
+- Query parameters controlling recursion depth, fan-out, or batch size
+- Any endpoint that triggers heavy DB, CPU, memory, or outbound calls
+
+## Why It Matters
+
+Not all abuse is about raw request count.
+A single request can be dangerously expensive when workload is unbounded.
+Attackers can force large scans, huge responses, or runaway processing jobs.
+This can produce denial-of-service and significant infrastructure cost.
+Legitimate users also suffer from latency and instability during abuse events.
+
+## What TorusGuard Looks For
+
+- Missing upper bounds on `limit`, `pageSize`, `depth`, `expand`, or `batchSize`
+- Export endpoints that allow entire dataset extraction in one request
+- Image/AI endpoints with unrestricted dimensions, duration, or token budgets
+- No request timeouts, execution budgets, or cancellation support
+- DB queries lacking pagination while returning client-controlled result sizes
+- Loops over user-provided ranges without hard caps
+
+## Unsafe Example
+
+```ts
+app.get("/api/reports/users", async (req, res) => {
+  const limit = Number(req.query.limit ?? 1000);
+  const users = await db.user.findMany({
+    where: { active: true },
+    take: limit
+  });
+  res.json({ users });
+});
+
+app.post("/api/export", async (req, res) => {
+  const rows = await db.orders.findMany(); // full table scan/export
+  const csv = await toCsv(rows);
+  res.type("text/csv").send(csv);
+});
+```
+
+## Safe Example
+
+```ts
+const MAX_REPORT_LIMIT = 100;
+const MAX_EXPORT_ROWS = 5000;
+
+app.get("/api/reports/users", async (req, res) => {
+  const requested = Number(req.query.limit ?? 25);
+  const limit = Math.min(Math.max(requested, 1), MAX_REPORT_LIMIT);
+  const users = await db.user.findMany({
+    where: { active: true },
+    take: limit
+  });
+  res.json({ users, limit });
+});
+
+app.post("/api/export", async (req, res) => {
+  const rows = await db.orders.findMany({ take: MAX_EXPORT_ROWS });
+  const csv = await toCsv(rows);
+  res.type("text/csv").send(csv);
+});
+```
+
+## Remediation
+
+1. Define explicit upper bounds for all user-controlled workload parameters.
+2. Clamp values server-side even when frontend already validates inputs.
+3. Require pagination for list endpoints and deny unbounded bulk reads.
+4. Add compute and execution guardrails (timeouts, cancellation, queue budgets).
+5. Cap export size and move large jobs to async pipelines with quotas.
+6. Set sane payload and response size thresholds per route type.
+7. Add observability for p95/p99 cost, timeout, and reject rates by endpoint.
+8. Load-test abuse scenarios and tune bounds before production rollout.
+
+## Verification
+
+- Request extreme `limit`/`depth` values and verify clamping behavior.
+- Confirm oversized exports are blocked or converted to queued async jobs.
+- Measure endpoint latency under stress and verify no runaway degradation.
+- Validate timeout and cancellation behavior for long-running workloads.
+- Ensure alerting fires when expensive request patterns spike.
+
+## False Positives and Exceptions
+
+- Internal analytics jobs running on private networks with dedicated quotas
+- One-off administrative endpoints gated by strong auth and network controls
+- Batch endpoints with strict signed-client access and audited operator use
+- Synthetic benchmarks intentionally disabling caps in isolated environments
+
+## Related Rules
+
+- `TG-RATE-001-unlimited-auth-endpoint.md`
+- `TG-RATE-002-unlimited-public-write-endpoint.md`
+- `TG-PLATFORM-004-missing-request-size-limits.md`
+- `TG-INPUT-001-missing-server-validation.md`