torusguard 1.4.0 → 2.1.0

package/.torusguard/skills/torusguard-audit/SKILL.md

@@ -1,41 +1,39 @@
 ---
 name: torusguard-audit
 description: Static AST security scanning, line-shift invariant fingerprinting, root-cause clustering, and 0-100 confidence scoring via CLI or AI Agent.
-version: 1.3.6
+version: 2.0.0
 workflow: .torusguard/workflows/audit.md
 tools: Read, Grep, Glob, Write, run_command
 scripts-binding:
-  - .torusguard/scripts/report_sync.py
-  - .torusguard/scripts/audit_runner.py
-  - .torusguard/scripts/term_ui.py
-  - .torusguard/scripts/finding_scorer.py
+  - internal/scanner/scanner.go
+  - cmd/torusguard/main.go
 ---
 
 # TorusGuard Audit — Static Code Security Analysis
 
 ## Objective
-Execute static AST analysis across polyglot project files, evaluate code against 74 canonical security rules across 11 families, assign stable line-shift invariant fingerprints, cluster architectural root causes, and score findings with auditable 0–100 confidence ratings.
+Execute static AST analysis across polyglot project files, evaluate code against 74 canonical security rules across 18 families, assign stable line-shift invariant fingerprints, cluster architectural root causes, synchronize findings with `security_report.md`, and score findings with auditable 0–100 confidence ratings.
 
 ---
 
-## Two Execution Modes
+## Tri-Mode Execution
 
 ### Mode A: Automated CLI Execution
 Run the static security audit from your terminal:
 ```bash
 # Scan current repository
-npx torusguard audit
+torusguard audit
 
 # Scan specific directory or example app
-npx torusguard audit ./examples/vulnerable-react-express
+torusguard audit ./examples/vulnerable-react-express
 
 # Include test fixtures and spec directories
-npx torusguard audit --include-tests
+torusguard audit --include-tests
 
 # Output machine-readable JSON
-npx torusguard audit --json
+torusguard audit --json
 ```
-**Under the Hood:** Executes `python .torusguard/scripts/audit_runner.py`.
+**Under the Hood:** Executes compiled Go static analysis engine (`internal/scanner`).
 - Auto-detects repository stack and skips build/cache directories (`node_modules`, `.git`, `.venv`, `dist`, `build`).
 - Evaluates files across 18 canonical security families:
   - `TG-SEC-*`: Hardcoded credentials, private keys, JWT secrets, client env leaks.
@@ -43,19 +41,33 @@ npx torusguard audit --json
   - `TG-DB-*`: Missing tenant isolation, service role keys in client code.
   - `TG-AUTH-*`: Plaintext passwords, missing cookie security flags (httpOnly, secure, sameSite).
   - `TG-PLATFORM-*`: Permissive wildcard CORS with credentials, missing security headers.
-  - `TG-DIFF-*`: Disabled TLS verification (`verify=False`, `rejectUnauthorized: false`).
-- Generates run directory: `.torusguard/runs/run-YYYYMMDD-HHMMSS-audit/`.
-- Writes `findings.json`, `findings.md`, and `manifest.json`.
+  - `TG-DIFF-*`: Disabled TLS verification (`verify=False`, `InsecureSkipVerify: true`).
+  - `TG-NPE-*`: Null-pointer exceptions, unchecked nil error dereferences.
+  - `TG-CONC-*`: Concurrency hazards, goroutine loop variable capture.
+- Writes findings directly to `security_report.md` at workspace root.
 - Displays standardized 75-column terminal cards.
-- Returns exit code `1` if findings are discovered, `0` if clean.
 
 ### Mode B: In-Session AI Chat Agent Scan
 When auditing files directly in AI chat:
 1. **Discover Sinks:** Use `grep_search` and `view_file` to search for dangerous patterns across server and client code.
 2. **Cluster Root Causes:** Group findings by causal architecture (e.g. `cluster-tenant-isolation`, `cluster-credentials-exposure`, `cluster-injection`).
 3. **Audit Evidence Sufficiency:** Ensure that user-controlled input reaches the vulnerable sink without prior sanitization or schema validation.
-4. **Present Actionable Findings:** Display finding cards with severity, rule ID, file, line, and remediation recommendation.
-5. **Prompt Next Phase:** Guide the operator to `/torusguard harden` or `npx torusguard harden`.
+4. **Context Minimization (1/9th Token Strategy):** Inspect only bounded AST context windows ($\pm 3$ lines) via `scanner.ExtractContext` rather than ingesting entire files.
+5. **Present Actionable Findings:** Display finding cards with severity, rule ID, file, line, and remediation recommendation.
+6. **Prompt Next Phase:** Guide the operator to `/torusguard harden` or `torusguard harden`.
+
+### Mode C: Native MCP Tool Execution
+For autonomous AI coding agents (Antigravity, Cursor, Windsurf, Claude Code):
+- **Tool Invocation:** Call `torusguard_audit` with target arguments:
+  ```json
+  {
+    "target": ".",
+    "include_ocr": true,
+    "max_image_mb": 10
+  }
+  ```
+- **Programmatic Return:** Receives formatted finding summaries, active rule counts, and confirmation that `security_report.md` is updated on disk.
+- **Resource Companion:** Inspect the living report via resource `torusguard://security_report` or rules catalog via `torusguard://rules_catalog`.
 
 ---
 
@@ -67,7 +79,9 @@ When auditing files directly in AI chat:
 | **TG-DB** | Database & Tenant Scoping | Unscoped `.objects.get(id=...)`, Prisma missing `tenantId` |
 | **TG-AUTH** | Authentication & Cookies | Insecure cookies (missing httpOnly/secure/sameSite) |
 | **TG-PLATFORM** | Server & Platform Config | Wildcard CORS (`origin: '*'`) with credentials |
-| **TG-DIFF** | Security Bypasses | Disabled TLS verification (`verify=False`) |
+| **TG-DIFF** | Security Bypasses | Disabled TLS verification (`verify=False`, `# nosec`) |
+| **TG-NPE** | Null Dereference / NPE | Unchecked optional chaining, unhandled nil error returns |
+| **TG-CONC** | Concurrency & Thread-Safety | Goroutine loop variable capture, unmutexed map mutations |
 
 ---
 
@@ -75,13 +89,48 @@ When auditing files directly in AI chat:
 ```markdown
 ### 🛡️ TorusGuard Static Security Audit Completed
 - **Run ID:** `run-20260910-121618-audit`
-- **Scope:** 7 files evaluated across 11 canonical families
+- **Scope:** 7 files evaluated across 18 canonical families
 - **Status:** ✖ CRITICAL FINDINGS DETECTED
 - **Findings:** 2 Critical, 2 High, 2 Medium/Low (6 total)
 - **Clusters:** 3 architectural root causes identified
-- **Artifacts:** `.torusguard/runs/<run_id>/findings.json`
-- **Next Action:** Run `npx torusguard harden` or `/torusguard harden`
+- **Artifacts:** `security_report.md`
+- **Next Action:** Run `torusguard harden` or `/torusguard harden`
 ```
 
-## Living Report Ground Truth
-- Read `security_report.md` in the workspace root before taking any action. Update the relevant finding card after completing remediation.
+---
+
+## 🏛️ OpenCodeReview Precision & Context Minimization
+- **1/9th Token Minimization:** Use `scanner.ExtractContext` to extract only the bounded $\pm 3$ lines context window instead of ingesting entire files.
+- **Line-Level Pinning:** Every finding is reported with exact 1-indexed line numbers, line content, severity, and suggested remediation.
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Unbounded File Reading** | Reads entire 800+ line files to diagnose a 1-line vulnerability. | Read only the bounded context ($\pm 3$ lines) around the finding's line number. |
+| **Ignoring NPE / Concurrency** | Focuses only on secrets and misses thread-safety and null-pointer hazards. | Enforce `TG-NPE-001` and `TG-CONC-001` checks during audit review. |
+| **False Positive Escalation** | Flags documentation strings or mock test fixtures as production vulnerabilities. | Skip test files (`*_test.go`, `.test.ts`) and verify sink exploitability before reporting. |
+| **Missing Sync to Ground Truth** | Produces analysis in chat without checking or updating `security_report.md`. | Always reconcile against `security_report.md` at workspace root. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before completing an audit pass, verify:
+- [ ] Did I run `torusguard audit` or inspect `security_report.md` first?
+- [ ] Are all reported findings pinned to precise line numbers?
+- [ ] Did I verify user input reaches the sink without prior validation?
+- [ ] Did I extract only the minimal AST context window ($\pm 3$ lines) to conserve tokens?
+- [ ] Did I evaluate against all 18 families including NPE and concurrency rules?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY: Scan source code and image assets using torusguard audit or torusguard_audit MCP tool.
+BUILD:  Synthesize findings clustered by root cause with exact line numbers and bounded AST snippets.
+CONFIRM: Synchronize living findings into security_report.md and guide operator to /torusguard harden.
+```

package/.torusguard/skills/torusguard-authorize/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: torusguard-authorize
 description: Register and validate runtime target authorization boundaries — scope boundaries, ownership proofs, TTL expiration, and Safety Gate enforcement.
-version: 1.3.6
+version: 2.0.0
 workflow: .torusguard/workflows/authorize.md
 tools: Read, Grep, Glob, Write, run_command
 scripts-binding:
+  - internal/scanner/scanner.go
   - .torusguard/scripts/report_sync.py
   - .torusguard/scripts/safety_gate.py
 ---
@@ -16,18 +17,27 @@ Define and validate legal runtime authorization boundaries, verify target owners
 
 ---
 
+## Tri-Mode Parity
+
+| Mode | Command / Tool | Governed Behavior |
+| :--- | :--- | :--- |
+| **Mode A: CLI Terminal** | `torusguard authorize` | Interactive boundary setup, generates cryptographically signed scope tokens. |
+| **Mode B: AI Chat Slash** | `/torusguard authorize` | Conversational parameter collection, validates host ownership and environment. |
+| **Mode C: Native MCP Tool**| — | Administrative gatekeeper ensuring strict safety boundaries before probes. |
+
+---
+
 ## Execution Steps
 
 1. **Capture Scope Parameters:** Collect target host URL, allowed path prefixes, forbidden prefixes, and session TTL.
-2. **Validate Environment:** Assert target is local (`localhost`, `127.0.0.1`) or staging (`*.staging.*`). Block production targets without explicit override.
+2. **Validate Environment:** Assert target is local (`localhost`, `127.0.0.1`) or staging (`*.staging.*`). Block production targets without explicit cryptographic override.
 3. **Verify Host Ownership:** Confirm ownership token or local process socket binding.
 4. **Invoke Safety Gate:**
    ```bash
-   python .torusguard/scripts/safety_gate.py check --url <target_url>
+   torusguard authorize --url <target_url>
    ```
-5. **Handle CLI Failures:** If `safety_gate.py` fails or is unavailable, YOU must manually verify the safety invariants and generate the JSON structure below.
-6. **Write Scope Record:** Persist authorized targets, rate limits, and expiration timestamp into `.torusguard/config/scope.json`.
-7. **Validate Schema:** Confirm `scope.json` adheres to `auth-boundary.schema.json`.
+5. **Write Scope Record:** Persist authorized targets, rate limits, and expiration timestamp into `.torusguard/config/scope.json`.
+6. **Validate Schema:** Confirm `scope.json` adheres to `auth-boundary.schema.json`.
 
 ---
 
@@ -39,6 +49,7 @@ Define and validate legal runtime authorization boundaries, verify target owners
 - Never authorize wildcard hosts (`*`) or third-party domains.
 - State-changing destructive actions (`DELETE`, bulk drops) are disabled by default.
 - Set strict TTL (default 4 hours, maximum 24 hours).
+- Fail-Closed Cryptography: Authorization token generation must panic on entropy failure. No hardcoded fallback tokens are permitted.
 
 ---
 
@@ -51,3 +62,34 @@ Define and validate legal runtime authorization boundaries, verify target owners
 - Scope File: `.torusguard/config/scope.json`
 Next: Run `/torusguard web-validate` to begin safe runtime probing.
 ```
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Wildcard Scope Authorization** | Accepts `*` or wide domain patterns like `*.com`, enabling unbounded network probes. | Strictly enforce exact domain/port matching (`http://localhost:3000`, `https://staging.internal`). |
+| **Infinite TTL** | Omits `expires_at` or sets multi-year expiration timestamps. | Enforce TTL bound of maximum 24 hours (default 4 hours) to prevent lingering test permissions. |
+| **Production Probe Authorization** | Authorizes live production domains without ownership challenge or manual user confirmation. | Reject production domains unless explicit cryptographic ownership challenge succeeds. |
+| **Destructive Method Inclusion** | Allows `DELETE`, `PUT /bulk`, or `DROP` routes in `allowed_paths`. | Blacklist state-altering destructive paths; confine runtime validation to safe, non-destructive probes. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before authorizing any runtime scope:
+- [ ] Is the target host local (`localhost`, `127.0.0.1`) or an authorized staging environment?
+- [ ] Are wildcards (`*`) strictly rejected?
+- [ ] Is the TTL strictly bounded (≤24 hours)?
+- [ ] Are destructive routes and SQL operations explicitly forbidden?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY:  Check target URL, environment, and ownership proof against safety boundaries.
+BUILD:   Construct scope.json record with explicit allowed paths and TTL bounds.
+CONFIRM: Validate JSON against auth-boundary.schema.json and persist to .torusguard/config/scope.json.
+```

package/.torusguard/skills/torusguard-container/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: torusguard-container
+description: Audits Dockerfiles, Containerfiles, and Docker Compose configurations for root users, exposed docker sockets, privileged mode, and embedded secrets via CLI, Chat, or MCP.
+version: 2.0.0
+workflow: .torusguard/workflows/container.md
+tools: Read, Grep, Glob, Write, run_command
+scripts-binding:
+  - internal/scanner/container.go
+  - cmd/torusguard/main.go
+  - cmd/torusguard/mcp.go
+---
+
+# TorusGuard Container & Docker Security Audit
+
+## Objective
+Detect and remediate critical container runtime and build-time security vulnerabilities across `Dockerfile`, `Containerfile`, `docker-compose.yml`, and `compose.yaml` files. Enforces non-root execution, privilege containment, socket isolation, and BuildKit secret mounts.
+
+---
+
+## Tri-Mode Execution
+
+### Mode A: Automated CLI Execution
+Run container audits against current directory or specific target project:
+```bash
+# Scan container files in current directory
+torusguard container
+
+# Scan container files in specific workspace target
+torusguard container --target ./deployments/docker
+```
+
+### Mode B: In-Session AI Chat Slash Command
+Run `/torusguard container` in chat.
+The agent invokes the native Go scanner or MCP tool to inspect container definitions, audit user permissions, and report structural container misconfigurations.
+
+### Mode C: Native MCP Tool Call
+MCP-enabled coding agents (Antigravity, Cursor, Windsurf, Claude Code) call:
+```json
+{
+  "tool": "torusguard_container",
+  "arguments": {
+    "target": "."
+  }
+}
+```
+
+---
+
+## Supported Patterns & Invariants
+- **TG-CONT-001 (Root Execution Default):** Detects omission of explicit `USER <non-root>` instruction or explicit `USER root` declarations in production container stages.
+- **TG-CONT-002 (Docker Socket Exposure):** Detects dangerous mounting of the host daemon socket (`/var/run/docker.sock`), which grants unconfined root privileges over the host.
+- **TG-CONT-003 (Privileged Container Flag):** Detects `privileged: true`, `seccomp:unconfined`, or `SYS_ADMIN` capability grants that defeat Linux namespace and cgroup boundaries.
+- **TG-CONT-004 (Build-Time Secret Injection):** Flags embedding sensitive tokens, passwords, or keys via `ARG` or `ENV` directives in Dockerfiles rather than BuildKit secret mounts.
+
+---
+
+## 🏛️ OpenCodeReview Hybrid Architecture Integration
+- **Deterministic Dockerfile & Compose Parser:** Pattern extraction is executed by Go AST/regex parsers without external Docker daemon dependencies.
+- **Token Efficiency:** Only flagged container directives and minimal surrounding context are returned to the agent context.
+- **Ponytail Bounds:** Remediation patches must add dedicated non-root users (`USER appuser`) or switch secrets to `--mount=type=secret` without full container file rewrites (≤35 additions, ≤25 deletions).
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Default Root Execution** | Forgets that Docker executes as UID 0 (`root`) unless a non-root `USER` is declared. | Always declare `RUN adduser -D appuser && USER appuser` before the entrypoint. |
+| **Secrets in Build Arguments** | Recommends `ARG API_KEY` or `ENV DB_PASSWORD`, leaving keys baked into image layers. | Use Docker BuildKit secret mounts: `RUN --mount=type=secret,id=mysecret ...`. |
+| **Permissive Privileged Mode** | Adds `privileged: true` or `cap_add: [ALL]` to resolve permission or port binding errors. | Grant only specific minimal Linux capabilities (e.g. `NET_BIND_SERVICE`) or fix file ownership. |
+| **Docker Socket Mounting** | Mounts `/var/run/docker.sock` inside container to run Docker commands inside Docker. | Use Docker-in-Docker (dind) rootless or ephemeral CI runners with isolated daemons. |
+| **Full File Rewrites** | Rewrites entire multi-stage Dockerfile destroying cached layer order. | Formulate surgical diffs replacing or inserting only the missing `USER` or mount flag. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before concluding a container security review, verify:
+- [ ] Did I scan all Dockerfiles (`Dockerfile`, `Dockerfile.*`, `Containerfile`)?
+- [ ] Did I scan all compose files (`docker-compose.yml`, `compose.yaml`)?
+- [ ] Is there an unprivileged non-root user defined before `ENTRYPOINT` or `CMD`?
+- [ ] Are sensitive environment variables passed via runtime `.env` / secret managers instead of `ARG` / `ENV`?
+- [ ] Is `/var/run/docker.sock` completely absent from compose volumes?
+- [ ] Are all proposed fixes within Ponytail churn bounds (≤35 additions, ≤25 deletions)?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY: Identify Dockerfiles and Compose files in the workspace.
+BUILD:  Execute torusguard container or torusguard_container to locate container privilege and secret flaws.
+CONFIRM: Formulate surgical remediation patch introducing non-root users and removing dangerous mounts, rechecking with torusguard recheck.
+```

package/.torusguard/skills/torusguard-exploit-check/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: torusguard-exploit-check
 description: Safe, non-destructive confirmation of exploitability using inert canary tokens and sentinels.
-version: 1.3.6
+version: 2.0.0
 workflow: .torusguard/workflows/exploit-check.md
 tools: Read, Grep, Glob, Bash, Write, run_command
 scripts-binding:
+  - internal/scanner/scanner.go
   - .torusguard/scripts/report_sync.py
   - .torusguard/scripts/safety_gate.py
   - .torusguard/scripts/finding_scorer.py
@@ -17,11 +18,21 @@ Confirm whether candidate findings are practically exploitable using safe, singl
 
 ---
 
+## Tri-Mode Parity
+
+| Mode | Command / Tool | Governed Behavior |
+| :--- | :--- | :--- |
+| **Mode A: CLI Terminal** | `torusguard exploit-check` | Dispatches single-step sentinel canaries, confirms exploitability safely. |
+| **Mode B: AI Chat Slash** | `/torusguard exploit-check` | Evaluates reproduction traces and classifies findings into 5 statuses. |
+| **Mode C: Native MCP Tool**| — | Bounded execution guarded by safety gate and inert payloads. |
+
+---
+
 ## Authorization Gate Check
 Before dispatching any exploitability probe:
 1. Verify target route is explicitly authorized in `.torusguard/config/scope.json`.
 2. Verify authorization TTL has not expired.
-3. Assert probe passes `.torusguard/scripts/safety_gate.py`.
+3. Assert probe passes safety boundaries.
 
 ---
 
@@ -37,15 +48,17 @@ Before dispatching any exploitability probe:
 
 1. **Verify Scope:** Read `scope.json`; assert authorized endpoint.
 2. **Select Canary:** Choose matching non-destructive probe strategy.
-3. **Handle Automation Failure:** If automated exploit check scripts fail, YOU must manually construct the safe HTTP request (using `curl` or `fetch`) and inspect the response.
-4. **Dispatch Probe:** Send request with header `X-TorusGuard-AuthID`.
-5. **Classify Status:** Transition finding into one of 5 canonical outcomes:
+3. **Dispatch Probe:** Send request with header `X-TorusGuard-AuthID`:
+   ```bash
+   torusguard exploit-check --finding TG-SEC-001
+   ```
+4. **Classify Status:** Transition finding into one of 5 canonical outcomes:
    - `Confirmed`: Canary reflected or secondary tenant data leaked.
    - `Not Reproducible`: Endpoint responded with 401/403 or sanitized input.
    - `Needs Review`: Ambiguous status code or incomplete response.
    - `Blocked by Controls`: WAF or rate limiter stopped probe.
    - `Out of Scope`: Target endpoint is not authorized.
-6. **Record Evidence:** Save trace in `.torusguard/runs/<run_id>/exploit-evidence.md`.
+5. **Record Evidence:** Save trace in `.torusguard/runs/<run_id>/exploit-evidence.md`.
 
 ---
 
@@ -68,3 +81,34 @@ Before dispatching any exploitability probe:
 - Evidence: <Response snippet or status code>
 Next: Run `/torusguard harden` to formulate surgical remediation bundle.
 ```
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Destructive Payloads** | Generates real data-altering payloads (`'; DROP TABLE users;--`, `<script>evil()</script>`). | Use strictly inert canaries (`' OR 1=1--`, `<tg-canary-tag>`) that cannot destroy state or exfiltrate data. |
+| **Fuzzing Floods** | Runs recursive wordlist fuzzing or multi-hundred request automated attacks. | Enforce single-step bounded confirmation (1-2 deterministic probe requests max). |
+| **False Confirmation** | Declares finding "Confirmed" based on a generic HTTP 500 error without validating the canary reflection. | Require differential response evidence (e.g. reflection of exact sentinel tag or tenant leak). |
+| **Missing Scope Check** | Probes external auth providers (OAuth Google/GitHub) during auth validation. | Confine probes strictly to internal endpoints authorized in `scope.json`. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before dispatching an exploitability check:
+- [ ] Is the probe payload completely inert and non-destructive?
+- [ ] Is the route explicitly in scope and within TTL?
+- [ ] Is the `X-TorusGuard-AuthID` header attached?
+- [ ] Is the outcome classification mapped to one of the 5 canonical statuses?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY:  Check route authorization in scope.json and confirm finding AST context.
+BUILD:   Select inert canary token (e.g. <tg-canary-tag>) and construct probe.
+CONFIRM: Evaluate response for differential proof, classify status, and record trace.
+```

package/.torusguard/skills/torusguard-full/SKILL.md

@@ -1,16 +1,14 @@
 ---
 name: torusguard-full
 description: Master 7-stage security pipeline orchestrator — coordinates discovery, authorization, static audit, runtime validation, governed remediation, recheck, and reporting.
-version: 1.3.6
+version: 2.0.0
 workflow: .torusguard/workflows/audit.md
 tools: Read, Grep, Glob, Bash, Edit, Write, run_command
 scripts-binding:
+  - internal/scanner/scanner.go
+  - internal/harden/patch.go
+  - internal/apply/apply.go
   - .torusguard/scripts/report_sync.py
-  - .torusguard/scripts/stack_detect.py
-  - .torusguard/scripts/safety_gate.py
-  - .torusguard/scripts/finding_scorer.py
-  - .torusguard/scripts/run_manager.py
-  - .torusguard/scripts/sarif_exporter.py
 ---
 
 # TorusGuard Full — Master 7-Stage Pipeline Orchestrator
@@ -20,15 +18,33 @@ Execute the full, closed-loop TorusGuard security lifecycle from stack discovery
 
 ---
 
+## Tri-Mode Pipeline Parity
+
+| Stage | Mode A: Terminal CLI | Mode B: AI Chat Slash | Mode C: Native MCP Tool |
+| :--- | :--- | :--- | :--- |
+| **0. Init** | `torusguard init` | `/torusguard init` | Init + `torusguard_status` |
+| **1. Authorize** | `torusguard authorize` | `/torusguard authorize` | Safety Gate Boundary |
+| **2. Audit & Vision** | `torusguard audit` / `ocr-scan` | `/torusguard audit` / `ocr-scan` | `torusguard_audit` / `torusguard_ocr_scan` |
+| **3. Verify** | `torusguard verify` | `/torusguard verify` | `torusguard_verify` |
+| **4. Harden** | `torusguard harden` | `/torusguard harden` | `torusguard_harden` |
+| **5. Apply** | `torusguard apply [--yes]` | `/torusguard apply` | Human Gate Approval |
+| **6. Recheck** | `torusguard recheck` | `/torusguard recheck` | `torusguard_recheck` |
+| **7. Report** | `torusguard report --html` | `/torusguard report` | `torusguard://security_report` |
+
+---
+
 ## 7-Stage Security Pipeline
-0. Init (Baseline) ──► 1. Authorize (Scope) ──► 2. Audit (AST Scan) ──► 3. Validate (Evidence/Exploit) ──► 4. Harden (Ponytail Patch) ──► 5. Apply (Backup & Edit) ──► 6. Recheck (Regression) ──► 7. Report (SARIF)
+```
+0. Init ──► 1. Authorize ──► 2. Audit ──► 3. Validate ──► 4. Harden ──► 5. Apply ──► 6. Recheck ──► 7. Report
+(Baseline)   (Scope Gate)     (AST Scan)   (Evidence)     (Ponytail)   (Human Gate)  (Regression)   (SARIF/HTML)
+```
 
 ---
 
 ## Specialist Skill Routing
 - **Phase 0:** `torusguard-init` (`profiler`)
 - **Phase 1:** `torusguard-authorize` (`reviewer`)
-- **Phase 2:** `torusguard-audit` (`auditor`)
+- **Phase 2:** `torusguard-audit` (`auditor`) / `torusguard-ocr-scan` (`vision`)
 - **Phase 3:** `torusguard-verify` / `torusguard-exploit-check` (`validator`)
 - **Phase 4:** `torusguard-harden` (`remediator`)
 - **Phase 5:** `torusguard-apply` (`remediator`)
@@ -38,19 +54,14 @@ Execute the full, closed-loop TorusGuard security lifecycle from stack discovery
 ---
 
 ## Pipeline Execution Instructions
-1. **Init:** Detect stack via `stack_detect.py` and activate rules in `.torusguard/rules/active/`.
+1. **Init:** Detect stack via `torusguard init` and activate tailored rules in `.torusguard/rules/active/`.
 2. **Authorize:** Verify target ownership and TTL in `.torusguard/config/scope.json`.
-3. **Audit:** Scan ASTs; assign fingerprints; cluster root causes; compute confidence scores.
+3. **Audit:** Scan ASTs via `torusguard audit` (or `torusguard ocr-scan` for visual assets); assign fingerprints; compute confidence scores.
 4. **Validate:** Audit evidence sufficiency; optionally send bounded probe canary.
-5. **Harden:** Formulate surgical diffs bound by Ponytail limits ($\le 35$ add, $\le 25$ del).
-6. **Apply:** Save `.bak` snapshot in `pre_apply/`; obtain Human Gate; apply patch.
-7. **Recheck:** Re-scan modified files; assert findings are `Fixed` with zero regressions.
-8. **Report:** Export OASIS SARIF v2.1.0 and emit signed markdown summary.
-
----
-
-## Confidence Scoring Rubric
-Evaluates Evidence (35 pts), Reproduction (25 pts), Corroboration (15 pts), Environment (15 pts), and Review Status (10 pts) into 4 bands: Confirmed (90–100), High (70–89), Medium (50–69), Needs Review (<50).
+5. **Harden:** Formulate surgical diffs bound by Ponytail limits ($\le 35$ additions, $\le 25$ deletions).
+6. **Apply:** Capture `.bak` snapshot in `.torusguard/snapshots/`; obtain Human Gate; apply patch via `torusguard apply`.
+7. **Recheck:** Re-scan modified files via `torusguard recheck`; assert findings are `Fixed` with zero regressions.
+8. **Report:** Export OASIS SARIF v2.1.0 and emit visual HTML dashboard via `torusguard report --html`.
 
 ---
 
@@ -62,6 +73,7 @@ Evaluates Evidence (35 pts), Reproduction (25 pts), Corroboration (15 pts), Envi
 - Human Gate mandatory before code modifications in Phase 5.
 - Enforce Ponytail line bounds ($\le 35$ additions, $\le 25$ deletions).
 - Never dispatch network probes outside authorized scope in `scope.json`.
+- Zero security bypasses permitted (`TG-DIFF-001`).
 
 ---
 
@@ -73,3 +85,34 @@ Evaluates Evidence (35 pts), Reproduction (25 pts), Corroboration (15 pts), Envi
 - SARIF Log: `.torusguard/runs/<run_id>/results.sarif`
 - Report: `.torusguard/runs/<run_id>/report.md`
 ```
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Pipeline Step Skipping** | Jumps directly from Audit to Apply without verifying evidence or validating Ponytail patch bounds. | Follow the 7 stages in sequential order; each stage gate must be satisfied. |
+| **Human Gate Bypass** | Writes modifications directly to disk without presenting candidate diffs or awaiting user confirmation. | Always require explicit Human Gate confirmation before Phase 5 (`torusguard apply`). |
+| **Full File Rewrites** | Rewrites complete source files during remediation, causing massive line churn and regression risk. | Formulate surgical patches respecting Ponytail bounds ($\le 35$ add, $\le 25$ del) using Line-Level Reflection. |
+| **Unsynchronized State** | Generates reports that don't match the statuses in `security_report.md`. | Keep `security_report.md` synchronized at every phase transition as the single living source of truth. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before orchestrating the full pipeline:
+- [ ] Are all prerequisite tools (`torusguard` binary) available?
+- [ ] Is `security_report.md` inspected prior to initiating any scans or fixes?
+- [ ] Are all patches bounded by Ponytail limits and verified without security bypasses?
+- [ ] Is a `.bak` snapshot captured before any disk modification?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY:  Review current workspace security posture and verify phase prerequisites.
+BUILD:   Execute the pipeline stage by stage using designated specialist skills.
+CONFIRM: Validate final SARIF, HTML report, and synchronized security_report.md.
+```

package/.torusguard/skills/torusguard-git-mine/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: torusguard-git-mine
+description: Mines git commit history, commit diffs, and local repository metadata for leaked credentials, private keys, and historical API tokens via CLI, Chat, or MCP.
+version: 2.0.0
+workflow: .torusguard/workflows/git-mine.md
+tools: Read, Grep, Glob, Write, run_command
+scripts-binding:
+  - internal/scanner/git_mine.go
+  - cmd/torusguard/main.go
+  - cmd/torusguard/mcp.go
+---
+
+# TorusGuard Git History Secret Mining
+
+## Objective
+Inspect local `.git` metadata, remote configurations, and commit logs across the repository's commit history to identify leaked API tokens, private keys, database URIs, and credentials that were committed in past revisions or embedded in remote URLs.
+
+---
+
+## Tri-Mode Execution
+
+### Mode A: Automated CLI Execution
+Run Git history mining against current repository or specified target workspace:
+```bash
+# Mine Git commit history and .git/config in current workspace
+torusguard git-mine
+
+# Mine specific repository target
+torusguard git-mine --target /path/to/repo
+```
+
+### Mode B: In-Session AI Chat Slash Command
+Run `/torusguard git-mine` in chat.
+The agent executes the compiled Go Git mining engine or MCP tool to inspect commit history logs, detect historical secret leaks, and provide provider revocation guidance.
+
+### Mode C: Native MCP Tool Call
+MCP-enabled coding agents (Antigravity, Cursor, Windsurf, Claude Code) call:
+```json
+{
+  "tool": "torusguard_git_mine",
+  "arguments": {
+    "target": "."
+  }
+}
+```
+
+---
+
+## Supported Patterns & Invariants
+- **TG-GIT-001 (Historical Secret Commit):** Detects API keys (OpenAI `sk-...`, AWS `AKIA...`, GitHub `ghp_...`), private certificates, or database credentials introduced in prior git commits even if removed from the current working tree.
+- **TG-GIT-002 (Plaintext Remote Credentials):** Flags remote URLs in `.git/config` containing basic authentication credentials (`https://user:token@github.com/...`).
+- **TG-GIT-003 (Sensitive File History Tracking):** Detects tracked `.env`, `id_rsa`, `.pem`, or `.key` files in git log metadata that bypass `.gitignore`.
+
+---
+
+## 🏛️ OpenCodeReview Hybrid Architecture Integration
+- **Deterministic History Inspection:** Analyzes commit logs via local Git commands or fallback file reading with strict 5-second timeouts and bounded commit depths.
+- **Token Minimization:** Emits commit SHA, author timestamp, and redacted secret preview rather than dumping full commit logs into LLM context.
+- **Revocation-First Governance:** Prioritizes immediate credential revocation at the provider (OpenAI, AWS, GitHub) before history rewrites (`git filter-repo` / BFG).
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Working Tree Only Bias** | Only scans files currently on disk, assuming deleted secrets are safely removed. | Always mine Git commit history (`git log -p`) because Git never forgets past commits. |
+| **Token in Remote Origin URL** | Recommends `git remote set-url origin https://ghp_xxx@github.com/...` which writes token to disk in plaintext. | Use SSH keys, GitHub CLI (`gh auth login`), or credential helpers (`git credential-manager`). |
+| **History Rewriting Over Revocation** | Recommends scrubbing Git history before revoking the leaked secret at the cloud provider. | Always rotate and revoke the credential immediately at the provider first; assume it was scraped. |
+| **Single Commit Amends** | Recommends `git commit --amend` when the secret was committed 5 commits ago. | Use `git rebase -i` or `git-filter-repo` for deeper historical scrubbing. |
+| **Tracking .env in Git** | Adds `.env` to `.gitignore` without running `git rm --cached .env`, leaving file tracked. | Run `git rm --cached <file>` so Git stops tracking the sensitive file in subsequent commits. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before concluding a Git repository security audit, verify:
+- [ ] Is `.git` directory present and valid?
+- [ ] Were remote URLs in `.git/config` checked for embedded plaintext passwords or tokens?
+- [ ] Were the most recent 50 commits audited for added secrets in commit diffs?
+- [ ] Did I verify whether `.env` or private keys were ever tracked in git history?
+- [ ] Was the user instructed to rotate/revoke leaked keys at the provider immediately?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY: Confirm workspace is a valid Git repository with accessible commit history.
+BUILD:  Execute torusguard git-mine or torusguard_git_mine to detect historical leaks and credential configs.
+CONFIRM: Provide immediate rotation steps, clean .git/config, and scrub historical commits via git-filter-repo.
+```