@jacobmolz/mcpguard 0.2.1 → 0.3.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/README.md +54 -8
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,6 +6,8 @@
|
|
|
6
6
|
|
|
7
7
|
Security proxy daemon for MCP servers — adds authentication, rate limiting, PII detection, permission scoping, and audit logging without modifying upstream servers.
|
|
8
8
|
|
|
9
|
+
|
|
10
|
+
|
|
9
11
|
## What is this?
|
|
10
12
|
|
|
11
13
|
MCP (Model Context Protocol) servers give AI coding tools access to files, databases, APIs, and more. But they have no built-in authentication, no audit trail, and no way to restrict which tools an agent can call.
|
|
@@ -89,16 +91,43 @@ MCP-Guard uses **terminate, inspect, re-originate** — it fully owns both the c
|
|
|
89
91
|
|
|
90
92
|
Config merge uses **floor-based semantics**: personal configs can restrict but never relax base policies. `allowed_tools` are intersected, `denied_tools` are unioned, rate limits take the stricter value.
|
|
91
93
|
|
|
92
|
-
##
|
|
94
|
+
## Why This Matters
|
|
93
95
|
|
|
94
|
-
|
|
96
|
+
### Without MCP-Guard
|
|
95
97
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
98
|
+
```
|
|
99
|
+
Agent asks to read /home/user/.env via filesystem MCP server
|
|
100
|
+
→ Server returns: AWS_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
|
101
|
+
→ API key is now in the agent's context window
|
|
102
|
+
→ No authentication. No audit trail. No one knows it happened.
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### With MCP-Guard
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
Agent asks to read /home/user/.env via filesystem MCP server
|
|
109
|
+
→ MCP-Guard intercepts the response
|
|
110
|
+
→ PII detector matches AWS key pattern → BLOCK
|
|
111
|
+
→ Audit log records: blocked response, server=filesystem, pii_type=aws_key
|
|
112
|
+
→ Agent receives: "Request blocked by security policy"
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## Scope
|
|
116
|
+
|
|
117
|
+
MCP-Guard operates at the **MCP protocol layer** — it inspects JSON-RPC messages between client and server. This is a deliberate architectural boundary.
|
|
118
|
+
|
|
119
|
+
**What MCP-Guard does not address:**
|
|
120
|
+
|
|
121
|
+
- **LLM prompt injection** — MCP-Guard does not analyze agent intent. Detecting whether an agent was tricked into making a malicious call requires agent-layer defenses.
|
|
122
|
+
- **Model jailbreaking or alignment bypasses** — MCP-Guard does not operate at the model layer. LLM safety is a model-layer concern, not a transport security concern.
|
|
123
|
+
- **Network-layer attacks** (MITM, DNS rebinding, TLS stripping) — MCP-Guard does not replace network security. Use standard network security controls.
|
|
124
|
+
- **Malicious MCP server implementations** — the proxy limits exposure via permissions and PII scanning, but cannot fix a compromised server.
|
|
125
|
+
|
|
126
|
+
MCP-Guard is the protocol-layer firewall. It complements agent-layer and network-layer defenses — it doesn't replace them.
|
|
127
|
+
|
|
128
|
+
## Benchmark Results
|
|
129
|
+
|
|
130
|
+
The benchmark suite is open-source and fully reproducible (`pnpm benchmark`). It tests MCP-Guard's deterministic interceptor pipeline — policy enforcement, pattern matching, and access control — against 7,095 programmatically generated attack scenarios across 10 categories and 10,168 legitimate requests. See [Benchmark Methodology](docs/benchmark-methodology.md) for threat model, statistical interpretation, and known limitations.
|
|
102
131
|
|
|
103
132
|
### Per-Category Detection
|
|
104
133
|
|
|
@@ -115,6 +144,23 @@ The benchmark suite tests 7,095 attack scenarios across 10 categories and 10,168
|
|
|
115
144
|
| PII request leak | 93.8% | Pass |
|
|
116
145
|
| Rate limit evasion | 92.4% | Pass |
|
|
117
146
|
|
|
147
|
+
### Summary
|
|
148
|
+
|
|
149
|
+
| Metric | Result | Target | Status |
|
|
150
|
+
|--------|--------|--------|--------|
|
|
151
|
+
| Detection rate | 97.0% | >95% | Pass |
|
|
152
|
+
| False positive rate | 0 in 10,168 requests (<0.03% at 95% CI) | <0.1% | Pass |
|
|
153
|
+
| Audit integrity | No raw PII in logs | Pass | Pass |
|
|
154
|
+
| p50 latency overhead | 0.17ms (deterministic pipeline, no network hop) | <5ms | Pass |
|
|
155
|
+
|
|
156
|
+
### Limitations
|
|
157
|
+
|
|
158
|
+
- Tested against own generated scenarios, not an independent corpus — [methodology explains mitigations](docs/benchmark-methodology.md#self-testing-honesty-about-our-own-test-suite)
|
|
159
|
+
- Regex PII detection misses semantic encoding (spelling out digits, splitting across fields)
|
|
160
|
+
- Does not address LLM-level prompt injection — complementary tools like those evaluated by [MCPSecBench](https://arxiv.org/abs/2508.13220) operate at the agent layer
|
|
161
|
+
- No coverage for network-layer attacks (MITM, DNS rebinding)
|
|
162
|
+
- ML-based detection planned but not yet implemented
|
|
163
|
+
|
|
118
164
|
> Full-suite results from `pnpm benchmark`. Quick mode (`pnpm benchmark:quick`) uses stratified sampling and typically reports ~89-93% detection. See [latest report](benchmarks/results/REPORT.md) for charts.
|
|
119
165
|
|
|
120
166
|
## CLI Reference
|
package/package.json
CHANGED