torusguard 2.1.0 → 2.1.1

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

@@ -1,94 +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.
-```
+---
+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/skills/torusguard/payload/skills/torusguard-git-mine/SKILL.md

@@ -1,92 +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.
-```
+---
+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.
+```

package/skills/torusguard/payload/skills/torusguard-ocr-scan/SKILL.md

@@ -1,94 +1,94 @@
----
-name: torusguard-ocr-scan
-description: Scans images, architecture diagrams, and screenshots via Tesseract OCR for leaked API keys, tokens, and credentials via CLI or AI Agent.
-version: 2.0.0
-workflow: .torusguard/workflows/ocr-scan.md
-tools: Read, Grep, Glob, Write, run_command
-scripts-binding:
-  - internal/scanner/ocr.go
-  - cmd/torusguard/main.go
----
-
-# TorusGuard OCR Vision Scan — Multi-Modal Secret Extraction
-
-## Objective
-Detect optical leaks of private API keys, AWS credentials, database URIs, GitHub personal access tokens, and private certificates embedded inside visual artifacts (PNG, JPG, WebP, BMP, TIFF) up to 10MB using Tesseract OCR and deterministic regex signatures.
-
----
-
-## Tri-Mode Execution
-
-### Mode A: Automated CLI Execution
-Run OCR scanning against a single diagram file or an entire directory of visual assets:
-```bash
-# Scan a specific architecture diagram or screenshot
-torusguard ocr-scan docs/architecture/diagram.png
-
-# Scan an entire directory of media assets
-torusguard ocr-scan ./assets/images/
-```
-
-### Mode B: In-Session AI Chat Slash Command
-Run `/torusguard ocr-scan <path>` in chat.
-The agent invokes the native Go scanner or MCP tool to extract optical text, analyze credential patterns, and report leaked keys.
-
-### Mode C: Native MCP Tool Call
-MCP-enabled coding agents (Antigravity, Cursor, Windsurf, Claude Code) call:
-```json
-{
-  "tool": "torusguard_ocr_scan",
-  "arguments": {
-    "target": "docs/architecture/cloud-architecture.png",
-    "max_image_mb": 10
-  }
-}
-```
-
----
-
-## Supported Patterns & Invariants
-- **TG-SEC-001:** Hardcoded API Keys / Tokens / OpenAI & Stripe Keys (`sk-live-...`, `sk-...`).
-- **TG-SEC-002:** AWS Access Key IDs (`AKIA[0-9A-Z]{16}`).
-- **TG-SEC-003:** GitHub Personal Access Tokens (`ghp_...`, `github_pat_...`).
-- **TG-SEC-004:** Database Connection URIs (`postgres://user:pass@host:5432/db`).
-- **TG-SEC-005:** Private Key Headers (`-----BEGIN RSA PRIVATE KEY-----`).
-- **TG-SEC-007:** Password assignments (`password = "..."`).
-- **10MB DoS Guard:** Files exceeding 10MB are rejected fail-closed to prevent resource exhaustion attacks.
-
----
-
-## 🏛️ OpenCodeReview Hybrid Architecture Integration
-- **Deterministic OCR Preprocessing:** Optical extraction and regex pattern matching run entirely in compiled Go code without LLM hallucination.
-- **Token Efficiency:** Only the extracted text and detected secret matches are emitted to the agent context (zero token waste on binary image blobs).
-
----
-
-## 🚨 LLM Trap Table
-
-| Pattern | What AI Does Wrong | What Is Actually Correct |
-| :--- | :--- | :--- |
-| **Reading Binary Images as Text** | Attempts to read raw `.png` or `.jpg` with `view_file` as utf-8 text. | Invoke `torusguard ocr-scan` or `torusguard_ocr_scan` to perform OCR. |
-| **Ignoring Image File Size Bounds** | Tries to OCR multi-hundred megabyte video files or giant raw images. | Adhere to the 10MB DoS boundary (`DefaultMaxImageSize`). |
-| **Echoing Full Leaked Secrets in Logs** | Prints live production credentials unredacted in terminal output or reports. | Partially redact sensitive tokens (e.g. `sk-live-****3211`). |
-| **Assuming Images Don't Contain Secrets** | Audits only `.go` or `.js` code and ignores cloud diagrams or screenshots. | Always run OCR vision scan across image directories during full audits. |
-
----
-
-## ✅ Pre-Flight Self-Audit
-
-Before concluding an OCR inspection, verify:
-- [ ] Is Tesseract installed and discoverable on PATH?
-- [ ] Are all target files valid image formats (`.png`, `.jpg`, `.jpeg`, `.webp`, `.bmp`, `.tiff`)?
-- [ ] Are target image file sizes strictly $\le 10$ MB?
-- [ ] Did I check against all 7 canonical secret signatures (`TG-SEC-001` through `TG-SEC-007`)?
-- [ ] Are confirmed leaks documented in `security_report.md` with remediation steps?
-
----
-
-## 🔁 VBC Protocol (Verify → Build → Confirm)
-
-```
-VERIFY: Confirm target image existence and size <= 10MB.
-BUILD:  Execute torusguard ocr-scan or torusguard_ocr_scan to extract optical text.
-CONFIRM: Match text against OCRSecretPattern signatures, redact sensitive tokens, and record in security_report.md.
-```
+---
+name: torusguard-ocr-scan
+description: Scans images, architecture diagrams, and screenshots via Tesseract OCR for leaked API keys, tokens, and credentials via CLI or AI Agent.
+version: 2.0.0
+workflow: .torusguard/workflows/ocr-scan.md
+tools: Read, Grep, Glob, Write, run_command
+scripts-binding:
+  - internal/scanner/ocr.go
+  - cmd/torusguard/main.go
+---
+
+# TorusGuard OCR Vision Scan — Multi-Modal Secret Extraction
+
+## Objective
+Detect optical leaks of private API keys, AWS credentials, database URIs, GitHub personal access tokens, and private certificates embedded inside visual artifacts (PNG, JPG, WebP, BMP, TIFF) up to 10MB using Tesseract OCR and deterministic regex signatures.
+
+---
+
+## Tri-Mode Execution
+
+### Mode A: Automated CLI Execution
+Run OCR scanning against a single diagram file or an entire directory of visual assets:
+```bash
+# Scan a specific architecture diagram or screenshot
+torusguard ocr-scan docs/architecture/diagram.png
+
+# Scan an entire directory of media assets
+torusguard ocr-scan ./assets/images/
+```
+
+### Mode B: In-Session AI Chat Slash Command
+Run `/torusguard ocr-scan <path>` in chat.
+The agent invokes the native Go scanner or MCP tool to extract optical text, analyze credential patterns, and report leaked keys.
+
+### Mode C: Native MCP Tool Call
+MCP-enabled coding agents (Antigravity, Cursor, Windsurf, Claude Code) call:
+```json
+{
+  "tool": "torusguard_ocr_scan",
+  "arguments": {
+    "target": "docs/architecture/cloud-architecture.png",
+    "max_image_mb": 10
+  }
+}
+```
+
+---
+
+## Supported Patterns & Invariants
+- **TG-SEC-001:** Hardcoded API Keys / Tokens / OpenAI & Stripe Keys (`sk-live-...`, `sk-...`).
+- **TG-SEC-002:** AWS Access Key IDs (`AKIA[0-9A-Z]{16}`).
+- **TG-SEC-003:** GitHub Personal Access Tokens (`ghp_...`, `github_pat_...`).
+- **TG-SEC-004:** Database Connection URIs (`postgres://user:pass@host:5432/db`).
+- **TG-SEC-005:** Private Key Headers (`-----BEGIN RSA PRIVATE KEY-----`).
+- **TG-SEC-007:** Password assignments (`password = "..."`).
+- **10MB DoS Guard:** Files exceeding 10MB are rejected fail-closed to prevent resource exhaustion attacks.
+
+---
+
+## 🏛️ OpenCodeReview Hybrid Architecture Integration
+- **Deterministic OCR Preprocessing:** Optical extraction and regex pattern matching run entirely in compiled Go code without LLM hallucination.
+- **Token Efficiency:** Only the extracted text and detected secret matches are emitted to the agent context (zero token waste on binary image blobs).
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Reading Binary Images as Text** | Attempts to read raw `.png` or `.jpg` with `view_file` as utf-8 text. | Invoke `torusguard ocr-scan` or `torusguard_ocr_scan` to perform OCR. |
+| **Ignoring Image File Size Bounds** | Tries to OCR multi-hundred megabyte video files or giant raw images. | Adhere to the 10MB DoS boundary (`DefaultMaxImageSize`). |
+| **Echoing Full Leaked Secrets in Logs** | Prints live production credentials unredacted in terminal output or reports. | Partially redact sensitive tokens (e.g. `sk-live-****3211`). |
+| **Assuming Images Don't Contain Secrets** | Audits only `.go` or `.js` code and ignores cloud diagrams or screenshots. | Always run OCR vision scan across image directories during full audits. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before concluding an OCR inspection, verify:
+- [ ] Is Tesseract installed and discoverable on PATH?
+- [ ] Are all target files valid image formats (`.png`, `.jpg`, `.jpeg`, `.webp`, `.bmp`, `.tiff`)?
+- [ ] Are target image file sizes strictly $\le 10$ MB?
+- [ ] Did I check against all 7 canonical secret signatures (`TG-SEC-001` through `TG-SEC-007`)?
+- [ ] Are confirmed leaks documented in `security_report.md` with remediation steps?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY: Confirm target image existence and size <= 10MB.
+BUILD:  Execute torusguard ocr-scan or torusguard_ocr_scan to extract optical text.
+CONFIRM: Match text against OCRSecretPattern signatures, redact sensitive tokens, and record in security_report.md.
+```