torusguard 0.9.2

package/.torusguard/references/supabase-security.md

@@ -0,0 +1,84 @@
+# Supabase Security Guide
+
+## When to use
+
+Load during audits of applications using Supabase Auth, Database, or Storage.
+
+**Related rules:** TG-DB-002, TG-DB-003, TG-AUTH-003, TG-SEC-002
+
+## Key distinction
+
+| Key | Where | Purpose |
+|-----|-------|---------|
+| **anon (public) key** | Browser OK | Client SDK with RLS enforced |
+| **service-role key** | Server only | Bypasses RLS — never in frontend |
+
+Violating this mapping triggers TG-DB-002 (Critical) and TG-DB-003 (Critical).
+
+## Checklist
+
+- [ ] Service-role key only in server/edge functions
+- [ ] RLS enabled on every table exposed to client
+- [ ] Policies verify `auth.uid()` ownership or role
+- [ ] Storage bucket policies restrict read/write by user
+- [ ] No sensitive logic relying only on client-side filters
+- [ ] Server-only admin actions use service-role in trusted environment
+
+## Browser client (safe)
+
+```javascript
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_ANON_KEY
+);
+```
+
+## Server admin (safe)
+
+```javascript
+// server/admin.js — never import in client bundle
+import { createClient } from '@supabase/supabase-js';
+
+const admin = createClient(
+  process.env.SUPABASE_URL,
+  process.env.SUPABASE_SERVICE_ROLE_KEY
+);
+```
+
+## RLS policy example
+
+```sql
+ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Users read own profile"
+  ON profiles FOR SELECT
+  USING (auth.uid() = user_id);
+
+CREATE POLICY "Users update own profile"
+  ON profiles FOR UPDATE
+  USING (auth.uid() = user_id);
+```
+
+## Manual RLS review checklist
+
+For each table reachable from the browser:
+
+1. Is RLS enabled?
+2. Does SELECT policy prevent cross-user reads?
+3. Do INSERT/UPDATE/DELETE policies verify ownership?
+4. Are admin-only tables blocked for anon/authenticated roles?
+5. Test with two user sessions — User A must not read User B rows
+
+Document review date in project `SECURITY.md`.
+
+## Storage
+
+Apply bucket policies mirroring database ownership. Do not use public buckets for private user files without signed URL strategy.
+
+## Related documentation
+
+- [rules/TG-DB-002-privileged-database-credential.md](../rules/TG-DB-002-privileged-database-credential.md)
+- [rules/TG-DB-003-frontend-admin-sdk.md](../rules/TG-DB-003-frontend-admin-sdk.md)
+- [skills/TorusGuard/references/frontend-no-db.md](../skills/TorusGuard/references/frontend-no-db.md)

package/.torusguard/rules/README.md

@@ -0,0 +1,62 @@
+# TorusGuard Security Rule Catalog & Activation System
+
+This directory manages the active and custom security rules enforced by TorusGuard.
+
+---
+
+## 1. Rule Architecture & Taxonomy
+
+TorusGuard security rules follow a canonical identifier pattern: `TG-<CATEGORY>-<NUMBER>`.
+
+| Category Prefix | Domain Area | Focus & Vulnerability Classes |
+| :--- | :--- | :--- |
+| `TG-AUTH` | Authentication & Authorization | Missing tenant scoping, client-only route guards, session cookie flags, insecure password resets |
+| `TG-INPUT` | Input Validation & Injection | SQL injection, unsafe HTML/template rendering, unvalidated file uploads, path traversal |
+| `TG-SEC` | Secrets & Configuration | Hardcoded API keys, tracked `.env` files, sensitive logging, exposed cloud credentials |
+| `TG-DB` | Database & ORM Security | Frontend direct DB access, admin SDK exposure, missing multi-tenant query isolation |
+| `TG-CLIENT` | Frontend & Client Bundles | Public production source maps, sensitive secrets embedded in client build assets |
+| `TG-RATE` | Rate Limiting & Resource Abuse | Unlimited auth endpoints, unbounded pagination, excessive resource consumption |
+| `TG-PLATFORM` | Platform & Gateway Hardening | Wildcard CORS with credentials, missing security headers, exposed stack traces |
+| `TG-SSRF` | Outbound Requests & SSRF | Unvalidated HTTP client destinations, metadata IP access, internal network probing |
+| `TG-SUPPLY` | Dependency & Supply Chain | Unpinned dependencies, known CVEs, malicious dependency confusion risks |
+
+---
+
+## 2. Active Rules System (`rules/active/`)
+
+When you run `/torusguard init`, TorusGuard automatically inspects your project stack and activates relevant rules in `rules/active/`.
+
+- **Universal Rules:** Always activated (`TG-SEC-*`, `TG-INPUT-*`, `TG-AUTH-*`).
+- **Framework-Specific Rules:**
+  - Python / Django: `TG-DB-004`, `TG-RATE-001`, `TG-PLATFORM-*`.
+  - Next.js / React: `TG-CLIENT-*`, `TG-PLATFORM-001`, `TG-AUTH-002`.
+  - API / Node.js: `TG-INPUT-001`, `TG-SSRF-001`, `TG-RATE-002`.
+
+---
+
+## 3. Creating Custom Rules
+
+You can add custom rules directly into this directory or configure a custom path in `.torusguard/config/torusguard.json`:
+
+```markdown
+# TG-CUSTOM-001: Require Organization UUID on All Tenant Queries
+
+**Severity:** High  
+**Category:** authentication-authorization  
+**Confidence Base:** 80  
+
+### Vulnerability Pattern
+Ensure every database query on multi-tenant models filters explicitly by `org_id` or `tenant_id`.
+
+### Unsafe Pattern
+```python
+# Unsafe: Queries tenant data globally without org predicate
+TenantRecord.objects.filter(status="active")
+```
+
+### Safe Pattern
+```python
+# Safe: Scoped to requesting organization
+TenantRecord.objects.filter(org_id=request.user.org_id, status="active")
+```
+```

package/.torusguard/rules/TORUSGUARD.md

@@ -0,0 +1,145 @@
+---
+trigger: always_on
+---
+
+# TorusGuard — Master Security Rules & Governance
+
+These rules are always active when TorusGuard is installed in the workspace.
+Every security command, every code audit, every runtime probe, and every remediation patch must strictly comply.
+
+**Core principle:** If the browser receives it, users can inspect it. Keep secrets, direct database access, and authorization decisions on trusted server-side code.
+
+---
+
+## Step 0 — Security Pre-Flight (Before Everything)
+
+Before taking any action or running any `/torusguard` command, enforce this cognitive gate:
+
+### 0a. Scope & Authorization Gate
+```
+Is the action purely static (read code, analyze ASTs, review configuration)?
+  → Permitted without authorization.md.
+Does the action interact with a running application or network endpoint?
+  → MANDATORY CHECK: Verify .torusguard/config/scope.json exists and contains:
+      - valid target hostname/IP
+      - explicit owner_confirmed: true
+      - unexpired duration_hours
+  → If missing or unconfirmed: HALT. Prompt user to run `/torusguard authorize` first.
+```
+
+### 0b. Safety & Non-Destruction Gate
+```
+Is the probe payload destructive (DROP, DELETE, write loops, memory exhaustion)?
+  → STRICTLY FORBIDDEN. Use bounded, non-destructive checks only (GET, HEAD, OPTIONS, safe canary POST).
+Does any generated report or captured evidence contain raw API keys, bearer tokens, or database passwords?
+  → MANDATORY: Redact to [REDACTED_API_KEY] or sha256 prefix hash. Never write raw credentials to disk.
+```
+
+---
+
+## Step 1 — Command Routing Table
+
+When the user invokes any `/torusguard` slash command, route directly to its workflow:
+
+| Command | Lifecycle Phase | Primary Agent | Workflow Path | Modifies Code? |
+| :--- | :--- | :--- | :--- | :---: |
+| `/torusguard init` | Baseline Setup | `profiler` | `.torusguard/workflows/init.md` | ❌ No (Docs/Config only) |
+| `/torusguard authorize` | Legal Scope Gate | `reviewer` | `.torusguard/workflows/authorize.md` | ❌ No |
+| `/torusguard audit` | Detect & Cluster | `auditor` | `.torusguard/workflows/audit.md` | ❌ No |
+| `/torusguard verify` | Verify & Score | `validator` | `.torusguard/workflows/verify.md` | ❌ No |
+| `/torusguard web-validate` | Runtime Probing | `validator` | `.torusguard/workflows/web-validate.md` | ❌ No |
+| `/torusguard exploit-check` | Exploitability | `validator` | `.torusguard/workflows/exploit-check.md` | ❌ No |
+| `/torusguard harden` | Remediate Plan | `remediator` | `.torusguard/workflows/harden.md` | ❌ No (Plan only) |
+| `/torusguard apply` | Governed Apply | `remediator` | `.torusguard/workflows/apply.md` | ✅ Yes (Bounded) |
+| `/torusguard recheck` | Verification | `reviewer` | `.torusguard/workflows/recheck.md` | ❌ No |
+| `/torusguard report` | Export & SARIF | `reviewer` | `.torusguard/workflows/report.md` | ❌ No |
+| `/torusguard status` | Posture Check | *System* | `.torusguard/workflows/status.md` | ❌ No |
+
+---
+
+## Step 2 — Agent Role Routing
+
+Every TorusGuard operation activates a specialized role. Each role has strict behavioral boundaries:
+
+| Role | Specialist Agent | Domain & Focus | Files / Actions |
+| :--- | :--- | :--- | :--- |
+| **Profiler** | `.torusguard/agents/profiler.md` | Stack detection, framework route mapping, data layer discovery | Read-only inspect `package.json`, `manage.py`, `pyproject.toml` |
+| **Auditor** | `.torusguard/agents/auditor.md` | Static code analysis, rule matching, root-cause clustering | Read-only scan source files, assign stable finding IDs |
+| **Validator** | `.torusguard/agents/validator.md` | Authorized HTTP/browser probes, bounded exploitability confirmation | Execute authorized network probes, capture redacted traces |
+| **Remediator** | `.torusguard/agents/remediator.md` | Remediation bundles, minimal-churn patches, before/after diffs | Generate diffs; apply bounded patches (≤35 add / ≤25 del) |
+| **Reviewer** | `.torusguard/agents/reviewer.md` | Evidence review, regression detection, SARIF export, sign-off | Audit evidence quality, verify recheck results |
+
+**Role Announcement Rule:**
+When an agent activates, declare the role:
+```markdown
+🛡️ [TorusGuard] Applying knowledge of @[agent-role]...
+```
+
+---
+
+## Step 3 — Universal Safety & Governance Constraints
+
+### Non-Negotiable Operating Standards
+
+1. **Folder-Per-Run Isolation:**
+   - Every operation writes its artifacts into a dedicated folder under `.torusguard/runs/<run-id>/`.
+   - Never dump temporary logs, findings, or patches directly into the project root.
+2. **Patch Governance Limits (Ponytail Protocol):**
+   - Maximum lines added per bundle: **35 lines**.
+   - Maximum lines deleted per bundle: **25 lines**.
+   - If a fix exceeds these limits, break it into smaller atomic bundles or flag as `Requires Manual Architectural Refactor`.
+   - Never rewrite an entire file when a targeted edit suffices.
+   - Preserve all existing auth checks, tenant isolation, and logging.
+3. **No Unconfirmed High-Severity Assertions:**
+   - Never report a finding as `Confirmed` without an exact AST source code citation or deterministic runtime trace.
+   - If a route delegates auth to an internal middleware or domain service, score `< 50` and classify as `Needs Review`.
+4. **Credential Safety:**
+   - Never persist cleartext secrets, bearer tokens, passwords, or connection strings in logs or reports.
+   - Sanitize all curl commands and HTTP dumps.
+
+---
+
+## Step 4 — 0–100 Confidence Scoring Rubric
+
+TorusGuard scores finding confidence using an objective 5-factor scoring model (Max: 100 pts):
+
+| Factor | Max Pts | Criteria |
+| :--- | :---: | :--- |
+| **Evidence Quality** | 35 | Exact AST source match (35) · Regex/Heuristic pattern (20) · Indirect indicator (10) |
+| **Reproduction Success** | 25 | Deterministic test reproduction (25) · Partial reproduction (15) · Static only (0) |
+| **Independent Confirmations** | 15 | Corroborated across 3+ files (15) · 2 files (10) · Single occurrence (5) |
+| **Environmental Clarity** | 15 | Direct code route (15) · Minor layer ambiguity (8) · Complex proxy/lambda unknown (0) |
+| **Manual Review Status** | 10 | Security engineer verified (10) · Agent consensus verified (5) · Unreviewed (0) |
+
+**Classification Bands:**
+- `90–100`: 🔒 **`Confirmed`** (Indisputable proof; immediate patch required)
+- `70–89`: 🟢 **`High Confidence`** (Strong indicators; prioritized remediation)
+- `50–69`: 🟡 **`Medium Confidence`** (Probable flaw; runtime confirmation recommended)
+- `< 50`: 🔍 **`Needs Review`** (Architectural ambiguity; requires human confirmation)
+
+---
+
+## Step 5 — Human-First Output Standard
+
+Every generated security report must follow the card-style presentation:
+
+1. **Detected Stack Block:**
+   ```markdown
+   ## Detected Stack
+   - Language: Python / TypeScript
+   - Framework: FastAPI / Next.js / Django
+   - Data layer: SQLAlchemy / Prisma / Supabase
+   - Dependency files: pyproject.toml / package.json
+   - Detection confidence: Confirmed (manage.py:5)
+   ```
+2. **Executive Posture Indicator:**
+   - `🔴 Action Required` (Critical/High findings unmitigated)
+   - `🟡 Warnings Found` (Medium findings or unverified boundaries)
+   - `🟢 Ready` (All findings verified remediated and rechecked clean)
+3. **Finding Card Structure:**
+   - **Header:** `[TG-RULE-XXX] Title` with Severity & Confidence badges
+   - **Provenance Chain:** Discovery Rule → Triggering Input → Decision Path
+   - **Raw Evidence:** Exact code excerpt with line numbers and SHA-256 hash
+   - **Facts vs Interpretation:** Clearly separate verifiable facts from AI analysis
+   - **Remediation Diff:** Framework-native `Before / After` minimal patch
+   - **Retest Status:** Verification method and recheck outcome

package/.torusguard/rules/active/TG-DIFF-001.md

@@ -0,0 +1,20 @@
+---
+id: TG-DIFF-001
+name: Accidental Security Check Bypass in Patch
+severity: CRITICAL
+category: Patch Governance / Diff Safety
+cwe: CWE-693
+---
+
+# TG-DIFF-001: Accidental Security Check Bypass in Patch Additions
+
+## Summary
+Flags unified diff additions (`+`) that introduce bypass comments (`# bypass auth`, `// nosec`), disabled certificate checks (`verify=False`), or explicit bypass flags (`skip_auth=True`).
+
+## Detection Invariants
+- Additions containing comments: `bypass auth`, `skip security check`, `disable_token_check`.
+- Additions setting `verify=False` in network HTTP clients.
+- Additions disabling CSRF protection (`@csrf_exempt`).
+
+## Remediation
+Ensure security controls remain active in generated patches. Never disable certificate checks or bypass authentication barriers to make code pass tests.

package/.torusguard/rules/active/TG-DIFF-002.md

@@ -0,0 +1,20 @@
+---
+id: TG-DIFF-002
+name: Secret and Token Ingestion in Patch Additions
+severity: CRITICAL
+category: Patch Governance / Secret Exposure
+cwe: CWE-798
+---
+
+# TG-DIFF-002: Secret and Token Ingestion in Patch Additions
+
+## Summary
+Flags unified diff additions (`+`) that introduce hardcoded live API tokens, JWT strings, private key headers, or credentials into source files during remediation.
+
+## Detection Invariants
+- Additions containing regex patterns matching API keys (`sk_live_`, `ak_live_`).
+- Additions introducing raw Bearer JWT tokens (`eyJ...`).
+- Additions introducing private key blocks (`-----BEGIN PRIVATE KEY-----`).
+
+## Remediation
+Load credentials from environment variables (`os.environ["API_KEY"]` or `process.env.API_KEY`). Never hardcode secrets in remediation diffs.

package/.torusguard/rules/active/TG-DIFF-003.md

@@ -0,0 +1,19 @@
+---
+id: TG-DIFF-003
+name: Unintentional Removal of Tenant Filter in Patch Deletions
+severity: HIGH
+category: Patch Governance / Tenant Isolation
+cwe: CWE-284
+---
+
+# TG-DIFF-003: Unintentional Removal of Tenant Filter in Patch Deletions
+
+## Summary
+Flags unified diff deletions (`-`) where tenant isolation scoping queries (e.g. `.filter(tenant=...)` or `where tenant_id =`) are removed without being reinstated in the corresponding patch additions.
+
+## Detection Invariants
+- Deleted lines matching `.filter(tenant=` or `tenant_id =`.
+- Corresponding added lines omitting equivalent tenant parameter bindings.
+
+## Remediation
+Ensure multi-tenant database queries retain tenant boundary clauses across all refactorings and bug fixes.

package/.torusguard/schemas/authorization.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "TorusGuardAuthorizationScope",
+  "description": "Schema for TorusGuard v0.7.0 authorized runtime validation scope and legal boundaries.",
+  "type": "object",
+  "required": [
+    "authorization_id",
+    "target_name",
+    "authorized_by",
+    "target_hosts",
+    "allowed_path_prefixes",
+    "valid_from",
+    "valid_until",
+    "max_depth",
+    "allow_state_changing_methods"
+  ],
+  "properties": {
+    "authorization_id": {
+      "type": "string",
+      "pattern": "^AUTH-[A-Za-z0-9_-]+$"
+    },
+    "target_name": {
+      "type": "string"
+    },
+    "authorized_by": {
+      "type": "string"
+    },
+    "authorization_type": {
+      "type": "string",
+      "enum": ["target_owner", "written_authorization", "ci_sandboxed_test"]
+    },
+    "target_hosts": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "allowed_path_prefixes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "forbidden_paths": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "valid_from": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "valid_until": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "max_depth": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 10
+    },
+    "max_requests": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 500
+    },
+    "allow_state_changing_methods": {
+      "type": "boolean"
+    },
+    "allowed_issue_classes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/.torusguard/schemas/confidence.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://torusguard.dev/schemas/confidence.schema.json",
+  "title": "TorusGuardConfidenceScore",
+  "description": "Auditable 0-100 confidence scoring rubric and breakdown for TorusGuard v0.5.1 findings.",
+  "type": "object",
+  "required": [
+    "score",
+    "band",
+    "factors",
+    "rationale"
+  ],
+  "properties": {
+    "score": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "Composite confidence score from 0 to 100."
+    },
+    "band": {
+      "type": "string",
+      "enum": ["Confirmed", "High Confidence", "Medium Confidence", "Low Confidence / Unconfirmed"],
+      "description": "Classification band derived from score threshold."
+    },
+    "factors": {
+      "type": "object",
+      "required": [
+        "evidence_quality",
+        "reproduction_success",
+        "independent_confirmations",
+        "environmental_clarity",
+        "manual_review_status"
+      ],
+      "properties": {
+        "evidence_quality": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 35,
+          "description": "Direct source AST / exact snippet vs indirect indication (Max: 35)."
+        },
+        "reproduction_success": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 25,
+          "description": "Deterministic reproduction in fixture or local test (Max: 25)."
+        },
+        "independent_confirmations": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 15,
+          "description": "Corroboration across multiple manifests/routes (Max: 15)."
+        },
+        "environmental_clarity": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 15,
+          "description": "Absence of unverified external service layers or proxies (Max: 15)."
+        },
+        "manual_review_status": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10,
+          "description": "Validation confirmed by human engineer (Max: 10)."
+        }
+      }
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Justification explaining why this confidence score and band were assigned."
+    }
+  }
+}

package/.torusguard/schemas/evidence.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://torusguard.dev/schemas/evidence.schema.json",
+  "title": "TorusGuardEvidencePackage",
+  "description": "Structured evidence package schema with raw technical proof, hashes, and provenance for TorusGuard v0.5.1.",
+  "type": "object",
+  "required": [
+    "type",
+    "location",
+    "raw_snippet",
+    "sha256_checksum",
+    "rationale",
+    "confidence_level",
+    "collected_at"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["source", "runtime", "test", "manual_review"],
+      "description": "Origin and modality of the technical evidence."
+    },
+    "location": {
+      "type": "string",
+      "description": "File path, line number range, configuration key, or route endpoint (e.g. app/views.py:45-52)."
+    },
+    "raw_snippet": {
+      "type": "string",
+      "description": "Exact, unedited excerpt of the offending source code, configuration, or log."
+    },
+    "sha256_checksum": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "Cryptographic SHA-256 hash of the raw evidence snippet for audit integrity."
+    },
+    "collected_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Timestamp when this evidence was extracted."
+    },
+    "context": {
+      "type": "string",
+      "description": "Surrounding architectural context (e.g. within unauthenticated route handler)."
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Technical justification explaining why this code snippet proves the vulnerability."
+    },
+    "confidence_level": {
+      "type": "string",
+      "enum": ["Confirmed", "High Confidence", "Medium Confidence", "Low Confidence", "Needs Review", "Informational"],
+      "description": "Confidence assessment derived solely from this evidence artifact."
+    },
+    "reproduction_notes": {
+      "type": "string",
+      "description": "Specific inputs or conditions required to trigger the issue."
+    },
+    "reviewer_notes": {
+      "type": "string",
+      "description": "Human or AI security reviewer annotations."
+    },
+    "is_sufficient_for_confirmed": {
+      "type": "boolean",
+      "description": "True only if direct unmitigated vulnerability is proven without external assumptions."
+    }
+  }
+}