torusguard 1.4.0 → 2.0.0-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/.torusguard/auth.json +5 -0
  2. package/.torusguard/rules_catalog.json +242 -518
  3. package/.torusguard/scripts/__pycache__/apply_runner.cpython-314.pyc +0 -0
  4. package/.torusguard/scripts/__pycache__/audit_runner.cpython-314.pyc +0 -0
  5. package/.torusguard/scripts/__pycache__/harden_runner.cpython-314.pyc +0 -0
  6. package/.torusguard/scripts/__pycache__/html_reporter.cpython-314.pyc +0 -0
  7. package/.torusguard/scripts/__pycache__/manifest_builder.cpython-314.pyc +0 -0
  8. package/.torusguard/scripts/__pycache__/recipes_runner.cpython-314.pyc +0 -0
  9. package/.torusguard/scripts/__pycache__/report_sync.cpython-314.pyc +0 -0
  10. package/.torusguard/snapshots/20260921-182638/go.mod.bak +11 -0
  11. package/.torusguard/snapshots/20260921-185213/file.go.bak +5 -0
  12. package/README.md +315 -393
  13. package/package.json +1 -1
  14. package/skills/torusguard/__pycache__/bootstrap.cpython-314.pyc +0 -0
  15. package/skills/torusguard/payload/TORUSGUARD.md +145 -145
  16. package/skills/torusguard/payload/agents/auditor.md +41 -41
  17. package/skills/torusguard/payload/agents/profiler.md +49 -49
  18. package/skills/torusguard/payload/agents/remediator.md +41 -41
  19. package/skills/torusguard/payload/agents/reviewer.md +39 -39
  20. package/skills/torusguard/payload/agents/validator.md +46 -46
  21. package/skills/torusguard/payload/config/scope.json +24 -24
  22. package/skills/torusguard/payload/references/csharp-security.md +41 -41
  23. package/skills/torusguard/payload/references/go-security.md +41 -41
  24. package/skills/torusguard/payload/references/java-security.md +40 -40
  25. package/skills/torusguard/payload/references/polyglot-security-matrix.md +25 -25
  26. package/skills/torusguard/payload/references/rust-security.md +40 -40
  27. package/skills/torusguard/payload/rules/custom/.gitkeep +1 -1
  28. package/skills/torusguard/payload/rules/custom/README.md +30 -30
  29. package/skills/torusguard/payload/scripts/rules_sync.py +321 -321
  30. package/skills/torusguard/payload/scripts/safety_gate.py +64 -64
  31. package/skills/torusguard/payload/skills/torusguard/references/csharp-security.md +41 -41
  32. package/skills/torusguard/payload/skills/torusguard/references/go-security.md +41 -41
  33. package/skills/torusguard/payload/skills/torusguard/references/java-security.md +40 -40
  34. package/skills/torusguard/payload/skills/torusguard/references/polyglot-security-matrix.md +25 -25
  35. package/skills/torusguard/payload/skills/torusguard/references/rust-security.md +40 -40
  36. package/skills/torusguard/payload/templates/audit-report.template.md +54 -54
  37. package/skills/torusguard/payload/templates/authorization.template.md +34 -34
  38. package/skills/torusguard/payload/templates/finding-card.template.md +32 -32
  39. package/skills/torusguard/payload/templates/remediation-bundle.template.md +35 -35
package/README.md CHANGED
@@ -1,504 +1,426 @@
1
- <div align="center">
2
- <img src="TorusGuard.png" alt="TorusGuard Autonomous Security Engine Banner" width="560" style="max-width: 100%; height: auto; border-radius: 12px; box-shadow: 0 10px 30px rgba(0,0,0,0.5);">
3
-
4
- # TorusGuard
5
-
6
- ### Autonomous Security Guardrails, Governed Remediation & Living Verification for AI-Built Applications
7
-
8
- <p align="center">
9
- <strong>Zero Telemetry · Zero External Python Dependencies · Pure Standard-Library Architecture · 100% Local-First</strong>
10
- </p>
11
-
12
- [![npm version](https://img.shields.io/badge/npm-v1.4.0-cb3837.svg?style=flat-square&logo=npm)](https://www.npmjs.com/package/torusguard)
13
- [![GitHub Packages](https://img.shields.io/badge/GitHub%20Packages-v1.4.0-181717.svg?style=flat-square&logo=github)](https://github.com/githubmofo/TorusGuard/pkgs/npm/torusguard)
14
- [![Release](https://img.shields.io/badge/Release-v1.4.0-blue.svg?style=flat-square)](https://github.com/githubmofo/TorusGuard/releases/latest)
15
- [![Tests](https://img.shields.io/badge/Tests-133%2F133%20Passing-brightgreen.svg?style=flat-square)](harness/runner.py)
16
- [![Security Health](https://img.shields.io/badge/Health%20Score-100%2F100%20Hardened-brightgreen.svg?style=flat-square)](security_report.md)
17
- [![Rules Catalog](https://img.shields.io/badge/Rules%20Catalog-74%20Rules%20%7C%2018%20Families-indigo.svg?style=flat-square)](rules/)
18
- [![Terminal Standard](https://img.shields.io/badge/Terminal-75--col%20Standard-informational.svg?style=flat-square)](.torusguard/scripts/term_ui.py)
19
- [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
20
- [![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B%20(Zero%20Deps)-blue.svg?style=flat-square&logo=python&logoColor=white)](https://python.org)
21
- [![Go 1.22+](https://img.shields.io/badge/Go-1.22%2B-00ADD8.svg?style=flat-square&logo=go&logoColor=white)](https://go.dev)
22
- [![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-339933.svg?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
23
- [![SARIF: v2.1.0](https://img.shields.io/badge/SARIF-v2.1.0%20OASIS-purple.svg?style=flat-square)](.torusguard/schemas/)
24
- [![OWASP: Top 10](https://img.shields.io/badge/OWASP-Top%2010%20Aligned-orange.svg?style=flat-square)](docs/architecture/SECURITY_ARCHITECTURE.md)
25
- [![Privacy](https://img.shields.io/badge/Privacy-100%25%20Local%20Zero--Egress-success.svg?style=flat-square)](docs/overview/security-philosophy.md)
26
- </div>
1
+ <p align="center">
2
+ <img src="TorusGuard.png" alt="TorusGuard Logo" width="200" />
3
+ </p>
4
+
5
+ <h1 align="center">TorusGuard</h1>
6
+
7
+ <p align="center">
8
+ <strong>The Hybrid Governance Security Engine for AI-built web applications.</strong><br>
9
+ <em>Pairs the intelligence of your AI Agent with a deterministic Go CLI to enforce strict security boundaries and patch limits.</em>
10
+ </p>
11
+
12
+ <p align="center">
13
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
14
+ <a href="https://github.com/githubmofo/TorusGuard/releases"><img src="https://img.shields.io/badge/version-2.0.0--alpha-orange.svg" alt="Version"></a>
15
+ <a href="https://www.npmjs.com/package/torusguard"><img src="https://img.shields.io/badge/npm-v2.0.0--alpha-CB3837?logo=npm&logoColor=white" alt="npm: v2.0.0-alpha"></a>
16
+ <img src="https://img.shields.io/badge/Privacy-Local_First-success" alt="Privacy: Local First">
17
+ <img src="https://img.shields.io/badge/Dependencies-Zero-brightgreen" alt="Dependencies: Zero">
18
+ <img src="https://img.shields.io/badge/SARIF-v2.1.0-6C3483" alt="SARIF">
19
+ <img src="https://img.shields.io/badge/OWASP-Top_10-000000?logo=owasp&logoColor=white" alt="OWASP">
20
+ </p>
21
+
22
+ <p align="center">
23
+ <img src="https://img.shields.io/badge/Unit%20Tests-100%25%20Passing-brightgreen?logo=go&logoColor=white" alt="Unit Tests: 100% Passing">
24
+ <img src="https://img.shields.io/badge/Polyglot%20Tests-36%2F36%20Repos%20Passed-brightgreen?logo=checkmarx&logoColor=white" alt="Polyglot Tests: 36/36 Repos Passed">
25
+ <img src="https://img.shields.io/badge/Tri--Mode%20E2E-16%2F16%20Verified-blue?logo=checkmarx&logoColor=white" alt="Tri-Mode E2E: 16/16 Verified">
26
+ <img src="https://img.shields.io/badge/Vision%20OCR-Tested%20%26%20Verified-blueviolet?logo=tesseract&logoColor=white" alt="Vision OCR: Tested & Verified">
27
+ <img src="https://img.shields.io/badge/Rules%20Verified-74%2F74%20Rules-success" alt="Rules: 74/74 Verified">
28
+ </p>
29
+
30
+ <p align="center">
31
+ <img src="https://img.shields.io/badge/Tri--Mode-CLI%20%7C%20Chat%20%7C%20MCP-blue" alt="Tri-Mode Parity">
32
+ <img src="https://img.shields.io/badge/Go-1.25-00ADD8?logo=go&logoColor=white" alt="Go">
33
+ <img src="https://img.shields.io/badge/Node.js-18+-339933?logo=nodedotjs&logoColor=white" alt="Node.js">
34
+ <img src="https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white" alt="Python">
35
+ <img src="https://img.shields.io/badge/TypeScript-5.0+-3178C6?logo=typescript&logoColor=white" alt="TypeScript">
36
+ <img src="https://img.shields.io/badge/Rust-2021-DEA584?logo=rust&logoColor=white" alt="Rust">
37
+ </p>
27
38
 
28
39
  ---
29
40
 
30
- > **The Developer Reality:** AI coding assistants (Cursor, Claude Code, Copilot, Windsurf, Antigravity) build software at superhuman speed, but routinely leak private keys into client bundles, drop tenant partition filters, or inject raw user input into LLM system prompts.
31
- > **TorusGuard forms an unbroken local guardrail around your codebase.** It audits static ASTs across 74 rules, runtime-verifies exploitability with inert canaries, synthesizes minimal surgical diffs adhering to the **Ponytail Protocol** ($\le 35$ additions, $\le 25$ deletions), and eliminates hallucinations by maintaining a verifiable single source of truth in `security_report.md`.
41
+ ## Table of Contents
42
+
43
+ - [What Is TorusGuard?](#what-is-torusguard)
44
+ - [Features](#-features)
45
+ - [Autonomous Architecture](#-autonomous-architecture)
46
+ - [Prerequisites](#-prerequisites)
47
+ - [Installation](#-installation)
48
+ - [Usage](#-usage)
49
+ - [Commands](#-commands)
50
+ - [Project Structure](#-project-structure)
51
+ - [Security Rules (74 Rules, 18 Families)](#-security-rules-74-rules-18-families)
52
+ - [AI Agent Integration](#-ai-agent-integration)
53
+ - [Verified Test Suite & Benchmarks](#-verified-test-suite--mass-benchmarks)
54
+ - [Non-Negotiable Invariants](#-non-negotiable-invariants)
55
+ - [Contributing](#-contributing)
56
+ - [License](#-license)
57
+ - [Documentation](#-documentation)
32
58
 
33
59
  ---
34
60
 
35
- ## 📑 Table of Contents
36
-
37
- 1. [Developer Overview & Value Proposition](#-developer-overview--value-proposition)
38
- 2. [End-to-End Autonomous Architecture](#-end-to-end-autonomous-architecture)
39
- 3. [Why TorusGuard? (Traditional SAST vs. AI Coding vs. TorusGuard)](#-why-torusguard)
40
- 4. [Installation & Setup Guide (npm, Go & CLI)](#-installation--setup-guide-npm-go--cli)
41
- 5. [Quickstart: The 5-Step Core Lifecycle](#-quickstart-the-5-step-core-lifecycle)
42
- 6. [Dual-Strategy Command Matrix (CLI & AI Chat Parity)](#-dual-strategy-command-matrix-cli--ai-chat-parity)
43
- 7. [Polyglot Go Engine & Native Runner](#-polyglot-go-engine--native-runner)
44
- 8. [Package Self-Update Engine (`update`)](#-package-self-update-engine-update)
45
- 9. [74 Canonical Security Rules Catalog (18 Families Across 6 Pillars)](#-74-canonical-security-rules-catalog-18-families-across-6-pillars)
46
- 10. [Ponytail Remediation Protocol & Rollback Safety](#-ponytail-remediation-protocol--rollback-safety)
47
- 11. [Living Security Report Ground Truth (`security_report.md`)](#-living-security-report-ground-truth-security_reportmd)
48
- 12. [Visual HTML Dashboard & SARIF v2.1.0 Export](#-visual-html-dashboard--sarif-v210-export)
49
- 13. [AI Editor Guardrails Auto-Sync](#-ai-editor-guardrails-auto-sync)
50
- 14. [Monorepo Fleet Support & Git Pre-Commit Diff Guard](#-monorepo-fleet-support--git-pre-commit-diff-guard)
51
- 15. [Verification & Test Harness (133/133 Passing Harness Explained)](#-verification--test-harness)
52
- 16. [Security Policy & Responsible Disclosure](#-security-policy--responsible-disclosure)
53
- 17. [License](#-license)
61
+ ## What Is TorusGuard?
54
62
 
55
- ---
63
+ TorusGuard is a **zero-dependency, single-binary security engine** that scans, hardens, and validates AI-generated codebases. It enforces 74 security rules across 18 architectural families and works in two complementary modes:
56
64
 
57
- ## 💡 Developer Overview & Value Proposition
65
+ - **CLI Mode (Go Binary)** — A deterministic scanner and enforcer that runs in your terminal or CI/CD pipeline.
66
+ - **AI Agent Mode** — Integrates natively with Antigravity, Cursor, Claude Code, Windsurf, VS Code, and other AI coding assistants via slash commands.
58
67
 
59
- When developers use AI coding agents to write features, models optimize for *getting the code to run* rather than *defensive architecture*. Common failure modes include:
60
- - **Exposing Private Credentials:** Leaking `process.env.SUPABASE_SERVICE_ROLE_KEY` or master database connection strings into Next.js `'use client'` bundles.
61
- - **Dropping Tenant Boundaries:** Querying Prisma or Mongoose by record ID without scoping by tenant (`where: { id }` instead of `where: { id, tenantId }`).
62
- - **Prompt Injection Vulnerabilities:** Interpolating untrusted user chat messages directly into system prompts.
63
- - **Destructive AI Rewrites:** When asked to fix a minor bug, AI models rewrite entire 500-line files, introducing fresh regressions and breaking surrounding business logic.
68
+ TorusGuard ensures that the code your AI assistant writes is secure *before* it reaches production.
64
69
 
65
- **TorusGuard solves this deterministically:**
66
- - **Zero-Egress Local Execution:** 100% of scanning and patching happens on your machine. Zero code or tokens are transmitted to external servers.
67
- - **Zero Pip Dependencies:** Pure Python standard library (`pathlib`, `re`, `json`, `difflib`, `shutil`). No virtualenv conflicts or broken build wheels.
68
- - **Ponytail Churn Bounds:** Patches are constrained strictly to $\le 35$ additions and $\le 25$ deletions. Surrounding business logic is never rewritten.
69
- - **Human Gate & Instant Undo:** Every change requires interactive approval with syntax-highlighted diffs, backed up byte-for-byte in `.torusguard/snapshots/` with instant 1-command rollback.
70
+ ---
70
71
 
71
- ### 🌐 The Browser-Code Truth Invariant
72
- > **"If the browser receives it, users can inspect it via DevTools."**
73
- > Frontend environment variables, client JavaScript bundles, and React Server Action payloads cannot conceal secrets. TorusGuard strictly enforces that database credentials, service role keys, private API secrets, and tenant boundaries remain exclusively on trusted server runtimes.
72
+ ## ✨ Features
73
+
74
+ - **74 Security Rules** across 18 families (Secrets, Auth, SQL Injection, SSRF, CSRF, GraphQL, Supply Chain, and more)
75
+ - **Heuristic AST Scanner** — Polyglot static analysis for Go, JavaScript, TypeScript, and Python
76
+ - **Ponytail Protocol** — Surgical patch bounds (≤35 additions, ≤25 deletions) to prevent full-file rewrites
77
+ - **Pre-Apply Snapshots** — Automatic `.bak` rollback snapshots before every code modification
78
+ - **SARIF v2.1.0 Export** — Standards-compliant output for GitHub Advanced Security, VS Code, and other SARIF consumers
79
+ - **Dark-Mode HTML Reports** — Single-file visual posture dashboards
80
+ - **Golden Fix Recipes** — Persistent memory of verified security patterns for reuse
81
+ - **SSRF Defense** — Built-in private IP blocking and AWS metadata protection in the web validator
82
+ - **Fail-Closed Cryptography** — No fallback tokens; panics on entropy failure
83
+ - **DoS Resilience** — 10,000-file scan limit and 5-minute context timeout to prevent resource exhaustion
84
+ - **16+ Language Stack Detection** — Go, Rust, Java, C#, PHP, Ruby, Kotlin, Elixir, Dart, Swift, Python, TypeScript, and more
85
+ - **Multi-Modal Vision OCR** — Scans architecture diagrams, mockups, and screenshots (`.png`, `.jpg`, `.webp`) via Tesseract OCR to detect leaked keys, tokens, and credentials
86
+ - **Native MCP Server (Model Context Protocol)** — Exposes standard JSON-RPC 2.0 stdio tools and resources for direct agent integration
87
+ - **Tri-Mode Parity** — Terminal CLI, AI Chat slash commands, and Native MCP Tools share identical governance workflows
74
88
 
75
89
  ---
76
90
 
77
- ## 📐 End-to-End Autonomous Architecture
91
+ ## 🧪 Proven Compatibility
78
92
 
79
- The following flowchart illustrates how TorusGuard safeguards your repository from initial developer input to verified, regression-free output:
93
+ TorusGuard’s static scanner and enforcement binary have been rigorously tested and confirmed compatible across **20 major technology stacks and frameworks**:
80
94
 
81
- ```mermaid
82
- flowchart TD
83
- subgraph In ["1. Workspace & AI Context"]
84
- A1["Polyglot Source Tree (16+ Languages)"]
85
- A2["AI Coding Assistant (Cursor / Claude / Antigravity)"]
86
- A3["Git Staged Diffs / Pre-Commit Hook"]
87
- end
95
+ | Ecosystem | Tested Frameworks & Runtimes |
96
+ |-----------|------------------------------|
97
+ | **JavaScript / TypeScript** | React, Next.js, Express, Vue, Angular, SvelteKit, NestJS |
98
+ | **Python** | Django, Flask, FastAPI, raw Python scripts |
99
+ | **Go** | Gin |
100
+ | **Java / C# (.NET)** | Spring Boot, ASP.NET Core, .NET Core Middleware |
101
+ | **Ruby** | Ruby on Rails, Sinatra |
102
+ | **PHP** | Laravel, Symfony |
103
+ | **Rust** | Actix Web |
88
104
 
89
- subgraph Core ["2. TorusGuard Engine (100% Local-First & Zero-Egress)"]
90
- direction TB
91
- B1["Static AST Engine: 74 Canonical Rules Across 18 Families"]
92
- B2["Living Ledger Sync: security_report.md (0-100 Score)"]
93
- B3["Ponytail Synthesizer: Minimal Surgical Diffs (&le;35 Add / &le;25 Del)"]
94
- B4["Pre-Apply Snapshot Engine: Byte-for-Byte .bak Backups"]
95
- B5["Human Gate: Interactive Syntax-Highlighted Approval"]
96
- B6["Targeted Differential Re-Scan: Confirmed Fixed State"]
105
+ ---
97
106
 
98
- B1 --> B2 --> B3 --> B4 --> B5 --> B6
99
- end
107
+ ## 🏗️ Autonomous Architecture
100
108
 
101
- subgraph Out ["3. Verified Deliverables & Artifacts"]
102
- C1["Hardened Production Code (Zero Regressions)"]
103
- C2["Self-Contained Dark-Mode HTML Dashboard"]
104
- C3["OASIS SARIF v2.1.0 for CI/CD Pipeline"]
105
- C4["Auto-Synced AI Rules (.cursorrules, CLAUDE.md, etc.)"]
106
- end
109
+ TorusGuard uses a **tri-track architecture** where intelligence, deterministic enforcement, and agent tool execution are cleanly separated across three unified operational modes:
107
110
 
108
- In --> Core --> Out
111
+ ```mermaid
112
+ flowchart TD
113
+ User([Developer / CI / AI Coding Assistant])
114
+
115
+ User --> ModeA[Mode A: Terminal CLI<br/><code>torusguard &lt;cmd&gt;</code><br/>Deterministic Go Binary]
116
+ User --> ModeB[Mode B: AI Chat Slash Command<br/><code>/torusguard &lt;cmd&gt;</code><br/>Chat Prompt & Workflow Bridge]
117
+ User --> ModeC[Mode C: Native MCP Protocol<br/><code>torusguard_audit / ocr_scan</code><br/>Stdio JSON-RPC 2.0 Agent Tools]
118
+
119
+ ModeA --> Router[Command Router & Dispatcher<br/>cmd/torusguard]
120
+ ModeB --> Router
121
+ ModeC --> Router
122
+
123
+ Router --> Engine
124
+
125
+ subgraph Engine[TorusGuard Core Engine]
126
+ Scanner[Polyglot AST & Heuristic Scanner<br/>74 Rules across 18 Families]
127
+ OCR[Multi-Modal Vision OCR Engine<br/>Tesseract Optical Analysis &le;10MB]
128
+ Harden[Harden Engine<br/>Ponytail Protocol &le;35 add, &le;25 del]
129
+ Apply[Snapshot & Apply Engine<br/>Byte-for-byte Rollback Backups]
130
+ Validate[Runtime Web Validator<br/>SSRF Defense & Audit Probing]
131
+ Recheck[Differential Recheck Engine<br/>Fix Closure Verification]
132
+ end
133
+
134
+ Engine --> Ledger[Living Security Ground Truth<br/><code>security_report.md</code>]
135
+ Engine --> Workspace[(.torusguard/ Workspace State<br/>rules/ &bull; schemas/ &bull; memory/ &bull; snapshots/)]
109
136
  ```
110
137
 
111
- ---
112
-
113
- ## ⚔️ Why TorusGuard?
138
+ **Key design decisions:**
139
+ - **Tri-Mode Parity:** The CLI (Mode A), Chat Slash Commands (Mode B), and Native MCP Tools (Mode C) share the exact same underlying governance and validation rules.
140
+ - **Multi-Modal Vision OCR:** Images, architecture diagrams, and screenshots are automatically scanned for leaked secrets using Tesseract OCR, bounded by strict 10MB memory safety limits.
141
+ - **Deterministic Enforcement:** The **Go binary** handles all deterministic operations (AST scanning, bounds checking, snapshotting, reporting).
142
+ - **AI Intelligence:** The **AI agent** handles intelligence-requiring tasks (patch generation, root-cause analysis, remediation formulation).
143
+ - **Living Ground Truth:** All modes synchronize with `security_report.md` to prevent finding drift or hallucination.
144
+ - **Zero-Bypass Guardrails:** Neither human nor AI can bypass Ponytail Protocol bounds (≤35 additions, ≤25 deletions) or the Human Gate before modifying code.
114
145
 
115
- | Security Dimension | Traditional SAST (SonarQube, Snyk) | Raw AI Coding Agents | TorusGuard v1.3.6 Engine |
116
- |:---|:---:|:---:|:---:|
117
- | **Target Architecture** | Human-written legacy codebases | High-churn AI code generation | **AI-built full-stack applications** |
118
- | **Remediation Model** | PDF reports & Jira tickets | Destructive full-file rewrites | **Ponytail Protocol** ($\le 35$ add, $\le 25$ del) |
119
- | **Fix Preservation** | None (scans from scratch) | Forgets context across chats | **Adaptive Security Memory** & Golden Recipes |
120
- | **Editor Sync** | Heavy background language daemons | Bloated prompt context ($> 2,000$ tokens) | **Stack-Adaptive Rules** ($\le 300$ prompt tokens) |
121
- | **Ground-Truth State** | External proprietary web dashboard | Ephemeral chat context (hallucinates) | **Living Security Ledger** (`security_report.md`) |
122
- | **Pre-Commit Defense** | Slow server-side webhooks | None (commits insecure code) | **Git Pre-Commit Diff Guard** ($< 200\text{ ms}$) |
123
- | **Privacy & Telemetry** | Cloud code upload / SaaS | Third-party cloud LLMs | **100% Local, Zero-Egress Guarantee** |
124
146
 
125
147
  ---
126
148
 
127
- ## 📦 Installation & Setup Guide (npm & CLI)
128
-
129
- TorusGuard is designed to be effortless to adopt in any project. There are no configuration servers, databases, or complex background daemons.
130
-
131
- ### 📋 Prerequisites
132
- - **Node.js:** 18.0.0 or higher
133
- - **Python:** 3.10 or higher (**Pure standard library** — **zero `pip` dependencies required**)
134
- - **Go (Optional):** 1.22 or higher (for native Go CLI compilation & Go module workflows)
149
+ ## 📋 Prerequisites
135
150
 
136
- > [!IMPORTANT]
137
- > **Zero Pip Dependencies Guarantee:** TorusGuard's core Python engine relies strictly on the Python standard library (`pathlib`, `re`, `json`, `difflib`, `shutil`, `sys`, `os`, `argparse`, `hashlib`). You **never** need to create a Python virtualenv (`venv`), run `pip install`, or configure external wheels. It works out of the box with your system Python.
151
+ - **Go 1.25+** (to build from source)
152
+ - **Git** (for `git apply` patch operations)
153
+ - **Node.js 18+** (for npm package installation)
138
154
 
139
155
  ---
140
156
 
141
- ### 1. Zero-Install Runner (Recommended)
142
- Run TorusGuard instantly in any repository without installing anything globally:
143
-
144
- ```bash
145
- # Run any command directly via npx
146
- npx torusguard init
147
- npx torusguard audit
148
- npx torusguard status
149
- npx torusguard update
150
- ```
157
+ ## 🚀 Installation
151
158
 
152
- ### 2. Project Dev Dependency
153
- Lock TorusGuard into your project's `package.json` for all team members and CI/CD pipelines:
159
+ ### Option 1: npm (Primary)
154
160
 
155
161
  ```bash
156
- npm install -D torusguard
157
- ```
158
-
159
- Add convenience scripts to your `package.json`:
160
- ```json
161
- {
162
- "scripts": {
163
- "security:audit": "torusguard audit",
164
- "security:harden": "torusguard harden",
165
- "security:recheck": "torusguard recheck",
166
- "security:status": "torusguard status",
167
- "security:update": "torusguard update"
168
- }
169
- }
162
+ npm install -g torusguard
170
163
  ```
171
164
 
172
- ### 3. Native Go CLI Runner
173
- For Go ecosystem developers, TorusGuard ships with a native Go runner module ([go.mod](go.mod)):
165
+ Or use directly without installing:
174
166
 
175
167
  ```bash
176
- # Run zero-dependency Go CLI entrypoint directly
177
- go run cmd/torusguard/main.go audit
178
-
179
- # Or install globally into your $GOPATH/bin
180
- go install github.com/torusguard/torusguard/cmd/torusguard@latest
181
- torusguard status
168
+ npx torusguard init
182
169
  ```
183
170
 
184
- ### 4. Global NPM Installation
185
- If you prefer having the `torusguard` binary available system-wide across all terminal sessions:
171
+ <a href="https://www.npmjs.com/package/torusguard">
172
+ <img src="https://img.shields.io/badge/npm-v2.0.0--alpha-CB3837?logo=npm&logoColor=white" alt="npm package">
173
+ </a>
174
+
175
+ ### Option 2: Build from Source (Recommended for Contributors)
186
176
 
187
177
  ```bash
188
- npm install -g torusguard
178
+ git clone https://github.com/githubmofo/TorusGuard.git
179
+ cd TorusGuard
180
+ go build -o torusguard ./cmd/torusguard
189
181
  ```
190
182
 
191
- ### 5. AI Agent Skill Installation
192
- Install TorusGuard as a native AI assistant skill for Cursor, Claude Code, Cline, or Antigravity:
183
+ ### Option 3: Go Install
193
184
 
194
185
  ```bash
195
- npx skills add torusguard
186
+ go install github.com/torusguard/torusguard/cmd/torusguard@latest
196
187
  ```
197
188
 
198
189
  ---
199
190
 
200
- ### 🔍 What Happens on First Run (`init`)
201
- When you execute `npx torusguard init` (or `npx torusguard init --template golang`) in your repository:
202
- 1. **Polyglot Profiling:** Automatically detects 16+ languages (Go, Rust, Java, C#, PHP, Python, TypeScript) and 30+ frameworks without manual configuration.
203
- 2. **Scaffolding:** Creates a local `.torusguard/` directory containing active security rules, schemas, and runners.
204
- 3. **Editor Rules Synchronization:** Automatically compiles compact, language-specific guardrails into `.cursorrules`, `CLAUDE.md`, `.agent/rules/torusguard.md`, and `.windsurfrules` ($\le 300$ prompt tokens).
205
- 4. **Living Ledger Initialization:** Creates `security_report.md` at workspace root to track finding states without hallucination.
206
- 5. **Baseline Policy:** Emits a production-ready `SECURITY.md` for responsible disclosure.
191
+ ## 💻 Usage
207
192
 
208
- ---
209
-
210
- ## ⚡ Quickstart: The 5-Step Core Lifecycle
211
-
212
- Run the complete autonomous governance cycle in 60 seconds from your terminal:
193
+ ### Quick Start
213
194
 
214
195
  ```bash
215
- # Step 1: Initialize workspace and profile stack (optional: --template golang|nextjs|fastapi)
216
- npx torusguard init
196
+ # Initialize TorusGuard in your project
197
+ torusguard init
217
198
 
218
- # Step 2: Run AST static security audit across 74 rules (optional: --watch, --sarif)
219
- npx torusguard audit
199
+ # Run a full security audit
200
+ torusguard audit
220
201
 
221
- # Step 3: Synthesize minimal surgical candidate patches (optional: --dry-run, --severity high)
222
- npx torusguard harden
202
+ # Check workspace posture
203
+ torusguard status
223
204
 
224
- # Step 4: Review syntax-highlighted diffs and apply with rollback backup (optional: --diff, --selective)
225
- npx torusguard apply
205
+ # Generate an HTML report
206
+ torusguard report --html
226
207
 
227
- # Step 5: Differentially recheck modified files to verify fix closure
228
- npx torusguard recheck
208
+ # Generate a SARIF report
209
+ torusguard report --sarif
229
210
  ```
230
211
 
231
- > 💡 **Prefer AI Chat?** Every step above can be triggered directly in your AI assistant chat using `/torusguard init`, `/torusguard audit`, `/torusguard harden`, `/torusguard apply`, and `/torusguard recheck`!
212
+ ### Remediation Workflow
232
213
 
233
- ---
214
+ ```bash
215
+ # Validate a candidate patch against Ponytail bounds
216
+ torusguard harden fix.patch
234
217
 
235
- ## ⌨️ Dual-Strategy Command Matrix (CLI & AI Chat Parity)
236
-
237
- TorusGuard guarantees **100% operational parity** between terminal CLI execution and AI chat slash commands. Terminal outputs strictly adhere to a **75-column visual width** with Unicode emojis and ANSI stripping. All commands support `--target <dir>` / `-t <dir>` for monorepo and subproject isolation.
238
-
239
- ### 🔄 Core Remediation Lifecycle
240
-
241
- | Lifecycle Stage | Mode A: Terminal CLI | Mode B: AI Chat Command | Governed Action & Primary Artifact |
242
- |:---|:---|:---|:---|
243
- | **1. Init** | `npx torusguard init [--template <name>] [--audit]` | `/torusguard init` | Profiles workspace, activates rules, scaffolds `.torusguard/` |
244
- | **2. Status** | `npx torusguard status` | `/torusguard status` | 75-column diagnostic overview of health score, stack, memory & rules |
245
- | **3. Audit** | `npx torusguard audit [--watch] [--sarif]` | `/torusguard audit` | 74-rule AST scan, line-shift fingerprints, throughput metrics, living ledger |
246
- | **4. Verify** | `npx torusguard verify` | `/torusguard verify` | Asserts evidence sufficiency & live disk line-shift fingerprint matches |
247
- | **5. Harden** | `npx torusguard harden [--dry-run] [--severity <s\>]` | `/torusguard harden` | Synthesizes Ponytail diffs ($\le 35$ add, $\le 25$ del) into candidate bundles |
248
- | **6. Apply** | `npx torusguard apply [--diff] [--selective] [--yes]` | `/torusguard apply` | Human Gate, pre-apply `.bak` snapshots, Golden Fix distillation |
249
- | **7. Rollback**| `npx torusguard rollback [--run <id>]` | `/torusguard rollback` | Instant restoration from pre-apply snapshots in `.torusguard/snapshots/` |
250
- | **8. Recheck** | `npx torusguard recheck` | `/torusguard recheck` | Differential AST re-scan; marks findings `RESOLVED 🟢` in living report |
251
- | **9. Recipes** | `npx torusguard recipes [--search <q>] [--export <p>]`| `/torusguard recipes` | Explores and exports verified Golden Fix patterns from `.torusguard/memory/` |
252
- | **10. Report** | `npx torusguard report --html [--sarif]` | `/torusguard report` | Emits single-file dark-mode HTML posture dashboard & OASIS SARIF v2.1.0 |
253
- | **11. Update** | `npx torusguard update [--install]` | `/torusguard update` | Verifies npm registry for latest versions and provides 1-command upgrade |
254
- | **12. Rules Sync**| `npx torusguard rules sync` | `/torusguard rules sync`| Synchronizes prompt guardrails across Cursor, Claude, Antigravity, Windsurf |
255
- | **13. Diff Guard**| `npx torusguard diff-guard [--install-hook]` | `/torusguard diff-guard`| Audits git diffs for security bypasses; binds pre-commit git hook |
256
- | **14. Authorize** | `npx torusguard authorize` | `/torusguard authorize` | Target domain allowlisting, cryptographic ownership proof, TTL limits |
257
- | **15. Validate** | `npx torusguard web-validate` | `/torusguard web-validate`| Authorized non-destructive HTTP probing with transparent audit headers |
258
- | **16. Exploit** | `npx torusguard exploit-check` | `/torusguard exploit-check`| Bounded single-step exploitability confirmation using inert sentinels |
218
+ # Apply the patch with rollback snapshot (requires --yes for Human Gate)
219
+ torusguard apply --yes fix.patch
259
220
 
260
- ---
221
+ # Verify the fix was applied correctly
222
+ torusguard recheck
261
223
 
262
- ## 🐹 Polyglot Go Engine & Native Runner
224
+ # Roll back if something went wrong
225
+ torusguard rollback
226
+ ```
263
227
 
264
- TorusGuard v1.4.0 introduces native, zero-dependency Go ecosystem support:
228
+ ### Runtime Validation
265
229
 
266
- ### 1. Go AST Invariant Security Rules
267
- - **`TG-INPUT-002` (Raw SQL Concatenation):** Detects unparameterized string concatenation and `fmt.Sprintf` query interpolation in `database/sql`, `sqlx`, and GORM.
268
- - **`TG-INPUT-006` (Path Traversal):** Detects unsanitized file reads (`os.Open`, `os.ReadFile`) using user request parameters.
269
- - **`TG-SSRF-004` (Unbounded HTTP Requests):** Flags `&http.Client{}` and `http.DefaultClient` lacking explicit timeout boundaries to prevent connection pooling denial-of-service.
270
- - **`TG-DIFF-001` (Security Bypasses):** Prevents insecure TLS validation (`InsecureSkipVerify: true`).
271
- - **`TG-SUPPLY-001` (Supply Chain):** Asserts lockfile presence and cryptographic tracking for `go.sum`.
230
+ ```bash
231
+ # Generate authorization token for runtime probing
232
+ torusguard authorize
272
233
 
273
- ### 2. Surgical Ponytail Remediation for Go
274
- Patches for Go follow strict Ponytail line churn limits ($\le 35$ additions, $\le 25$ deletions):
275
- ```go
276
- // Example: TG-SSRF-004 Remediation
277
- - client := &http.Client{}
278
- + client := &http.Client{Timeout: 10 * time.Second}
234
+ # Probe a running application for security headers
235
+ torusguard web-validate
279
236
 
280
- // Example: TG-INPUT-006 Path Traversal Remediation
281
- - data, err := os.ReadFile("/data/" + c.Query("file"))
282
- + data, err := os.ReadFile(filepath.Join("/data", filepath.Base(c.Query("file"))))
237
+ # Send bounded inert payloads to test input handling
238
+ torusguard exploit-check
283
239
  ```
284
240
 
285
241
  ---
286
242
 
287
- ## 🔄 Package Self-Update Engine (`update`)
243
+ ## 🔧 Commands
244
+
245
+ | Command | Description |
246
+ | :--------------- | :------------------------------------------------------------- |
247
+ | `init` | Scaffold `.torusguard/` workspace, detect stack, activate rules |
248
+ | `status` | Diagnostic overview of posture, stack, and active rules |
249
+ | `audit` | Static heuristic security scan against active TG-* rules |
250
+ | `verify` | Live disk line match audit and evidence sufficiency check |
251
+ | `harden` | Validate patches against Ponytail Protocol bounds |
252
+ | `apply` | Apply patches with pre-apply `.bak` rollback snapshots |
253
+ | `rollback` | Instant restoration from pre-apply snapshots |
254
+ | `recheck` | Differential re-scan on modified files |
255
+ | `report` | Generate HTML (`--html`) or SARIF (`--sarif`) posture reports |
256
+ | `recipes` | Manage the Golden Fix recipe library |
257
+ | `authorize` | Generate cryptographic auth tokens for runtime probing |
258
+ | `web-validate` | Authorized HTTP probing with `X-TorusGuard-Audit` headers |
259
+ | `ocr-scan` | Run Tesseract OCR secret scan on images/diagrams (<10MB) |
260
+ | `mcp` | Run native Model Context Protocol (MCP) server over stdio |
261
+ | `update` | Self-update the TorusGuard engine |
262
+ | `help` | Show interactive command guide |
288
263
 
289
- Keep your security guardrails continuously synchronized with the latest threat models:
264
+ ---
290
265
 
291
- ```bash
292
- # Check registry for newer versions
293
- npx torusguard update
266
+ ## 📁 Project Structure
294
267
 
295
- # Automatically upgrade to latest version
296
- npx torusguard update --install
297
268
  ```
298
-
299
- - **Zero-Dependency Registry Check:** Queries `https://registry.npmjs.org/torusguard/latest` natively.
300
- - **SemVer Delta Analysis:** Displays current version against registry latest in standard 75-column cards.
301
- - **Automated Upgrade Flow:** Executes package installation upon user authorization.
302
-
303
- ---
304
-
305
- ## 📋 74 Canonical Security Rules Catalog (18 Families Across 6 Pillars)
306
-
307
- TorusGuard's AST scanner inspects polyglot source trees across 74 canonical security rules organized into **6 core security pillars** across 18 families:
308
-
309
- ```text
310
- ┌─────────────────────────────────────────────────────────────────────────────┐
311
- │ 74 CANONICAL RULES ACROSS 6 PILLARS │
312
- └─────────────────────────────────────────────────────────────────────────────┘
313
- 1. Secrets & Identity ──► TG-SEC (7) · TG-AUTH (8) · TG-CLIENT (2)
314
- 2. Data & Injection Defense ──► TG-DB (4) · TG-INPUT (6) · TG-CSRF (2)
315
- 3. AI Agent & LLM Security ──► TG-AGENT (4)
316
- 4. Network & Real-Time ──► TG-SSRF (4) · TG-WEBHOOK (4) · TG-WS (4)
317
- 5. Platform & API Limits ──► TG-RATE (3) · TG-GQL (4) · TG-PLATFORM (4)
318
- TG-CACHE (3) · TG-EDGE (2)
319
- 6. Supply Chain & Governance──► TG-SUPPLY (6) · TG-BIZ (4) · TG-DIFF (3)
269
+ TorusGuard/
270
+ ├── cmd/torusguard/ # CLI entry point, command router & MCP server
271
+ │ ├── main.go # CLI command router
272
+ │ └── mcp.go # Model Context Protocol (MCP) JSON-RPC 2.0 stdio server
273
+ ├── internal/
274
+ │ ├── apply/ # Patch application + pre-apply snapshot engine
275
+ │ ├── harden/ # Ponytail Protocol bounds enforcement
276
+ │ ├── memory/ # Golden Fix recipe persistence
277
+ │ ├── recheck/ # Differential re-scan engine
278
+ │ ├── report/ # SARIF v2.1.0 + dark-mode HTML generators
279
+ │ ├── rules/ # TG-* rule catalog loader
280
+ │ ├── scanner/ # Heuristic polyglot security scanner + Tesseract OCR
281
+ │ │ ├── scanner.go # Polyglot code AST & heuristic scanner
282
+ │ │ └── ocr.go # Multi-modal Vision OCR secret detection
283
+ │ ├── termui/ # 75-column terminal UI formatting
284
+ │ ├── validate/ # authorize / web-validate / exploit-check / verify
285
+ │ └── workspace/ # init + polyglot stack detection
286
+ ├── .torusguard/ # Generated workspace state
287
+ │ ├── rules/ # Active security rule definitions
288
+ │ ├── schemas/ # JSON schemas for findings, recipes, etc.
289
+ │ ├── memory/ # Persistent security context
290
+ │ └── snapshots/ # Pre-apply rollback backups
291
+ ├── docs/ # Architecture and usage documentation
292
+ ├── bin/ # npm package CLI wrapper
293
+ ├── go.mod # Go module (github.com/torusguard/torusguard)
294
+ └── package.json # npm package definition
320
295
  ```
321
296
 
322
- | Pillar | Family Prefix | Rules | Critical Invariant Enforced |
323
- |:---|:---|:---:|:---|
324
- | **🔑 Secrets & Client Bundles** | `TG-SEC`, `TG-CLIENT` | **9** | Zero hardcoded API keys, JWT secrets, private certificates, or server keys in client bundles. |
325
- | **🛡️ Authentication & Sessions** | `TG-AUTH`, `TG-CSRF` | **10** | Timing-safe string compares, strong password hashing, algorithm verification, SameSite cookies. |
326
- | **🗄️ Database & Input Safety** | `TG-DB`, `TG-INPUT` | **10** | Parameterized SQL queries, multi-tenant isolation (`where: { tenantId }`), path sanitization. |
327
- | **🤖 AI Agent & LLM Guardrails** | `TG-AGENT` | **4** | Structural user prompt isolation, delimiter wrapping, shell tool sandboxing, MCP least-privilege. |
328
- | **🌐 Network, Webhooks & WS** | `TG-SSRF`, `TG-WEBHOOK`, `TG-WS` | **12** | Private IP range blocking (`169.254.169.254`), HMAC-SHA256 signature checks, WS origin validation. |
329
- | **⚡ Platform, Edge & Governance** | `TG-RATE`, `TG-GQL`, `TG-PLATFORM`, `TG-CACHE`, `TG-EDGE`, `TG-SUPPLY`, `TG-BIZ`, `TG-DIFF` | **29** | Auth rate limiting, GraphQL depth bounds, Helmet headers, lockfile integrity, zero `# nosec` bypasses. |
330
-
331
- <details>
332
- <summary><strong>🔍 Click to expand full 18-family catalog breakdown</strong></summary>
333
-
334
- <br>
335
-
336
- - **`TG-SEC` (Secrets & API Tokens — 7 rules):** Detects hardcoded JWT secrets, private certificates, cloud API keys, environment variable leakage, and secrets in URL queries or logs.
337
- - **`TG-AUTH` (Authentication & Access Control — 8 rules):** Enforces constant-time string comparisons, strong password hashing (`bcrypt`/`argon2`), JWT algorithm pinning, mass assignment prevention, and server-side role verification.
338
- - **`TG-DB` (Database Partitioning & Injection — 4 rules):** Mandates tenant-scoped queries across Prisma, Mongoose, SQLAlchemy, and GORM; eliminates raw SQL string concatenation.
339
- - **`TG-INPUT` (Input Validation & Traversal — 6 rules):** Enforces safe path sanitization (`path.basename`), command argument escaping, safe DOM text assignments, and server-side file upload bounds.
340
- - **`TG-RATE` (Rate Limiting & Resource Protection — 3 rules):** Enforces rate-limiting middleware on authentication routes, pagination bounds, and request payload size limits.
341
- - **`TG-AGENT` (AI Agent & LLM Defense — 4 rules):** Enforces structural separation of user prompts from system instructions, inert XML delimiters, and containerized tool execution.
342
- - **`TG-SSRF` (Server-Side Request Forgery — 4 rules):** Restricts dynamic outbound HTTP calls, blocks AWS/cloud metadata access (`169.254.169.254`), and enforces request timeouts.
343
- - **`TG-WEBHOOK` (Webhook Verification — 4 rules):** Mandates cryptographic HMAC-SHA256 signature validation before body parsing, replay prevention, and timestamp expiration.
344
- - **`TG-WS` (WebSocket Security — 4 rules):** Enforces handshake authentication, origin validation, channel-level authorization, and frame size caps.
345
- - **`TG-CSRF` (Cross-Site Request Forgery — 2 rules):** Enforces anti-CSRF tokens on state-changing operations and `SameSite` cookie attributes.
346
- - **`TG-GQL` (GraphQL Protection — 4 rules):** Enforces query depth limiting, production introspection suppression, and field-level resolver authorization.
347
- - **`TG-SUPPLY` (Supply Chain Integrity — 6 rules):** Audits dependency lockfile presence, checks against known CVEs, prevents `--no-audit` build flags, and inspects build scripts.
348
- - **`TG-BIZ` (Business Logic Bounds — 4 rules):** Validates negative quantity inputs, coupon/discount boundaries, and race-condition transaction locks.
349
- - **`TG-CACHE` (Cache Isolation — 3 rules):** Enforces `Cache-Control: no-store, private` on authenticated responses and sanitizes unkeyed request headers.
350
- - **`TG-CLIENT` (Client Bundle Hygiene — 2 rules):** Forbids importing private server environment variables into browser bundles and suppresses production source maps.
351
- - **`TG-PLATFORM` (Server Hardening — 4 rules):** Enforces Helmet HTTP security headers, CORS origin whitelisting, cookie `secure` flags, and debug mode suppression.
352
- - **`TG-DIFF` (Polyglot Diff Integrity — 3 rules):** Intercepts security bypass comments (`# nosec`, `InsecureSkipVerify: true`) and asserts Ponytail patch budgets.
353
- - **`TG-EDGE` (Edge & Serverless Limits — 2 rules):** Prevents cross-request memory leaks in Cloudflare Workers and enforces subrequest fan-out limits.
354
-
355
- </details>
356
-
357
297
  ---
358
298
 
359
- ## ✂️ Ponytail Remediation Protocol & Rollback Safety
360
-
361
- Traditional AI coding assistants routinely destroy functional features by attempting full-file rewrites. TorusGuard strictly enforces the **Ponytail Protocol**:
362
-
363
- $$\Delta \text{Lines} \le 35\text{ Additions}, \quad \Delta \text{Lines} \le 25\text{ Deletions}$$
364
-
365
- ### 🛡️ Pre-Apply Rollback Snapshots
366
- Before modifying a single file on disk, `apply_runner.py` creates a byte-for-byte backup:
367
- ```text
368
- .torusguard/snapshots/<run_id>/<target_file>.bak
369
- ```
370
-
371
- If a patch causes unforeseen behavior or test failures, execute an instant 1-command rollback:
372
- ```bash
373
- npx torusguard rollback
374
- ```
375
- All affected files are immediately restored to their exact pre-patch byte state.
299
+ ## 🔒 Security Rules (74 Rules, 18 Families)
300
+
301
+ | Family | Domain | Rules | Core Invariant |
302
+ | :------------- | :------------------------------- | :---: | :------------------------------------------------------- |
303
+ | `TG-SEC` | Core Secrets & API Tokens | 7 | Zero hardcoded API keys or JWT secrets in source |
304
+ | `TG-AUTH` | Authentication & Sessions | 8 | Timing-safe compares, strong hashing, algorithm verify |
305
+ | `TG-DB` | Database Isolation & Injection | 4 | Parameterized queries and tenant partition scoping |
306
+ | `TG-INPUT` | Input Sanitization & Traversal | 6 | Strict path sanitization, safe DOM assignments |
307
+ | `TG-RATE` | Rate Limiting & Resources | 3 | Rate-limiting on auth endpoints, payload size bounds |
308
+ | `TG-AGENT` | AI Agent & LLM Injection | 4 | Structural prompt isolation, tool call schema validation |
309
+ | `TG-SSRF` | Server-Side Request Forgery | 4 | Hostname whitelisting, private IP range blocking |
310
+ | `TG-WEBHOOK` | Inbound Webhook Verification | 4 | HMAC-SHA256 signature verification, replay prevention |
311
+ | `TG-WS` | WebSocket & Real-Time | 4 | Origin verification, handshake auth, frame size limits |
312
+ | `TG-CSRF` | Cross-Site Request Forgery | 2 | SameSite cookies, anti-CSRF token verification |
313
+ | `TG-GQL` | GraphQL Safety | 4 | Query depth limiting, introspection suppression |
314
+ | `TG-SUPPLY` | Supply Chain & Dependencies | 6 | Lockfile integrity, known CVE audits |
315
+ | `TG-BIZ` | Business Logic & Workflows | 4 | Negative amount validation, transaction locks |
316
+ | `TG-CACHE` | Cache Poisoning & Timing | 3 | Cache-control headers, unkeyed header sanitization |
317
+ | `TG-CLIENT` | Client Bundle & Frontend | 2 | Zero private env vars in client bundles |
318
+ | `TG-PLATFORM` | Server Hardening & Headers | 4 | Helmet headers, debug suppression, cookie secure flags |
319
+ | `TG-DIFF` | Polyglot Bypass & Churn | 3 | Block `# nosec`, `InsecureSkipVerify`, churn bounds |
320
+ | `TG-EDGE` | Edge Computing & Serverless | 2 | Subrequest fan-out limits, execution timeouts |
376
321
 
377
322
  ---
378
323
 
379
- ## 📜 Living Security Report Ground Truth (`security_report.md`)
380
-
381
- To eliminate AI hallucination, TorusGuard maintains `security_report.md` at the workspace root as the single source of truth across all CLI commands and AI chat sessions.
382
-
383
- ### 🔄 Lifecycle State Machine
384
- ```text
385
- ┌─────────────────────────────────────────────────────────────────────────────┐
386
- │ SECURITY REPORT LIFECYCLE STATE MACHINE │
387
- └─────────────────────────────────────────────────────────────────────────────┘
388
- [ OPEN 🔴 ] ──(verify)──► [ VERIFIED 🟠 ] ──(harden)──► [ CANDIDATE 🟡 ]
389
- │
390
- (apply)
391
- │
392
- ▼
393
- [ RESOLVED 🟢 ] ◄──(recheck: confirmed)── [ APPLIED 🔵 ]
394
- │
395
- └──(recheck: failed)──► [ REGRESSED ❌ ]
396
- ```
324
+ ## 🤖 AI Agent Integration
397
325
 
398
- ### 🧮 Posture Health Score (0–100)
399
- The Health Score dynamically reflects the open risk ledger:
400
- $$\text{Penalty} = (25 \times \text{Critical}) + (15 \times \text{High}) + (5 \times \text{Medium}) + (2 \times \text{Low})$$
401
- $$\text{Score} = \max(0, \min(100, 100 - \text{Penalty}))$$
326
+ TorusGuard works natively inside AI coding assistants. Add the configuration file to your project root and your AI agent automatically enforces TorusGuard security invariants.
402
327
 
403
- *When all findings are verified closed via differential recheck, the repository achieves **Health Score: 100/100 🟢 Hardened & Secure**.*
328
+ ### Supported Agents
404
329
 
405
- ---
330
+ | Agent | Configuration File | Status |
331
+ | :------------------- | :-------------------- | :----- |
332
+ | Antigravity (Gemini) | `AGENTS.md` | ✅ Full support |
333
+ | Claude Code | `CLAUDE.md` | ✅ Full support |
334
+ | Cursor | `.cursorrules` | ✅ Full support |
335
+ | Windsurf | `.windsurfrules` | ✅ Full support |
336
+ | VS Code Copilot | `AGENTS.md` | ✅ Full support |
337
+ | Kimi | `SKILL.md` | ✅ Full support |
406
338
 
407
- ## 📊 Visual HTML Dashboard & SARIF v2.1.0 Export
339
+ ### Slash Commands (AI Chat Mode)
408
340
 
409
- Generate a standalone, zero-external-CDN, dark-mode visual posture dashboard:
410
- ```bash
411
- npx torusguard report --html
412
341
  ```
413
- - **SVG Circular Posture Gauge:** Animated visual health score ($0-100$).
414
- - **7-Stage Closed-Loop Pipeline:** Visual state timeline across all lifecycle phases.
415
- - **Golden Fix Recipes Grid:** Syntax-highlighted unified diffs with Ponytail metrics.
416
- - **Zero-CDN Architecture:** Completely offline-ready; embeds all styles and assets inline.
417
-
418
- To integrate with **GitHub Code Scanning**, export standard SARIF:
419
- ```bash
420
- npx torusguard report > results.sarif
342
+ /torusguard init # Initialize workspace
343
+ /torusguard audit # Run security + OCR scan; sync security_report.md
344
+ /torusguard ocr-scan # Scan diagram or image assets for leaked credentials
345
+ /torusguard harden # Formulate remediation patches
346
+ /torusguard apply # Apply patches with Human Gate
347
+ /torusguard recheck # Verify fix closure
348
+ /torusguard report # Generate posture report
349
+ /torusguard status # Check posture overview
350
+ /torusguard full # End-to-end 7-stage pipeline
421
351
  ```
422
352
 
423
- ---
353
+ ### Native MCP Tools (Agent Toolkit Mode)
424
354
 
425
- ## 🤖 AI Editor Guardrails Auto-Sync
355
+ When configured with `.agents/mcp_config.json` or `mcp_config.json`, AI coding agents gain native tool calling:
426
356
 
427
- TorusGuard compiles project security invariants, golden recipes, and active guardrails into prompt-optimized rule files:
428
- ```bash
429
- npx torusguard rules sync
430
- ```
357
+ - `torusguard_audit`: Deep static AST scan + Vision OCR; writes `security_report.md`
358
+ - `torusguard_ocr_scan`: Dedicated image credential analysis via Tesseract (5-10MB bounds)
359
+ - `torusguard_harden`: Validates remediation diff against Ponytail Protocol bounds
360
+ - `torusguard_recheck`: Differential re-scan confirming fix closure
361
+ - `torusguard_status`: Workspace posture and tech stack inspection
362
+ - `torusguard://security_report`: MCP Resource reading the living security report
431
363
 
432
- ### Supported AI Editors:
433
- - **Cursor:** Injects non-destructive rules into `.cursorrules`
434
- - **Claude Code:** Injects non-destructive rules into `CLAUDE.md`
435
- - **Antigravity IDE:** Injects non-destructive rules into `.agent/rules/torusguard.md`
436
- - **Windsurf:** Injects non-destructive rules into `.windsurfrules`
364
+ ---
437
365
 
438
- *All rules are compiled under a strict overhead ceiling of $\le 300$ prompt tokens to preserve AI reasoning context.*
366
+ ## 🧪 Verified Test Suite & Mass Benchmarks
439
367
 
440
- ---
368
+ TorusGuard undergoes rigorous automated multi-tier testing across polyglot stacks, multi-modal vision assets, and agent communication protocols:
441
369
 
442
- ## 🏢 Monorepo Fleet Support & Git Pre-Commit Diff Guard
370
+ | Testing Tier | Scope & Target Stacks | Pass Rate | Verified Capabilities |
371
+ | :--- | :--- | :---: | :--- |
372
+ | **Go Engine & Unit Tests** | `cmd/torusguard`, `internal/scanner`, `internal/*` | **100% Passing** | Deterministic AST matching, 74 rule patterns, JSON-RPC 2.0 MCP protocol. |
373
+ | **Mass Polyglot Benchmarks** | **20 Enterprise Tech Stacks** (Go, Python, Java, Node, Rust, PHP, C#, Ruby, Svelte, Vue, Angular) | **20/20 Passed** | Framework auto-profiling, heuristic AST analysis, finding deduplication. |
374
+ | **Tri-Mode & Vision E2E** | **16 Diverse Framework Repos** (React, Next.js, Express, Django, FastAPI, Spring Boot, etc.) | **16/16 Passed** | Mode A (CLI) + Mode B (Slash Commands) + Mode C (Native MCP Tools) + Multi-Modal Vision OCR. |
375
+ | **Multi-Modal Vision OCR** | Diagram & Image assets (`.png`, `.jpg`, etc.) via Tesseract v5.4.0 | **100% Recall** | Secrets detection (`TG-SEC-001` - `TG-SEC-007`), 10MB DoS bounding, OCR character substitution tolerance. |
376
+ | **Ponytail Churn Limits** | Surgical patch validation across all 74 rules | **Bounded** | Line bounds (≤35 additions, ≤25 deletions), zero-bypass verification (`TG-DIFF-001`). |
443
377
 
444
- TorusGuard automatically discovers and profiles multi-package workspaces:
445
- - **Monorepo Ecosystems:** pnpm workspaces, npm/yarn workspaces, Cargo workspaces, Go multi-module workspaces, Gradle multi-project builds.
446
- - **Universal Polyglot Profiler:** Automatically identifies 16+ languages and maps ORM boundaries independently per sub-package.
447
- - **Pre-Commit Diff Guard:** Run `npx torusguard diff-guard --install-hook` to bind `.git/hooks/pre-commit` and block security bypasses before code is committed.
378
+ All test environments are completely sandboxed, verified with byte-for-byte assertions, and cleaned up automatically.
448
379
 
449
380
  ---
450
381
 
451
- ## 🧪 Verification & Test Harness
382
+ ## 🛡️ Non-Negotiable Invariants
452
383
 
453
- ### What Happens When You Run `npm test`?
454
- TorusGuard enforces a strict **100% pass requirement across 133 tests in 21 test suites** before every release.
455
- The test harness runs with **zero third-party dependencies** via standard Python 3:
384
+ 1. **Browser-Code Truth:** Never expose secrets in frontend bundles.
385
+ 2. **Multi-Tenant Isolation:** Always scope DB lookups by tenant/user ownership.
386
+ 3. **Ponytail Churn Bounds:** Patches ≤35 additions, ≤25 deletions. No full-file rewrites.
387
+ 4. **Zero Security Bypasses:** Never insert `# nosec`, `verify=False`, `InsecureSkipVerify: true`.
388
+ 5. **Snapshots Before Edits:** Mandatory `.bak` backup before every modification.
389
+ 6. **Fail-Closed Cryptography:** Panic on entropy failure. No fallback tokens.
390
+ 7. **SSRF Boundary Enforcement:** Block private IPs and cloud metadata before probing.
391
+ 8. **DoS Resilience:** 10,000-file max, 5-minute timeout.
456
392
 
457
- ```bash
458
- npm test
459
- # Equivalent to: python harness/runner.py
460
- ```
461
-
462
- When a developer runs:
463
- ```bash
464
- npm test
465
- ```
466
- The test harness invokes `python harness/runner.py` directly using the Python standard library. It systematically verifies:
467
- 1. **JSON Schema Validity:** 10 formal schemas (`finding`, `evidence`, `remediation`, `rule`, `lifecycle`, `provenance`, etc.).
468
- 2. **74-Rule Catalog Integrity:** AST detection accuracy across all 18 security families.
469
- 3. **Polyglot Go Engine:** Go module definition, Go stack detection (Gin, Fiber, GORM), and Go AST rules (`TG-INPUT-002`, `TG-INPUT-006`, `TG-SSRF-004`).
470
- 4. **Line-Shift Fingerprinting:** Stable anchor matching across file edits without line number drift.
471
- 5. **Secret Redaction:** Stripe secret keys and JWT tokens safely masked.
472
- 6. **Deterministic Replay:** 3-pass differential validation across Django, DRF, FastAPI, Flask, and SQLAlchemy fixtures.
473
- 7. **Ponytail Patch Churn Bounds:** Verifying line budgets ($\le 35$ additions, $\le 25$ deletions).
474
- 8. **Deepened Command Verification:** Audit watch loop & SARIF export, Harden dry-run & severity floor, Recipes search & export, Apply diff preview & snapshot ledger, and Bootstrap templates.
475
- 9. **Living Security Report State Transitions:** Discovery (`OPEN 🔴`), Candidate (`CANDIDATE 🟡`), Applied (`APPLIED 🔵`), and Verified Closure (`RESOLVED 🟢`).
476
- 10. **Cryptographic Manifest Parity:** 100% SHA-256 match across all indexed workspace files.
393
+ ---
477
394
 
478
- ```bash
479
- # Run formal TorusGuard test harness
480
- npm test
395
+ ## 🤝 Contributing
481
396
 
482
- # Expected Output:
483
- # ================================================================================
484
- # SUMMARY: 133 Passed | 0 Failed
485
- # ================================================================================
486
- ```
397
+ 1. Fork the repository
398
+ 2. Create a feature branch: `git checkout -b feat/your-feature`
399
+ 3. Commit changes: `git commit -m "feat: add your feature"`
400
+ 4. Push to branch: `git push origin feat/your-feature`
401
+ 5. Open a Pull Request
487
402
 
488
- To validate diff guard and monorepo profiling independently:
489
- ```bash
490
- python harness/validate_v0_9_2_diff_and_monorepo.py
491
- ```
403
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.
492
404
 
493
405
  ---
494
406
 
495
- ## 🔒 Security Policy & Responsible Disclosure
407
+ ## 📄 License
496
408
 
497
- If you believe you have discovered a security vulnerability in TorusGuard itself, please report it responsibly and privately through [GitHub Private Vulnerability Reporting](https://github.com/githubmofo/TorusGuard/security/advisories/new) or contact the project maintainers. Do not file public issues for undisclosed security flaws. For complete details, consult [SECURITY.md](SECURITY.md).
409
+ [MIT](LICENSE) © 2026 Jenish Lad
498
410
 
499
411
  ---
500
412
 
501
- ## 📄 License
502
-
503
- TorusGuard is released under the [MIT License](LICENSE).
504
- Copyright (c) 2026 Jenish Lad ([@githubmofo](https://github.com/githubmofo)).
413
+ ## 📚 Documentation
414
+
415
+ | Document | Description |
416
+ | :-------------------------------------------------------- | :--------------------------------------- |
417
+ | [Architecture](docs/architecture/ARCHITECTURE.md) | System design and module relationships |
418
+ | [Security Architecture](docs/architecture/SECURITY_ARCHITECTURE.md) | Threat model and security design |
419
+ | [Detection Engine](docs/architecture/DETECTION_ENGINE.md) | Scanner internals and rule matching |
420
+ | [API Specification](docs/architecture/API_SPECIFICATION.md) | CLI argument specification |
421
+ | [Security Philosophy](docs/overview/security-philosophy.md) | Core design principles |
422
+ | [Testing Playbook](docs/usage/testing-playbook.md) | Testing guide and CI integration |
423
+ | [Demo Guide](docs/demo.md) | Quick start and full lifecycle demo |
424
+ | [Roadmap](docs/roadmap.md) | Feature roadmap and release planning |
425
+ | [SECURITY.md](SECURITY.md) | Vulnerability disclosure policy |
426
+ | [CHANGELOG.md](CHANGELOG.md) | Version history and release notes |