@mcp-guardian/server 1.3.4 → 1.3.6
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 +1 -1
- package/SECURITY.md +131 -0
- package/default-policy.yaml +53 -0
- package/package.json +6 -2
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
[](LICENSE)
|
|
10
10
|
[](https://github.com/rudraneel93/mcp-guardian/actions/workflows/ci.yml)
|
|
11
11
|
|
|
12
|
-
> **Always use the latest version:** `npm install @mcp-guardian/server@latest` — current is **v1.3.
|
|
12
|
+
> **Always use the latest version:** `npm install -g @mcp-guardian/server@latest` — current is **v1.3.5**. See the [Changelog](./CHANGELOG.md) for full version history and [GitHub Releases](https://github.com/rudraneel93/mcp-guardian/releases) for per-version source tags.
|
|
13
13
|
|
|
14
14
|
MCP Guardian is a **security and governance proxy** for [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) infrastructure. It sits between AI clients and MCP servers, enforcing active security policies, tracking real token costs, and monitoring health — all while providing enterprise-grade observability and audit trails.
|
|
15
15
|
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
## Threat Model (STRIDE per MCP Interaction)
|
|
4
|
+
|
|
5
|
+
MCP Guardian's security posture is modeled against the STRIDE framework for each MCP interaction vector.
|
|
6
|
+
|
|
7
|
+
### 1. Spoofing (Identity Forgery)
|
|
8
|
+
|
|
9
|
+
| Threat | Mitigation |
|
|
10
|
+
|---|---|
|
|
11
|
+
| Typo-squatted MCP server packages | Typo-squat detector with Levenshtein distance against 24 known official packages |
|
|
12
|
+
| Fake MCP server responding to health probes | TLS certificate validation for SSE/HTTP transports |
|
|
13
|
+
| Malicious server impersonating a trusted tool | Command validation flags non-standard executables |
|
|
14
|
+
|
|
15
|
+
### 2. Tampering (Data/Command Injection)
|
|
16
|
+
|
|
17
|
+
| Threat | Mitigation |
|
|
18
|
+
|---|---|
|
|
19
|
+
| Shell injection via tool arguments | Active policy engine blocks patterns (rm -rf, shell chaining, backtick substitution) |
|
|
20
|
+
| Encoded payload bypasses (URL, hex, unicode, HTML entities) | PayloadNormalizer (v1.2) — multi-stage decode before regex evaluation |
|
|
21
|
+
| Shell obfuscation (ANSI-C quoting, quote splitting, backslash escapes) | ShellTokenizer (v1.2) — semantic AST analysis of command structure |
|
|
22
|
+
| Path traversal | Active policy engine blocks ../ patterns |
|
|
23
|
+
| Supply chain compromise of MCP server package | CVE checker queries OSV.dev and NVD for known vulnerabilities |
|
|
24
|
+
|
|
25
|
+
### 3. Repudiation (Deniability)
|
|
26
|
+
|
|
27
|
+
| Threat | Mitigation |
|
|
28
|
+
|---|---|
|
|
29
|
+
| No audit trail for blocked/allowed tool calls | Structured JSON logging (pino) captures every policy_decision |
|
|
30
|
+
| Policy changes without audit | PolicyAuditor (v1.0.1) records every policy change with hash verification |
|
|
31
|
+
| Denied access attempts not recorded | tool_blocked events logged at WARN level for SIEM alerting |
|
|
32
|
+
|
|
33
|
+
### 4. Information Disclosure (Secrets/Data Leakage)
|
|
34
|
+
|
|
35
|
+
| Threat | Mitigation |
|
|
36
|
+
|---|---|
|
|
37
|
+
| Hardcoded API keys, tokens, passwords in MCP config | Secret scanner (6 regex patterns) |
|
|
38
|
+
| Unauthenticated dashboard access | DashboardAuth (v1.2) — JWT sessions, API keys, CSRF protection, rate-limited login |
|
|
39
|
+
| Unencrypted transport | Auth prober flags unencrypted transports |
|
|
40
|
+
| Sensitive data in generated reports | Reports use config names, not raw secrets |
|
|
41
|
+
|
|
42
|
+
### 5. Denial of Service (Availability)
|
|
43
|
+
|
|
44
|
+
| Threat | Mitigation |
|
|
45
|
+
|---|---|
|
|
46
|
+
| Token bombs | Token budget rule (maxTokens) flags/blocks oversized calls |
|
|
47
|
+
| Tool overload (>15 tools) | Health monitor detects overload; --fail-on-overload CLI flag |
|
|
48
|
+
| Rate abuse | Rate limiting rule (maxCallsPerMinute) per server+tool |
|
|
49
|
+
| API ban on CVE lookup services | Token-bucket rate limiter on OSV.dev (5 req/min) and NVD (20 req/min with key) |
|
|
50
|
+
|
|
51
|
+
### 6. Elevation of Privilege (Agent Hijacking)
|
|
52
|
+
|
|
53
|
+
| Threat | Mitigation |
|
|
54
|
+
|---|---|
|
|
55
|
+
| Confused deputy attack | Tool allowlist/denylist in policy engine; argument pattern blocking |
|
|
56
|
+
| Agent tricked into calling dangerous tools | Default policy denies execute_command, bash, sh, eval, exec |
|
|
57
|
+
| Missing authentication on MCP servers | OAuth 2.1/OIDC JWT validation with RBAC (scopes, client IDs) |
|
|
58
|
+
|
|
59
|
+
## Supported Versions
|
|
60
|
+
|
|
61
|
+
| Version | Status | Security Updates |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| 1.0.x | ✅ Current | All updates |
|
|
64
|
+
| 0.7.x | ✅ Supported | Critical only |
|
|
65
|
+
| <0.7.0 | ❌ Unsupported | None |
|
|
66
|
+
|
|
67
|
+
## Reporting a Vulnerability
|
|
68
|
+
|
|
69
|
+
**Do not open a public issue for security vulnerabilities.**
|
|
70
|
+
|
|
71
|
+
Email **rudraneel93@gmail.com** with:
|
|
72
|
+
- Description of the vulnerability
|
|
73
|
+
- Steps to reproduce
|
|
74
|
+
- Affected version(s)
|
|
75
|
+
- Any proof-of-concept or crash data
|
|
76
|
+
|
|
77
|
+
Response timeline:
|
|
78
|
+
- **24 hours:** Acknowledgement
|
|
79
|
+
- **72 hours:** Initial assessment
|
|
80
|
+
- **7 days:** Patch or mitigation plan
|
|
81
|
+
|
|
82
|
+
## Incident Response
|
|
83
|
+
|
|
84
|
+
### Severity Classification
|
|
85
|
+
|
|
86
|
+
| Level | Example | Response |
|
|
87
|
+
|---|---|---|
|
|
88
|
+
| **Critical** | RCE via proxy, auth bypass, secret leak | Patch within 24 hours, CVE disclosure |
|
|
89
|
+
| **High** | Policy bypass, DoS vulnerability | Patch within 72 hours |
|
|
90
|
+
| **Medium** | Information disclosure, limited impact | Patch in next release |
|
|
91
|
+
| **Low** | Minor configuration issues | Documented workaround |
|
|
92
|
+
|
|
93
|
+
### Emergency Patch Process
|
|
94
|
+
|
|
95
|
+
1. **Isolate:** If a vulnerability is confirmed, immediately document the affected versions and attack vector
|
|
96
|
+
2. **Mitigate:** Provide a temporary workaround (policy rule, config change) within 24 hours
|
|
97
|
+
3. **Patch:** Release a fix with full test coverage
|
|
98
|
+
4. **Disclose:** Publish advisory in GitHub Security Advisories and npm audit
|
|
99
|
+
|
|
100
|
+
### Dependency Supply Chain
|
|
101
|
+
|
|
102
|
+
- All dependencies are pinned via `package-lock.json`
|
|
103
|
+
- CI pipeline runs `npm audit` on every commit
|
|
104
|
+
- Critical dependencies (`@modelcontextprotocol/sdk`, `jose`, `pg`) are reviewed on each major version bump
|
|
105
|
+
- OTel gRPC exporter removed (v1.0.1) due to critical CVE in protobufjs dependency chain
|
|
106
|
+
|
|
107
|
+
## Security Design Principles
|
|
108
|
+
|
|
109
|
+
1. **Least Privilege:** The policy engine denies by default when configured with allowlists
|
|
110
|
+
2. **Defense in Depth:** Static scanning (config audit) + runtime enforcement (proxy policy) + SIEM logging
|
|
111
|
+
3. **Fail Secure:** Graceful shutdown flushes DB before exit; blocked calls return explicit errors
|
|
112
|
+
4. **Auditability:** Every policy decision, block, and proxy event is logged as structured JSON. Policy changes are recorded via PolicyAuditor
|
|
113
|
+
5. **Zero Trust on Input:** All tool arguments are pattern-checked regardless of source
|
|
114
|
+
|
|
115
|
+
## Dependencies
|
|
116
|
+
|
|
117
|
+
MCP Guardian requires these critical dependencies:
|
|
118
|
+
|
|
119
|
+
| Dependency | Purpose | Security Notes |
|
|
120
|
+
|---|---|---|
|
|
121
|
+
| `@modelcontextprotocol/sdk` | MCP protocol implementation | Keep updated to latest; CVE monitoring |
|
|
122
|
+
| `tiktoken` | Token counting (o200k_base encoding) | Pure JS, no native bindings |
|
|
123
|
+
| `sql.js` | SQLite storage | WASM-based, no native compilation |
|
|
124
|
+
| `pino` | Structured logging | High-performance JSON logger |
|
|
125
|
+
| `js-yaml` | YAML policy parsing | Policy files only |
|
|
126
|
+
| `jose` | JWT/JWK validation | OAuth 2.1/OIDC support |
|
|
127
|
+
| `ioredis` | Redis client | Session cache and rate limit store |
|
|
128
|
+
| `pg` | PostgreSQL client | Production DB backend |
|
|
129
|
+
| `prom-client` | Prometheus metrics | Monitoring |
|
|
130
|
+
|
|
131
|
+
Run `npm audit` regularly and update dependencies through Dependabot or similar tools.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
# MCP Guardian — Default Policy Configuration
|
|
3
|
+
# Use with: mcp-guardian proxy --policy ./default-policy.yaml
|
|
4
|
+
|
|
5
|
+
version: "1.0"
|
|
6
|
+
policy:
|
|
7
|
+
# Mode: audit (passive, log only), warn (block → flag), block (active enforcement)
|
|
8
|
+
mode: warn
|
|
9
|
+
|
|
10
|
+
rules:
|
|
11
|
+
# ── Block shell injection patterns ──────────────────────────
|
|
12
|
+
- name: "block-shell-injection"
|
|
13
|
+
description: "Block tool calls containing shell injection or command chaining"
|
|
14
|
+
action: block
|
|
15
|
+
patterns:
|
|
16
|
+
- "curl\\s|wget\\s" # Network download tools
|
|
17
|
+
- "rm\\s+-rf" # Destructive commands
|
|
18
|
+
- ";\\s*\\w" # Shell chaining
|
|
19
|
+
- "&&|\\|\\|" # Shell logical operators
|
|
20
|
+
- "\\$\\{" # Shell variable expansion
|
|
21
|
+
- "`[^`]+`" # Backtick command substitution
|
|
22
|
+
- "/etc/passwd|/etc/shadow" # Sensitive system files
|
|
23
|
+
|
|
24
|
+
# ── Block path traversal ─────────────────────────────────────
|
|
25
|
+
- name: "block-path-traversal"
|
|
26
|
+
description: "Block tool calls with path traversal attempts"
|
|
27
|
+
action: block
|
|
28
|
+
patterns:
|
|
29
|
+
- "\\.\\.\\/" # Path traversal
|
|
30
|
+
|
|
31
|
+
# ── Deny dangerous tools ─────────────────────────────────────
|
|
32
|
+
- name: "deny-dangerous-tools"
|
|
33
|
+
description: "Explicitly deny tools that can execute arbitrary code"
|
|
34
|
+
action: block
|
|
35
|
+
tools:
|
|
36
|
+
deny:
|
|
37
|
+
- "execute_command"
|
|
38
|
+
- "bash"
|
|
39
|
+
- "sh"
|
|
40
|
+
- "eval"
|
|
41
|
+
- "exec"
|
|
42
|
+
|
|
43
|
+
# ── Rate limit ───────────────────────────────────────────────
|
|
44
|
+
- name: "rate-limit-tool-calls"
|
|
45
|
+
description: "Limit tool calls to 120 per minute per server+tool"
|
|
46
|
+
action: flag
|
|
47
|
+
maxCallsPerMinute: 120
|
|
48
|
+
|
|
49
|
+
# ── Token budget ─────────────────────────────────────────────
|
|
50
|
+
- name: "token-budget"
|
|
51
|
+
description: "Flag tool calls exceeding 50K input tokens"
|
|
52
|
+
action: flag
|
|
53
|
+
maxTokens: 50000
|
package/package.json
CHANGED
|
@@ -1,10 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mcp-guardian/server",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.6",
|
|
4
4
|
"description": "Security, cost, and health audit for MCP infrastructure",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|
|
7
|
-
"dist"
|
|
7
|
+
"dist",
|
|
8
|
+
"README.md",
|
|
9
|
+
"LICENSE",
|
|
10
|
+
"SECURITY.md",
|
|
11
|
+
"default-policy.yaml"
|
|
8
12
|
],
|
|
9
13
|
"bin": {
|
|
10
14
|
"mcp-guardian": "./dist/cli.js"
|