torusguard 2.0.0-alpha → 2.1.0

package/skills/torusguard-status/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: torusguard-status
 description: Display current TorusGuard security posture, active configuration, rules catalog, and run history via CLI or AI Agent.
-version: 1.3.6
+version: 2.0.0
 workflow: .torusguard/workflows/status.md
 tools: Read, Grep, Glob, run_command, Write
 scripts-binding:
+  - internal/scanner/scanner.go
   - .torusguard/scripts/report_sync.py
   - .torusguard/scripts/run_manager.py
-  - .torusguard/scripts/term_ui.py
 ---
 
 # TorusGuard Status — Workspace Security Posture & Diagnostic Overview
@@ -17,23 +17,34 @@ Provide an instant diagnostic summary of the repository's security state, active
 
 ---
 
-## Two Execution Modes
+## Tri-Mode Parity
+
+| Mode | Command / Tool | Governed Behavior |
+| :--- | :--- | :--- |
+| **Mode A: CLI Terminal** | `torusguard status` | Emits 75-column diagnostic cards with stack, posture, and active rules. |
+| **Mode B: AI Chat Slash** | `/torusguard status` | Parses workspace posture, reviews latest run manifest and open findings. |
+| **Mode C: Native MCP Tool**| `torusguard_status` | Returns structured diagnostic payload directly to AI coding agents. |
+
+---
+
+## Tri-Mode Execution
 
 ### Mode A: Automated CLI Execution
 Run the diagnostic overview from your terminal:
 ```bash
 # Display 75-column status cards
-npx torusguard status
+torusguard status
 
 # Check status of specific project directory
-npx torusguard status ./examples/vulnerable-react-express
+torusguard status ./examples/vulnerable-react-express
 
 # Output machine-readable JSON
-npx torusguard status --json
+torusguard status --json
 ```
+
 **Under the Hood:**
 - Evaluates `.torusguard/config/torusguard.json` for initialized status and detected stack.
-- Enumerates active rules in `.torusguard/rules/active/` (or canonical 74 rules).
+- Enumerates active rules in `.torusguard/rules/active/` (or canonical 74 rules across 18 families).
 - Scans `.torusguard/runs/` for run history, finding counts, and verified fixes.
 - Inspects `.torusguard/config/scope.json` for authorized runtime validation targets.
 - Displays mathematically aligned 75-column terminal cards.
@@ -43,15 +54,26 @@ When checking workspace status in AI chat:
 1. **Verify Workspace Setup:** Check if `.torusguard/` exists on disk.
 2. **Inspect Active Config:** Read `.torusguard/config/torusguard.json` for detected stack, framework, and rules.
 3. **Inspect Latest Run:** Find the latest run directory under `.torusguard/runs/` and read `manifest.json`.
-4. **Inspect Memory Engine:** Check `.torusguard/memory/patterns.json` for captured Golden Fix Recipes.
-5. **Render Diagnostic Card:** Present an overview of posture, stack, and recommended next steps.
+4. **Inspect Living Ledger:** Inspect `security_report.md` for current open/fixed finding counts.
+5. **Inspect Memory Engine:** Check `.torusguard/memory/patterns.json` for captured Golden Fix Recipes.
+6. **Render Diagnostic Card:** Present an overview of posture, stack, and recommended next steps.
+
+### Mode C: Native MCP Tool Execution
+For autonomous AI coding agents (Antigravity, Cursor, Windsurf, Claude Code):
+- **Tool Invocation:** Call `torusguard_status` with target directory:
+  ```json
+  {
+    "target": "."
+  }
+  ```
+- **Programmatic Return:** Receives formatted diagnostic status string detailing detected stack, engine version, and active protection state.
 
 ---
 
 ## Output Card Format
 ```markdown
 ### 🛡️ TorusGuard Workspace Status Overview
-- **Version:** v1.3.3 | **Stack:** Node.js / React / Express
+- **Version:** v2.0.0 | **Stack:** Node.js / React / Express
 - **Active Rules:** 74 canonical security rules enabled
 - **Historical Runs:** 3 runs recorded
 - **Golden Recipes:** 4 distilled into persistent memory
@@ -60,3 +82,34 @@ When checking workspace status in AI chat:
 
 ## Living Report Ground Truth
 - Read `security_report.md` in the workspace root before taking any action. Update the relevant finding card after completing remediation.
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Hallucinated Posture** | Reports repository is "100% secure" without reading `security_report.md` or `.torusguard/config/torusguard.json`. | Read actual disk artifacts (`security_report.md`, `manifest.json`) before reporting status. |
+| **Phantom Run Counts** | Fabricates arbitrary run IDs or counts instead of checking `.torusguard/runs/`. | Enumerate `.torusguard/runs/` directories or use `torusguard status` CLI/MCP output. |
+| **Stack Guessing** | Assumes project stack without inspecting package manifests (`go.mod`, `package.json`, `Cargo.toml`). | Verify detected stack from `torusguard.json` or root dependency files. |
+| **Stale Cache Reliance** | Reports previous conversation status after new files or patches were applied. | Perform fresh inspection of workspace status on each invocation. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before emitting a status report:
+- [ ] Did I verify the existence and content of `.torusguard/config/torusguard.json`?
+- [ ] Did I check `security_report.md` for active finding counts?
+- [ ] Did I verify if `.torusguard/runs/` contains historical run data?
+- [ ] Are all reported counts and stack frameworks backed by active disk state?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY:  Check disk for .torusguard/ directory and read configuration files.
+BUILD:   Aggregate stack information, active rules, and latest run findings.
+CONFIRM: Emit standardized 75-column diagnostic summary card with recommended next steps.
+```

package/skills/torusguard-verify/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: torusguard-verify
 description: Verify finding evidence sufficiency, audit live code line matches, and calibrate 0–100 confidence scores.
-version: 1.3.6
+version: 2.0.0
 workflow: .torusguard/workflows/verify.md
 tools: Read, Grep, Glob, Write, run_command
 scripts-binding:
+  - internal/scanner/scanner.go
   - .torusguard/scripts/report_sync.py
   - .torusguard/scripts/finding_scorer.py
 ---
@@ -16,22 +17,31 @@ Audit the evidence sufficiency of candidate findings by reading current disk lin
 
 ---
 
+## Tri-Mode Parity
+
+| Mode | Command / Tool | Governed Behavior |
+| :--- | :--- | :--- |
+| **Mode A: CLI Terminal** | `torusguard verify` | Verifies evidence across findings on disk, asserts line matches. |
+| **Mode B: AI Chat Slash** | `/torusguard verify` | Performs live code inspection, audits source-to-sink taint flows. |
+| **Mode C: Native MCP Tool**| `torusguard_audit` / verify | Diagnostic validation of candidate security findings. |
+
+---
+
 ## Execution Steps
 
-1. **Locate Target Findings:** Load active findings from `.torusguard/runs/<latest-run>/findings.md`.
-2. **Handle CLI Failures:** If `python .torusguard/scripts/finding_scorer.py` or the verify workflow fails, YOU must manually read the code and calibrate the score based on the evidence parameters.
-3. **Live Disk Line Match:** Inspect exact cited lines using `view_file` to confirm code presence.
-4. **Audit Evidence Sufficiency:** Verify source-to-sink flow against criteria below.
-5. **Calibrate Confidence Score:**
+1. **Locate Target Findings:** Load active findings from `security_report.md` or `.torusguard/runs/<latest-run>/findings.md`.
+2. **Live Disk Line Match:** Inspect exact cited lines using `view_file` to confirm code presence on disk. Do not rely on stale line numbers.
+3. **Audit Evidence Sufficiency:** Verify source-to-sink flow against criteria below.
+4. **Calibrate Confidence Score:**
    ```bash
-   python .torusguard/scripts/finding_scorer.py --run <run_dir> --verify
+   torusguard verify
    ```
-6. **Update State:** Mark finding as `Confirmed`, `Needs Review`, or `False Positive`.
-7. **Emit Verified Evidence:** Save report in `.torusguard/runs/<run_id>/verified-evidence.md`.
+5. **Update State:** Mark finding as `Confirmed`, `Needs Review`, or `False Positive`.
+6. **Emit Verified Evidence:** Save report in `.torusguard/runs/<run_id>/verified-evidence.md`.
 
 ---
 
-## Evidence Sufficiency
+## Evidence Sufficiency Rubric
 A finding is verified as sufficient when:
 - **Direct AST Match:** The vulnerable API or sink call exists on disk at the cited location.
 - **Exposed Surface:** The sink is reachable from an external route, view, or public method.
@@ -59,3 +69,35 @@ A finding is verified as sufficient when:
 - Artifact: `.torusguard/runs/<run_id>/verified-evidence.md`
 Next: Run `/torusguard harden` to formulate surgical fixes for confirmed flaws.
 ```
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Stale Line Reliance** | Assumes finding line number matches current disk state without inspecting active file. | Read live disk lines via `view_file` to verify the exact AST sink is located at that line. |
+| **Sanitizer Blindness** | Flags parameterized queries or sanitized inputs as SQLi because raw SQL keywords exist. | Inspect surrounding lines ($\pm 3$) for parameter bindings (`?`, `$1`, prep statements) or sanitizers. |
+| **Test Fixture Confusion** | Confirms vulnerabilities inside mock test files or test suites as production risks. | Check file path against test exclusion patterns (`_test.go`, `.test.ts`, `fixtures/`). Test vulnerabilities must be contextualized or ignored. |
+| **Hallucinated Reachability** | Confirms private internal functions with no external caller as exploitable web attack surfaces. | Verify if the tainted source is actually reachable from public handlers or API routes. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before calibrating or confirming any finding:
+- [ ] Did I read the live file content directly from disk?
+- [ ] Did I verify the exact cited code exists and matches the AST rule pattern?
+- [ ] Did I check for neutralizing middleware, sanitizers, or parameterization in the context window?
+- [ ] Did I verify that the file is not an excluded test fixture or mock?
+- [ ] Is the confidence score (0-100) calibrated against real evidence, not assumptions?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY:  Read cited file lines on disk to verify presence of the reported sink.
+BUILD:   Trace source-to-sink flow and check for existing sanitizers or validators.
+CONFIRM: Calibrate confidence score and record verified status in security_report.md.
+```

package/skills/torusguard-web-validate/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: torusguard-web-validate
 description: Execute authorized HTTP probing against local/staging web applications — session capture, transparent audit headers, and secret redaction.
-version: 1.3.6
+version: 2.0.0
 workflow: .torusguard/workflows/web-validate.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
 ---
@@ -16,16 +17,27 @@ Safely probe live web applications within authorized scope, injecting transparen
 
 ---
 
+## Tri-Mode Parity
+
+| Mode | Command / Tool | Governed Behavior |
+| :--- | :--- | :--- |
+| **Mode A: CLI Terminal** | `torusguard web-validate` | Dispatches bounded HTTP probes with transparent audit headers and redaction. |
+| **Mode B: AI Chat Slash** | `/torusguard web-validate` | Interactive verification of endpoints, security headers, and cookie flags. |
+| **Mode C: Native MCP Tool**| — | Safe runtime execution guarded by scope.json boundaries. |
+
+---
+
 ## Authorization Gate Check
 Before dispatching any HTTP request:
 1. Verify `.torusguard/config/scope.json` exists and contains target URL.
 2. Confirm current timestamp is prior to `expires_at` TTL.
 3. Assert target is local or non-production staging.
+4. **SSRF Boundary Enforcement:** Resolve target IP and assert it does not target cloud metadata endpoints (`169.254.169.254`) or unintended internal subnets (`127.0.0.1` unless explicitly authorized as local dev).
 
 ---
 
 ## Safety Gate
-All requests pass through `.torusguard/scripts/safety_gate.py`:
+All requests pass through safety boundary checks:
 - `Auto-Allowed`: Read-only `GET`, `HEAD`, `OPTIONS` on non-sensitive paths.
 - `Approval Required`: Requests touching auth, sessions, or parameters.
 - `Manual Only`: Any destructive method (`DELETE`, `DROP`) is strictly blocked.
@@ -34,13 +46,15 @@ All requests pass through `.torusguard/scripts/safety_gate.py`:
 
 ## Execution Steps
 
-1. **Gate Check:** Validate scope in `scope.json` and query `safety_gate.py`.
-2. **Handle Automation Failure:** If automated web validation scripts fail, YOU must manually construct the HTTP requests (using `curl` or `fetch`) and inspect the responses.
+1. **Gate Check:** Validate scope in `scope.json`.
+2. **Execute Probe:**
+   ```bash
+   torusguard web-validate --target http://localhost:3000
+   ```
 3. **Inject Audit Header:** Attach `X-TorusGuard-AuthID: <auth_id>` to all outbound requests.
-4. **Dispatch Bounded Probe:** Send single non-destructive HTTP request.
-5. **Validate Security Headers:** Check for CSP, HSTS, X-Content-Type-Options, and CORS configurations.
-6. **Audit Cookie Flags:** Verify `HttpOnly`, `Secure`, and `SameSite` on session cookies.
-7. **Capture Replay Trace:** Save sanitized trace in `.torusguard/runs/<run_id>/requests.json`.
+4. **Validate Security Headers:** Check for CSP, HSTS, X-Content-Type-Options, and CORS configurations.
+5. **Audit Cookie Flags:** Verify `HttpOnly`, `Secure`, and `SameSite` on session cookies.
+6. **Capture Replay Trace:** Save sanitized trace in `.torusguard/runs/<run_id>/requests.json`.
 
 ---
 
@@ -68,3 +82,34 @@ All Bearer tokens, cookies, passwords, and API keys are redacted prior to disk s
 - Replay Trace: `.torusguard/runs/<run_id>/requests.json`
 Next: Run `/torusguard exploit-check` to confirm exploitability of candidate flaws.
 ```
+
+---
+
+## 🚨 LLM Trap Table
+
+| Pattern | What AI Does Wrong | What Is Actually Correct |
+| :--- | :--- | :--- |
+| **Scope Bypass Probing** | Sends HTTP requests to arbitrary endpoints without validating `.torusguard/config/scope.json`. | Check `scope.json` and verify TTL before every outbound probe. |
+| **Token Exposure in Traces** | Writes unredacted `Authorization: Bearer <secret>` or session cookies to `requests.json`. | Redact all credentials to `[REDACTED]` before saving traces to disk. |
+| **SSRF Blindness** | Follows redirects or probes endpoints pointing to AWS/GCP metadata (`169.254.169.254`). | Block private IP ranges and metadata addresses under invariant 9. |
+| **Unbounded Flooding** | Launches high-concurrency request loops or stress tests against local dev server. | Enforce rate limiting and cap session probes to maximum 50 requests. |
+
+---
+
+## ✅ Pre-Flight Self-Audit
+
+Before dispatching web probes:
+- [ ] Is the target URL verified inside `scope.json` and within valid TTL?
+- [ ] Are transparent audit headers (`X-TorusGuard-AuthID`) attached?
+- [ ] Are destructive operations (`DELETE`, drops) blocked?
+- [ ] Are sensitive tokens and cookies redacted from trace logs?
+
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY:  Check scope.json validity, TTL, and SSRF boundaries for the target URL.
+BUILD:   Construct bounded HTTP request with X-TorusGuard-AuthID audit header.
+CONFIRM: Redact sensitive tokens and save sanitized trace into requests.json.
+```