@yagyeshvyas/vibeguard 1.3.0 → 1.11.1

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 (167) hide show
  1. package/.vibeguard-mcp.example.json +51 -0
  2. package/CHANGELOG.md +604 -216
  3. package/MCP-FIREWALL.md +296 -0
  4. package/README.md +355 -31
  5. package/bin/cli.js +355 -27
  6. package/bin/cmd-agent-monitor.js +45 -0
  7. package/bin/cmd-agent-risk.js +64 -0
  8. package/bin/cmd-gif.js +62 -0
  9. package/bin/cmd-git-scan.js +74 -0
  10. package/bin/cmd-llm-proxy.js +164 -0
  11. package/bin/cmd-mcp-firewall.js +191 -0
  12. package/bin/cmd-pentest.js +103 -0
  13. package/bin/cmd-platform.js +137 -0
  14. package/bin/cmd-pr-scan.js +135 -0
  15. package/bin/cmd-sbom-diff.js +38 -0
  16. package/bin/cmd-skill-scan.js +35 -0
  17. package/docs/AISVS.md +25 -0
  18. package/docs/ARCHITECTURE.md +81 -0
  19. package/docs/INSTALLATION.md +139 -0
  20. package/docs/WINDOWS.md +74 -0
  21. package/docs/security-policy.strict.example.json +134 -0
  22. package/docs/security-policy.strict.example.pub.pem +3 -0
  23. package/package.json +45 -7
  24. package/src/.vibeguard/cache/file-hashes.json +60 -0
  25. package/src/.vibeguard/latest-snapshot.json +36 -0
  26. package/src/.vibeguard/mcp-pins.json +1 -0
  27. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/auto.js +428 -0
  28. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/daemon.js +344 -0
  29. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/dashboard.js +279 -0
  30. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/engine.js +297 -0
  31. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/hook.js +151 -0
  32. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/install.js +299 -0
  33. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/manifest.json +65 -0
  34. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/mcp-server.js +2051 -0
  35. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/plugin.js +168 -0
  36. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/pre-deploy.js +362 -0
  37. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/repl.js +150 -0
  38. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/rules.js +1611 -0
  39. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/sbom.js +164 -0
  40. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/shell-guard.js +292 -0
  41. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/slopsquat.js +144 -0
  42. package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/trace.js +220 -0
  43. package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/auto.js +428 -0
  44. package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/daemon.js +344 -0
  45. package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/engine.js +297 -0
  46. package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/install.js +299 -0
  47. package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/manifest.json +37 -0
  48. package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/mcp-server.js +2055 -0
  49. package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/plugin.js +168 -0
  50. package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/pre-deploy.js +362 -0
  51. package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/trace.js +220 -0
  52. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/auto.js +428 -0
  53. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/daemon.js +344 -0
  54. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/dashboard.js +279 -0
  55. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/engine.js +297 -0
  56. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/hook.js +151 -0
  57. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/install.js +299 -0
  58. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/manifest.json +65 -0
  59. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/mcp-server.js +2055 -0
  60. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/plugin.js +168 -0
  61. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/pre-deploy.js +362 -0
  62. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/repl.js +150 -0
  63. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/rules.js +1611 -0
  64. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/sbom.js +164 -0
  65. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/shell-guard.js +292 -0
  66. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/slopsquat.js +144 -0
  67. package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/trace.js +220 -0
  68. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/auto.js +428 -0
  69. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/daemon.js +344 -0
  70. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/dashboard.js +279 -0
  71. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/engine.js +297 -0
  72. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/hook.js +151 -0
  73. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/install.js +299 -0
  74. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/manifest.json +65 -0
  75. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/mcp-server.js +2054 -0
  76. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/plugin.js +168 -0
  77. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/pre-deploy.js +362 -0
  78. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/repl.js +150 -0
  79. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/rules.js +1611 -0
  80. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/sbom.js +164 -0
  81. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/shell-guard.js +292 -0
  82. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/slopsquat.js +144 -0
  83. package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/trace.js +220 -0
  84. package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/auto.js +428 -0
  85. package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/daemon.js +344 -0
  86. package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/engine.js +297 -0
  87. package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/install.js +299 -0
  88. package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/manifest.json +37 -0
  89. package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/mcp-server.js +2055 -0
  90. package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/plugin.js +168 -0
  91. package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/pre-deploy.js +362 -0
  92. package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/trace.js +220 -0
  93. package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/auto.js +428 -0
  94. package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/daemon.js +344 -0
  95. package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/engine.js +297 -0
  96. package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/manifest.json +33 -0
  97. package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/mcp-server.js +2055 -0
  98. package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/rules.js +1611 -0
  99. package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/shell-guard.js +292 -0
  100. package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/trace.js +220 -0
  101. package/src/.vibeguard-baseline.json +5226 -0
  102. package/src/action-guard.js +84 -6
  103. package/src/agent-monitor.js +262 -0
  104. package/src/agent-policy.js +642 -0
  105. package/src/agent-risk.js +271 -0
  106. package/src/agentic.js +1513 -0
  107. package/src/ast.js +165 -7
  108. package/src/audit-trail.js +212 -67
  109. package/src/auto.js +427 -427
  110. package/src/autofix.js +11 -4
  111. package/src/bundles.js +198 -0
  112. package/src/daemon.js +343 -343
  113. package/src/dashboard.js +278 -278
  114. package/src/engine.js +3 -0
  115. package/src/entropy.js +187 -0
  116. package/src/firewall.js +19 -3
  117. package/src/gif.js +134 -0
  118. package/src/gitscan.js +282 -0
  119. package/src/hook.js +151 -151
  120. package/src/injection-decode.js +136 -0
  121. package/src/install.js +298 -280
  122. package/src/integrity.js +16 -1
  123. package/src/integrity.json +43 -13
  124. package/src/interceptor.js +12 -9
  125. package/src/llm-proxy.js +986 -0
  126. package/src/mcp-audit.js +61 -5
  127. package/src/mcp-firewall.js +971 -0
  128. package/src/mcp-server.js +2500 -2047
  129. package/src/obfuscation.js +315 -0
  130. package/src/owasp-agentic.js +314 -0
  131. package/src/pentest.js +589 -0
  132. package/src/pii.js +4 -0
  133. package/src/platform/aisvs.js +38 -0
  134. package/src/platform/approval.js +187 -0
  135. package/src/platform/canonical.js +73 -0
  136. package/src/platform/contracts.js +158 -0
  137. package/src/platform/delegation.js +73 -0
  138. package/src/platform/http-gateway.js +177 -0
  139. package/src/platform/identity.js +253 -0
  140. package/src/platform/jwt.js +86 -0
  141. package/src/platform/mcp-http-bridge.js +199 -0
  142. package/src/platform/memory-guard.js +64 -0
  143. package/src/platform/os-sandbox.js +144 -0
  144. package/src/platform/policy.js +332 -0
  145. package/src/platform/sandbox-manager.js +92 -0
  146. package/src/platform/signed-audit.js +357 -0
  147. package/src/platform/ssrf.js +129 -0
  148. package/src/plugin.js +182 -168
  149. package/src/pre-deploy.js +170 -55
  150. package/src/privacy-audit.js +272 -272
  151. package/src/repl.js +150 -150
  152. package/src/report.js +7 -1
  153. package/src/routes.js +1210 -0
  154. package/src/rules-2026.js +1407 -0
  155. package/src/rules-pack.js +3068 -3019
  156. package/src/rules.js +376 -60
  157. package/src/sandbox.js +200 -10
  158. package/src/sbom.js +193 -164
  159. package/src/scanner.js +189 -33
  160. package/src/shell-guard.js +11 -0
  161. package/src/skill-scan.js +477 -0
  162. package/src/slopsquat.js +144 -144
  163. package/src/surface.js +408 -0
  164. package/src/taint-ast.js +204 -37
  165. package/src/taint.js +15 -3
  166. package/src/tokenlean.js +579 -0
  167. package/src/trace.js +220 -220
@@ -0,0 +1,296 @@
1
+ # VibeGuard MCP Firewall
2
+
3
+ A real-time firewall between an AI agent and the MCP servers it trusts.
4
+
5
+ Most agent stacks treat MCP as a trusted bus: the client asks, the server
6
+ answers, tool descriptions and tool results flow straight into the model's
7
+ context. Every one of those channels is attacker-controlled in a compromised or
8
+ malicious server. VibeGuard proxies the channel in both directions and enforces
9
+ policy on every message — offline, no network, no dependencies.
10
+
11
+ ```
12
+ Agent / MCP client ──► vibeguard mcp-firewall ──► MCP server
13
+ (Claude Code, policy + definition (filesystem, shell,
14
+ Cursor, SDK) pinning + secret scan database, SaaS)
15
+ │
16
+ ▼
17
+ .vibeguard/audit/mcp-firewall.jsonl
18
+ hash-chained, tamper-evident
19
+ ```
20
+
21
+ ## What it does
22
+
23
+ | Layer | What is checked | When |
24
+ |---|---|---|
25
+ | Tool poisoning | Injection text, hidden Unicode, concealment instructions, forced invocation, encoded payloads, `readOnlyHint` lies in tool names/descriptions/schemas | `tools/list` response |
26
+ | Definition pinning | SHA-256 of each tool definition; a changed description after approval is a rug-pull | `tools/list` response |
27
+ | Permissions | Per-tool allow/deny/approval rules, capability gates, project-scoped paths, denied credential stores | `tools/call` request |
28
+ | Command safety | Destructive/obfuscated shell commands, exfil pipelines | `tools/call` request |
29
+ | Egress | Host allow/deny lists, cloud-metadata block, secret-in-URL | `tools/call` request |
30
+ | Secret exfiltration | Live credentials in arguments, credential + destination in one call | `tools/call` request |
31
+ | Result scrubbing | Secrets and PII redacted from tool output before it enters the model context | `tools/call` response |
32
+ | Result poisoning | Prompt-injection text inside tool output is withheld and replaced with an explicit notice | `tools/call` response |
33
+ | Prompt prompts | Injection scan on `prompts/get` arguments | request |
34
+ | Audit + risk | Every verdict appended to a hash-chained log with a risk value | always |
35
+
36
+ Blocked `tools/call` requests are answered locally and **never forwarded** to
37
+ the server. Poisoned tools are removed from the `tools/list` result, with a
38
+ `_vibeguard` note listing what was removed and why.
39
+
40
+ ## Quick start
41
+
42
+ ```bash
43
+ # 1. Audit what you already trust (config only, never runs a server)
44
+ vibeguard mcp-audit
45
+
46
+ # 2. Write a policy you can edit, or copy the example
47
+ vibeguard mcp-firewall --init
48
+
49
+ # 3. Verify the firewall works offline
50
+ vibeguard mcp-firewall --selftest
51
+
52
+ # 4. Proxy a configured server by name (.mcp.json / .cursor/mcp.json / .vscode/mcp.json)
53
+ vibeguard mcp-firewall --server filesystem
54
+
55
+ # Or an ad-hoc command (quote the whole command line)
56
+ vibeguard mcp-firewall --exec "npx -y @modelcontextprotocol/server-filesystem ."
57
+
58
+ # 5. Point your MCP client at the proxy instead of the server.
59
+ # Claude Code example:
60
+ claude mcp add filesystem -- vibeguard mcp-firewall --server filesystem
61
+ ```
62
+
63
+ If you edit the *same* config file the proxy reads, `--server <name>` would
64
+ resolve to the proxy entry and recurse. The proxy refuses that with a clear
65
+ error; use `--exec "<original server command>"` in that case, or put the proxy
66
+ entry in a different client config.
67
+
68
+ The proxy speaks newline-delimited JSON-RPC 2.0 on stdio. Stdout carries only
69
+ protocol traffic; all banners and diagnostics go to stderr.
70
+
71
+ ## Modes
72
+
73
+ ```bash
74
+ vibeguard mcp-firewall --server <name> # long-running stdio proxy
75
+ vibeguard mcp-firewall --exec "<command>" # long-running ad-hoc proxy
76
+ vibeguard mcp-firewall --check '<json>' # evaluate one tool call
77
+ vibeguard mcp-firewall --init # write a default policy
78
+ vibeguard mcp-firewall --selftest [--json] # 11 offline attack scenarios
79
+ vibeguard mcp-firewall --status [--json] # summarize the audit log
80
+ vibeguard mcp-firewall --list-servers # show configured servers
81
+ vibeguard mcp-firewall --policy <file> # inspect a policy
82
+ ```
83
+
84
+ `--check` exits `2` on block, `1` on warn, `0` on allow:
85
+
86
+ ```bash
87
+ vibeguard mcp-firewall --check '{"server":"fs","tool":"read_file","args":{"path":".env"}}'
88
+ ```
89
+
90
+ ## Policy
91
+
92
+ Place `.vibeguard-mcp.json` in the project root (or pass `--policy`). Every
93
+ field is optional; the defaults are safe but usable. See
94
+ [`.vibeguard-mcp.example.json`](.vibeguard-mcp.example.json) for a copy-paste
95
+ starting point.
96
+
97
+ ```json
98
+ {
99
+ "version": 1,
100
+ "defaultAction": "allow",
101
+ "toolRules": [
102
+ { "match": "mcp__filesystem__write_*", "action": "warn", "reason": "writes are reviewed" },
103
+ { "match": "mcp__shell__*", "action": "block" }
104
+ ],
105
+ "denyTools": ["dangerous_*"],
106
+ "allowTools": [],
107
+ "approvalRequired": ["delete_*"],
108
+ "blockedCapabilities": ["shell"],
109
+ "allowedPaths": ["../shared-config"],
110
+ "deniedPaths": ["**/.env", "**/.ssh/**", "**/*.pem"],
111
+ "enforceProjectScope": true,
112
+ "allowedHosts": ["api.example.com"],
113
+ "deniedHosts": ["169.254.169.254", "metadata.google.internal"],
114
+ "trustedHosts": ["localhost"],
115
+ "blockExternalNetwork": false,
116
+ "secretScan": true,
117
+ "piiScan": true,
118
+ "piiMode": "warn",
119
+ "blockPromptInjection": true,
120
+ "pinToolDefinitions": true,
121
+ "scrubToolResults": true,
122
+ "blockToolResultInjection": true,
123
+ "maxArgumentBytes": 65536,
124
+ "maxCallsPerMinute": 240,
125
+ "logAllowedCalls": true,
126
+ "failClosed": false
127
+ }
128
+ ```
129
+
130
+ ### Field notes
131
+
132
+ - `defaultAction` — `allow`, `warn` or `block` for tools with no matching rule.
133
+ Set `block` + an explicit `allowTools` list for a deny-by-default posture.
134
+ - `toolRules` — ordered; first match wins. `match` is a glob (`*`, `**`, `?`).
135
+ Actions: `allow`, `warn`, `block`, `approval` (headless proxies convert
136
+ approval to a block with a clear reason).
137
+ - `allowTools` — when non-empty, only these tools (or an explicit allow rule)
138
+ may run.
139
+ - `blockedCapabilities` / `allowedCapabilities` — capability classes derived
140
+ from tool name and arguments: `shell`, `code-exec`, `fs.read`, `fs.write`,
141
+ `network`, `database`, `secrets`, `generic`.
142
+ - `enforceProjectScope` — reads outside the project are warned; writes are
143
+ blocked unless the path matches `allowedPaths`.
144
+ - `allowedHosts` — when non-empty, external egress to anything else is blocked.
145
+ Localhost/private IPs are not "external".
146
+ - `trustedHosts` — hosts explicitly allowed to receive sensitive data.
147
+ - `piiMode` — `warn` (default) or `block` for personal data in arguments.
148
+ - `pinToolDefinitions` — first sight pins each tool definition under
149
+ `.vibeguard/mcp-tool-pins.json`; a later change is blocked as drift.
150
+ - `blockToolResultInjection` — tool output containing prompt-injection text is
151
+ withheld and replaced with a notice instead of entering the model context.
152
+ - `failClosed` — if the policy file is invalid, block everything instead of
153
+ falling back to defaults.
154
+
155
+ ## Audit and monitoring
156
+
157
+ Every decision is appended to `.vibeguard/audit/mcp-firewall.jsonl`. Each entry
158
+ commits to the previous entry's SHA-256, so edits and deletions are detectable:
159
+
160
+ ```bash
161
+ vibeguard mcp-firewall --status # counts, top blocked tools, anomalies
162
+ vibeguard agent-monitor # richer runtime report
163
+ vibeguard agent-monitor --watch # live tail (one line per decision)
164
+ vibeguard audit-trail verify # verify the in-process chain
165
+ ```
166
+
167
+ The monitor maps runtime events into the behavior engine and flags trust
168
+ building, data gathering before egress, slow exfiltration, privilege
169
+ escalation, repeated blocks, rapid fire and tampering.
170
+
171
+ ## Risk scoring
172
+
173
+ ```bash
174
+ vibeguard agent-risk [dir] [--json]
175
+ vibeguard owasp-coverage [dir] [--all]
176
+ ```
177
+
178
+ `agent-risk` combines five domains into a 0-100 score and A-F grade:
179
+
180
+ | Domain | Weight | Input |
181
+ |---|---|---|
182
+ | MCP config | 35% | tool poisoning, unpinned servers, shells, secrets, broad FS, drift |
183
+ | Skills | 30% | malicious skill/plugin/instruction files |
184
+ | Runtime | 20% | blocked calls, poisoned tools, redactions, behavior anomalies |
185
+ | Policy | 10% | explicit policy vs defaults, egress allowlist |
186
+ | Audit | 5% | log present, chain intact |
187
+
188
+ Exit codes: `2` critical or F, `1` any risk, `0` clean.
189
+
190
+ ## OWASP coverage
191
+
192
+ `vibeguard owasp-coverage` maps every implemented control to:
193
+
194
+ - **OWASP Top 10 for Agentic Applications** (ASI01-ASI10)
195
+ - **OWASP MCP Top 10** (MCP01-MCP10)
196
+ - optionally the **OWASP LLM Top 10** (`--all`)
197
+
198
+ Statuses are explicit: `ENFORCED` (runtime can block), `DETECTED` (scanner
199
+ reports it), `MONITORED` (audit/behavior exposes it), `ADVISORY` (guidance only).
200
+ The command exits `0` only when every selected control is mapped. Coverage is
201
+ not a claim that a risk is eliminated; the status says what the control does.
202
+
203
+ ## Skills and plugins
204
+
205
+ ```bash
206
+ vibeguard skill-scan [dir] [extra paths...] [--json] [--all]
207
+ ```
208
+
209
+ Scans `SKILL.md`, `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.claude/agents`,
210
+ `.claude/skills`, `plugin.json`, marketplace files and embedded MCP server
211
+ configs for prompt injection, hidden Unicode, exfiltration instructions,
212
+ credential-store access, destructive commands, remote code loaders,
213
+ obfuscation, permission bypass, self-modification, risky/unpinned packages and
214
+ secrets.
215
+
216
+ ## The MCP tools
217
+
218
+ The same engines are available to an agent through the MCP server:
219
+
220
+ | Tool | Purpose |
221
+ |---|---|
222
+ | `mcp_firewall` | `check` a tool call, `selftest`, `status`, `policy` |
223
+ | `scan_skills` | malicious skill/plugin scan |
224
+ | `agent_risk` | unified agent risk score |
225
+ | `owasp_coverage` | OWASP mapping |
226
+ | `agent_monitor` | runtime activity and anomaly report |
227
+ | `sandbox_exec` | run untrusted code (`isolation: auto/process/vm`) |
228
+
229
+ ## Sandbox
230
+
231
+ `vibeguard sandbox "<code>"` executes JavaScript in a locked context. On Node
232
+ 20+ the default `auto` mode now uses **process isolation**: a separate Node
233
+ process running under the permission model (filesystem and `child_process`
234
+ denied by the runtime), with module loading for network/process modules
235
+ blocked, `fetch`/`WebSocket` removed, a stripped environment, a memory cap and
236
+ a hard timeout. Node 18 falls back to the vm sandbox. Neither mode is a
237
+ container — same OS user, no kernel boundary — but `process` is a real process
238
+ boundary with deny-by-default capabilities.
239
+
240
+ ```bash
241
+ vibeguard sandbox "const x = 1 + 2; x" --isolation process --json
242
+ ```
243
+
244
+ ## Windows and offline
245
+
246
+ - No network calls anywhere in the firewall, monitor, skill scanner, risk or
247
+ coverage code. The only network code in VibeGuard remains the opt-in `url`,
248
+ `cve`, `pentest`, proxy and GIF commands.
249
+ - No symlink traversal, no shell invocation for the proxy (`spawn` with an argv
250
+ array), no POSIX-only paths. The process sandbox works on Windows 11 with
251
+ Node 20+.
252
+ - ANSI colors degrade gracefully (set `NO_COLOR=1` to disable).
253
+ - Audit logs use forward-slash normalization for path matching on Windows.
254
+
255
+ ## Strict mode
256
+
257
+ `vibeguard mcp-firewall --server <name> --strict` forces the legacy policy
258
+ engine into default-deny: an unknown tool is blocked unless an explicit allow
259
+ rule/allowlist admits it. The additive v2 policy engine
260
+ (`src/platform/policy.js`) supports signed Ed25519 policies, realpath path
261
+ checks, approvals and per-resource rules; it is tested as a library/CLI but is
262
+ not yet the live stdio gateway policy. See
263
+ [`reports/known-limitations.md`](reports/known-limitations.md).
264
+
265
+ The v2 gateway also inspects all content-bearing response methods
266
+ (`resources/read`, `prompts/get`, unknown methods), not only `tools/call`.
267
+
268
+ ## Honest status
269
+
270
+ The process sandbox is **unverified, same-user and not an OS boundary**. The
271
+ `vibeguard sandbox backends` command reports `verified=NO`; do not describe it
272
+ as isolation. OS-level backends are planned, not implemented.
273
+
274
+
275
+ - The proxy currently speaks the **stdio** MCP transport (the transport Claude
276
+ Code, Cursor and most local clients use). HTTP/SSE remote transports are not
277
+ proxied; audit those with `vibeguard mcp-audit`.
278
+ - The proxy is a **filter, not a sandbox for the server**. A malicious server
279
+ can still do whatever its own code does when it is invoked. The proxy
280
+ guarantees the agent cannot ask it to do the dangerous thing through this
281
+ channel, and that there is a tamper-evident record of the attempt.
282
+ - Pattern rules can be evaded by a determined attacker who knows them. The
283
+ semantic prompt classifier and the policy engine raise the bar; they do not
284
+ prove absence of risk.
285
+ - `pinToolDefinitions` pins on first sight. Review a server before first use;
286
+ the pin only protects against later changes.
287
+ - `sandbox_exec` is not a container and does not isolate the OS user.
288
+ - OWASP coverage maps controls, not perfect prevention.
289
+
290
+ ## Signed audit, auth and kill switch
291
+
292
+ - Strict mode writes signed Ed25519 gateway events by default and fails closed if the audit sink is unavailable.
293
+ - `--token` + `--token-pub` enforce a VGAT principal capability set on stdio; `--approval-token` + `--approval-pub` enforce a signed single-use approval for approval-required rules.
294
+ - `--kill-on-block` / `--max-blocks N` quarantine-kills the upstream and exits 3 after blocked calls.
295
+ - `src/platform/mcp-http-bridge.js` provides authenticated JSON-RPC POST and SSE notification flow over stdio; it is loopback-tested and does not provide TLS/OAuth remote deployment.
296
+ - Linux `unshare` network/PID isolation is available via `vibeguard sandbox verify`; Windows/macOS OS backends are not implemented.