torusguard 0.9.2

package/skills/torusguard/payload/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/skills/torusguard/payload/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/skills/torusguard/payload/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/skills/torusguard/payload/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/skills/torusguard/payload/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/skills/torusguard/payload/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/skills/torusguard/payload/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."
+    }
+  }
+}

package/skills/torusguard/payload/schemas/finding.schema.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://torusguard.dev/schemas/finding.schema.json",
+  "title": "TorusGuardCanonicalFinding",
+  "description": "Canonical normalized finding object schema for TorusGuard v0.5.1 with provenance and auditable confidence scoring.",
+  "type": "object",
+  "required": [
+    "finding_id",
+    "rule_id",
+    "title",
+    "category",
+    "severity",
+    "confidence",
+    "status",
+    "affected_component",
+    "evidence",
+    "provenance",
+    "reproduction_method",
+    "remediation",
+    "retest_result",
+    "timestamps"
+  ],
+  "properties": {
+    "finding_id": {
+      "type": "string",
+      "pattern": "^TG-FIND-[0-9]{4}-[a-f0-9]{4,12}$",
+      "description": "Unique canonical identifier for this finding instance."
+    },
+    "rule_id": {
+      "type": "string",
+      "pattern": "^TG-[A-Z0-9]+-[0-9]{3}$",
+      "description": "Canonical TorusGuard Rule ID (e.g. TG-AUTH-007, TG-SEC-001)."
+    },
+    "title": {
+      "type": "string",
+      "description": "Concise, human-readable finding title."
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "authentication-authorization",
+        "input-validation-encoding",
+        "data-access-orm",
+        "file-upload-handling",
+        "secrets-configuration",
+        "dependency-supply-chain",
+        "network-ssrf-boundaries",
+        "business-logic-rate-limiting",
+        "client-cache-platform"
+      ],
+      "description": "Normalized lifecycle taxonomy category."
+    },
+    "severity": {
+      "type": "object",
+      "required": ["level", "rationale", "rubric_justification"],
+      "properties": {
+        "level": {
+          "type": "string",
+          "enum": ["Critical", "High", "Medium", "Low", "Informational"]
+        },
+        "rationale": {
+          "type": "string",
+          "description": "Justification for assigned severity level."
+        },
+        "rubric_justification": {
+          "type": "string",
+          "description": "Explicit reason why this finding is not a higher or lower severity."
+        }
+      }
+    },
+    "confidence": {
+      "$ref": "confidence.schema.json"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "Confirmed",
+        "High Confidence",
+        "Medium Confidence",
+        "Low Confidence",
+        "Unconfirmed",
+        "Needs Review",
+        "Remediated",
+        "Verified Fixed"
+      ],
+      "description": "Standardized operational verification status."
+    },
+    "affected_component": {
+      "type": "object",
+      "required": ["component_name", "target_path"],
+      "properties": {
+        "component_name": { "type": "string" },
+        "target_path": { "type": "string" },
+        "start_line": { "type": "integer" },
+        "end_line": { "type": "integer" },
+        "symbol": { "type": "string" }
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "evidence.schema.json" }
+    },
+    "provenance": {
+      "$ref": "provenance.schema.json"
+    },
+    "reproduction_method": {
+      "type": "object",
+      "required": ["step_by_step", "deterministic"],
+      "properties": {
+        "step_by_step": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "test_command": { "type": "string" },
+        "deterministic": { "type": "boolean" },
+        "expected_failure_response": { "type": "string" }
+      }
+    },
+    "remediation": {
+      "$ref": "remediation.schema.json"
+    },
+    "retest_result": {
+      "$ref": "retest.schema.json"
+    },
+    "requirement_reference": {
+      "type": "object",
+      "properties": {
+        "asvs_v4": { "type": "string" },
+        "nist_ssdf": { "type": "string" },
+        "owasp_top10": { "type": "string" }
+      }
+    },
+    "cwe": {
+      "type": "string",
+      "pattern": "^CWE-[0-9]{1,5}$"
+    },
+    "timestamps": {
+      "type": "object",
+      "required": ["discovered_at", "updated_at"],
+      "properties": {
+        "discovered_at": { "type": "string", "format": "date-time" },
+        "verified_at": { "type": "string", "format": "date-time" },
+        "remediated_at": { "type": "string", "format": "date-time" },
+        "retested_at": { "type": "string", "format": "date-time" },
+        "updated_at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "notes": {
+      "type": "object",
+      "required": ["raw_facts_summary", "ai_interpretation"],
+      "properties": {
+        "raw_facts_summary": {
+          "type": "string",
+          "description": "Objective, unembellished summary of verified code facts."
+        },
+        "ai_interpretation": {
+          "type": "string",
+          "description": "AI-generated risk analysis and contextual reasoning."
+        }
+      }
+    }
+  }
+}

package/skills/torusguard/payload/schemas/provenance.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://torusguard.dev/schemas/provenance.schema.json",
+  "title": "TorusGuardProvenanceChain",
+  "description": "Structured provenance chain tracking discovery and decision path for TorusGuard v0.5.1 findings.",
+  "type": "object",
+  "required": [
+    "discovery_module",
+    "triggering_input",
+    "evidence_collected",
+    "decision_path",
+    "verification_step"
+  ],
+  "properties": {
+    "discovery_module": {
+      "type": "string",
+      "description": "Module or rule that initiated the detection (e.g. rules/authorization/TG-AUTH-007)."
+    },
+    "triggering_input": {
+      "type": "string",
+      "description": "The specific input, AST node, manifest line, or configuration key that triggered detection."
+    },
+    "evidence_collected": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of evidence identifiers or file locations gathered during discovery."
+    },
+    "decision_path": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Ordered sequence of logical evaluation steps leading to the finding classification."
+    },
+    "verification_step": {
+      "type": "string",
+      "description": "Verification method used to confirm or refute the finding."
+    },
+    "agent_environment": {
+      "type": "string",
+      "description": "Runtime context (e.g. TorusGuard Engine v0.5.1 on Python 3.11)."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}