torusguard 0.9.2 โ 0.9.4
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 +2 -2
- package/.torusguard/config/torusguard.json +1 -1
- package/.torusguard/skills/torusguard/SKILL.md +1 -1
- package/README.md +300 -219
- package/bin/torusguard.js +54 -30
- package/package.json +3 -3
- package/skills/torusguard/SKILL.md +1 -1
- package/skills/torusguard/__pycache__/bootstrap.cpython-311.pyc +0 -0
- package/skills/torusguard/bootstrap.py +56 -30
- package/skills/torusguard/payload/.manifest.json +2 -2
- package/skills/torusguard/payload/config/torusguard.json +1 -1
- package/skills/torusguard/payload/skills/torusguard/SKILL.md +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": "218eeae10b538aca9b548d1b756d7d4f91a5b624e0bce07533f0c187860586e6",
|
|
12
12
|
"references/django-security.md": "a15b7eb11b51dd1970d3d65544cf79ebea91fb99dc0e085e58a56532a718dce7",
|
|
13
13
|
"references/drf-security.md": "c7a7af3acaef895bf4798590acc88b3a2e9831a49eb2d23b4d8f31540ab264cc",
|
|
14
14
|
"references/express-security.md": "dff1db15e614d29d8c272f9da345b418077e62dc883fe210c7a50c552c76493f",
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
"scripts/safety_gate.py": "3379b7534b2590cf563717a448983ad8ed7e8f174f0ad65683d33e8a10f51558",
|
|
41
41
|
"scripts/sarif_exporter.py": "35c66637413afc4b72d5bd426638447c77231d2a8594dce5addceffd4803a20d",
|
|
42
42
|
"scripts/stack_detect.py": "99b7bdf9829d58ff5b8c59afd6e8b6429bbb11d830ac73dec491101cbbc41574",
|
|
43
|
-
"skills/torusguard/SKILL.md": "
|
|
43
|
+
"skills/torusguard/SKILL.md": "5282a9e73c2faad97f079ff527def34b96709615c0dd297fe9b1bb2894f03e20",
|
|
44
44
|
"skills/torusguard/bootstrap.py": "7e348065a622089ab1d51e9bf4864e5b0022aaee1ccb2ecbf7057c14e792e2c7",
|
|
45
45
|
"skills/torusguard/references/auth-and-sessions.md": "34c2843f8c0dbe3574e54f00a39a92a1f431527ec5f69b2d64c84240d424a39e",
|
|
46
46
|
"skills/torusguard/references/business-logic-and-abuse.md": "0d6088936bc1a01023070332fccef0f2e0734358a5119379055f3d2895c22567",
|
package/README.md
CHANGED
|
@@ -3,12 +3,14 @@
|
|
|
3
3
|
|
|
4
4
|
# TorusGuard
|
|
5
5
|
|
|
6
|
-
**Security
|
|
6
|
+
**Autonomous 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)
|
|
11
|
-
[](https://nodejs.org)
|
|
13
|
+
[](.torusguard/schemas/)
|
|
12
14
|
[](.torusguard/.manifest.json)
|
|
13
15
|
[](docs/architecture/SECURITY_ARCHITECTURE.md)
|
|
14
16
|
</div>
|
|
@@ -17,303 +19,382 @@
|
|
|
17
19
|
|
|
18
20
|
## ๐ก Executive Summary
|
|
19
21
|
|
|
20
|
-
AI coding
|
|
22
|
+
Modern AI coding agents generate full-stack web applications at unprecedented velocity. However, they consistently introduce critical security anti-patterns: leaking service-role credentials to browser bundles, omitting multi-tenant query boundaries, disabling CSRF defenses, or granting unconstrained tool permissions.
|
|
21
23
|
|
|
22
|
-
**TorusGuard** is an
|
|
23
|
-
- **Find real vulnerabilities:** Scan your codebase against 71 security rules across Python, TypeScript, and modern frameworks.
|
|
24
|
-
- **Confirm exploitability:** Verify whether weaknesses are truly reachable before creating noise.
|
|
25
|
-
- **Patch safely:** Generate and apply minimal, surgical fixes that resolve flaws without breaking existing functionality.
|
|
24
|
+
**TorusGuard** is an autonomous application security co-pilot specifically engineered for AI-built software. It integrates natively into your development environment (Antigravity, Cursor, Claude Code, VS Code Copilot, Kimi, Windsurf, Cline) to deliver:
|
|
26
25
|
|
|
27
|
-
|
|
26
|
+
1. **Deterministic Static Auditing:** Scan Python and TypeScript source code using 71 specialized security rules across 11 families.
|
|
27
|
+
2. **Authorized Runtime Validation:** Execute bounded, non-destructive HTTP probes to eliminate false alarms and confirm real exploitability.
|
|
28
|
+
3. **Governed Minimal Remediation:** Generate surgical, reviewable patches constrained by the **Ponytail Protocol** ($\le 35$ additions, $\le 25$ deletions) to eliminate unintended regressions.
|
|
29
|
+
4. **Open Industry Standards:** Emit OASIS SARIF v2.1.0 telemetry with stable AST line-shift invariant hashes for native GitHub Code Scanning integration.
|
|
30
|
+
|
|
31
|
+
### ๐ The Core Invariant: The Browser-Code Truth
|
|
28
32
|
> **"If the browser receives it, users can inspect it."**
|
|
29
|
-
>
|
|
33
|
+
> Frontend environment variables, JavaScript network bundles, and React Server Action payloads cannot conceal secrets. TorusGuard strictly enforces that database credentials, private API keys, and authorization barriers remain exclusively on trusted server boundaries.
|
|
30
34
|
|
|
31
35
|
---
|
|
32
36
|
|
|
33
|
-
##
|
|
37
|
+
## โก Dual-Track Distribution Architecture
|
|
34
38
|
|
|
35
|
-
|
|
39
|
+
TorusGuard features a decoupled **Dual-Track Architecture** allowing teams to choose between zero-setup in-memory agent intelligence and full repository governance:
|
|
36
40
|
|
|
37
41
|
```mermaid
|
|
38
|
-
flowchart
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
F --> G["7. Report<br><code>/torusguard report</code>"]
|
|
45
|
-
|
|
46
|
-
style A fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#fff
|
|
47
|
-
style B fill:#1e293b,stroke:#6366f1,stroke-width:2px,color:#fff
|
|
48
|
-
style C fill:#1e293b,stroke:#8b5cf6,stroke-width:2px,color:#fff
|
|
49
|
-
style D fill:#1e293b,stroke:#ec4899,stroke-width:2px,color:#fff
|
|
50
|
-
style E fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fff
|
|
51
|
-
style F fill:#1e293b,stroke:#10b981,stroke-width:2px,color:#fff
|
|
52
|
-
style G fill:#1e293b,stroke:#06b6d4,stroke-width:2px,color:#fff
|
|
53
|
-
```
|
|
42
|
+
flowchart TD
|
|
43
|
+
subgraph Core ["๐ก๏ธ TorusGuard Core Intelligence Engine"]
|
|
44
|
+
Rules["71 Canonical Security Rules"]
|
|
45
|
+
Ponytail["Ponytail Patch Governor (<=35 add, <=25 del)"]
|
|
46
|
+
Scorer["5-Factor Mathematical Confidence Scorer"]
|
|
47
|
+
end
|
|
54
48
|
|
|
55
|
-
|
|
56
|
-
|
|
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.
|
|
49
|
+
Core --> Track1["โก Track 1: Universal AI Agent Skill"]
|
|
50
|
+
Core --> Track2["๐ก๏ธ Track 2: Production NPM Package"]
|
|
62
51
|
|
|
63
|
-
|
|
52
|
+
subgraph Track1Scope ["Track 1: In-Memory Agent Execution"]
|
|
53
|
+
T1Cmd["npx skills add ... -a universal -y"]
|
|
54
|
+
T1Env["Works in ANY AI Agent (Cursor, Kimi, Antigravity, Copilot)"]
|
|
55
|
+
T1Disk["Zero local file footprint (pure in-memory reasoning)"]
|
|
56
|
+
T1Router["Single clean slash command: /torusguard"]
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
subgraph Track2Scope ["Track 2: Full Local Governance"]
|
|
60
|
+
T2Cmd["npx torusguard init / npm i -D torusguard"]
|
|
61
|
+
T2Env["Persistent .torusguard/ repository workspace"]
|
|
62
|
+
T2CLI["Native Terminal CLI: npx torusguard status / audit"]
|
|
63
|
+
T2Palette["Unlocks all 11 individual slash commands (/torusguard-*)"]
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
Track1 --> Track1Scope
|
|
67
|
+
Track2 --> Track2Scope
|
|
64
68
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
TorusGuard operates on a high-performance **Two-Tier Command Engine** designed for AI-assisted development environments. It unifies interactive slash commands with specialized domain knowledge while preserving maximum context window capacity:
|
|
68
|
-
|
|
69
|
-
1. **Interactive Workflows (`.torusguard/workflows/<cmd>.md`):**
|
|
70
|
-
Structured execution playbooks triggered by slash commands (e.g., `/torusguard audit`). Each workflow enforces pre-flight context validation, provides situational decision matrices, executes deterministic CLI commands, and enforces strict failure recovery rules.
|
|
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
|
|
69
|
+
Track1Scope -. Harmonizes with .- Track2Scope
|
|
93
70
|
```
|
|
94
71
|
|
|
95
|
-
|
|
72
|
+
### Track Comparison Matrix
|
|
96
73
|
|
|
97
|
-
|
|
74
|
+
| Capability | โก Track 1: Universal AI Agent Skill | ๐ก๏ธ Track 2: Production NPM Package |
|
|
75
|
+
| :--- | :--- | :--- |
|
|
76
|
+
| **Primary Command** | `npx skills add https://github.com/githubmofo/TorusGuard -a universal -y` | `npx torusguard init` or `npm install -D torusguard` |
|
|
77
|
+
| **Supported Agents** | All AI Agents (Antigravity, Cursor, Claude Code, Copilot, Kimi, Windsurf) | Any Node/Python repository, GitHub Actions CI/CD, Antigravity, Cursor |
|
|
78
|
+
| **Disk Footprint** | In-memory agent context (`.agents/skills/torusguard/` only) | Complete local workspace (`.torusguard/` with config, rules, schemas, runs) |
|
|
79
|
+
| **Slash Commands** | Single master dispatcher: `/torusguard` | Full 11-command palette: `/torusguard-audit`, `/torusguard-apply`, etc. |
|
|
80
|
+
| **Terminal CLI** | None (AI chat-driven) | Native terminal runner: `npx torusguard status`, `npx torusguard audit` |
|
|
81
|
+
| **Prerequisites** | None (pure AI agent execution) | Node.js 18+ (and Python 3.10+ for native verification scripts) |
|
|
82
|
+
| **Best For** | Instant zero-setup security advice in chat | Production repositories, team compliance, CI/CD SARIF exports |
|
|
98
83
|
|
|
99
|
-
|
|
84
|
+
---
|
|
100
85
|
|
|
101
|
-
|
|
86
|
+
## ๐ Installation & Quick Start
|
|
102
87
|
|
|
103
|
-
|
|
104
|
-
Install directly into any AI
|
|
88
|
+
### Track 1: Universal AI Agent Skill (Zero Setup)
|
|
89
|
+
Install directly into any AI assistant adhering to the Open Agent Skills standard:
|
|
105
90
|
```bash
|
|
106
|
-
|
|
91
|
+
# Recommended one-liner (silent, zero-prompts, targets all IDE agents):
|
|
92
|
+
npx skills add https://github.com/githubmofo/TorusGuard -a universal -y
|
|
107
93
|
```
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
*
|
|
94
|
+
* **`-a universal`**: Automatically registers the skill for Antigravity, Cursor, Gemini CLI, Claude Code, VS Code Copilot, and Kimi without prompt friction.
|
|
95
|
+
* **`-y`**: Bypasses interactive confirmation prompts and completes in **under 2 seconds**.
|
|
96
|
+
* Once installed, simply type `/torusguard` in chat or ask: *"Audit this component for security flaws"*.
|
|
111
97
|
|
|
112
|
-
|
|
113
|
-
Scaffold
|
|
98
|
+
### Track 2: Production NPM Package (Full Governance)
|
|
99
|
+
Scaffold your repository with local configuration, offline scripts, and granular workflows:
|
|
114
100
|
```bash
|
|
115
|
-
# Direct runner:
|
|
101
|
+
# Direct runner (recommended):
|
|
116
102
|
npx torusguard init
|
|
117
103
|
|
|
118
|
-
# Or install
|
|
104
|
+
# Or install as a development dependency:
|
|
119
105
|
npm install -D torusguard
|
|
120
106
|
```
|
|
121
|
-
*
|
|
122
|
-
*
|
|
123
|
-
*
|
|
124
|
-
|
|
125
|
-
|
|
107
|
+
* Generates the `.torusguard/` workspace directory.
|
|
108
|
+
* Populates your IDE command palette with all 11 individual `/torusguard-*` workflows.
|
|
109
|
+
* Run instant terminal checks anytime:
|
|
110
|
+
```bash
|
|
111
|
+
npx torusguard status
|
|
112
|
+
npx torusguard audit
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Standalone Python Installer (Alternative)
|
|
116
|
+
For Python-only environments, Docker containers, or air-gapped CI/CD runners:
|
|
126
117
|
```bash
|
|
118
|
+
# From cloned repository:
|
|
127
119
|
python install.py
|
|
128
|
-
|
|
120
|
+
|
|
121
|
+
# Or via remote one-liner:
|
|
129
122
|
curl -sSL https://raw.githubusercontent.com/githubmofo/TorusGuard/main/install.py | python
|
|
130
123
|
```
|
|
131
124
|
|
|
132
125
|
---
|
|
133
126
|
|
|
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
|
|
127
|
+
## ๐ Comprehensive Command Catalog
|
|
128
|
+
|
|
129
|
+
When Track 2 is initialized, the complete 11-command palette becomes available in your IDE (`.agent/workflows/`, `.agents/workflows/`, `.claude/commands/`, `.cursor/rules/`):
|
|
130
|
+
|
|
131
|
+
| Slash Command | Specialist Skill | Lifecycle Phase | Operational Description | Code Changed? |
|
|
132
|
+
| :--- | :--- | :---: | :--- | :---: |
|
|
133
|
+
| `/torusguard` | `skills/torusguard` | Router | Master natural-language command dispatcher and prompt auditor. | No |
|
|
134
|
+
| `/torusguard init`<br>*(or `/torusguard-init`)* | `skills/torusguard-init` | Phase 0 | Profiles repository stack, discovers frameworks, and enables matching rules. | Yes (`.torusguard/`) |
|
|
135
|
+
| `/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`) |
|
|
136
|
+
| `/torusguard audit`<br>*(or `/torusguard-audit`)* | `skills/torusguard-audit` | Phase 2 | Scans source code and clusters repeated alerts by root-cause identity. | No |
|
|
137
|
+
| `/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 |
|
|
138
|
+
| `/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 |
|
|
139
|
+
| `/torusguard exploit-check`<br>*(or `/torusguard-exploit-check`)* | `skills/torusguard-exploit-check` | Phase 3 | Validates exploitability safely into 5 formal verification statuses. | No |
|
|
140
|
+
| `/torusguard harden`<br>*(or `/torusguard-harden`)* | `skills/torusguard-harden` | Phase 4 | Packages 4-artifact Remediation Bundles with framework-idiomatic fixes. | No |
|
|
141
|
+
| `/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)** |
|
|
142
|
+
| `/torusguard recheck`<br>*(or `/torusguard-recheck`)* | `skills/torusguard-recheck` | Phase 6 | Executes differential re-audit strictly on modified files to verify fix closure. | No |
|
|
143
|
+
| `/torusguard report`<br>*(or `/torusguard-report`)* | `skills/torusguard-report` | Phase 7 | Emits executive summary markdown and OASIS SARIF v2.1.0 CI artifacts. | No |
|
|
144
|
+
| `/torusguard status`<br>*(or `/torusguard-status`)* | `skills/torusguard-status` | Diagnostic | Inspects active security posture, thresholds, and recent run history. | No |
|
|
145
|
+
| `/torusguard full` | `skills/torusguard-full` | End-to-End | Orchestrates the entire 7-stage security cycle in one coordinated sequence. | **Yes (Governed)** |
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## ๐ The 7-Stage Closed-Loop Finding Lifecycle
|
|
150
|
+
|
|
151
|
+
Every candidate vulnerability transitions through an auditable, deterministic state machine with zero regression tolerance:
|
|
152
|
+
|
|
153
|
+
```mermaid
|
|
154
|
+
flowchart LR
|
|
155
|
+
Detect["1. Detect<br>/torusguard audit"] --> Classify["2. Classify<br>AST Line Hashing"]
|
|
156
|
+
Classify --> Verify["3. Verify<br>verify / web-validate"]
|
|
157
|
+
Verify --> Remediate["4. Remediate<br>/torusguard harden"]
|
|
158
|
+
Remediate --> Apply["5. Apply<br>/torusguard apply"]
|
|
159
|
+
Apply --> Recheck["6. Recheck<br>/torusguard recheck"]
|
|
160
|
+
Recheck --> Report["7. Report<br>/torusguard report"]
|
|
161
|
+
|
|
162
|
+
style Detect fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#fff
|
|
163
|
+
style Classify fill:#1e293b,stroke:#6366f1,stroke-width:2px,color:#fff
|
|
164
|
+
style Verify fill:#1e293b,stroke:#8b5cf6,stroke-width:2px,color:#fff
|
|
165
|
+
style Remediate fill:#1e293b,stroke:#ec4899,stroke-width:2px,color:#fff
|
|
166
|
+
style Apply fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fff
|
|
167
|
+
style Recheck fill:#1e293b,stroke:#10b981,stroke-width:2px,color:#fff
|
|
168
|
+
style Report fill:#1e293b,stroke:#06b6d4,stroke-width:2px,color:#fff
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Lifecycle Stage Breakdown
|
|
172
|
+
|
|
173
|
+
| Stage | Command | Responsible Agent | Primary Activity & Invariant Guarantee |
|
|
174
|
+
| :---: | :--- | :---: | :--- |
|
|
175
|
+
| **1. Detect** | `/torusguard audit` | `auditor` | Static AST and regex inspection flags potential vulnerabilities across Python and TypeScript. |
|
|
176
|
+
| **2. Classify** | *(automatic)* | `auditor` | Computes line-shift invariant `primaryLocationLineHash` fingerprints and clusters repeated instances into root causes. |
|
|
177
|
+
| **3. Verify** | `/torusguard verify` | `validator` | Applies a 5-factor mathematical scoring model (0โ100) and executes authorized, bounded runtime HTTP probes. |
|
|
178
|
+
| **4. Remediate** | `/torusguard harden` | `remediator` | Generates self-contained Remediation Bundles containing unified diffs and rollbacks. |
|
|
179
|
+
| **5. Apply** | `/torusguard apply` | `remediator` | Takes pre-apply file snapshots and enforces **Ponytail bounds** ($\le 35$ additions, $\le 25$ deletions). |
|
|
180
|
+
| **6. Recheck** | `/torusguard recheck` | `reviewer` | Performs differential re-audit strictly on modified files to verify fix closure without introducing new flaws. |
|
|
181
|
+
| **7. Report** | `/torusguard report` | `reviewer` | Synthesizes an executive Markdown summary and exports an OASIS SARIF v2.1.0 file for CI/CD tracking. |
|
|
150
182
|
|
|
151
183
|
---
|
|
152
184
|
|
|
153
185
|
## ๐ฏ Specialist Agents & Authority Separation
|
|
154
186
|
|
|
155
|
-
To eliminate AI confirmation bias, security responsibilities are divided across 5 formal roles
|
|
187
|
+
To eliminate AI confirmation bias, security responsibilities are divided across **5 formal, isolated roles**:
|
|
156
188
|
|
|
157
189
|
```mermaid
|
|
158
190
|
flowchart TD
|
|
159
|
-
subgraph Discovery
|
|
160
|
-
P["๐ Profiler Agent<br
|
|
191
|
+
subgraph DiscoveryPhase ["Discovery Phase"]
|
|
192
|
+
P["๐ Profiler Agent<br>profiler.md"]
|
|
161
193
|
end
|
|
162
|
-
|
|
163
|
-
|
|
194
|
+
|
|
195
|
+
subgraph DetectionPhase ["Detection Phase"]
|
|
196
|
+
A["๐ Auditor Agent<br>auditor.md"]
|
|
164
197
|
end
|
|
165
|
-
|
|
166
|
-
|
|
198
|
+
|
|
199
|
+
subgraph VerificationPhase ["Verification Phase"]
|
|
200
|
+
V["๐งช Validator Agent<br>validator.md"]
|
|
167
201
|
end
|
|
168
|
-
|
|
169
|
-
|
|
202
|
+
|
|
203
|
+
subgraph RemediationPhase ["Remediation Phase"]
|
|
204
|
+
R["๐ ๏ธ Remediator Agent<br>remediator.md"]
|
|
170
205
|
end
|
|
171
|
-
|
|
172
|
-
|
|
206
|
+
|
|
207
|
+
subgraph ReviewPhase ["Review & Sign-Off Phase"]
|
|
208
|
+
REV["โ๏ธ Reviewer Agent<br>reviewer.md"]
|
|
209
|
+
HumanGate["๐ค Human Gate (Approval)"]
|
|
173
210
|
end
|
|
174
211
|
|
|
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
|
|
212
|
+
P -->|Stack Profile| A
|
|
213
|
+
A -->|Static Findings| V
|
|
214
|
+
V -->|Validated Evidence| R
|
|
215
|
+
R -->|Remediation Diff| REV
|
|
216
|
+
REV -->|Zero-Regress Sign-Off| HumanGate
|
|
217
|
+
|
|
218
|
+
style P fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#fff
|
|
219
|
+
style A fill:#1e293b,stroke:#6366f1,stroke-width:2px,color:#fff
|
|
220
|
+
style V fill:#1e293b,stroke:#8b5cf6,stroke-width:2px,color:#fff
|
|
221
|
+
style R fill:#1e293b,stroke:#ec4899,stroke-width:2px,color:#fff
|
|
222
|
+
style REV fill:#1e293b,stroke:#10b981,stroke-width:2px,color:#fff
|
|
223
|
+
style HumanGate fill:#334155,stroke:#f59e0b,stroke-width:2px,color:#fff
|
|
186
224
|
```
|
|
187
225
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
226
|
+
### Agent Responsibilities & Isolation Rules
|
|
227
|
+
|
|
228
|
+
| Agent | Specification | Dedicated Purpose | Anti-Bias Isolation Rule |
|
|
229
|
+
| :--- | :--- | :--- | :--- |
|
|
230
|
+
| **๐ Profiler** | `.torusguard/agents/profiler.md` | Discovers frameworks, ORMs, and packages. | Cannot conduct vulnerability detection. |
|
|
231
|
+
| **๐ Auditor** | `.torusguard/agents/auditor.md` | AST pattern matching and root-cause clustering. | Cannot propose code modifications or execute probes. |
|
|
232
|
+
| **๐งช Validator** | `.torusguard/agents/validator.md` | Bounded runtime HTTP validation and scoring. | Bound by `scope.json` authorization boundaries. |
|
|
233
|
+
| **๐ ๏ธ Remediator** | `.torusguard/agents/remediator.md` | Formulates surgical, minimal code patches. | **Cannot approve its own patch.** |
|
|
234
|
+
| **โ๏ธ Reviewer** | `.torusguard/agents/reviewer.md` | Pre-flight verification and compliance sign-off. | **Must be independent from Remediator.** |
|
|
235
|
+
|
|
236
|
+
* **Zero Self-Review:** The agent that writes a patch (`Remediator`) can never sign off on its merge (`Reviewer` + Human Gate required).
|
|
237
|
+
* **Cryptographic Provenance:** Every role handoff is recorded in `role-audit.json` with SHA-256 signatures.
|
|
193
238
|
|
|
194
239
|
---
|
|
195
240
|
|
|
196
|
-
##
|
|
241
|
+
## ๐ก๏ธ Core Innovation Highlights
|
|
197
242
|
|
|
198
|
-
|
|
243
|
+
### 1. The Ponytail Protocol (Minimal Patch Churn Bounds)
|
|
244
|
+
Unbounded AI code generators frequently rewrite adjacent business logic, introduce accidental syntax errors, or strip comments. TorusGuard strictly enforces the **Ponytail Protocol**:
|
|
245
|
+
* **$\le 35$ Additions** per remediation patch.
|
|
246
|
+
* **$\le 25$ Deletions** per remediation patch.
|
|
247
|
+
* **Deterministic Single Responsibility:** Every patch resolves exactly one root-cause cluster without side effects.
|
|
199
248
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
249
|
+
### 2. Auditable Mathematical Confidence Scoring (0โ100)
|
|
250
|
+
TorusGuard computes confidence scores using a formal 5-factor mathematical formula before escalating findings to developers:
|
|
251
|
+
$$\text{Score} = (w_d \cdot D) + (w_e \cdot E) + (w_c \cdot C_{ast}) - P_{fp} - P_{drift}$$
|
|
252
|
+
* **$D$ (Detection Determinism, 30%):** Exact string/AST regex matches vs speculative patterns.
|
|
253
|
+
* **$E$ (Runtime Evidence, 25%):** Confirmed HTTP exploitability response status.
|
|
254
|
+
* **$C_{ast}$ (AST Contextuality, 25%):** Direct assignment in critical execution path vs commented code.
|
|
255
|
+
* **$P_{fp}$ (False Positive Penalty, up to -20):** Safe wrapper detection (e.g. parameterized queries, sanitizers).
|
|
256
|
+
* **$P_{drift}$ (Line Drift Penalty, up to -10):** Unmatched surrounding file context.
|
|
207
257
|
|
|
208
|
-
###
|
|
209
|
-
-
|
|
210
|
-
- **`70โ89` (`High Confidence`)**: Strong direct indicators; prioritized remediation.
|
|
211
|
-
- **`50โ69` (`Medium Confidence`)**: Probable flaw; runtime confirmation recommended.
|
|
212
|
-
- **`< 50` (`Needs Review`)**: Architectural ambiguity or potential delegated control.
|
|
258
|
+
### 3. Stable Line-Shift Invariant Fingerprinting (`primaryLocationLineHash`)
|
|
259
|
+
Traditional static tools break finding identity when a developer inserts 2 lines at the top of a file. TorusGuard computes a stable SHA-256 hash across the AST node content, enclosing function scope, and syntactic tokens. Findings maintain permanent tracking identity across Git commits and branch renames.
|
|
213
260
|
|
|
214
261
|
---
|
|
215
262
|
|
|
216
|
-
##
|
|
263
|
+
## ๐ก๏ธ Rule Catalog & Detection Families (71 Canonical Rules)
|
|
217
264
|
|
|
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
|
-
```
|
|
265
|
+
TorusGuard enforces 71 rules across modern application stacks:
|
|
231
266
|
|
|
232
|
-
|
|
267
|
+
| Rule Family | Target Domain | Invariant Guarantees & Detection Scope |
|
|
268
|
+
| :--- | :--- | :--- |
|
|
269
|
+
| **`TG-SEC-*`** | Secrets & Credentials | Blocks exposed API keys, private certs, Supabase service roles, and hardcoded tokens. |
|
|
270
|
+
| **`TG-DB-*`** | Database & Queries | Enforces parameterized SQL queries and mandatory multi-tenant isolation filters (`.filter(tenant=...)`). |
|
|
271
|
+
| **`TG-INPUT-*`** | Input Validation | Validates Pydantic/Zod boundaries, prevents path traversal, and blocks unsanitized command execution. |
|
|
272
|
+
| **`TG-AUTH-*`** | Authentication & RBAC | Requires server-side route guards, enforces session TTLs, stops mass-assignment, and guards against IDOR. |
|
|
273
|
+
| **`TG-CLIENT-*`** | Client Bundle Leaks | Blocks server-side environment variables (`SUPABASE_KEY`, `DATABASE_URL`) from browser bundles. |
|
|
274
|
+
| **`TG-DIFF-*`** | Diff Line Inspection | Evaluates patch additions/deletions for auth bypass comments (`// nosec`), disabled TLS, or filter removals. |
|
|
275
|
+
| **`TG-AGENT-*`** | AI Agent & MCP Security | Enforces prompt injection delimiters, sandboxes tool execution, and restricts destructive tool capabilities. |
|
|
276
|
+
| **`TG-EDGE-*`** | Serverless & Edge | Prevents global memory leakage in V8 isolates (Cloudflare Workers) and cold-start state bleed in AWS Lambda. |
|
|
277
|
+
| **`TG-SUPPLY-*`** | Supply Chain & CI/CD | Enforces GitHub Actions least-privilege permissions, validates Docker build secrets, and flags risky deps. |
|
|
278
|
+
| **`TG-SSRF-*`** | Outbound Networking | Enforces webhook HMAC signature verification, prevents SSRF DNS rebinding, and blocks internal subnets. |
|
|
279
|
+
| **`TG-BIZ-*`** | Business Logic | Protects multi-step financial transactions, race conditions, and currency rounding precision. |
|
|
233
280
|
|
|
234
281
|
---
|
|
235
282
|
|
|
236
|
-
##
|
|
283
|
+
## ๐ฌ Content-Aware Diff Line Scanner (`diff_guard.py`)
|
|
237
284
|
|
|
238
|
-
|
|
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%)** |
|
|
285
|
+
Every patch generated by TorusGuard (or submitted via Pull Request) is analyzed by our unified diff inspector:
|
|
286
|
+
* **`TG-DIFF-001` (Bypass Markers):** Detects bypass comments (`# bypass auth`, `// nosec`) and disabled TLS verification (`verify=False`).
|
|
287
|
+
* **`TG-DIFF-002` (Credential Ingestion):** Intercepts live JWTs, Bearer tokens, or high-entropy secrets introduced in additions.
|
|
288
|
+
* **`TG-DIFF-003` (Tenant Removal):** Blocks deletions that strip tenant isolation clauses (`.filter(tenant=...)`, `where tenant_id`).
|
|
251
289
|
|
|
252
290
|
---
|
|
253
291
|
|
|
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.
|
|
292
|
+
## ๐ข Monorepo Sub-Scope Orchestration (`monorepo_detector.py`)
|
|
262
293
|
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
294
|
+
TorusGuard natively discovers and isolates sub-projects in complex monorepos:
|
|
295
|
+
* **Package Managers:** Turborepo, pnpm workspaces, npm/yarn workspaces, Lerna.
|
|
296
|
+
* **Service Independence:** Profiles backend services (FastAPI/Django) and frontend applications (Next.js/React) separately.
|
|
297
|
+
* **Targeted Scanning:** Audit the entire repository or focus strictly on a specific service:
|
|
298
|
+
```bash
|
|
299
|
+
npx torusguard audit --target apps/api
|
|
300
|
+
```
|
|
269
301
|
|
|
270
302
|
---
|
|
271
303
|
|
|
272
|
-
##
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
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)
|
|
304
|
+
## ๐ฎ Interactive Multi-Stack Playground (`demo/playground/`)
|
|
305
|
+
|
|
306
|
+
Test TorusGuard against real, runnable vulnerable applications without exposing production code:
|
|
307
|
+
```bash
|
|
308
|
+
# Explore FastAPI playground:
|
|
309
|
+
python demo/playground/vulnerable_fastapi/main.py
|
|
310
|
+
|
|
311
|
+
# Run TorusGuard audit against the playground:
|
|
312
|
+
npx torusguard audit --target demo/playground/vulnerable_fastapi
|
|
288
313
|
```
|
|
314
|
+
* **FastAPI Playground:** Demonstrates raw SQL string formatting, unauthenticated routes, and missing tenant scopes.
|
|
315
|
+
* **Next.js Playground:** Demonstrates Next.js Server Action data leaks, prompt injection sinks, and exposed client secrets.
|
|
289
316
|
|
|
290
317
|
---
|
|
291
318
|
|
|
292
|
-
##
|
|
319
|
+
## ๐ GitHub Actions CI/CD Integration
|
|
320
|
+
|
|
321
|
+
Integrate TorusGuard directly into your GitHub Actions workflow to scan pull requests and export OASIS SARIF v2.1.0 to GitHub Advanced Security:
|
|
322
|
+
|
|
323
|
+
```yaml
|
|
324
|
+
name: TorusGuard Security Scan
|
|
293
325
|
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
326
|
+
on:
|
|
327
|
+
push:
|
|
328
|
+
branches: [main]
|
|
329
|
+
pull_request:
|
|
330
|
+
branches: [main]
|
|
331
|
+
|
|
332
|
+
jobs:
|
|
333
|
+
security-audit:
|
|
334
|
+
runs-on: ubuntu-latest
|
|
335
|
+
steps:
|
|
336
|
+
- name: Checkout Code
|
|
337
|
+
uses: actions/checkout@v4
|
|
338
|
+
|
|
339
|
+
- name: Setup Node.js
|
|
340
|
+
uses: actions/setup-node@v4
|
|
341
|
+
with:
|
|
342
|
+
node-version: 18
|
|
343
|
+
|
|
344
|
+
- name: Setup Python
|
|
345
|
+
uses: actions/setup-python@v5
|
|
346
|
+
with:
|
|
347
|
+
python-version: '3.11'
|
|
348
|
+
|
|
349
|
+
- name: Initialize TorusGuard
|
|
350
|
+
run: npx torusguard init --force
|
|
351
|
+
|
|
352
|
+
- name: Execute Security Audit
|
|
353
|
+
run: npx torusguard audit
|
|
354
|
+
|
|
355
|
+
- name: Generate SARIF Telemetry
|
|
356
|
+
run: npx torusguard report
|
|
357
|
+
|
|
358
|
+
- name: Upload SARIF to GitHub Code Scanning
|
|
359
|
+
uses: github/codeql-action/upload-sarif@v3
|
|
360
|
+
with:
|
|
361
|
+
sarif_file: .torusguard/runs/latest/report.sarif
|
|
362
|
+
if: always()
|
|
363
|
+
```
|
|
301
364
|
|
|
302
365
|
---
|
|
303
366
|
|
|
304
|
-
##
|
|
367
|
+
## ๐งช Comprehensive Verification Battery (11/11 Passed)
|
|
368
|
+
|
|
369
|
+
TorusGuard enforces strict testing standards. Every release must achieve a **100% pass rate** across our entire test suite:
|
|
370
|
+
|
|
371
|
+
```bash
|
|
372
|
+
python harness/validate_v0_9_2_dual_track.py
|
|
373
|
+
python harness/validate_v0_9_2_diff_and_monorepo.py
|
|
374
|
+
python harness/validate_v0_9_2_workflows_and_skills.py
|
|
375
|
+
python .torusguard/scripts/manifest_builder.py --check
|
|
376
|
+
python harness/validate_v0_9_1_installer.py
|
|
377
|
+
python harness/validate_v0_9_0_skills.py
|
|
378
|
+
python harness/runner.py
|
|
379
|
+
python harness/validate_v0_7_0_runtime.py
|
|
380
|
+
python harness/validate_v0_8_0_part1.py
|
|
381
|
+
python harness/validate_v0_8_0_part2.py
|
|
382
|
+
python harness/validate_v0_8_0_part3.py
|
|
383
|
+
```
|
|
305
384
|
|
|
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.
|
|
385
|
+
* **Cryptographic Manifest:** All workspace templates are verified against SHA-256 signatures in `.torusguard/.manifest.json`.
|
|
386
|
+
* **Token Budget Guarantee:** All skills and workflows strictly respect a **1,000โ1,500 token budget** to avoid AI context bloat.
|
|
311
387
|
|
|
312
388
|
---
|
|
313
389
|
|
|
314
|
-
##
|
|
390
|
+
## ๐ License & Community
|
|
391
|
+
|
|
392
|
+
TorusGuard is open-source software licensed under the [MIT License](LICENSE).
|
|
315
393
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
394
|
+
* **Author:** Jenish Lad ([@githubmofo](https://github.com/githubmofo))
|
|
395
|
+
* **Repository:** [https://github.com/githubmofo/TorusGuard](https://github.com/githubmofo/TorusGuard)
|
|
396
|
+
* **NPM Package:** [https://www.npmjs.com/package/torusguard](https://www.npmjs.com/package/torusguard)
|
|
397
|
+
* **Bug Reports & Issues:** [https://github.com/githubmofo/TorusGuard/issues](https://github.com/githubmofo/TorusGuard/issues)
|
|
398
|
+
* **Security Policy:** [SECURITY.md](SECURITY.md)
|
|
399
|
+
* **Contributing Guide:** [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
400
|
+
* **Maintainer Hygiene:** [MAINTAINERS.md](MAINTAINERS.md)
|
package/bin/torusguard.js
CHANGED
|
@@ -15,6 +15,15 @@ const command = args[0] || 'init';
|
|
|
15
15
|
const rootDir = path.resolve(__dirname, '..');
|
|
16
16
|
const cwd = process.cwd();
|
|
17
17
|
|
|
18
|
+
// ANSI Color Helpers
|
|
19
|
+
const BOLD = '\x1b[1m';
|
|
20
|
+
const RESET = '\x1b[0m';
|
|
21
|
+
const CYAN = '\x1b[36m';
|
|
22
|
+
const GREEN = '\x1b[32m';
|
|
23
|
+
const YELLOW = '\x1b[33m';
|
|
24
|
+
const GRAY = '\x1b[90m';
|
|
25
|
+
const DIM = '\x1b[2m';
|
|
26
|
+
|
|
18
27
|
// Detect available Python binary (python or python3)
|
|
19
28
|
let pythonCmd = 'python';
|
|
20
29
|
try {
|
|
@@ -36,23 +45,24 @@ try {
|
|
|
36
45
|
|
|
37
46
|
function printHelp() {
|
|
38
47
|
console.log(`
|
|
39
|
-
|
|
40
|
-
TORUSGUARD
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
48
|
+
${CYAN}โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ${RESET}
|
|
49
|
+
${CYAN}โ${RESET} ${BOLD}๐ก๏ธ TORUSGUARD CLI v0.9.4${RESET} ${GRAY}[Autonomous Security Engine]${RESET} ${CYAN}โ${RESET}
|
|
50
|
+
${CYAN}โ${RESET} ${DIM}Governed Remediation & Security Guardrails for AI Web Applications${RESET} ${CYAN}โ${RESET}
|
|
51
|
+
${CYAN}โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ${RESET}
|
|
52
|
+
|
|
53
|
+
${BOLD}Usage:${RESET}
|
|
54
|
+
${GREEN}npx torusguard${RESET} [command] [options]
|
|
55
|
+
|
|
56
|
+
${BOLD}Commands:${RESET}
|
|
57
|
+
${CYAN}init${RESET} Scaffold ${BOLD}.torusguard/${RESET} workspace and unlock all 11 slash commands
|
|
58
|
+
${CYAN}status${RESET} Display active security posture, configured rules, and stack
|
|
59
|
+
${CYAN}audit${RESET} Execute static security AST audit on target project
|
|
60
|
+
${CYAN}report${RESET} Export OASIS SARIF v2.1.0 security telemetry
|
|
61
|
+
${CYAN}help${RESET} Show this interactive command guide
|
|
62
|
+
|
|
63
|
+
${BOLD}Options:${RESET}
|
|
64
|
+
${GRAY}--target <dir>${RESET} Target directory to analyze or scaffold ${DIM}(default: .)${RESET}
|
|
65
|
+
${GRAY}--force${RESET} Overwrite existing configuration and re-scaffold templates
|
|
56
66
|
`);
|
|
57
67
|
}
|
|
58
68
|
|
|
@@ -66,23 +76,38 @@ if (command === 'status') {
|
|
|
66
76
|
if (fs.existsSync(cfgPath)) {
|
|
67
77
|
try {
|
|
68
78
|
const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
|
|
69
|
-
console.log(
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
+
console.log(`
|
|
80
|
+
${CYAN}โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ${RESET}
|
|
81
|
+
${CYAN}โ${RESET} ${BOLD}๐ก๏ธ TORUSGUARD ACTIVE SECURITY POSTURE${RESET} ${GRAY}v0.9.4${RESET} ${CYAN}โ${RESET}
|
|
82
|
+
${CYAN}โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ${RESET}
|
|
83
|
+
|
|
84
|
+
${BOLD}โธ Workspace Location:${RESET} ${GREEN}${cwd}${RESET}
|
|
85
|
+
${BOLD}โธ Governance Mode:${RESET} ${GREEN}Full Local Governance (.torusguard/)${RESET}
|
|
86
|
+
|
|
87
|
+
${BOLD}โบ Environment & Stack:${RESET}
|
|
88
|
+
${GRAY}โฟ Language:${RESET} ${BOLD}${cfg.detected_stack?.language || 'TypeScript'}${RESET}
|
|
89
|
+
${GRAY}โฟ Framework:${RESET} ${BOLD}${cfg.detected_stack?.framework || 'None (Generic Web)'}${RESET}
|
|
90
|
+
${GRAY}โฟ Data Layer:${RESET} ${BOLD}${cfg.detected_stack?.data_layer || 'None'}${RESET}
|
|
91
|
+
${GRAY}โฟ Rules Catalog:${RESET} ${GREEN}71 Canonical Security Rules Active${RESET}
|
|
92
|
+
|
|
93
|
+
${BOLD}โบ Governance Telemetry:${RESET}
|
|
94
|
+
${GRAY}โฟ Severity Floor:${RESET} ${YELLOW}${cfg.severity_threshold || 'medium'}${RESET}
|
|
95
|
+
${GRAY}โฟ Runs Directory:${RESET} ${CYAN}${cfg.runs_dir || '.torusguard/runs'}${RESET}
|
|
96
|
+
${GRAY}โฟ Ponytail Bounds:${RESET} ${GREEN}โค 35 additions, โค 25 deletions${RESET}
|
|
97
|
+
|
|
98
|
+
${CYAN}โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ${RESET}
|
|
99
|
+
${CYAN}โ${RESET} ${BOLD}๐ก Quick Action:${RESET} In your AI chat, run ${CYAN}/torusguard-audit${RESET} to scan. ${CYAN}โ${RESET}
|
|
100
|
+
${CYAN}โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ${RESET}
|
|
101
|
+
`);
|
|
79
102
|
process.exit(0);
|
|
80
103
|
} catch (e) {
|
|
81
104
|
// Fallback to python runner
|
|
82
105
|
}
|
|
83
106
|
} else {
|
|
84
|
-
console.log(
|
|
85
|
-
|
|
107
|
+
console.log(`
|
|
108
|
+
${YELLOW}Notice:${RESET} No .torusguard workspace found in current directory.
|
|
109
|
+
Run ${GREEN}npx torusguard init${RESET} to scaffold full workspace governance.
|
|
110
|
+
`);
|
|
86
111
|
process.exit(0);
|
|
87
112
|
}
|
|
88
113
|
}
|
|
@@ -96,7 +121,6 @@ const scriptToRun = fs.existsSync(localBootstrap) ? localBootstrap : localInstal
|
|
|
96
121
|
let scriptArgs = [scriptToRun];
|
|
97
122
|
if (command === 'init') {
|
|
98
123
|
scriptArgs.push('--full-commands');
|
|
99
|
-
// Forward remaining arguments
|
|
100
124
|
scriptArgs.push(...args.slice(1));
|
|
101
125
|
} else {
|
|
102
126
|
scriptArgs.push(...args);
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "torusguard",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.4",
|
|
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
|
|
@@ -13,6 +13,18 @@ import argparse
|
|
|
13
13
|
import subprocess
|
|
14
14
|
from pathlib import Path
|
|
15
15
|
|
|
16
|
+
# Ensure UTF-8 stdout/stderr on Windows consoles
|
|
17
|
+
if sys.stdout and hasattr(sys.stdout, "reconfigure"):
|
|
18
|
+
try:
|
|
19
|
+
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
|
|
20
|
+
except Exception:
|
|
21
|
+
pass
|
|
22
|
+
if sys.stderr and hasattr(sys.stderr, "reconfigure"):
|
|
23
|
+
try:
|
|
24
|
+
sys.stderr.reconfigure(encoding="utf-8", errors="replace")
|
|
25
|
+
except Exception:
|
|
26
|
+
pass
|
|
27
|
+
|
|
16
28
|
|
|
17
29
|
def find_project_root(start_dir=None):
|
|
18
30
|
"""Detect project root directory by searching for standard repo root markers."""
|
|
@@ -40,29 +52,41 @@ def scaffold_workspace(target_root=None, force=False, full_commands=False):
|
|
|
40
52
|
script_dir = Path(__file__).resolve().parent
|
|
41
53
|
payload_dir = script_dir / "payload"
|
|
42
54
|
|
|
43
|
-
print("================================================================================")
|
|
44
|
-
print("TORUSGUARD WORKSPACE BOOTSTRAPPER")
|
|
45
|
-
print("================================================================================")
|
|
46
|
-
print(f"Target Directory: {target_root}")
|
|
47
|
-
print(f"Destination: {torusguard_target}")
|
|
48
|
-
|
|
49
55
|
if torusguard_target.exists() and not force:
|
|
50
|
-
print(
|
|
56
|
+
print("""
|
|
57
|
+
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
|
|
58
|
+
โ ๐ก๏ธ TORUSGUARD WORKSPACE STATUS [Active] โ
|
|
59
|
+
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
|
|
60
|
+
""")
|
|
61
|
+
print(f" โธ Project Root: {target_root}")
|
|
62
|
+
print(f" โธ Workspace: .torusguard/ (Already Initialized)")
|
|
51
63
|
config_file = torusguard_target / "config" / "torusguard.json"
|
|
52
64
|
if config_file.exists():
|
|
53
65
|
try:
|
|
54
66
|
with open(config_file, "r", encoding="utf-8") as f:
|
|
55
67
|
cfg = json.load(f)
|
|
56
|
-
print(f"
|
|
57
|
-
print(f"Severity
|
|
68
|
+
print(f" โธ Version: {cfg.get('version', '0.9.3')}")
|
|
69
|
+
print(f" โธ Severity Floor: {cfg.get('severity_threshold', 'medium')}")
|
|
58
70
|
except Exception:
|
|
59
71
|
pass
|
|
60
|
-
print("
|
|
72
|
+
print("""
|
|
73
|
+
๐ก Workspace already exists. To refresh templates or re-scaffold, run:
|
|
74
|
+
npx torusguard init --force
|
|
75
|
+
""")
|
|
61
76
|
return True
|
|
62
77
|
|
|
78
|
+
print("""
|
|
79
|
+
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
|
|
80
|
+
โ ๐ก๏ธ TORUSGUARD WORKSPACE INITIALIZATION v0.9.3 โ
|
|
81
|
+
โ Governed Remediation & AI Application Guardrails โ
|
|
82
|
+
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
|
|
83
|
+
""")
|
|
84
|
+
print(f" โธ Target Project: {target_root}")
|
|
85
|
+
print(f" โธ Destination: {torusguard_target}")
|
|
86
|
+
|
|
63
87
|
# 1. Unpack Payload Template
|
|
64
88
|
if payload_dir.is_dir():
|
|
65
|
-
print("\
|
|
89
|
+
print("\n โธ Step 1/3: Unpacking Offline Governance Assets...")
|
|
66
90
|
try:
|
|
67
91
|
if torusguard_target.exists() and force:
|
|
68
92
|
shutil.rmtree(torusguard_target)
|
|
@@ -71,9 +95,9 @@ def scaffold_workspace(target_root=None, force=False, full_commands=False):
|
|
|
71
95
|
torusguard_target,
|
|
72
96
|
ignore=shutil.ignore_patterns("runs", "*.pyc", "__pycache__", ".git*")
|
|
73
97
|
)
|
|
74
|
-
print("
|
|
98
|
+
print(" โ Copied canonical rules, schemas, scripts, and workflows (93 files)")
|
|
75
99
|
except Exception as e:
|
|
76
|
-
print(f"
|
|
100
|
+
print(f" โ Failed to unpack payload: {e}")
|
|
77
101
|
return False
|
|
78
102
|
else:
|
|
79
103
|
# Fallback: create base structure
|
|
@@ -100,7 +124,7 @@ def scaffold_workspace(target_root=None, force=False, full_commands=False):
|
|
|
100
124
|
gitkeep_rules.write_text("", encoding="utf-8")
|
|
101
125
|
|
|
102
126
|
# 3. Stack Detection & Tailoring
|
|
103
|
-
print("\
|
|
127
|
+
print("\n โธ Step 2/3: Executing Stack Detection & Rule Alignment...")
|
|
104
128
|
stack_detect_script = torusguard_target / "scripts" / "stack_detect.py"
|
|
105
129
|
detected_stack = {"language": "Unknown", "framework": "None", "data_layer": "None", "confidence": "Uncertain"}
|
|
106
130
|
|
|
@@ -114,11 +138,11 @@ def scaffold_workspace(target_root=None, force=False, full_commands=False):
|
|
|
114
138
|
)
|
|
115
139
|
if res.returncode == 0 and res.stdout.strip():
|
|
116
140
|
detected_stack = json.loads(res.stdout)
|
|
117
|
-
print(f"
|
|
118
|
-
print(f"
|
|
119
|
-
print(f"
|
|
141
|
+
print(f" โฟ Language: {detected_stack.get('language')}")
|
|
142
|
+
print(f" โฟ Framework: {detected_stack.get('framework')}")
|
|
143
|
+
print(f" โฟ Data Layer: {detected_stack.get('data_layer')}")
|
|
120
144
|
except Exception as e:
|
|
121
|
-
print(f"
|
|
145
|
+
print(f" โ Stack detection warning: {e}")
|
|
122
146
|
|
|
123
147
|
# 4. Update torusguard.json configuration
|
|
124
148
|
config_file = torusguard_target / "config" / "torusguard.json"
|
|
@@ -133,12 +157,12 @@ def scaffold_workspace(target_root=None, force=False, full_commands=False):
|
|
|
133
157
|
}
|
|
134
158
|
with open(config_file, "w", encoding="utf-8") as f:
|
|
135
159
|
json.dump(cfg, f, indent=2)
|
|
136
|
-
print("
|
|
160
|
+
print(" โ Configured .torusguard/config/torusguard.json (71 Rules Active)")
|
|
137
161
|
except Exception as e:
|
|
138
|
-
print(f"
|
|
162
|
+
print(f" โ Config update error: {e}")
|
|
139
163
|
|
|
140
164
|
# 5. Register Slash Commands for AI IDEs (.agent, .claude, .cursor)
|
|
141
|
-
print("\
|
|
165
|
+
print("\n โธ Step 3/3: Registering AI IDE Command Bridges...")
|
|
142
166
|
registered_ides = []
|
|
143
167
|
tg_workflow_content = """---
|
|
144
168
|
description: TorusGuard Autonomous Security Command Engine โ run static security audits, authorized runtime web validation, governed remediation, and SARIF exports.
|
|
@@ -232,16 +256,18 @@ Parse the requested action from `$ARGUMENTS` (e.g. `audit`, `verify`, `web-valid
|
|
|
232
256
|
registered_ides.append("Universal Agent Standard (AGENTS.md for Kimi / Open Agents)")
|
|
233
257
|
|
|
234
258
|
for r in registered_ides:
|
|
235
|
-
print(f"
|
|
259
|
+
print(f" โ {r}")
|
|
236
260
|
|
|
237
|
-
print("
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
261
|
+
print(f"""
|
|
262
|
+
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
|
|
263
|
+
โ โจ TorusGuard Workspace Initialized Successfully! โ
|
|
264
|
+
โ โ
|
|
265
|
+
โ ๐ Next Steps: โ
|
|
266
|
+
โ 1. In AI Chat: Type `/torusguard-audit` or `/torusguard` to scan โ
|
|
267
|
+
โ 2. In Terminal: Run `npx torusguard status` for security posture โ
|
|
268
|
+
โ 3. In CI/CD: Run `npx torusguard audit` to generate SARIF data โ
|
|
269
|
+
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
|
|
270
|
+
""")
|
|
245
271
|
return True
|
|
246
272
|
|
|
247
273
|
|
|
@@ -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": "218eeae10b538aca9b548d1b756d7d4f91a5b624e0bce07533f0c187860586e6",
|
|
12
12
|
"references/django-security.md": "a15b7eb11b51dd1970d3d65544cf79ebea91fb99dc0e085e58a56532a718dce7",
|
|
13
13
|
"references/drf-security.md": "c7a7af3acaef895bf4798590acc88b3a2e9831a49eb2d23b4d8f31540ab264cc",
|
|
14
14
|
"references/express-security.md": "dff1db15e614d29d8c272f9da345b418077e62dc883fe210c7a50c552c76493f",
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
"scripts/safety_gate.py": "3379b7534b2590cf563717a448983ad8ed7e8f174f0ad65683d33e8a10f51558",
|
|
41
41
|
"scripts/sarif_exporter.py": "35c66637413afc4b72d5bd426638447c77231d2a8594dce5addceffd4803a20d",
|
|
42
42
|
"scripts/stack_detect.py": "99b7bdf9829d58ff5b8c59afd6e8b6429bbb11d830ac73dec491101cbbc41574",
|
|
43
|
-
"skills/torusguard/SKILL.md": "
|
|
43
|
+
"skills/torusguard/SKILL.md": "5282a9e73c2faad97f079ff527def34b96709615c0dd297fe9b1bb2894f03e20",
|
|
44
44
|
"skills/torusguard/bootstrap.py": "7e348065a622089ab1d51e9bf4864e5b0022aaee1ccb2ecbf7057c14e792e2c7",
|
|
45
45
|
"skills/torusguard/references/auth-and-sessions.md": "34c2843f8c0dbe3574e54f00a39a92a1f431527ec5f69b2d64c84240d424a39e",
|
|
46
46
|
"skills/torusguard/references/business-logic-and-abuse.md": "0d6088936bc1a01023070332fccef0f2e0734358a5119379055f3d2895c22567",
|