aldok10/zara-privacy-mcp
GitHub: aldok10/zara-privacy-mcp
一个位于 AI agent 与外部服务之间的 MCP 网关，在所有调用中自动检测、掩码敏感数据并拦截危险操作以防止信息泄露。
Stars: 0 | Forks: 0
# Zara Privacy MCP
一个安全的 MCP (Model Context Protocol) 服务器，位于您的 AI agent 和外部服务之间。它会自动检测并掩码机密信息和个人数据，防止敏感信息泄露给 LLM 提供商、数据库或 API。
**一句话总结它的功能：** 您的 AI agent 通过此 MCP 进行的每一次调用都会被自动扫描和掩码处理——API key、密码、电子邮件、电话号码、信用卡——实现零泄露。
```
Your AI Agent
│
▼ (stdio JSON-RPC)
┌──────────────────────┐
│ Zara Privacy MCP │ ← auto-scans, masks, blocks dangerous ops
└──────────────────────┘
│
▼
Databases / APIs / AI Providers
```
## 为什么使用它？
| 问题 | Zara 如何解决 |
|---------|-------------------|
| AI agent 意外将您的 API key 发送给 LLM | 在发送前自动脱敏机密信息，之后还原 |
| 有人查询 `SELECT * FROM users` 并泄露电子邮件 | 数据库结果在返回前会被自动掩码 |
| agent 尝试执行 `DROP TABLE` 或 `FLUSHALL` | 被安全门拦截——永远不会执行 |
| LLM 提供商在会话中途宕机 | 自动故障转移到链中的下一个提供商 |
| token 成本太高 | 在 AI 调用前压缩工具输出（节省 20-40%） |
## 快速开始
### 前置条件
- 已安装 Go 1.21+（用于从源码构建）
- 一个 MCP 客户端（OpenCode、Kiro、Claude Code 或任何兼容 MCP 的工具）
### 安装选项
**选项 A：go install（推荐）**
```
go install github.com/aldok10/zara-privacy-mcp/cmd/server@latest
# 二进制文件安装到 $GOPATH/bin/server — 重命名它：
mv $(go env GOPATH)/bin/server $(go env GOPATH)/bin/zara-privacy-mcp
```
**选项 B：从 GitHub Releases 下载**
下载适合您操作系统的最新预编译二进制文件：
| 操作系统 | 架构 | 下载 |
|----|-------------|----------|
| Linux | amd64 | [zara-privacy-mcp-linux-amd64](https://github.com/aldok10/zara-privacy-mcp/releases/latest) |
| macOS | arm64 (Apple Silicon) | [zara-privacy-mcp-darwin-arm64](https://github.com/aldok10/zara-privacy-mcp/releases/latest) |
| Windows | amd64 | [zara-privacy-mcp-windows-amd64.exe](https://github.com/aldok10/zara-privacy-mcp/releases/latest) |
```
# 示例：Linux
curl -Lo zara-privacy-mcp https://github.com/aldok10/zara-privacy-mcp/releases/latest/download/zara-privacy-mcp-linux-amd64
chmod +x zara-privacy-mcp
sudo mv zara-privacy-mcp /usr/local/bin/
```
**选项 C：从源码构建**
```
git clone https://github.com/aldok10/zara-privacy-mcp.git
cd zara-privacy-mcp
make build
```
### 2. 设置您的连接
```
cp .env.example .env
# 编辑 .env — 添加你的 database/API/AI credentials
```
### 3. 创建包装脚本
使用您的环境变量编辑 `scripts/mcp-wrapper.sh`：
```
#!/bin/sh
export ZARA_ENCRYPTION_KEY="pick-a-strong-passphrase-here!!"
export ZARA_DB_MYDB_DSN="postgres://user:pass@localhost:5432/mydb"
# 根据需要添加更多 connections...
exec /path/to/zara-privacy-mcp --stdio
```
```
chmod +x scripts/mcp-wrapper.sh
```
### 4. 在您的 AI 工具中注册
添加到您工具的 MCP 配置中（例如 `~/.config/opencode/opencode.json`）：
```
{
"mcp": {
"zara-privacy-mcp": {
"type": "local",
"command": ["/absolute/path/to/scripts/mcp-wrapper.sh"],
"enabled": true
}
}
}
```
### 5. 重启您的 AI 工具——完成！
现在您的 agent 可以使用这 20 个工具了。它可以查询数据库、调用 API，并与 AI 提供商聊天——所有这些都通过隐私网关进行。
### 验证其有效性
```
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
| ./scripts/mcp-wrapper.sh 2>/dev/null \
| python3 -c "import sys,json; print(f'{len(json.load(sys.stdin)[\"result\"][\"tools\"])} tools loaded')"
# 输出：已加载 20 个工具
```
## 包含内容（20 个工具）
### 隐私工具——扫描并掩码敏感数据
| 工具 | 功能 |
|------|-------------|
| `scan_context` | 查找文本中的机密信息和个人身份信息 (PII)，返回风险评分 |
| `redact_context` | 将敏感数据替换为 `[EMAIL_1]`、`[API_KEY_1]` 占位符 |
| `unredact_response` | 在 LLM 响应后从占位符还原原始内容 |
| `compress_context` | 通过去重和去除干扰信息来减少 token 使用量 |
| `memory_filter` | 阻止高风险数据被存储在 agent 内存中 |
| `classify_data` | 将数据标记为 PUBLIC、INTERNAL、CONFIDENTIAL 或 SECRET |
| `store_stats` | 显示存储了多少个占位符 |
### 数据库工具——安全查询任何数据库
| 工具 | 功能 |
|------|-------------|
| `db_query` | 运行 SQL 查询——结果会自动掩码 PII |
| `db_list_tables` | 列出已配置数据库中的表 |
| `db_describe` | 显示列名、类型和约束 |
支持：PostgreSQL、MySQL、SQL Server、SQLite、Oracle、ClickHouse。
### MongoDB 与 Redis 工具
| 工具 | 功能 |
|------|-------------|
| `mongo_find` | 查询 MongoDB 集合——结果自动掩码 |
| `mongo_list_collections` | 列出集合 |
| `redis_exec` | 运行 Redis 命令（GET、SET、HGETALL 等） |
| `redis_keys` | 列出匹配特定模式的 key |
### HTTP API 工具——比 curl 更安全的替代方案
| 工具 | 功能 |
|------|-------------|
| `http_request` | 发起 HTTP 调用，并自动注入认证 header |
| `http_list_apis` | 显示已配置的 API endpoint |
### AI 提供商工具——私密地与任何 LLM 聊天
| 工具 | 功能 |
|------|-------------|
| `ai_chat` | 向 AI 发送消息——发送前自动脱敏，接收后自动还原 |
| `ai_list_providers` | 显示可用的提供商和模型 |
| `ai_quota_status` | 显示 token 使用量和剩余配额 |
9 个免费提供商（Kiro、OpenCode、Codex 等）已预先注册为备选方案。
### 配置
| 工具 | 功能 |
|------|-------------|
| `config_list` | 显示所有活跃连接，且不暴露机密信息 |
## 配置参考
所有配置均通过环境变量完成。将 `` 替换为您自己的标签（例如 `PROD`、`STAGING`、`LOCAL`）。
```
# === 必填 ===
ZARA_ENCRYPTION_KEY="your-passphrase-min-16-chars"
# === Database（根据需要添加任意多个） ===
ZARA_DB__DSN=postgres://user:pass@host:5432/db
ZARA_DB__DRIVER=postgres # optional — auto-detected from DSN
# === MongoDB ===
ZARA_MONGO__URI=mongodb://user:pass@host:27017
ZARA_MONGO__DATABASE=mydb
# === Redis ===
ZARA_REDIS__ADDR=host:6379
ZARA_REDIS__PASSWORD=secret
# === HTTP API ===
ZARA_API__URL=https://api.example.com
ZARA_API__AUTH=bearer # bearer, basic, header, or none
ZARA_API__AUTH_ENV=MY_TOKEN # env var name holding the actual token
# === AI Provider ===
ZARA_AI__BASE_URL=https://api.openai.com/v1
ZARA_AI__API_KEY_ENV=OPENAI_KEY1,OPENAI_KEY2 # comma = round-robin pool
ZARA_AI__MODELS=gpt-4o,gpt-4o-mini
# === 可选 ===
ZARA_OBSERVE_URL=http://localhost:5080 # OpenObserve telemetry
ZARA_AUDIT_LOG=/var/log/zara-audit.log # blocked operations log
```
## 安全性
旨在符合 [OWASP AISVS 1.0](https://github.com/OWASP/AISVS)：
- **拦截危险的 SQL**：DROP、TRUNCATE、ALTER、不带 WHERE 的 DELETE
- **拦截危险的 Redis**：FLUSHALL、SHUTDOWN、EVAL、CONFIG
- **拦截 MongoDB 注入**：$where、$expr、$function
- **SSRF 保护**：阻止对私有 IP（10.x、192.168.x）和云元数据（169.254.169.254）的请求
- **速率限制**：最多 20 个并发工具调用
- **输入大小限制**：1MB 文本，10MB HTTP body
- **超时**：所有外部调用限时 30 秒
- **Panic 恢复**：服务器绝不会因错误的工具调用而崩溃
- **审计日志**：记录每一个被拦截的操作及其时间戳和原因
## 开发
```
make build # Build binary (version injected from git)
make test # Run all tests with race detection
make lint # go vet + staticcheck
make smoke # Quick end-to-end test
make build-linux # Cross-compile for Linux
make build-darwin # Cross-compile for macOS ARM
```
无需重启即可热重载配置：
```
kill -HUP $(pgrep zara-privacy-mcp)
```
## 工作原理（深入底层）
1. **agent 调用工具**（例如 `db_query`），通过 MCP stdio
2. **安全门检查**——这是危险操作吗？如果是，则拦截。
3. **执行**——针对真实服务运行查询/请求
4. **掩码结果**——扫描每一个字符串值以查找机密信息（24 种模式）和 PII（18 种模式），并替换为掩码版本
5. **返回给 agent**——干净、安全的响应
对于 AI 调用（`ai_chat`）：
1. **脱敏消息**——在发送前将机密信息/PII 替换为 `[PLACEHOLDER]`
2. **发送给提供商**——提供商永远看不到原始值
3. **还原响应**——在返回给 agent 的响应中恢复原始内容
## 支持
如果这个项目对您有帮助：
[](https://sociabuzz.com/aldok10)
## License
MIT。
标签：AI代理, Go语言, MCP网关, 多线程, 搜索引擎查询, 数据库代理, 数据脱敏, 日志审计, 程序破解, 网络安全, 隐私保护