torusguard 1.0.0 → 1.3.1

package/.torusguard/rules/active/TG-DB-004-missing-tenant-query-isolation.md

@@ -0,0 +1,103 @@
+---
+id: TG-DB-004
+title: Missing Tenant Query Isolation in Multi-Tenant Models
+category: data-access-orm
+severity: Critical
+confidence: Confirmed
+frameworks:
+  - django
+  - drf
+  - fastapi
+  - flask
+  - sqlalchemy
+cwe: CWE-284
+asvs_v4: V4.1.3
+nist_ssdf: PW.5.1
+---
+
+# TG-DB-004: Missing Tenant Query Isolation in Multi-Tenant Models
+
+## 🚨 Problem Statement
+Applications built on a multi-tenant architecture often fail to scope database lookups (`SELECT`, `UPDATE`, `DELETE`) by the current authenticated tenant. Allowing a direct primary key (ID) lookup without a composite tenant filter allows Insecure Direct Object Reference (IDOR) attacks, enabling users to access or modify data belonging to other tenants.
+
+> **Tuning Guardrails (v0.5.6):**
+> - **DO NOT flag** every primary-key lookup.
+> - **ESCALATE** when tenant-owned data can be loaded or modified without a verified tenant scope.
+> - **DETECT** established tenant-scoped managers, repositories, `get_queryset()`, dependency injection, or parent-resource ownership checks.
+> - **MARK** complex multi-layer scope flows as `Needs Review` instead of `Confirmed` when source-only proof is inadequate.
+
+---
+
+## 💥 Adversarial Threat & Exploitation
+An attacker from Tenant B supplies the record UUID of a confidential document belonging to Tenant A:
+```http
+GET /api/v1/invoices/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d HTTP/1.1
+Host: saas.example.com
+Authorization: Bearer <Tenant_B_JWT>
+```
+If the backend performs `session.get(Invoice, invoice_id)` or `Invoice.objects.get(id=invoice_id)` without scoping to `tenant_id=current_user.tenant_id`, the invoice belonging to Tenant A is returned to the attacker.
+
+---
+
+## 🛠️ Framework-Native Remediations
+
+### 🐍 SQLAlchemy (Scoped Tenant Queries)
+
+#### ❌ Unsafe Pattern
+```python
+# Unsafe: Global primary key lookup without tenant filter
+@app.get("/invoices/{invoice_id}")
+def get_invoice(invoice_id: str, db: Session = Depends(get_db), user: User = Depends(get_current_user)):
+    invoice = db.query(Invoice).filter(Invoice.id == invoice_id).first()
+    if not invoice:
+        raise HTTPException(status_code=404, detail="Invoice not found")
+    return invoice
+```
+
+#### ✅ Safe Remediation
+```python
+# Safe: Enforce tenant scoping on every query filter
+@app.get("/invoices/{invoice_id}")
+def get_invoice(invoice_id: str, db: Session = Depends(get_db), user: User = Depends(get_current_user)):
+    invoice = (
+        db.query(Invoice)
+        .filter(Invoice.id == invoice_id, Invoice.tenant_id == user.tenant_id)
+        .first()
+    )
+    if not invoice:
+        raise HTTPException(status_code=404, detail="Invoice not found")
+    return invoice
+```
+
+---
+
+### 🐍 Django ORM (Scoped Manager / ViewSet Queryset)
+
+#### ❌ Unsafe Pattern
+```python
+# Unsafe: Global queryset in DRF ViewSet
+class InvoiceViewSet(viewsets.ModelViewSet):
+    queryset = Invoice.objects.all()  # Exposes all tenant records
+    serializer_class = InvoiceSerializer
+```
+
+#### ✅ Safe Remediation
+```python
+# Safe: Override get_queryset to enforce tenant boundary on every request
+class InvoiceViewSet(viewsets.ModelViewSet):
+    serializer_class = InvoiceSerializer
+    permission_classes = [permissions.IsAuthenticated]
+
+    def get_queryset(self):
+        # Strictly scope lookups to authenticated user's organization
+        return Invoice.objects.filter(tenant=self.request.user.tenant)
+```
+
+---
+
+## 🧪 Verification & Reproduction
+1. Send request with valid Tenant B token requesting Tenant A resource ID:
+   ```bash
+   curl -H "Authorization: Bearer <Tenant_B_Token>" http://localhost:8000/invoices/<Tenant_A_UUID>
+   ```
+2. **Assertion:** Request must return `404 Not Found`, denying access to cross-tenant data.

package/.torusguard/rules/active/TG-INPUT-001-missing-server-validation.md

@@ -0,0 +1,98 @@
+# TG-INPUT-001: Missing Server-Side Validation
+
+## Severity
+High
+
+## Applies To
+- REST and GraphQL API handlers
+- Form-processing backend endpoints
+- Message queue consumers that accept external payloads
+- Admin/import endpoints that trust UI validation
+
+## Why It Matters
+Client-side checks are easy to bypass because attackers can send crafted requests directly to backend endpoints.
+When the server does not validate required fields, data type, length, format, range, and allowed values, malicious input can trigger account takeover paths, integrity failures, and downstream injection vulnerabilities.
+Server-side validation is also required to keep business rules enforceable when multiple clients, scripts, and integrations call the same APIs.
+
+## What TorusGuard Looks For
+- Request data read from `req.body`, `req.query`, `req.params`, headers, or raw payloads without schema validation.
+- Validation done only in frontend files while backend endpoint accepts the same fields blindly.
+- Direct persistence of user-provided objects with broad spread operators.
+- Type coercion and fallback logic that silently accepts invalid values.
+- Missing allowlists for enum-like fields such as role, status, country code, or operation type.
+
+## Unsafe Example
+```js
+// Express route that trusts client validation
+app.post("/api/profile", async (req, res) => {
+  const { displayName, age, newsletter, role } = req.body;
+
+  // No server-side validation:
+  // - displayName could be extremely long or contain control chars
+  // - age could be negative or non-numeric
+  // - newsletter could be arbitrary string
+  // - role could be escalated to "admin"
+  const updated = await db.user.update({
+    where: { id: req.user.id },
+    data: { displayName, age, newsletter, role }
+  });
+
+  res.json({ ok: true, user: updated });
+});
+```
+
+## Safe Example
+```js
+import { z } from "zod";
+
+const updateProfileSchema = z.object({
+  displayName: z.string().min(2).max(60).regex(/^[a-zA-Z0-9 _.-]+$/),
+  age: z.number().int().min(13).max(120),
+  newsletter: z.boolean(),
+  role: z.enum(["user"]) // client cannot self-assign privileged roles
+});
+
+app.post("/api/profile", async (req, res) => {
+  const parsed = updateProfileSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(400).json({
+      ok: false,
+      error: "Invalid input",
+      details: parsed.error.issues
+    });
+  }
+
+  const { displayName, age, newsletter } = parsed.data;
+  const updated = await db.user.update({
+    where: { id: req.user.id },
+    data: { displayName, age, newsletter }
+  });
+
+  res.json({ ok: true, user: updated });
+});
+```
+
+## Remediation
+1. Define strict server-side schemas for every externally reachable input surface.
+2. Validate before business logic, authorization decisions, and database writes.
+3. Enforce field allowlists; reject unexpected keys rather than silently ignoring them.
+4. Apply normalization after validation (trim, case-fold, canonical forms) where needed.
+5. Centralize reusable validators for shared payloads to prevent drift across endpoints.
+6. Return clear but non-sensitive validation errors, and log rejection metrics for monitoring.
+
+## Verification
+- Send malformed payloads directly with `curl` or API clients, bypassing the web UI.
+- Confirm invalid types, out-of-range values, and unknown fields return `400`.
+- Attempt privilege-related field tampering and verify values are rejected or ignored safely.
+- Run integration tests covering boundary values and negative cases.
+- Ensure validation runs for all entry paths, including batch/import and background worker routes.
+
+## False Positives and Exceptions
+- Internal service-to-service endpoints may appear unvalidated but can be acceptable if strong contract validation is enforced at the gateway and mutual trust boundaries are documented.
+- Auto-generated API frameworks sometimes perform implicit validation; keep explicit schema definitions for auditability.
+- Legacy endpoints under migration can be temporarily exempted only with compensating controls and a tracked deprecation timeline.
+
+## Related Rules
+- [TG-INPUT-002](./TG-INPUT-002-raw-sql-concatenation.md)
+- [TG-INPUT-003](./TG-INPUT-003-unsafe-html-or-code-execution.md)
+- [TG-AUTH-003](./TG-AUTH-003-missing-object-authorization.md)

package/.torusguard/rules/active/TG-INPUT-002-raw-sql-concatenation.md

@@ -0,0 +1,94 @@
+# TG-INPUT-002: Raw SQL Concatenation
+
+## Severity
+Critical
+
+## Applies To
+- Backend services that execute SQL queries
+- Scripts and cron jobs that build dynamic SQL
+- Data export/reporting endpoints with filters and sorting
+- Administrative tooling with direct database access
+
+## Why It Matters
+Concatenating untrusted input into SQL statements allows SQL injection, one of the highest-impact application vulnerabilities.
+Successful exploitation can expose sensitive records, bypass authentication checks, modify or delete data, and in some environments execute database-level administrative operations.
+Even read-only endpoints can become a pivot for full data exfiltration when query construction is unsafe.
+
+## What TorusGuard Looks For
+- String interpolation or concatenation inside SQL query text using request-derived data.
+- Dynamic `WHERE`, `ORDER BY`, `LIMIT`, or table-name fragments assembled from raw user input.
+- Use of low-level query APIs without bind parameters.
+- Sanitization-only approaches (replace/escape) used instead of parameterization.
+- Unsafe helper functions that return query strings rather than query templates plus values.
+
+## Unsafe Example
+```js
+app.get("/api/orders", async (req, res) => {
+  const customerId = req.query.customerId;
+  const sort = req.query.sort || "created_at DESC";
+
+  // Both customerId and sort are attacker-controlled
+  const sql =
+    "SELECT id, total, created_at FROM orders " +
+    "WHERE customer_id = '" + customerId + "' " +
+    "ORDER BY " + sort;
+
+  const rows = await db.query(sql);
+  res.json({ ok: true, orders: rows });
+});
+```
+
+## Safe Example
+```js
+const SORT_COLUMNS = new Map([
+  ["newest", "created_at DESC"],
+  ["oldest", "created_at ASC"],
+  ["total_high", "total DESC"],
+  ["total_low", "total ASC"]
+]);
+
+app.get("/api/orders", async (req, res) => {
+  const customerId = String(req.query.customerId || "");
+  const sortKey = String(req.query.sort || "newest");
+  const sortSql = SORT_COLUMNS.get(sortKey);
+
+  if (!sortSql || !/^[a-f0-9-]{36}$/.test(customerId)) {
+    return res.status(400).json({ ok: false, error: "Invalid query parameters" });
+  }
+
+  const sql = `
+    SELECT id, total, created_at
+    FROM orders
+    WHERE customer_id = $1
+    ORDER BY ${sortSql}
+  `;
+
+  const rows = await db.query(sql, [customerId]);
+  res.json({ ok: true, orders: rows });
+});
+```
+
+## Remediation
+1. Replace all string-built SQL with parameterized queries or prepared statements.
+2. Bind user input as values, never as SQL syntax fragments.
+3. For dynamic sorting/filtering, map user options to fixed allowlisted SQL snippets.
+4. Restrict database account privileges to least privilege to reduce blast radius.
+5. Add static analysis and code review checks that ban raw concatenated SQL.
+6. Cover injection payloads in automated tests for every query endpoint.
+
+## Verification
+- Search for query construction using template interpolation with request variables.
+- Attempt payloads such as `' OR '1'='1` and confirm they are treated as literal values.
+- Verify sort/filter options accept only predefined keys.
+- Review database logs for rejected malformed statements and suspicious patterns.
+- Confirm all DB access layers support parameter binding and are consistently used.
+
+## False Positives and Exceptions
+- Hardcoded SQL strings with no untrusted input are generally safe.
+- Migration files may contain dynamic SQL for schema operations; these are acceptable if not user-influenced.
+- Internal ETL code can still be vulnerable if source data is not trusted; do not auto-exempt.
+
+## Related Rules
+- [TG-INPUT-001](./TG-INPUT-001-missing-server-validation.md)
+- [TG-INPUT-003](./TG-INPUT-003-unsafe-html-or-code-execution.md)
+- [TG-AUTH-003](./TG-AUTH-003-missing-object-authorization.md)

package/.torusguard/rules/active/TG-INPUT-003-unsafe-html-or-code-execution.md

@@ -0,0 +1,102 @@
+# TG-INPUT-003: Unsafe HTML Rendering or Code Execution
+
+## Severity
+High
+
+## Applies To
+- Server-side rendering pipelines
+- Rich text/comment rendering features
+- Template engines and markdown-to-HTML converters
+- Dynamic expression evaluators and script execution utilities
+
+## Why It Matters
+When untrusted content is rendered as HTML without sanitization, attackers can inject scripts and trigger stored or reflected XSS.
+When untrusted input reaches evaluators such as `eval`, `Function`, or shell execution helpers, remote code execution and server compromise become possible.
+These flaws frequently lead to session theft, account takeover, and full application compromise.
+
+## What TorusGuard Looks For
+- Use of dangerous rendering APIs such as `innerHTML`, `dangerouslySetInnerHTML`, or unsanitized template output.
+- Markdown or rich text conversion with unsafe options enabled.
+- Invocation of `eval`, `new Function`, VM contexts, or command execution with user-controlled fragments.
+- Security filters that rely only on regex stripping of script tags.
+- User content stored and later rendered in privileged admin views.
+
+## Unsafe Example
+```js
+app.post("/api/notes/preview", (req, res) => {
+  const body = req.body.content;
+
+  // Stored then rendered unsafely
+  const html = `<article>${body}</article>`;
+  res.send(html);
+});
+
+app.post("/api/calc", (req, res) => {
+  const expression = req.body.expression;
+
+  // User controls executed code
+  const result = eval(expression);
+  res.json({ ok: true, result });
+});
+```
+
+## Safe Example
+```js
+import sanitizeHtml from "sanitize-html";
+
+app.post("/api/notes/preview", (req, res) => {
+  const content = String(req.body.content || "");
+  const safe = sanitizeHtml(content, {
+    allowedTags: ["p", "b", "i", "strong", "em", "ul", "ol", "li", "a", "code", "pre"],
+    allowedAttributes: { a: ["href", "title"] },
+    allowedSchemes: ["http", "https", "mailto"]
+  });
+
+  res.send(`<article>${safe}</article>`);
+});
+
+app.post("/api/calc", (req, res) => {
+  const op = String(req.body.op || "");
+  const left = Number(req.body.left);
+  const right = Number(req.body.right);
+
+  if (!Number.isFinite(left) || !Number.isFinite(right)) {
+    return res.status(400).json({ ok: false, error: "Invalid numeric input" });
+  }
+
+  const operations = {
+    add: (a, b) => a + b,
+    sub: (a, b) => a - b,
+    mul: (a, b) => a * b,
+    div: (a, b) => (b === 0 ? null : a / b)
+  };
+
+  if (!operations[op]) return res.status(400).json({ ok: false, error: "Unsupported operation" });
+  res.json({ ok: true, result: operations[op](left, right) });
+});
+```
+
+## Remediation
+1. Treat all user-controlled text as untrusted until sanitized for the target context.
+2. Use maintained HTML sanitizers with explicit allowlists for tags and attributes.
+3. Ban runtime code execution functions (`eval`, `Function`, shell interpolation) in request paths.
+4. Replace expression execution with constrained allowlisted operations.
+5. Enforce contextual output encoding in templates and frontend rendering layers.
+6. Add CSP and defense-in-depth controls, but do not treat them as primary mitigation.
+
+## Verification
+- Submit payloads containing event handlers, script tags, and `javascript:` URLs.
+- Confirm rendered output strips unsafe elements and attributes.
+- Attempt expression payloads like `process.env` and verify they are rejected.
+- Run security tests for stored and reflected rendering flows, including admin pages.
+- Ensure static analysis flags prohibited runtime execution APIs.
+
+## False Positives and Exceptions
+- Trusted, static CMS content curated by privileged staff may allow richer HTML if isolated and sanitized by policy.
+- Template literals are not inherently unsafe; only sinks that interpret HTML/code create risk.
+- Sandboxed code execution environments still require strict resource and capability restrictions.
+
+## Related Rules
+- [TG-INPUT-001](./TG-INPUT-001-missing-server-validation.md)
+- [TG-INPUT-002](./TG-INPUT-002-raw-sql-concatenation.md)
+- [TG-AUTH-004](./TG-AUTH-004-insecure-session-cookie.md)

package/.torusguard/rules/active/TG-INPUT-004-unrestricted-file-upload.md

@@ -0,0 +1,92 @@
+# TG-INPUT-004: Unrestricted File Upload
+
+## Severity
+High
+
+## Applies To
+- Profile avatar and document upload endpoints
+- Media management APIs and admin upload tools
+- Import features that accept archives or spreadsheets
+- Object storage presigned upload workflows
+
+## Why It Matters
+Unrestricted uploads let attackers store executable scripts, malware, oversized payloads, and deceptive file types.
+If uploaded files are publicly accessible or processed unsafely, attackers can trigger XSS, remote code execution, SSRF through parsers, or storage exhaustion denial of service.
+Weak upload controls also create legal and compliance risk when sensitive content is mishandled.
+
+## What TorusGuard Looks For
+- Acceptance based only on filename extension or client-provided MIME type.
+- Missing maximum file size, count, or rate limits.
+- Uploading directly to web-served directories without safe naming.
+- Lack of malware scanning or content-type verification by signature.
+- Processing of complex formats without sandboxing and strict parser limits.
+
+## Unsafe Example
+```js
+app.post("/api/upload", upload.single("file"), async (req, res) => {
+  const file = req.file;
+
+  // Trusts original name and MIME from client
+  const destination = path.join(__dirname, "public/uploads", file.originalname);
+  await fs.promises.writeFile(destination, file.buffer);
+
+  // Public URL serves whatever was uploaded
+  res.json({ ok: true, url: `/uploads/${file.originalname}` });
+});
+```
+
+## Safe Example
+```js
+import crypto from "crypto";
+import FileType from "file-type";
+
+const MAX_SIZE = 5 * 1024 * 1024;
+const ALLOWED = new Set(["image/png", "image/jpeg", "application/pdf"]);
+
+app.post("/api/upload", upload.single("file"), async (req, res) => {
+  const file = req.file;
+  if (!file || file.size > MAX_SIZE) {
+    return res.status(400).json({ ok: false, error: "Invalid file size" });
+  }
+
+  const detected = await FileType.fromBuffer(file.buffer);
+  const mime = detected?.mime || "";
+  if (!ALLOWED.has(mime)) {
+    return res.status(400).json({ ok: false, error: "Unsupported file type" });
+  }
+
+  const extension = mime === "image/png" ? "png" : mime === "image/jpeg" ? "jpg" : "pdf";
+  const storedName = `${crypto.randomUUID()}.${extension}`;
+  const storagePath = path.join(__dirname, "private_uploads", storedName);
+
+  await fs.promises.writeFile(storagePath, file.buffer, { mode: 0o600 });
+  await queueForMalwareScan(storagePath);
+
+  res.json({ ok: true, fileId: storedName });
+});
+```
+
+## Remediation
+1. Enforce strict allowlists for file type, extension, and verified signature/MIME.
+2. Set max size, max count, and upload rate limits per user and per endpoint.
+3. Store files outside web root with generated names, never original filenames.
+4. Scan uploaded content with malware detection before making files retrievable.
+5. Re-validate file safety at retrieval and transformation points (thumbnailing, OCR, parsing).
+6. Use presigned uploads with constrained policies and short expirations where applicable.
+
+## Verification
+- Upload files with double extensions (`.jpg.php`) and mismatched MIME signatures.
+- Attempt oversized and high-frequency uploads to validate throttling and limits.
+- Confirm stored filenames are non-guessable and not user-controlled.
+- Verify uploaded objects cannot be executed as active content by browsers.
+- Ensure parser pipelines reject malformed archives and nested compression bombs.
+
+## False Positives and Exceptions
+- Internal-only transfer channels with signed artifacts may permit broader file types, but must still enforce size and scanning controls.
+- Some media pipelines rely on asynchronous scanning; temporary quarantine states are acceptable with blocked access until scan completion.
+- Legacy endpoints may need phased migration, but unrestricted direct serving is not acceptable long term.
+
+## Related Rules
+- [TG-INPUT-001](./TG-INPUT-001-missing-server-validation.md)
+- [TG-INPUT-003](./TG-INPUT-003-unsafe-html-or-code-execution.md)
+- [TG-AUTH-004](./TG-AUTH-004-insecure-session-cookie.md)

package/.torusguard/rules/active/TG-INPUT-005-unsafe-template-rendering-and-escaping.md

@@ -0,0 +1,102 @@
+---
+id: TG-INPUT-005
+title: Unsafe Template Rendering & Disabled Autoescaping
+category: input-validation-encoding
+severity: High
+confidence: Confirmed
+frameworks:
+  - django
+  - flask
+  - fastapi
+cwe: CWE-79
+asvs_v4: V5.3.3
+nist_ssdf: PW.5.1
+---
+
+# TG-INPUT-005: Unsafe Template Rendering & Disabled Autoescaping
+
+## 🚨 Problem Statement
+Rendering user-controlled input directly into templates without context-aware escaping (e.g., using `render_template_string` or explicitly disabling escaping with `|safe` or `mark_safe`) allows attackers to inject malicious HTML, JavaScript, or server-side template directives.
+
+> **Tuning Guardrails (v0.5.6):**
+> - **DISTINGUISH** direct unsafe rendering from framework-managed autoescaped template rendering (e.g., passing context variables to `render_template("foo.html", var=x)`).
+> - **DO NOT flag** safe templating utilities or correctly escaped output paths.
+> - **FLAG ONLY** when unsafe rendering, disabled escaping, `mark_safe`, `|safe`, or dynamic template execution is materially relevant.
+
+---
+
+## 💥 Adversarial Threat & Exploitation
+1. **Server-Side Template Injection (Flask / Jinja2):**
+   ```python
+   # Unsafe Flask SSTI
+   @app.route("/greet")
+   def greet():
+       name = request.args.get("name")
+       template = f"<h1>Hello {name}</h1>"
+       return render_template_string(template)  # RCE via {{ 7*7 }} or {{ config.__class__... }}
+   ```
+2. **Cross-Site Scripting (Django / Jinja2):**
+   ```python
+   # Unsafe Django mark_safe
+   from django.utils.safestring import mark_safe
+
+   def comment_view(request):
+       user_comment = request.POST.get("comment")
+       # Bypasses HTML escaping
+       html_output = mark_safe(f"<div class='comment'>{user_comment}</div>")
+       return HttpResponse(html_output)
+   ```
+
+---
+
+## 🛠️ Framework-Native Remediations
+
+### 🐍 Flask / Jinja2 (Safe Parameter Passing)
+
+#### ❌ Unsafe Pattern
+```python
+# Unsafe: Concatenating input into template string
+return render_template_string(f"Hello {user_input}")
+```
+
+#### ✅ Safe Remediation
+```python
+# Safe: Pass input as context variable to autoescaped template file
+from flask import render_template
+
+@app.route("/greet")
+def greet():
+    name = request.args.get("name", "")
+    return render_template("greet.html", name=name)  # Automatically HTML-escaped by Jinja2
+```
+
+---
+
+### 🐍 Django (Template Context & `format_html`)
+
+#### ❌ Unsafe Pattern
+```python
+# Unsafe: mark_safe on unescaped input string
+return HttpResponse(mark_safe(f"<b>Welcome, {username}</b>"))
+```
+
+#### ✅ Safe Remediation
+```python
+# Safe: Use format_html for conditional safe markup with autoescaped arguments
+from django.utils.html import format_html
+
+def welcome_view(request):
+    username = request.GET.get("username", "")
+    # format_html escapes variables while preserving the fixed HTML wrapper
+    safe_markup = format_html("<b>Welcome, {}</b>", username)
+    return HttpResponse(safe_markup)
+```
+
+---
+
+## 🧪 Verification & Reproduction
+1. Submit XSS payload:
+   ```bash
+   curl "http://localhost:5000/greet?name=%3Cscript%3Ealert(1)%3C/script%3E"
+   ```
+2. **Assertion:** Response body must contain HTML entity encoded characters (`&lt;script&gt;alert(1)&lt;/script&gt;`) and must NOT execute raw tags.