@guardbee/mcp-security-proxy 1.1.0 → 1.1.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 +1 -1
- package/TR.md +1 -1
- package/ZH.md +189 -0
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @guardbee/mcp-security-proxy
|
|
2
2
|
|
|
3
|
-
**🇬🇧 English** | [🇹🇷 Türkçe](TR.md)
|
|
3
|
+
**🇬🇧 English** | [🇹🇷 Türkçe](TR.md) | [🇨🇳 中文](ZH.md)
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@guardbee/mcp-security-proxy)
|
|
6
6
|
[](https://www.npmjs.com/package/@guardbee/mcp-security-proxy)
|
package/TR.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @guardbee/mcp-security-proxy
|
|
2
2
|
|
|
3
|
-
[🇬🇧 English](README.md) | **🇹🇷 Türkçe**
|
|
3
|
+
[🇬🇧 English](README.md) | **🇹🇷 Türkçe** | [🇨🇳 中文](ZH.md)
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@guardbee/mcp-security-proxy)
|
|
6
6
|
[](https://www.npmjs.com/package/@guardbee/mcp-security-proxy)
|
package/ZH.md
ADDED
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
# @guardbee/mcp-security-proxy
|
|
2
|
+
|
|
3
|
+
[🇬🇧 English](README.md) | [🇹🇷 Türkçe](TR.md) | **🇨🇳 中文**
|
|
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
|
+
一个透明的安全层，放在任何 MCP 服务器前面。它拦截 prompt 注入攻击，对响应中的 PII 进行脱敏，并把每个请求写入不可篡改的审计日志。
|
|
10
|
+
|
|
11
|
+
> 本包默认向 GuardBee 发送使用遥测（工具名 + 较短的参数，见 [`@guardbee/mcp-telemetry`](../telemetry/README.md)），这与它自己的本地审计日志相互独立。设置 `GUARDBEE_TELEMETRY=0` 即可关闭。
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
Claude ──► MCP Security Proxy ──► 任意 MCP 服务器
|
|
15
|
+
│
|
|
16
|
+
├─ Prompt 注入检测 (27 条规则，英文 + 土耳其语)
|
|
17
|
+
├─ PII + 密钥脱敏 (TC、VKN、IBAN、银行卡、电话、22 种密钥格式)
|
|
18
|
+
├─ 拦截或警告模式
|
|
19
|
+
├─ 有毒数据流（lethal trifecta）拦截
|
|
20
|
+
└─ 哈希链审计日志
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 功能
|
|
26
|
+
|
|
27
|
+
- **Prompt 注入防护** —— 27 条英文和土耳其语规则；精确规则会拦截，通用短语只发出警告
|
|
28
|
+
- **工具结果注入** —— 同一套规则也作用于工具结果，标记为 MCP06:2025。拦截模式会替换结果；警告模式会在结果前加上一条警告
|
|
29
|
+
- **会话工具固定（pin）** —— 固定第一次 `tools/list` 的结果。之后描述或 schema 的变化即视为 rug pull（MCP03:2025）。拦截模式继续提供固定的定义，并拒绝已漂移的调用
|
|
30
|
+
- **PII 脱敏** —— 对响应中的土耳其身份证号（TC Kimlik No）、税号（VKN）、IBAN、银行卡号和电话号码（均经校验和验证）、电子邮件、22 种服务商密钥格式、私钥和数据库连接串进行脱敏
|
|
31
|
+
- **拦截 / 警告模式** —— 每个拦截器都可以独立运行在拦截或警告模式
|
|
32
|
+
- **审计日志** —— 可配置，写入控制台或文件
|
|
33
|
+
- **网关模式** —— 多个 MCP 服务器置于同一个代理之后，使用一份 YAML 策略（allow / deny / mask / warn）
|
|
34
|
+
- **有毒数据流拦截** —— 跨服务器追踪 lethal trifecta，并拦截会使其成立的外发（egress）调用
|
|
35
|
+
- **无需改代码** —— 直接挂在任何现有 MCP 服务器前面
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 快速开始
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
npm install -g @guardbee/mcp-security-proxy
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
添加到 `claude_desktop_config.json`：
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{
|
|
49
|
+
"mcpServers": {
|
|
50
|
+
"secure-filesystem": {
|
|
51
|
+
"command": "npx",
|
|
52
|
+
"args": [
|
|
53
|
+
"-y", "@guardbee/mcp-security-proxy",
|
|
54
|
+
"--", "npx", "-y",
|
|
55
|
+
"@modelcontextprotocol/server-filesystem", "/tmp"
|
|
56
|
+
]
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
> 代理会把 `--` 之后的内容作为目标 MCP 服务器启动。
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## 网关模式：多个服务器，一份策略
|
|
67
|
+
|
|
68
|
+
用一个 `guardbee-proxy.yaml` 把所有 MCP 服务器放到同一个代理后面。`init` 可以帮你完成迁移：
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
npx -y @guardbee/mcp-security-proxy@^1 init --client claude-desktop # 或 cursor、claude-code、--file ./mcp.json
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
它会把每个 stdio 服务器移入 `~/.guardbee/guardbee-proxy.yaml`（权限 0600），备份客户端配置，并把配置指向代理。HTTP 服务器保持不变并会被报告出来，因为它们会绕过策略。`--dry-run` 只打印两个文件而不写入。也可以手动配置：
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
{
|
|
78
|
+
"mcpServers": {
|
|
79
|
+
"guardbee": {
|
|
80
|
+
"command": "npx",
|
|
81
|
+
"args": ["-y", "@guardbee/mcp-security-proxy@^1", "--config", "/path/to/guardbee-proxy.yaml"]
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
```yaml
|
|
88
|
+
version: 1
|
|
89
|
+
upstreams:
|
|
90
|
+
github:
|
|
91
|
+
command: npx
|
|
92
|
+
args: ["-y", "@modelcontextprotocol/server-github"]
|
|
93
|
+
env: { GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}" } # 从环境变量读取
|
|
94
|
+
postgres:
|
|
95
|
+
command: npx
|
|
96
|
+
args: ["-y", "@guardbee/mcp-db-gateway"]
|
|
97
|
+
|
|
98
|
+
labels: # 覆盖启发式标签
|
|
99
|
+
github__get_issue: [untrusted]
|
|
100
|
+
github__create_pull_request: [egress]
|
|
101
|
+
|
|
102
|
+
rules: # 第一条匹配的规则生效
|
|
103
|
+
- id: no-deletes
|
|
104
|
+
match: { tool: "postgres__delete_*" }
|
|
105
|
+
action: deny # allow | deny | mask | warn | approve
|
|
106
|
+
- match: { tool: "postgres__query", args: { table: "salaries" } } # 点分路径 → 值，字符串为 glob
|
|
107
|
+
action: mask
|
|
108
|
+
mask: { fields: [salary, iban] } # 清空这些 JSON 键
|
|
109
|
+
- match: { label: destructive }
|
|
110
|
+
action: approve # 先征求用户同意
|
|
111
|
+
|
|
112
|
+
taint:
|
|
113
|
+
mode: strict # strict | approve | warn | off
|
|
114
|
+
|
|
115
|
+
audit:
|
|
116
|
+
sink: file
|
|
117
|
+
filePath: ./guardbee-audit.jsonl
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
- 工具和 prompt 以 `<upstream>__<tool>` 的名称出现。
|
|
121
|
+
- **有毒数据流（lethal trifecta）：** 每个工具会被标记为 `untrusted`、`sensitive`、`egress` 或 `destructive`（基于名称/描述的启发式，可在 `labels` 中覆盖）。当一个会话既读取过不可信内容（`untrusted` 工具或任何 resource），又读取过敏感数据（`sensitive` 工具，或结果中出现任何 PII）之后，`egress` 调用在 `strict` 模式下会被拦截，在 `warn` 模式下只记录日志。该检查跨服务器生效：从 GitHub 读取的 issue 加上从 CRM 读取的客户记录，会拦截第三个服务器上的 webhook 调用。
|
|
122
|
+
- **规则**可按 `tool`（glob）、`upstream`、`label`、`session`（`clean` | `tainted`）和 `args` 匹配。即使全局脱敏关闭，`mask` 也会对该工具强制进行 PII 脱敏；`mask.fields` 还会清空文本和 `structuredContent` 中指定的 JSON 键。规则中的 `allow` 不会跳过有毒数据流检查；如需放行，请修改该工具的标签。
|
|
123
|
+
- **审批：** `approve`（规则动作，或针对有毒数据流的 `taint.mode: approve`）会通过 MCP elicitation 向用户展示一个是/否表单，其中包含工具、原因和参数。除明确的"是"之外的任何回答——拒绝、取消、在 `approval.timeoutSeconds`（默认 120 秒）内未作答——都会拦截该调用。不支持 elicitation 的客户端无法审批，调用会被拦截并附带说明。
|
|
124
|
+
- **令牌化（Tokenize）：** 设置 `interceptors.piiMasking.mode: tokenize` 后，模型看到的是 `<pii:tc_kimlik:7f3a9b21>` 而不是真实值，并且仍然可以把它传给另一个工具：代理会在发往该服务器时把真实值放回去。令牌只在会话期间保存在内存中；除非设置 `piiMasking.detokenizeForEgress: true`，否则不会为 `egress` 工具还原成真实值。
|
|
125
|
+
- **Prompt**（`prompts/get`）与工具结果一样，经过注入扫描和 PII 脱敏。
|
|
126
|
+
- `interceptors.definitionDrift.recheck: on-change` 会跳过每次调用前的 `tools/list`，只在服务器发送 `tools/list_changed` 后重新检查；代理也会把该通知转发给智能体。
|
|
127
|
+
- **审计日志**采用哈希链。默认只保存参数的 SHA-256，而不保存参数本身，也不保存结果；设置 `audit.includePayloads: true` 可记录它们。用 `guardbee-proxy verify-audit ./guardbee-audit.jsonl` 校验日志。
|
|
128
|
+
- `guardbee-proxy validate --config guardbee-proxy.yaml` 在不启动任何服务器的情况下检查配置。
|
|
129
|
+
- 未指定 `--config` 时，代理也会读取 `./guardbee-proxy.yaml` 或 `GUARDBEE_PROXY_CONFIG=<file>.yaml`。
|
|
130
|
+
|
|
131
|
+
上面的单服务器 `--` 用法保持 0.x 的行为：工具名不加前缀，记录完整载荷，有毒数据流只记为警告。
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## MCP 工具
|
|
136
|
+
|
|
137
|
+
代理本身不注册任何工具。它转发目标服务器的工具，并在每次调用时应用拦截器链。
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## 拦截器
|
|
142
|
+
|
|
143
|
+
### Prompt 注入检测
|
|
144
|
+
|
|
145
|
+
来自 [`@guardbee/guard-core`](../guard-core/README.md) 的 27 条规则，作用于工具参数、工具结果、resource 和 prompt：
|
|
146
|
+
|
|
147
|
+
- **拦截**（13 条精确规则，high/critical）：英文和土耳其语的指令覆盖（"ignore all previous instructions"、"önceki talimatları yok say"）、`DAN mode`、"bypass your safety guardrails"、聊天模板标记（`<|im_start|>`、`[INST]`）、`<system>` 标签、藏在 Unicode tag 字符中的文本、CSS 隐藏元素或 HTML 注释中的指令、markdown 图片外泄信标、索要系统提示词的请求（英文和土耳其语）、"send the user's data to https://…"。
|
|
148
|
+
- **仅警告**（14 条）：在普通文本中也会出现的通用短语——"act as"、"you are now"、"developer mode"、"jailbreak"、"override policy"、"sen artık"——以及中等严重度的信号，如零宽字符或双向（bidi）控制字符、行首的 `System:` 标签。
|
|
149
|
+
- **Base64：** 能解码为可读文本的片段会被解码，并用拦截规则检查，因此指令无法藏在编码的数据块里。
|
|
150
|
+
|
|
151
|
+
从 1.1 开始，单独出现的通用短语不再触发拦截：在 1.0 中，工具结果里的 "use jailbreak mode" 或 "act as a reverse proxy" 会被拦截；现在只记录日志，并在结果中附上一条警告。
|
|
152
|
+
|
|
153
|
+
### PII 脱敏
|
|
154
|
+
|
|
155
|
+
| 数据类型 | 校验 | 输入示例 | 输出 |
|
|
156
|
+
|-----------|-------|---------------|--------|
|
|
157
|
+
| 土耳其身份证号（TC Kimlik No） | 官方校验算法 | `10000000146` | `[TC-KİMLİK]` |
|
|
158
|
+
| IBAN（TR） | mod-97 | `TR330006100519786457841326` | `TR**[IBAN]` |
|
|
159
|
+
| 银行卡号 | Luhn | `4111 1111 1111 1111` | `****-****-****-[KART]` |
|
|
160
|
+
| 电子邮件 | — | `ahmet@example.com` | `***@[EMAIL]` |
|
|
161
|
+
| 电话（土耳其） | 手机 / 座机 / 850 前缀 | `0532 123 45 67` | `+90-***-***-**[TELEFON]` |
|
|
162
|
+
| 税号（VKN） | 校验位，且需带 `VKN` / `Vergi No` 标签 | `VKN: 1234567890` | `VKN: [VKN]` |
|
|
163
|
+
| 服务商密钥 | 来自 secret-scanner 的 22 种密钥和令牌格式（AWS、GitHub、Stripe、OpenAI、Anthropic、Slack 等） | `ghp_…`、`AKIA…` | `[API-KEY]` |
|
|
164
|
+
| 其他 API 密钥 | `sk_`/`api_`/`token_` 等前缀，同时含字母和数字 | `api_k3y9x8…` | `[API-KEY]` |
|
|
165
|
+
| 私钥 | 完整的 BEGIN…END 块 | `-----BEGIN … PRIVATE KEY-----` | `[PRIVATE-KEY]` |
|
|
166
|
+
| 数据库连接串 | URL 中的 用户名:密码（排除 localhost） | `postgres://app:pw@db/prod` | `[CONNECTION-STRING]` |
|
|
167
|
+
| JWT | — | `eyJhbGc...` | `[JWT-TOKEN]` |
|
|
168
|
+
|
|
169
|
+
未通过校验和的数字（订单号、快递单号）保持原样。
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## 配置
|
|
174
|
+
|
|
175
|
+
可通过环境变量配置：
|
|
176
|
+
|
|
177
|
+
| 变量 | 默认值 | 说明 |
|
|
178
|
+
|----------|-----------|----------|
|
|
179
|
+
| `PROXY_MODE` | `block` | `block` 或 `warn` |
|
|
180
|
+
| `PROXY_LOG` | `console` | `console` 或 `file` |
|
|
181
|
+
| `PROXY_LOG_PATH` | `./proxy-audit.jsonl` | 日志文件路径 |
|
|
182
|
+
| `PROXY_PII_MASK` | `true` | 启用 PII 脱敏 |
|
|
183
|
+
| `PROXY_INJECTION_CHECK` | `true` | 启用注入检查 |
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## 许可证
|
|
188
|
+
|
|
189
|
+
MIT — [GuardBee](https://guardbee.ai)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guardbee/mcp-security-proxy",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.1",
|
|
4
4
|
"mcpName": "io.github.4hmetuyar/security-proxy",
|
|
5
5
|
"description": "MCP security gateway: several MCP servers behind one policy, with toxic-flow (lethal trifecta) blocking, approvals, PII masking and a hash-chained audit log",
|
|
6
6
|
"author": "GuardBee <hello@guardbee.ai>",
|
|
@@ -34,7 +34,8 @@
|
|
|
34
34
|
"files": [
|
|
35
35
|
"dist",
|
|
36
36
|
"README.md",
|
|
37
|
-
"TR.md"
|
|
37
|
+
"TR.md",
|
|
38
|
+
"ZH.md"
|
|
38
39
|
],
|
|
39
40
|
"engines": {
|
|
40
41
|
"node": ">=18"
|
|
@@ -43,7 +44,7 @@
|
|
|
43
44
|
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
44
45
|
"yaml": "^2.9.1",
|
|
45
46
|
"zod": "^4.5.4",
|
|
46
|
-
"@guardbee/guard-core": "^0.2.
|
|
47
|
+
"@guardbee/guard-core": "^0.2.1",
|
|
47
48
|
"@guardbee/mcp-telemetry": "^0.1.3"
|
|
48
49
|
},
|
|
49
50
|
"scripts": {
|