torusguard 0.9.2 → 0.9.3
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.
- package/.torusguard/.manifest.json +1 -1
- package/.torusguard/config/torusguard.json +1 -1
- package/README.md +187 -215
- package/bin/torusguard.js +2 -2
- package/package.json +3 -3
- package/skills/torusguard/__pycache__/bootstrap.cpython-311.pyc +0 -0
- package/skills/torusguard/payload/.manifest.json +1 -1
- package/skills/torusguard/payload/config/torusguard.json +1 -1
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
"agents/validator.md": "79fc4431de5c5507f8730aee6c5c3e61fd238cbf8cf8c7c6aac462eee9761ed6",
|
|
9
9
|
"config/scope.json": "b198a86186b4c6d5e1af516bf4e3a6afa8878e622ca1d57a5bf72d294f8c6f25",
|
|
10
10
|
"config/slash-commands.json": "5390f0d26f8117a62e56c58147d3a0d2deab1a20956302b212703281d13fa84e",
|
|
11
|
-
"config/torusguard.json": "
|
|
11
|
+
"config/torusguard.json": "fa2db9e3dbe5642dad99ae5be5db875f307ec82a61812a72be4922f760dbe0dd",
|
|
12
12
|
"references/django-security.md": "a15b7eb11b51dd1970d3d65544cf79ebea91fb99dc0e085e58a56532a718dce7",
|
|
13
13
|
"references/drf-security.md": "c7a7af3acaef895bf4798590acc88b3a2e9831a49eb2d23b4d8f31540ab264cc",
|
|
14
14
|
"references/express-security.md": "dff1db15e614d29d8c272f9da345b418077e62dc883fe210c7a50c552c76493f",
|
package/README.md
CHANGED
|
@@ -5,9 +5,11 @@
|
|
|
5
5
|
|
|
6
6
|
**Security guardrails, governed remediation, and authorized runtime validation for AI-built web applications.**
|
|
7
7
|
|
|
8
|
-
[](https://www.npmjs.com/package/torusguard)
|
|
9
|
+
[](https://github.com/githubmofo/TorusGuard/releases/latest)
|
|
9
10
|
[](LICENSE)
|
|
10
11
|
[](https://python.org)
|
|
12
|
+
[](https://nodejs.org)
|
|
11
13
|
[](schemas/)
|
|
12
14
|
[](.torusguard/.manifest.json)
|
|
13
15
|
[](docs/architecture/SECURITY_ARCHITECTURE.md)
|
|
@@ -17,142 +19,153 @@
|
|
|
17
19
|
|
|
18
20
|
## 💡 Executive Summary
|
|
19
21
|
|
|
20
|
-
AI coding
|
|
22
|
+
Modern AI coding agents generate full-stack applications with remarkable speed. However, they frequently introduce severe security flaws—leaking service-role credentials to client bundles, bypassing multi-tenant query boundaries, omitting CSRF defenses, or exposing unsandboxed shell dispatch tools.
|
|
21
23
|
|
|
22
|
-
**TorusGuard** is an
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
24
|
+
**TorusGuard** is an autonomous application security co-pilot specifically designed for AI-built software. It integrates directly into your AI coding workflows (Antigravity, Cursor, Claude Code, VS Code Copilot, Kimi, Windsurf, Cline) to:
|
|
25
|
+
|
|
26
|
+
1. **Detect Real Vulnerabilities:** Statically scan source code across Python and TypeScript using 71 specialized security rules.
|
|
27
|
+
2. **Validate Exploitability:** Perform authorized, non-destructive runtime probes to eliminate false positives before generating alerts.
|
|
28
|
+
3. **Govern Remediation:** Generate minimal, surgically bounded patches ($\le 35$ additions, $\le 25$ deletions) using the **Ponytail Protocol** to eliminate code regressions.
|
|
29
|
+
4. **Export Open Standards:** Emit OASIS SARIF v2.1.0 telemetry with stable AST line hashes for seamless GitHub Code Scanning integration.
|
|
26
30
|
|
|
27
31
|
### 🌐 The Core Principle: The Browser-Code Truth
|
|
28
32
|
> **"If the browser receives it, users can inspect it."**
|
|
29
|
-
>
|
|
33
|
+
> Client-side code, frontend environment variables, network bundles, and React Server Action payloads cannot hide secrets. TorusGuard enforces that database credentials, private API keys, and authorization checks must reside strictly on trusted server boundaries.
|
|
30
34
|
|
|
31
35
|
---
|
|
32
36
|
|
|
33
|
-
##
|
|
37
|
+
## ⚡ Dual-Track Distribution Architecture
|
|
34
38
|
|
|
35
|
-
|
|
39
|
+
To provide maximum developer flexibility, TorusGuard is decoupled into **two clean, independent tracks** that live peacefully in the same repository without conflict:
|
|
36
40
|
|
|
37
41
|
```mermaid
|
|
38
|
-
flowchart
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
style
|
|
48
|
-
style
|
|
49
|
-
style
|
|
50
|
-
style
|
|
51
|
-
style
|
|
52
|
-
style G fill:#1e293b,stroke:#06b6d4,stroke-width:2px,color:#fff
|
|
42
|
+
flowchart TD
|
|
43
|
+
TG["TorusGuard Engine (v0.9.2)"]
|
|
44
|
+
|
|
45
|
+
TG --> T1["⚡ Track 1: Universal AI Agent Skill<br><code>npx skills add ... --skill 'torusguard'</code>"]
|
|
46
|
+
TG --> T2["🛡️ Track 2: Production NPM Package<br><code>npx torusguard init</code> / <code>npm i -D torusguard</code>"]
|
|
47
|
+
|
|
48
|
+
T1 --> R1["• Works in ANY AI IDE (Kimi, Cursor, Copilot, Antigravity)<br>• Zero local file footprint (in-memory reasoning)<br>• Single unified command: <code>/torusguard</code>"]
|
|
49
|
+
T2 --> R2["• Scaffolds full <code>.torusguard/</code> workspace directory<br>• Terminal CLI (<code>npx torusguard status / audit</code>)<br>• Unlocks all 11 individual slash commands (<code>/torusguard-*</code>)"]
|
|
50
|
+
|
|
51
|
+
style TG fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#fff
|
|
52
|
+
style T1 fill:#0f172a,stroke:#10b981,stroke-width:2px,color:#fff
|
|
53
|
+
style T2 fill:#0f172a,stroke:#6366f1,stroke-width:2px,color:#fff
|
|
54
|
+
style R1 fill:#1e293b,stroke:#059669,color:#cbd5e1
|
|
55
|
+
style R2 fill:#1e293b,stroke:#4f46e5,color:#cbd5e1
|
|
53
56
|
```
|
|
54
57
|
|
|
55
|
-
|
|
56
|
-
2. **Classify:** Computes line-shift invariant `primaryLocationLineHash` fingerprints and collapses repeated alerts into systemic root-cause clusters.
|
|
57
|
-
3. **Verify (`/torusguard verify` / `web-validate` / `exploit-check`):** Validates evidence quality across a 5-factor rubric and executes bounded HTTP/browser probes.
|
|
58
|
-
4. **Remediate (`/torusguard harden`):** Generates self-contained 4-artifact Remediation Bundles with framework-idiomatic Before/After fixes.
|
|
59
|
-
5. **Apply (`/torusguard apply`):** Employs the **Ponytail engine** to apply surgical, minimal patches governed by strict line churn limits ($\le 35$ additions, $\le 25$ deletions).
|
|
60
|
-
6. **Recheck (`/torusguard recheck`):** Scopes differential re-audits strictly to modified files, asserting `Confirmed Fixed` or detecting regressions.
|
|
61
|
-
7. **Report & Archive (`/torusguard report`):** Emits signed executive markdown reports and exports OASIS-compliant SARIF v2.1.0 logs for CI/CD.
|
|
58
|
+
### Track Comparison Matrix
|
|
62
59
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
2. **Specialist Skills (`.torusguard/skills/torusguard-<cmd>/SKILL.md`):**
|
|
72
|
-
Focused domain manuals that are lazy-loaded on demand. Instead of polluting the AI's context with a monolithic security handbook, only the exact AST sinks, non-destructive canaries, and confidence scoring formulas relevant to the active command are loaded into memory.
|
|
73
|
-
|
|
74
|
-
```text
|
|
75
|
-
User / AI types Slash Command (e.g. /torusguard audit)
|
|
76
|
-
│
|
|
77
|
-
▼
|
|
78
|
-
[.torusguard/workflows/audit.md] ← Interactive Execution Playbook
|
|
79
|
-
├── 1. Formal Metadata & Role Contract (agent, required-skills, bound scripts)
|
|
80
|
-
├── 2. Mandatory Pre-Flight Context Inspection (disk state, authorization TTL)
|
|
81
|
-
├── 3. "When to Use" Decision Table (situational triggers)
|
|
82
|
-
├── 4. Deterministic Phase-by-Phase CLI Invocations
|
|
83
|
-
├── 5. Failure Recovery & Cascade Rules (3-retry limit, HALT vs CONTINUE)
|
|
84
|
-
├── 6. Strict Safety & Hallucination Boundaries
|
|
85
|
-
└── 7. Standardized Output Cards & Next Step Routing
|
|
86
|
-
│
|
|
87
|
-
▼ Lazy-Loads Matching Specialist Skill
|
|
88
|
-
[.torusguard/skills/torusguard-audit/SKILL.md] ← Focused Domain Manual
|
|
89
|
-
├── 1. Framework AST Sinks & Regex Indicators (Python & TypeScript)
|
|
90
|
-
├── 2. Root-Cause Clustering Algorithms
|
|
91
|
-
├── 3. 5-Factor 0–100 Confidence Scoring Rubric
|
|
92
|
-
└── 4. Non-Destructive Probe Safety Boundaries
|
|
93
|
-
```
|
|
60
|
+
| Feature | ⚡ Track 1: Universal AI Agent Skill | 🛡️ Track 2: Production NPM Package |
|
|
61
|
+
| :--- | :--- | :--- |
|
|
62
|
+
| **Installation** | `npx skills add https://github.com/githubmofo/TorusGuard --skill "torusguard"` | `npx torusguard init` or `npm install -D torusguard` |
|
|
63
|
+
| **Target IDEs** | All AI Agents (Kimi, Antigravity, VS Code, Cursor, Claude Code, Windsurf) | Any Node/Python repo, CI/CD pipelines, Antigravity, Cursor |
|
|
64
|
+
| **Filesystem Footprint** | Pure in-memory context (`.agents/skills/torusguard/` only) | Complete local workspace (`.torusguard/` with config, rules, runs) |
|
|
65
|
+
| **Slash Commands** | Single clean router: `/torusguard` | Full granular suite: `/torusguard-*` (11 commands) |
|
|
66
|
+
| **Prerequisites** | None (pure AI agent execution) | Node.js 18+ (and Python 3.10+ for native scripts) |
|
|
67
|
+
| **Best For** | Instant zero-setup security advice in chat | Production repositories, CI/CD SARIF reports, offline scans |
|
|
94
68
|
|
|
95
69
|
---
|
|
96
70
|
|
|
97
|
-
## 🚀 Quick Start
|
|
98
|
-
|
|
99
|
-
### 1. Installation into Your Project
|
|
71
|
+
## 🚀 Installation & Quick Start
|
|
100
72
|
|
|
101
|
-
|
|
73
|
+
Choose the path that fits your development workflow:
|
|
102
74
|
|
|
103
|
-
|
|
104
|
-
Install directly into any AI
|
|
75
|
+
### Track 1: Universal AI Agent Skill (Zero Setup)
|
|
76
|
+
Install directly into any AI assistant compatible with the Open Agent Skills standard:
|
|
105
77
|
```bash
|
|
106
78
|
npx skills add https://github.com/githubmofo/TorusGuard --skill "torusguard"
|
|
107
79
|
```
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
* **Use Case:** Instant security reviews, OWASP AST guidance, and Ponytail Protocol patch boundaries in any chat.
|
|
80
|
+
* Once installed, simply type `/torusguard` in chat or ask: *"Audit this component for security flaws"*.
|
|
81
|
+
* Operates immediately with zero project configuration required.
|
|
111
82
|
|
|
112
|
-
|
|
113
|
-
Scaffold
|
|
83
|
+
### Track 2: Production NPM Package (Full Governance)
|
|
84
|
+
Scaffold your repository with full local governance and terminal automation:
|
|
114
85
|
```bash
|
|
115
|
-
# Direct runner:
|
|
86
|
+
# Direct runner (recommended):
|
|
116
87
|
npx torusguard init
|
|
117
88
|
|
|
118
|
-
# Or install
|
|
89
|
+
# Or install as a dev dependency:
|
|
119
90
|
npm install -D torusguard
|
|
120
91
|
```
|
|
121
|
-
*
|
|
122
|
-
*
|
|
123
|
-
*
|
|
124
|
-
|
|
125
|
-
|
|
92
|
+
* Creates the `.torusguard/` workspace directory.
|
|
93
|
+
* Automatically populates the IDE slash command palette with all 11 individual `/torusguard-*` workflows.
|
|
94
|
+
* Run direct terminal checks anytime:
|
|
95
|
+
```bash
|
|
96
|
+
npx torusguard status
|
|
97
|
+
npx torusguard audit
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Standalone Python Installer (Alternative)
|
|
101
|
+
For Python-only environments, Docker containers, or air-gapped CI/CD runners:
|
|
126
102
|
```bash
|
|
103
|
+
# Cloned repo:
|
|
127
104
|
python install.py
|
|
128
|
-
|
|
105
|
+
|
|
106
|
+
# Or via remote one-liner:
|
|
129
107
|
curl -sSL https://raw.githubusercontent.com/githubmofo/TorusGuard/main/install.py | python
|
|
130
108
|
```
|
|
131
109
|
|
|
132
110
|
---
|
|
133
111
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
|
139
|
-
|
|
|
140
|
-
| `/torusguard
|
|
141
|
-
| `/torusguard
|
|
142
|
-
| `/torusguard
|
|
143
|
-
| `/torusguard
|
|
144
|
-
| `/torusguard
|
|
145
|
-
| `/torusguard
|
|
146
|
-
| `/torusguard
|
|
147
|
-
| `/torusguard
|
|
148
|
-
| `/torusguard
|
|
149
|
-
| `/torusguard
|
|
112
|
+
## 📋 Comprehensive Command Catalog
|
|
113
|
+
|
|
114
|
+
When Track 2 is initialized, the complete 11-command palette becomes available in your IDE (`.agent/workflows/`, `.agents/workflows/`, `.claude/commands/`, `.cursor/rules/`):
|
|
115
|
+
|
|
116
|
+
| Slash Command | Specialist Skill | Lifecycle Phase | Action Description | Code Changed? |
|
|
117
|
+
| :--- | :--- | :---: | :--- | :---: |
|
|
118
|
+
| `/torusguard` | `skills/torusguard` | Router | Master natural-language command dispatcher and prompt auditor. | No |
|
|
119
|
+
| `/torusguard init`<br>*(or `/torusguard-init`)* | `skills/torusguard-init` | Phase 0 | Profiles repository stack, discovers frameworks, and enables matching rules. | Yes (`.torusguard/`) |
|
|
120
|
+
| `/torusguard authorize`<br>*(or `/torusguard-authorize`)* | `skills/torusguard-authorize` | Phase 1 | Establishes target ownership, scopes URL boundaries, and sets scan rate limits. | Yes (`scope.json`) |
|
|
121
|
+
| `/torusguard audit`<br>*(or `/torusguard-audit`)* | `skills/torusguard-audit` | Phase 2 | Scans source code and clusters repeated alerts by root-cause identity. | No |
|
|
122
|
+
| `/torusguard verify`<br>*(or `/torusguard-verify`)* | `skills/torusguard-verify` | Phase 3 | Scores findings across a 5-factor mathematical rubric (0–100) to purge false alarms. | No |
|
|
123
|
+
| `/torusguard web-validate`<br>*(or `/torusguard-web-validate`)* | `skills/torusguard-web-validate` | Phase 3 | Dispatches authorized, non-destructive HTTP requests with transparent audit headers. | No |
|
|
124
|
+
| `/torusguard exploit-check`<br>*(or `/torusguard-exploit-check`)* | `skills/torusguard-exploit-check` | Phase 3 | Validates exploitability safely into 5 formal verification statuses. | No |
|
|
125
|
+
| `/torusguard harden`<br>*(or `/torusguard-harden`)* | `skills/torusguard-harden` | Phase 4 | Packages 4-artifact Remediation Bundles with framework-idiomatic fixes. | No |
|
|
126
|
+
| `/torusguard apply`<br>*(or `/torusguard-apply`)* | `skills/torusguard-apply` | Phase 5 | Applies surgical patches bounded by Ponytail limits ($\le 35$ additions, $\le 25$ deletions). | **Yes (Patch)** |
|
|
127
|
+
| `/torusguard recheck`<br>*(or `/torusguard-recheck`)* | `skills/torusguard-recheck` | Phase 6 | Executes differential re-audit strictly on modified files to verify fix closure. | No |
|
|
128
|
+
| `/torusguard report`<br>*(or `/torusguard-report`)* | `skills/torusguard-report` | Phase 7 | Emits executive summary markdown and OASIS SARIF v2.1.0 CI artifacts. | No |
|
|
129
|
+
| `/torusguard status`<br>*(or `/torusguard-status`)* | `skills/torusguard-status` | Diagnostic | Inspects active security posture, thresholds, and recent run history. | No |
|
|
130
|
+
| `/torusguard full` | `skills/torusguard-full` | End-to-End | Orchestrates the entire 7-stage security cycle in one coordinated sequence. | **Yes (Governed)** |
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## 🔄 The 7-Stage Closed-Loop Finding Lifecycle
|
|
135
|
+
|
|
136
|
+
Every candidate vulnerability transitions through an auditable, deterministic state machine:
|
|
137
|
+
|
|
138
|
+
```mermaid
|
|
139
|
+
flowchart LR
|
|
140
|
+
A["1. Detect<br><code>/torusguard-audit</code>"] --> B["2. Classify<br>AST Line Hashing"]
|
|
141
|
+
B --> C["3. Verify<br><code>verify / web-validate</code>"]
|
|
142
|
+
C --> D["4. Remediate<br><code>/torusguard-harden</code>"]
|
|
143
|
+
D --> E["5. Apply<br><code>/torusguard-apply</code>"]
|
|
144
|
+
E --> F["6. Recheck<br><code>/torusguard-recheck</code>"]
|
|
145
|
+
F --> G["7. Report<br><code>/torusguard-report</code>"]
|
|
146
|
+
|
|
147
|
+
style A fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#fff
|
|
148
|
+
style B fill:#1e293b,stroke:#6366f1,stroke-width:2px,color:#fff
|
|
149
|
+
style C fill:#1e293b,stroke:#8b5cf6,stroke-width:2px,color:#fff
|
|
150
|
+
style D fill:#1e293b,stroke:#ec4899,stroke-width:2px,color:#fff
|
|
151
|
+
style E fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fff
|
|
152
|
+
style F fill:#1e293b,stroke:#10b981,stroke-width:2px,color:#fff
|
|
153
|
+
style G fill:#1e293b,stroke:#06b6d4,stroke-width:2px,color:#fff
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
1. **Detect:** AST and regex heuristics scan source code, manifests, and configurations.
|
|
157
|
+
2. **Classify:** Computes line-shift invariant `primaryLocationLineHash` fingerprints and collapses repeated alerts into systemic root-cause clusters.
|
|
158
|
+
3. **Verify:** Scores evidence quality across a 5-factor mathematical rubric (0–100) and executes safe, bounded runtime probes.
|
|
159
|
+
4. **Remediate:** Formulates self-contained Remediation Bundles with framework-idiomatic Before/After fixes.
|
|
160
|
+
5. **Apply:** Employs the **Ponytail engine** to apply surgical patches governed by strict line churn limits ($\le 35$ additions, $\le 25$ deletions).
|
|
161
|
+
6. **Recheck:** Scopes differential re-audits strictly to modified files, confirming fix closure with zero regression.
|
|
162
|
+
7. **Report:** Generates human-first markdown summaries and OASIS SARIF v2.1.0 payloads for CI/CD pipelines.
|
|
150
163
|
|
|
151
164
|
---
|
|
152
165
|
|
|
153
166
|
## 🎯 Specialist Agents & Authority Separation
|
|
154
167
|
|
|
155
|
-
To eliminate AI confirmation bias, security responsibilities are divided across 5 formal roles
|
|
168
|
+
To eliminate AI confirmation bias, security responsibilities are divided across **5 formal, isolated roles**:
|
|
156
169
|
|
|
157
170
|
```mermaid
|
|
158
171
|
flowchart TD
|
|
@@ -162,158 +175,117 @@ flowchart TD
|
|
|
162
175
|
subgraph Detection
|
|
163
176
|
A["🔎 Auditor Agent<br><code>auditor.md</code>"]
|
|
164
177
|
end
|
|
165
|
-
subgraph
|
|
178
|
+
subgraph Verification
|
|
166
179
|
V["🧪 Validator Agent<br><code>validator.md</code>"]
|
|
167
180
|
end
|
|
168
181
|
subgraph Remediation
|
|
169
182
|
R["🛠️ Remediator Agent<br><code>remediator.md</code>"]
|
|
170
183
|
end
|
|
171
|
-
subgraph
|
|
172
|
-
|
|
184
|
+
subgraph Review
|
|
185
|
+
REV["⚖️ Reviewer Agent<br><code>reviewer.md</code>"]
|
|
173
186
|
end
|
|
174
187
|
|
|
175
|
-
P -->|
|
|
176
|
-
A -->|
|
|
177
|
-
V -->|
|
|
178
|
-
R -->|
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
style P fill:#
|
|
182
|
-
style A fill:#
|
|
183
|
-
style V fill:#
|
|
184
|
-
style R fill:#
|
|
185
|
-
style
|
|
188
|
+
P -->|Stack Profile| A
|
|
189
|
+
A -->|Static Findings| V
|
|
190
|
+
V -->|Validated Evidence| R
|
|
191
|
+
R -->|Remediation Diff| REV
|
|
192
|
+
REV -->|Final Verification| HumanGate["👤 Human Gate (Approval)"]
|
|
193
|
+
|
|
194
|
+
style P fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#fff
|
|
195
|
+
style A fill:#1e293b,stroke:#6366f1,stroke-width:2px,color:#fff
|
|
196
|
+
style V fill:#1e293b,stroke:#8b5cf6,stroke-width:2px,color:#fff
|
|
197
|
+
style R fill:#1e293b,stroke:#ec4899,stroke-width:2px,color:#fff
|
|
198
|
+
style REV fill:#1e293b,stroke:#10b981,stroke-width:2px,color:#fff
|
|
199
|
+
style HumanGate fill:#334155,stroke:#f59e0b,stroke-width:2px,color:#fff
|
|
186
200
|
```
|
|
187
201
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
3. **Validator (`validator.md`)**: Evaluates evidence sufficiency, probes live routes within `scope.json`, and confirms exploitability. *Authority: Bounded network read-only.*
|
|
191
|
-
4. **Remediator (`remediator.md`)**: Formulates minimal unified diffs under Ponytail Protocol limits. *Authority: Requires Human Gate approval for disk writes.*
|
|
192
|
-
5. **Reviewer (`reviewer.md`)**: Differentially re-scans modified lines, asserts closure, detects regressions, and exports SARIF logs. *Authority: Independent audit verification.*
|
|
202
|
+
* **No Self-Review:** The agent that proposes a patch (`Remediator`) can never approve its application (`Reviewer` + Human Gate required).
|
|
203
|
+
* **Deterministic Handoffs:** Every transition is recorded in `role-audit.json` with cryptographic provenance.
|
|
193
204
|
|
|
194
205
|
---
|
|
195
206
|
|
|
196
|
-
##
|
|
197
|
-
|
|
198
|
-
TorusGuard scores finding confidence using an objective 5-factor mathematical model (Max: 100 points):
|
|
207
|
+
## 🛡️ Rule Catalog & Detection Families (71 Canonical Rules)
|
|
199
208
|
|
|
200
|
-
|
|
201
|
-
| :--- | :---: | :--- |
|
|
202
|
-
| **1. Evidence Quality** | **35** | **35 pts**: Exact AST source match with untrusted data flow into sensitive sink.<br>**20 pts**: Regex/pattern heuristic match with confirmed code presence.<br>**10 pts**: Indirect indicator (outdated package or suspicious import). |
|
|
203
|
-
| **2. Reproduction Success** | **25** | **25 pts**: Deterministic unit test or runtime trace reproduces the flaw.<br>**15 pts**: Partial trace or simulated execution path confirmed.<br>**0 pts**: Purely static hypothesis without reproduction. |
|
|
204
|
-
| **3. Independent Confirmations** | **15** | **15 pts**: Flaw pattern corroborated across 3+ independent source files.<br>**10 pts**: Flaw pattern corroborated across 2 independent files.<br>**5 pts**: Single isolated occurrence. |
|
|
205
|
-
| **4. Environmental Clarity** | **15** | **15 pts**: Direct, clearly mapped framework route with explicit controller.<br>**8 pts**: Minor middleware indirection; deployment context partially clear.<br>**0 pts**: Dynamic routing, custom lambdas, or unknown gateway filters. |
|
|
206
|
-
| **5. Manual Review Status** | **10** | **10 pts**: Security engineer has explicitly reviewed and verified finding.<br>**5 pts**: Agent consensus / secondary review completed.<br>**0 pts**: Automated first-pass check only. |
|
|
209
|
+
TorusGuard enforces 71 rules across modern application stacks:
|
|
207
210
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
-
|
|
211
|
+
| Rule Family | Domain | Key Invariants & Detection Scope |
|
|
212
|
+
| :--- | :--- | :--- |
|
|
213
|
+
| **`TG-SEC-*`** | Secrets & Credentials | Blocks exposed API keys, private certs, Supabase service roles, and hardcoded tokens. |
|
|
214
|
+
| **`TG-DB-*`** | Database & Queries | Parameterized query enforcement, multi-tenant isolation filters (`.filter(tenant=...)`). |
|
|
215
|
+
| **`TG-INPUT-*`** | Input Validation | Pydantic/Zod boundary validation, path traversal prevention, command injection blocks. |
|
|
216
|
+
| **`TG-AUTH-*`** | Authentication & RBAC | Server-side route guards, session expiry, mass-assignment protection, IDOR prevention. |
|
|
217
|
+
| **`TG-CLIENT-*`** | Client Bundle Leaks | Blocks server-side environment variables (`SUPABASE_KEY`, `DATABASE_URL`) from browser bundles. |
|
|
218
|
+
| **`TG-DIFF-*`** | Diff Line Inspection | Evaluates patch additions/deletions for auth bypass comments (`// nosec`), disabled TLS, or filter removals. |
|
|
219
|
+
| **`TG-AGENT-*`** | AI Agent & MCP Security | Prompt injection boundaries in system prompts, unsandboxed tool execution, excessive tool permissions. |
|
|
220
|
+
| **`TG-EDGE-*`** | Serverless & Edge | Global memory leakage in V8 isolates (Cloudflare Workers), ephemeral cold-start leakage in AWS Lambda. |
|
|
221
|
+
| **`TG-SUPPLY-*`** | Supply Chain & CI/CD | GitHub Actions least privilege, container build secret mounts, destructive package upgrades. |
|
|
222
|
+
| **`TG-SSRF-*`** | Outbound Networking | Webhook signature validation, SSRF DNS re-binding protection, internal subnet blocking. |
|
|
223
|
+
| **`TG-BIZ-*`** | Business Logic | Multi-step transaction consistency, race condition guards, financial rounding integrity. |
|
|
213
224
|
|
|
214
225
|
---
|
|
215
226
|
|
|
216
|
-
##
|
|
227
|
+
## 🔬 Content-Aware Diff Line Scanner (`diff_guard.py`)
|
|
217
228
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
│ PONYTAIL PROTOCOL BOUNDS │
|
|
223
|
-
├────────────────────────────────────────────────────────┤
|
|
224
|
-
│ • Additions: <= 35 lines per bundle │
|
|
225
|
-
│ • Deletions: <= 25 lines per bundle │
|
|
226
|
-
│ • Zero full-file rewrites │
|
|
227
|
-
│ • Mandatory pre-apply rollback backup in pre_apply/ │
|
|
228
|
-
│ • Preserve existing error handling and public APIs │
|
|
229
|
-
└────────────────────────────────────────────────────────┘
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
Any fix exceeding these bounds is partitioned into sequential sub-bundles or flagged as `Requires Manual Architectural Refactor`.
|
|
229
|
+
Every patch generated by TorusGuard (or submitted via pull request) is verified against unified diff invariants:
|
|
230
|
+
* **`TG-DIFF-001` (Bypass Markers):** Flags additions containing `# bypass auth`, `// nosec`, or `verify=False`.
|
|
231
|
+
* **`TG-DIFF-002` (Credential Ingestion):** Rejects additions introducing live JWTs, Bearer tokens, or API keys.
|
|
232
|
+
* **`TG-DIFF-003` (Tenant Removal):** Rejects deletions removing tenant isolation clauses (`.filter(tenant=...)`, `where tenant_id`).
|
|
233
233
|
|
|
234
234
|
---
|
|
235
235
|
|
|
236
|
-
##
|
|
236
|
+
## 🏢 Monorepo Sub-Scope Orchestration (`monorepo_detector.py`)
|
|
237
237
|
|
|
238
|
-
TorusGuard
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
| **Workflows & Skills Suite** | `harness/validate_v0_9_2_workflows_and_skills.py` | 35 | **PASS (100%)** |
|
|
243
|
-
| **Manifest Integrity Verifier** | `.torusguard/scripts/manifest_builder.py --check` | 88 | **PASS (100%)** |
|
|
244
|
-
| **Installer Simulation Suite** | `harness/validate_v0_9_1_installer.py` | 14 | **PASS (100%)** |
|
|
245
|
-
| **Granular Skills Suite** | `harness/validate_v0_9_0_skills.py` | 53 | **PASS (100%)** |
|
|
246
|
-
| **Core Validation Harness** | `harness/runner.py` | 75 | **PASS (100%)** |
|
|
247
|
-
| **Senior QA Runtime Suite** | `harness/validate_v0_7_0_runtime.py` | 67 | **PASS (100%)** |
|
|
248
|
-
| **v0.8.0 Part 1 Foundation** | `harness/validate_v0_8_0_part1.py` | 11 | **PASS (100%)** |
|
|
249
|
-
| **v0.8.0 Part 2 Workflows & Agents** | `harness/validate_v0_8_0_part2.py` | 20 | **PASS (100%)** |
|
|
250
|
-
| **v0.8.0 Part 3 Scripts & References** | `harness/validate_v0_8_0_part3.py` | 18 | **PASS (100%)** |
|
|
238
|
+
TorusGuard automatically detects and profiles complex multi-package repositories:
|
|
239
|
+
* **Package Managers:** Turborepo, pnpm workspaces, npm/yarn workspaces, Lerna.
|
|
240
|
+
* **Service Resolution:** Profiles backend services (FastAPI/Django) and frontend apps (Next.js/React) independently.
|
|
241
|
+
* **Targeted Scoping:** Run audits across the entire workspace or focus strictly on a sub-package (`--target apps/backend`).
|
|
251
242
|
|
|
252
243
|
---
|
|
253
244
|
|
|
254
|
-
##
|
|
255
|
-
|
|
256
|
-
### 🐍 Python Ecosystem
|
|
257
|
-
- **[Django Guide](.torusguard/references/django-security.md):** Settings, CSRF, ORM queries, ModelForms, object ownership, and async coroutines (`aget()`).
|
|
258
|
-
- **[Django REST Framework Guide](.torusguard/references/drf-security.md):** Default permissions, ViewSets, serializers, throttles, and pagination.
|
|
259
|
-
- **[FastAPI Guide](.torusguard/references/fastapi-security.md):** Pydantic v2 schemas, `Annotated` dependency injection, SSRF boundaries, and HMAC webhooks.
|
|
260
|
-
- **[Flask Guide](.torusguard/references/flask-security.md):** Factory patterns, secure session cookies, `CSRFProtect`, and path traversal storage limits.
|
|
261
|
-
- **[SQLAlchemy Guide](.torusguard/references/sqlalchemy-security.md):** Bound query parameters, 2.0 `select()` statements, and multi-tenant isolation.
|
|
262
|
-
|
|
263
|
-
### 🌐 JavaScript & TypeScript Ecosystem
|
|
264
|
-
- **[React + Vite Guide](.torusguard/references/react-vite-security.md):** Frontend env variable boundaries, build artifact leakage, and source maps.
|
|
265
|
-
- **[Next.js Guide](.torusguard/references/nextjs-security.md):** App Router / Pages Router security, Server Components, and Server Action authorization (`"use server"`).
|
|
266
|
-
- **[Express Guide](.torusguard/references/express-security.md):** Helmet middleware, parameter validation, rate limiting, and CORS headers.
|
|
267
|
-
- **[Supabase Guide](.torusguard/references/supabase-security.md):** Row-Level Security (RLS), service-role key isolation, and secure client queries.
|
|
268
|
-
- **[Firebase Guide](.torusguard/references/firebase-security.md):** Firestore Security Rules, client SDK boundaries, and privileged admin tasks.
|
|
245
|
+
## 🎮 Interactive Multi-Stack Playground (`demo/playground/`)
|
|
269
246
|
|
|
270
|
-
|
|
247
|
+
Test TorusGuard against real, runnable vulnerable applications without putting production code at risk:
|
|
248
|
+
```bash
|
|
249
|
+
# Explore FastAPI playground:
|
|
250
|
+
python demo/playground/vulnerable_fastapi/main.py
|
|
271
251
|
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
Every execution is completely self-contained within an isolated directory (`.torusguard/runs/<run-id>/`):
|
|
275
|
-
|
|
276
|
-
```text
|
|
277
|
-
.torusguard/runs/run-20260902-120000-audit/
|
|
278
|
-
├── manifest.json # Execution metadata, git commit hash, and summary counts
|
|
279
|
-
├── summary.md # Executive summary and root-cause cluster matrix
|
|
280
|
-
├── findings.md # Detailed finding cards with code excerpts and remediation
|
|
281
|
-
├── web-validation.md # HTTP interaction log and endpoint status codes
|
|
282
|
-
├── requests.json # Redacted request payloads (tokens/passwords masked)
|
|
283
|
-
├── responses.json # Redacted response payloads
|
|
284
|
-
├── session-notes.md # Active session cookies and tenant context
|
|
285
|
-
├── replay.json # Deterministic replay trace for regression verification
|
|
286
|
-
├── results.sarif # OASIS SARIF v2.1.0 export for CI/CD & GitHub Code Scanning
|
|
287
|
-
└── patches/ # Formulated remediation bundles (diffs & pre-apply snapshots)
|
|
252
|
+
# Run TorusGuard audit on the playground:
|
|
253
|
+
npx torusguard audit --target demo/playground/vulnerable_fastapi
|
|
288
254
|
```
|
|
255
|
+
* **FastAPI Playground:** Demonstrates SQL injection, unauthenticated endpoints, and missing tenant scopes.
|
|
256
|
+
* **Next.js Playground:** Demonstrates Next.js Server Action data leaks, prompt injection sinks, and exposed client secrets.
|
|
289
257
|
|
|
290
258
|
---
|
|
291
259
|
|
|
292
|
-
##
|
|
260
|
+
## 🧪 Comprehensive Verification Suite (11/11 Passed)
|
|
293
261
|
|
|
294
|
-
|
|
295
|
-
|---|---|
|
|
296
|
-
| 🛡️ **[Security Policy](SECURITY.md)** | Responsible disclosure guidelines, supported versions, and release gate criteria |
|
|
297
|
-
| 👥 **[Maintainer Guide](MAINTAINERS.md)** | Account security, branch protections, supply-chain hygiene, and cryptographic release signing |
|
|
298
|
-
| 🏗️ **[System Architecture](.torusguard/ARCHITECTURE.md)** | Lifecycle flowcharts, authority separation, scoring rubric, and directory topology |
|
|
299
|
-
| 🗺️ **[Development Roadmap](docs/roadmap.md)** | Past releases, active milestones, and future horizons |
|
|
300
|
-
| 📝 **[Changelog](CHANGELOG.md)** | Complete release history following Keep a Changelog |
|
|
301
|
-
|
|
302
|
-
---
|
|
262
|
+
TorusGuard maintains zero-compromise test discipline. Every release must pass 100% of our regression suites:
|
|
303
263
|
|
|
304
|
-
|
|
264
|
+
```bash
|
|
265
|
+
# Run the complete test battery:
|
|
266
|
+
python harness/validate_v0_9_2_dual_track.py
|
|
267
|
+
python harness/validate_v0_9_2_diff_and_monorepo.py
|
|
268
|
+
python harness/validate_v0_9_2_workflows_and_skills.py
|
|
269
|
+
python .torusguard/scripts/manifest_builder.py --check
|
|
270
|
+
python harness/validate_v0_9_1_installer.py
|
|
271
|
+
python harness/validate_v0_9_0_skills.py
|
|
272
|
+
python harness/runner.py
|
|
273
|
+
python harness/validate_v0_7_0_runtime.py
|
|
274
|
+
python harness/validate_v0_8_0_part1.py
|
|
275
|
+
python harness/validate_v0_8_0_part2.py
|
|
276
|
+
python harness/validate_v0_8_0_part3.py
|
|
277
|
+
```
|
|
305
278
|
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
- **Not an unbounded vulnerability scanner:** Probes are bounded, single-step assertions against authorized endpoints with strict request budgets.
|
|
309
|
-
- **Not client-side DRM:** Browser-delivered JavaScript cannot be hidden from DevTools; security must reside on the backend.
|
|
310
|
-
- **Not an "unhackable" guarantee:** Security is continuous; TorusGuard provides structured guardrails, not absolute immunity.
|
|
279
|
+
* **Cryptographic Integrity:** All workspace templates are verified against SHA-256 signatures in `.torusguard/.manifest.json`.
|
|
280
|
+
* **Token Budget Guarantee:** All skills and workflows strictly respect a **1,000–1,500 token budget** to prevent AI context degradation.
|
|
311
281
|
|
|
312
282
|
---
|
|
313
283
|
|
|
314
|
-
##
|
|
284
|
+
## 📄 License & Community
|
|
285
|
+
|
|
286
|
+
TorusGuard is open-source software licensed under the [MIT License](LICENSE).
|
|
315
287
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
288
|
+
* **Author:** Jenish Lad ([@githubmofo](https://github.com/githubmofo))
|
|
289
|
+
* **Repository:** [https://github.com/githubmofo/TorusGuard](https://github.com/githubmofo/TorusGuard)
|
|
290
|
+
* **NPM Package:** [https://www.npmjs.com/package/torusguard](https://www.npmjs.com/package/torusguard)
|
|
291
|
+
* **Bug Reports & Issues:** [https://github.com/githubmofo/TorusGuard/issues](https://github.com/githubmofo/TorusGuard/issues)
|
package/bin/torusguard.js
CHANGED
|
@@ -37,7 +37,7 @@ try {
|
|
|
37
37
|
function printHelp() {
|
|
38
38
|
console.log(`
|
|
39
39
|
================================================================================
|
|
40
|
-
TORUSGUARD NPM PACKAGE — CLI COMMANDS (v0.9.
|
|
40
|
+
TORUSGUARD NPM PACKAGE — CLI COMMANDS (v0.9.3)
|
|
41
41
|
================================================================================
|
|
42
42
|
Usage:
|
|
43
43
|
npx torusguard [command] [options]
|
|
@@ -69,7 +69,7 @@ if (command === 'status') {
|
|
|
69
69
|
console.log('================================================================================');
|
|
70
70
|
console.log('TORUSGUARD ACTIVE POSTURE STATUS');
|
|
71
71
|
console.log('================================================================================');
|
|
72
|
-
console.log(`Version: ${cfg.version || '0.9.
|
|
72
|
+
console.log(`Version: ${cfg.version || '0.9.3'}`);
|
|
73
73
|
console.log(`Product: ${cfg.product || 'TorusGuard'}`);
|
|
74
74
|
console.log(`Severity Threshold: ${cfg.severity_threshold || 'medium'}`);
|
|
75
75
|
console.log(`Runs Directory: ${cfg.runs_dir || '.torusguard/runs'}`);
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "torusguard",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.3",
|
|
4
4
|
"description": "Security guardrails, governed remediation, and authorized runtime validation for AI-built web applications.",
|
|
5
5
|
"main": "bin/torusguard.js",
|
|
6
6
|
"bin": {
|
|
7
|
-
"torusguard": "
|
|
7
|
+
"torusguard": "bin/torusguard.js"
|
|
8
8
|
},
|
|
9
9
|
"files": [
|
|
10
10
|
"bin/",
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
"license": "MIT",
|
|
37
37
|
"repository": {
|
|
38
38
|
"type": "git",
|
|
39
|
-
"url": "https://github.com/githubmofo/TorusGuard.git"
|
|
39
|
+
"url": "git+https://github.com/githubmofo/TorusGuard.git"
|
|
40
40
|
},
|
|
41
41
|
"bugs": {
|
|
42
42
|
"url": "https://github.com/githubmofo/TorusGuard/issues"
|
|
Binary file
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
"agents/validator.md": "79fc4431de5c5507f8730aee6c5c3e61fd238cbf8cf8c7c6aac462eee9761ed6",
|
|
9
9
|
"config/scope.json": "b198a86186b4c6d5e1af516bf4e3a6afa8878e622ca1d57a5bf72d294f8c6f25",
|
|
10
10
|
"config/slash-commands.json": "5390f0d26f8117a62e56c58147d3a0d2deab1a20956302b212703281d13fa84e",
|
|
11
|
-
"config/torusguard.json": "
|
|
11
|
+
"config/torusguard.json": "fa2db9e3dbe5642dad99ae5be5db875f307ec82a61812a72be4922f760dbe0dd",
|
|
12
12
|
"references/django-security.md": "a15b7eb11b51dd1970d3d65544cf79ebea91fb99dc0e085e58a56532a718dce7",
|
|
13
13
|
"references/drf-security.md": "c7a7af3acaef895bf4798590acc88b3a2e9831a49eb2d23b4d8f31540ab264cc",
|
|
14
14
|
"references/express-security.md": "dff1db15e614d29d8c272f9da345b418077e62dc883fe210c7a50c552c76493f",
|