@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.
- package/.vibeguard-mcp.example.json +51 -0
- package/CHANGELOG.md +604 -216
- package/MCP-FIREWALL.md +296 -0
- package/README.md +355 -31
- package/bin/cli.js +355 -27
- package/bin/cmd-agent-monitor.js +45 -0
- package/bin/cmd-agent-risk.js +64 -0
- package/bin/cmd-gif.js +62 -0
- package/bin/cmd-git-scan.js +74 -0
- package/bin/cmd-llm-proxy.js +164 -0
- package/bin/cmd-mcp-firewall.js +191 -0
- package/bin/cmd-pentest.js +103 -0
- package/bin/cmd-platform.js +137 -0
- package/bin/cmd-pr-scan.js +135 -0
- package/bin/cmd-sbom-diff.js +38 -0
- package/bin/cmd-skill-scan.js +35 -0
- package/docs/AISVS.md +25 -0
- package/docs/ARCHITECTURE.md +81 -0
- package/docs/INSTALLATION.md +139 -0
- package/docs/WINDOWS.md +74 -0
- package/docs/security-policy.strict.example.json +134 -0
- package/docs/security-policy.strict.example.pub.pem +3 -0
- package/package.json +45 -7
- package/src/.vibeguard/cache/file-hashes.json +60 -0
- package/src/.vibeguard/latest-snapshot.json +36 -0
- package/src/.vibeguard/mcp-pins.json +1 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/auto.js +428 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/daemon.js +344 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/dashboard.js +279 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/engine.js +297 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/hook.js +151 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/install.js +299 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/manifest.json +65 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/mcp-server.js +2051 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/plugin.js +168 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/pre-deploy.js +362 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/repl.js +150 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/rules.js +1611 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/sbom.js +164 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/shell-guard.js +292 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/slopsquat.js +144 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-23-50-635Z/trace.js +220 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/auto.js +428 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/daemon.js +344 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/engine.js +297 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/install.js +299 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/manifest.json +37 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/mcp-server.js +2055 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/plugin.js +168 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/pre-deploy.js +362 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-26-26-074Z/trace.js +220 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/auto.js +428 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/daemon.js +344 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/dashboard.js +279 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/engine.js +297 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/hook.js +151 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/install.js +299 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/manifest.json +65 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/mcp-server.js +2055 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/plugin.js +168 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/pre-deploy.js +362 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/repl.js +150 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/rules.js +1611 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/sbom.js +164 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/shell-guard.js +292 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/slopsquat.js +144 -0
- package/src/.vibeguard/snapshots/2026-08-05T16-35-06-272Z/trace.js +220 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/auto.js +428 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/daemon.js +344 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/dashboard.js +279 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/engine.js +297 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/hook.js +151 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/install.js +299 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/manifest.json +65 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/mcp-server.js +2054 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/plugin.js +168 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/pre-deploy.js +362 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/repl.js +150 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/rules.js +1611 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/sbom.js +164 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/shell-guard.js +292 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/slopsquat.js +144 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-08-40-613Z/trace.js +220 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/auto.js +428 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/daemon.js +344 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/engine.js +297 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/install.js +299 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/manifest.json +37 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/mcp-server.js +2055 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/plugin.js +168 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/pre-deploy.js +362 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-11-32-644Z/trace.js +220 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/auto.js +428 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/daemon.js +344 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/engine.js +297 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/manifest.json +33 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/mcp-server.js +2055 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/rules.js +1611 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/shell-guard.js +292 -0
- package/src/.vibeguard/snapshots/2026-08-05T18-16-47-635Z/trace.js +220 -0
- package/src/.vibeguard-baseline.json +5226 -0
- package/src/action-guard.js +84 -6
- package/src/agent-monitor.js +262 -0
- package/src/agent-policy.js +642 -0
- package/src/agent-risk.js +271 -0
- package/src/agentic.js +1513 -0
- package/src/ast.js +165 -7
- package/src/audit-trail.js +212 -67
- package/src/auto.js +427 -427
- package/src/autofix.js +11 -4
- package/src/bundles.js +198 -0
- package/src/daemon.js +343 -343
- package/src/dashboard.js +278 -278
- package/src/engine.js +3 -0
- package/src/entropy.js +187 -0
- package/src/firewall.js +19 -3
- package/src/gif.js +134 -0
- package/src/gitscan.js +282 -0
- package/src/hook.js +151 -151
- package/src/injection-decode.js +136 -0
- package/src/install.js +298 -280
- package/src/integrity.js +16 -1
- package/src/integrity.json +43 -13
- package/src/interceptor.js +12 -9
- package/src/llm-proxy.js +986 -0
- package/src/mcp-audit.js +61 -5
- package/src/mcp-firewall.js +971 -0
- package/src/mcp-server.js +2500 -2047
- package/src/obfuscation.js +315 -0
- package/src/owasp-agentic.js +314 -0
- package/src/pentest.js +589 -0
- package/src/pii.js +4 -0
- package/src/platform/aisvs.js +38 -0
- package/src/platform/approval.js +187 -0
- package/src/platform/canonical.js +73 -0
- package/src/platform/contracts.js +158 -0
- package/src/platform/delegation.js +73 -0
- package/src/platform/http-gateway.js +177 -0
- package/src/platform/identity.js +253 -0
- package/src/platform/jwt.js +86 -0
- package/src/platform/mcp-http-bridge.js +199 -0
- package/src/platform/memory-guard.js +64 -0
- package/src/platform/os-sandbox.js +144 -0
- package/src/platform/policy.js +332 -0
- package/src/platform/sandbox-manager.js +92 -0
- package/src/platform/signed-audit.js +357 -0
- package/src/platform/ssrf.js +129 -0
- package/src/plugin.js +182 -168
- package/src/pre-deploy.js +170 -55
- package/src/privacy-audit.js +272 -272
- package/src/repl.js +150 -150
- package/src/report.js +7 -1
- package/src/routes.js +1210 -0
- package/src/rules-2026.js +1407 -0
- package/src/rules-pack.js +3068 -3019
- package/src/rules.js +376 -60
- package/src/sandbox.js +200 -10
- package/src/sbom.js +193 -164
- package/src/scanner.js +189 -33
- package/src/shell-guard.js +11 -0
- package/src/skill-scan.js +477 -0
- package/src/slopsquat.js +144 -144
- package/src/surface.js +408 -0
- package/src/taint-ast.js +204 -37
- package/src/taint.js +15 -3
- package/src/tokenlean.js +579 -0
- package/src/trace.js +220 -220
package/MCP-FIREWALL.md
ADDED
|
@@ -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.
|