@guardbee/mcp-security-proxy 0.2.0 → 0.2.2
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 +38 -36
- package/TR.md +112 -0
- package/package.json +8 -6
package/README.md
CHANGED
|
@@ -1,41 +1,43 @@
|
|
|
1
1
|
# @guardbee/mcp-security-proxy
|
|
2
2
|
|
|
3
|
+
**🇬🇧 English** | [🇹🇷 Türkçe](TR.md)
|
|
4
|
+
|
|
3
5
|
[](https://www.npmjs.com/package/@guardbee/mcp-security-proxy)
|
|
4
6
|
[](https://www.npmjs.com/package/@guardbee/mcp-security-proxy)
|
|
5
7
|
[](LICENSE)
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
A transparent security layer that sits in front of any MCP server. Blocks prompt injection attacks, masks PII in responses, and writes every request to an immutable audit log.
|
|
8
10
|
|
|
9
|
-
>
|
|
11
|
+
> This package sends usage telemetry to GuardBee by default (tool name + short parameters, see [`@guardbee/mcp-telemetry`](../telemetry/README.md)) — separate from and independent of its own local audit log. Disable with `GUARDBEE_TELEMETRY=0`.
|
|
10
12
|
|
|
11
13
|
```
|
|
12
|
-
Claude ──► MCP Security Proxy ──►
|
|
14
|
+
Claude ──► MCP Security Proxy ──► Any MCP Server
|
|
13
15
|
│
|
|
14
|
-
├─ Prompt injection
|
|
15
|
-
├─ PII
|
|
16
|
-
├─ Block
|
|
17
|
-
└─
|
|
16
|
+
├─ Prompt injection detection (16 attack patterns)
|
|
17
|
+
├─ PII masking (national ID, IBAN, email, JWT, API key)
|
|
18
|
+
├─ Block or warn mode
|
|
19
|
+
└─ Configurable audit log
|
|
18
20
|
```
|
|
19
21
|
|
|
20
22
|
---
|
|
21
23
|
|
|
22
|
-
##
|
|
24
|
+
## Features
|
|
23
25
|
|
|
24
|
-
- **Prompt Injection
|
|
25
|
-
- **PII
|
|
26
|
-
- **Block / Warn
|
|
27
|
-
- **Audit Log** —
|
|
28
|
-
- **
|
|
26
|
+
- **Prompt Injection Protection** — 16 attack patterns block requests attempting to override system prompts
|
|
27
|
+
- **PII Masking** — national ID numbers, IBAN, email, phone, JWT tokens, API keys are automatically masked in responses
|
|
28
|
+
- **Block / Warn Mode** — each interceptor can independently run in blocking or warning mode
|
|
29
|
+
- **Audit Log** — configurable log written to console or a file
|
|
30
|
+
- **Zero Code Changes** — attaches in front of any existing MCP server
|
|
29
31
|
|
|
30
32
|
---
|
|
31
33
|
|
|
32
|
-
##
|
|
34
|
+
## Quick Start
|
|
33
35
|
|
|
34
36
|
```bash
|
|
35
37
|
npm install -g @guardbee/mcp-security-proxy
|
|
36
38
|
```
|
|
37
39
|
|
|
38
|
-
`claude_desktop_config.json
|
|
40
|
+
Add to `claude_desktop_config.json`:
|
|
39
41
|
|
|
40
42
|
```json
|
|
41
43
|
{
|
|
@@ -52,59 +54,59 @@ npm install -g @guardbee/mcp-security-proxy
|
|
|
52
54
|
}
|
|
53
55
|
```
|
|
54
56
|
|
|
55
|
-
>
|
|
57
|
+
> The proxy launches whatever comes after `--` as the target MCP server.
|
|
56
58
|
|
|
57
59
|
---
|
|
58
60
|
|
|
59
61
|
## MCP Tools
|
|
60
62
|
|
|
61
|
-
|
|
63
|
+
The proxy transparently forwards tools from the target server, applying the interceptor chain on every pass-through. It also exposes one management tool:
|
|
62
64
|
|
|
63
|
-
| Tool |
|
|
65
|
+
| Tool | Description |
|
|
64
66
|
|------|----------|
|
|
65
|
-
| `proxy_status` |
|
|
67
|
+
| `proxy_status` | Shows active interceptors and stats on the most recently blocked requests |
|
|
66
68
|
|
|
67
69
|
---
|
|
68
70
|
|
|
69
|
-
##
|
|
71
|
+
## Interceptors
|
|
70
72
|
|
|
71
73
|
### Prompt Injection Detector
|
|
72
74
|
|
|
73
|
-
|
|
75
|
+
Looks for the following attack patterns in incoming messages:
|
|
74
76
|
|
|
75
77
|
- `ignore previous instructions`
|
|
76
78
|
- `disregard your system prompt`
|
|
77
79
|
- `you are now [DAN/jailbreak]`
|
|
78
|
-
-
|
|
79
|
-
-
|
|
80
|
-
-
|
|
80
|
+
- commands hidden via ANSI escape sequences
|
|
81
|
+
- base64-encoded instructions
|
|
82
|
+
- and 11 more patterns
|
|
81
83
|
|
|
82
84
|
### PII Masker
|
|
83
85
|
|
|
84
|
-
|
|
|
86
|
+
| Data Type | Example Input | Output |
|
|
85
87
|
|-----------|------------|-------|
|
|
86
|
-
|
|
|
88
|
+
| National ID | `12345678901` | `[TC-REDACTED]` |
|
|
87
89
|
| IBAN | `TR320006200...` | `TR32***` |
|
|
88
|
-
|
|
|
90
|
+
| Email | `ahmet@example.com` | `ah***@example.com` |
|
|
89
91
|
| JWT | `eyJhbGc...` | `[JWT-REDACTED]` |
|
|
90
92
|
| API Key | `sk-abc123...` | `[KEY-REDACTED]` |
|
|
91
93
|
|
|
92
94
|
---
|
|
93
95
|
|
|
94
|
-
##
|
|
96
|
+
## Configuration
|
|
95
97
|
|
|
96
|
-
|
|
98
|
+
Configurable via environment variables:
|
|
97
99
|
|
|
98
|
-
|
|
|
100
|
+
| Variable | Default | Description |
|
|
99
101
|
|----------|-----------|----------|
|
|
100
|
-
| `PROXY_MODE` | `block` | `block`
|
|
101
|
-
| `PROXY_LOG` | `console` | `console`
|
|
102
|
-
| `PROXY_LOG_PATH` | `./proxy-audit.jsonl` | Log
|
|
103
|
-
| `PROXY_PII_MASK` | `true` | PII
|
|
104
|
-
| `PROXY_INJECTION_CHECK` | `true` |
|
|
102
|
+
| `PROXY_MODE` | `block` | `block` or `warn` |
|
|
103
|
+
| `PROXY_LOG` | `console` | `console` or `file` |
|
|
104
|
+
| `PROXY_LOG_PATH` | `./proxy-audit.jsonl` | Log file path |
|
|
105
|
+
| `PROXY_PII_MASK` | `true` | Enable PII masking |
|
|
106
|
+
| `PROXY_INJECTION_CHECK` | `true` | Enable injection checking |
|
|
105
107
|
|
|
106
108
|
---
|
|
107
109
|
|
|
108
|
-
##
|
|
110
|
+
## License
|
|
109
111
|
|
|
110
112
|
MIT — [GuardBee](https://guardbee.ai)
|
package/TR.md
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# @guardbee/mcp-security-proxy
|
|
2
|
+
|
|
3
|
+
[🇬🇧 English](README.md) | **🇹🇷 Türkçe**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@guardbee/mcp-security-proxy)
|
|
6
|
+
[](https://www.npmjs.com/package/@guardbee/mcp-security-proxy)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
|
|
9
|
+
Herhangi bir MCP sunucusunun önüne oturan şeffaf güvenlik katmanı. Prompt injection saldırılarını engeller, yanıtlardaki PII'yi maskeler ve her isteği değiştirilemez audit log'a yazar.
|
|
10
|
+
|
|
11
|
+
> Bu paket varsayılan olarak GuardBee'ye kullanım telemetrisi gönderir (tool adı + kısa parametreler, bkz. [`@guardbee/mcp-telemetry`](../telemetry/TR.md)) — bu, kendi local audit log'undan ayrı ve bağımsızdır. Kapatmak için `GUARDBEE_TELEMETRY=0`.
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
Claude ──► MCP Security Proxy ──► Herhangi bir MCP Sunucu
|
|
15
|
+
│
|
|
16
|
+
├─ Prompt injection tespiti (16 saldırı deseni)
|
|
17
|
+
├─ PII maskeleme (TC kimlik, IBAN, e-posta, JWT, API key)
|
|
18
|
+
├─ Block veya warn modu
|
|
19
|
+
└─ Yapılandırılabilir audit log
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Özellikler
|
|
25
|
+
|
|
26
|
+
- **Prompt Injection Koruması** — 16 saldırı deseni ile sistem prompt'larını geçersiz kılmaya çalışan istekler engellenir
|
|
27
|
+
- **PII Maskeleme** — TC kimlik no, IBAN, e-posta, telefon, JWT token, API key yanıtlarda otomatik maskelenir
|
|
28
|
+
- **Block / Warn Modu** — Her interceptor bağımsız olarak engelleyici veya uyarı modunda çalışabilir
|
|
29
|
+
- **Audit Log** — Console veya dosyaya yazılan yapılandırılabilir log
|
|
30
|
+
- **Sıfır Kod Değişikliği** — Mevcut herhangi bir MCP sunucusunun önüne takılır
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Hızlı Başlangıç
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npm install -g @guardbee/mcp-security-proxy
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`claude_desktop_config.json` dosyasına ekleyin:
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"mcpServers": {
|
|
45
|
+
"secure-filesystem": {
|
|
46
|
+
"command": "npx",
|
|
47
|
+
"args": [
|
|
48
|
+
"-y", "@guardbee/mcp-security-proxy",
|
|
49
|
+
"--", "npx", "-y",
|
|
50
|
+
"@modelcontextprotocol/server-filesystem", "/tmp"
|
|
51
|
+
]
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
> Proxy, `--` sonrasındaki komutu hedef MCP sunucu olarak başlatır.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## MCP Tools
|
|
62
|
+
|
|
63
|
+
Proxy, tool'ları hedef sunucudan şeffaf olarak aktarır ve her geçişte interceptor zincirini uygular. Ek olarak aşağıdaki yönetim tool'unu sunar:
|
|
64
|
+
|
|
65
|
+
| Tool | Açıklama |
|
|
66
|
+
|------|----------|
|
|
67
|
+
| `proxy_status` | Aktif interceptor'ları ve son engellenen istek istatistiklerini gösterir |
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Interceptor'lar
|
|
72
|
+
|
|
73
|
+
### Prompt Injection Detector
|
|
74
|
+
|
|
75
|
+
Gelen mesajlarda aşağıdaki saldırı desenlerini arar:
|
|
76
|
+
|
|
77
|
+
- `ignore previous instructions`
|
|
78
|
+
- `disregard your system prompt`
|
|
79
|
+
- `you are now [DAN/jailbreak]`
|
|
80
|
+
- ANSI escape dizileri ile gizlenmiş komutlar
|
|
81
|
+
- Base64 kodlanmış talimatlar
|
|
82
|
+
- ve 11 desen daha
|
|
83
|
+
|
|
84
|
+
### PII Masker
|
|
85
|
+
|
|
86
|
+
| Veri Tipi | Örnek Girdi | Çıktı |
|
|
87
|
+
|-----------|------------|-------|
|
|
88
|
+
| TC Kimlik | `12345678901` | `[TC-REDACTED]` |
|
|
89
|
+
| IBAN | `TR320006200...` | `TR32***` |
|
|
90
|
+
| E-posta | `ahmet@example.com` | `ah***@example.com` |
|
|
91
|
+
| JWT | `eyJhbGc...` | `[JWT-REDACTED]` |
|
|
92
|
+
| API Key | `sk-abc123...` | `[KEY-REDACTED]` |
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Yapılandırma
|
|
97
|
+
|
|
98
|
+
Ortam değişkenleri ile yapılandırılabilir:
|
|
99
|
+
|
|
100
|
+
| Değişken | Varsayılan | Açıklama |
|
|
101
|
+
|----------|-----------|----------|
|
|
102
|
+
| `PROXY_MODE` | `block` | `block` veya `warn` |
|
|
103
|
+
| `PROXY_LOG` | `console` | `console` veya `file` |
|
|
104
|
+
| `PROXY_LOG_PATH` | `./proxy-audit.jsonl` | Log dosya yolu |
|
|
105
|
+
| `PROXY_PII_MASK` | `true` | PII maskelemeyi etkinleştir |
|
|
106
|
+
| `PROXY_INJECTION_CHECK` | `true` | Injection kontrolünü etkinleştir |
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Lisans
|
|
111
|
+
|
|
112
|
+
MIT — [GuardBee](https://guardbee.ai)
|
package/package.json
CHANGED
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guardbee/mcp-security-proxy",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.2",
|
|
4
4
|
"description": "Security proxy for MCP servers — intercepts tool calls, detects prompt injection, masks PII, and writes audit logs",
|
|
5
5
|
"author": "GuardBee <hello@guardbee.ai>",
|
|
6
6
|
"license": "MIT",
|
|
7
|
-
"homepage": "https://github.com/GuardBee/guardbee-mcp
|
|
7
|
+
"homepage": "https://github.com/GuardBee/guardbee-mcp/tree/main/packages/security-proxy#readme",
|
|
8
8
|
"repository": {
|
|
9
9
|
"type": "git",
|
|
10
|
-
"url": "https://github.com/GuardBee/guardbee-mcp
|
|
10
|
+
"url": "https://github.com/GuardBee/guardbee-mcp.git",
|
|
11
|
+
"directory": "packages/security-proxy"
|
|
11
12
|
},
|
|
12
13
|
"bugs": {
|
|
13
|
-
"url": "https://github.com/GuardBee/guardbee-mcp
|
|
14
|
+
"url": "https://github.com/GuardBee/guardbee-mcp/issues"
|
|
14
15
|
},
|
|
15
16
|
"keywords": [
|
|
16
17
|
"mcp",
|
|
@@ -31,7 +32,8 @@
|
|
|
31
32
|
},
|
|
32
33
|
"files": [
|
|
33
34
|
"dist",
|
|
34
|
-
"README.md"
|
|
35
|
+
"README.md",
|
|
36
|
+
"TR.md"
|
|
35
37
|
],
|
|
36
38
|
"engines": {
|
|
37
39
|
"node": ">=18"
|
|
@@ -39,7 +41,7 @@
|
|
|
39
41
|
"dependencies": {
|
|
40
42
|
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
41
43
|
"zod": "^4.5.4",
|
|
42
|
-
"@guardbee/mcp-telemetry": "^0.1.
|
|
44
|
+
"@guardbee/mcp-telemetry": "^0.1.2"
|
|
43
45
|
},
|
|
44
46
|
"scripts": {
|
|
45
47
|
"build": "tsc",
|