TharVid/dvarapala

# Dvarapala [](https://github.com/TharVid/dvarapala/actions/workflows/ci.yml) [](https://github.com/TharVid/dvarapala/releases/latest) [](LICENSE) [](https://github.com/TharVid/dvarapala/pkgs/container/dvarapala) Dvarapala 位于 LLM 客户端（Claude Code, Claude Desktop, Cursor, Cline, 自定义 agent）与任何**第三方 MCP server** 之间。它会解析双向的每一条 JSON-RPC 消息，执行 YAML 策略，并**拒绝/脱敏/记录**任何违反规则的操作——且**无需对底层 MCP server 进行任何改动**。 它**并未**重新发明检测机制。相反，它将久经考验的开源软件——gitleaks、Microsoft Presidio、ProtectAI llm-guard、garak——组合成一个感知 MCP 的执行层。 ## 它能阻止什么 - **工具投毒（Tool poisoning）** — 隐藏在工具描述中的恶意指令 - **工具篡改/ rug-pull** — 工具定义在不同会话之间被悄悄篡改（跨重启指纹校验） - 通过工具输出进行的**间接 prompt 注入** - **机密信息泄露** — AWS 密钥、GitHub token、私钥、JWT 等（基于 gitleaks，150+ 条规则） - 通过工具输出进行的 **PII / PHI / PCI 窃取**（基于 Presidio sidecar） - **破坏性操作** — `rm -rf`、`DROP TABLE`、`dd if=…of=/dev/sda` 等 - **过度自主行为（Excessive agency）** — 将工具串联成数据窃取路径 ## 安装 ### macOS / Linux ``` brew tap tharvid/dvarapala brew install dvarapala ``` ### Windows ``` scoop bucket add dvarapala https://github.com/TharVid/scoop-dvarapala scoop install dvarapala ``` ### Docker ``` docker pull ghcr.io/tharvid/dvarapala:latest ``` ### Go ``` go install github.com/tharvid/dvarapala/cmd/dvarapala@latest ``` ### Linux 软件包 从 [最新发布版本](https://github.com/TharVid/dvarapala/releases/latest) 中获取对应的文件，并使用 `dpkg -i` / `rpm -i` / `apk add --allow-untrusted` 进行安装。真正的 `apt install dvarapala` 将在 v0.1.2 版本中提供。 ## 5 分钟快速上手 ``` # 1. Scaffold 一个默认策略 dvarapala init # 2. Health-check dvarapala doctor # 3. 一键 Wrap Claude Code 配置中的所有现有 MCP server dvarapala install --client claude-code --wrap-all # 4. 重启 Claude Code，然后在另一个终端中查看流量 dvarapala logs -f ``` `--wrap-all` 会读取 `~/.claude.json`，找到所有的 MCP server，并执行以下操作： - 对于 **stdio MCP**（基于 npx 等）：重写入口，使其通过带有您策略的 `dvarapala wrap` 进行路由。 - 对于 **HTTP/SSE MCP**：在后台生成一个分离的 `dvarapala proxy` 守护进程（对您不可见），将客户端 URL 指向本地代理。使用 `dvarapala daemon list | stop NAME | stop-all` 进行管理。 已经被包装或代理的条目将被保留——该命令是幂等的。每当您使用 `claude mcp add` 添加新服务器时，都可以再次运行它。 相同的标志也适用于其他客户端： ``` dvarapala install --client claude-desktop --wrap-all dvarapala install --client cursor --wrap-all dvarapala install --client cline --wrap-all ``` 您将看到 Claude Code 发送到文件系统 MCP server 的每一条 JSON-RPC 消息都流经网关，并根据策略执行 `action=allow` / `deny` / `redact`。尝试让 Claude 读取一个包含伪造 AWS 密钥的文件——网关会在 LLM 看到它们之前将其脱敏。 如需更深入的演练，请参阅 **[docs/getting-started.md](docs/getting-started.md)** 以及 **[docs/deployment/](docs/deployment/)** 中针对各客户端的指南。 ## 三种部署形态 | 模式 | 使用场景 | 命令 | |---|---|---| | **Wrap** | 每个进程对应一个 stdio MCP —— 直接嵌入 Claude Code/Desktop/Cursor/Cline 配置中 | `dvarapala wrap -- npx ... server-filesystem` | | **Proxy** | 一个托管的 HTTP MCP（Atlassian, Sentry, 内部 microservice） | `dvarapala proxy --upstream URL` | | **Hub** | 一个 Dvarapala 前置多个 MCP（企业级形态） | `dvarapala hub --config hub.yaml` | 这三种模式共享相同的引擎、检测器、审计日志和策略 YAML。详见 **[docs/architecture.md](docs/architecture.md)**。 ## 作用范围 **Dvarapala 保护的是第三方 MCP server** —— 社区 npm 包、自定义企业 MCP、托管 MCP 服务。这些是充满风险的攻击面。 **Dvarapala 不会替代 LLM 客户端自身的权限系统** —— Claude Code 内置的 `Read`/`Write`/`Bash`/`Edit` 不是 MCP，它们受 [Anthropic 的权限模型](https://docs.claude.com/en/docs/claude-code/iam) 管辖。请同时使用两者：客户端权限用于内置工具，Dvarapala 用于第三方 MCP。这两层都是必不可少的。 ``` ┌─────────────────────────────────────────────────┐ │ LLM Client (Claude Code, Cursor, …) │ │ ┌──────────────────┐ ┌────────────────────────┐│ │ │ Built-in tools │ │ Third-party MCPs ││ │ │ Read, Write, … │ │ github, postgres, … ││ │ └────────┬─────────┘ └─────────┬──────────────┘│ │ │ │ │ │ Anthropic perms ┌──────▼──────┐ │ │ │ Dvarapala │ ← us │ │ └──────┬──────┘ │ └────────────────────────────────┬┴─────────────────┘ ▼ Real MCP servers ``` ## 检测器 对明确定义类别的检测被委托给最优秀的开源软件 —— Dvarapala 只是将它们粘合在一起，而不是维护自己的正则表达式集。特定于 MCP 的检测器才是其真正的创新贡献。 | 检测器 | 来源 | 状态 | 检测内容 | |---|---|---|---| | **gitleaks** | 嵌入式 Go 库 | 始终开启 | 机密信息（AWS, GitHub, GCP, 私钥, JWT 等） | | **tool-poisoning** | Dvarapala 原生 | 始终开启 | 工具描述中的 prompt 注入模式 | | **tool-mutation** | Dvarapala 原生（持久化 SHA-256 存储） | 始终开启 | rug-pull —— 跨会话的工具定义篡改 | | **destructive-actions** | Dvarapala 原生 | 始终开启 | `rm -rf`、`DROP TABLE`、`dd if=…of=/dev/sd*` | | **Presidio** | Microsoft, sidecar | 通过 `DVARAPALA_PRESIDIO_URL` 按需开启 | PII / PHI / PCI（50+ 识别器, HIPAA, GDPR） | | **llm-guard** | ProtectAI, sidecar | 通过 `DVARAPALA_LLMGUARD_URL` 按需开启 | 间接 prompt 注入（ML 模型 + 启发式算法） | 有关规则包请参阅 **[docs/built-in-rules.md](docs/built-in-rules.md)**，有关策略 schema 请参阅 **[docs/policy-language.md](docs/policy-language.md)**。 ## 命令 | 命令 | 用途 | |---|---| | `dvarapala wrap -- CMD` | 使用安全策略包装一个 MCP stdio 服务器 | | `dvarapala proxy --upstream URL` | 作为托管的 HTTP/SSE MCP 的代理运行 | | `dvarapala hub --config FILE` | 作为多 MCP 聚合器运行 | | `dvarapala init` | 生成 `~/.dvarapala/policy.yaml` 脚手架 | | `dvarapala lint POLICY` | 校验策略文件 | | `dvarapala test --case FILE` | 根据策略运行攻击样本测试 | | `dvarapala scan --command CMD` | 对任何 MCP server 进行一次性安全审计 | | `dvarapala install --client CLIENT --server NAME --command CMD` | 自动编辑 MCP 客户端配置 | | `dvarapala doctor` | 诊断安装、策略、sidecar 和配置 | | `dvarapala daemon list \| stop NAME \| stop-all \| remove NAME \| clean` | 管理由 `--wrap-all` 生成的后台 HTTP 代理守护进程 | | `dvarapala logs [-f]` | 美化输出或持续追踪审计日志 | | `dvarapala ui` | 提供审计日志的本地 Web 视图（实时，只读） | | `dvarapala version` | 打印版本信息 | 完整的标志参考：**[docs/cli-reference.md](docs/cli-reference.md)**。 ## 采用的技术 | 关注点 | 库 | |---|---| | 机密信息 | [gitleaks](https://github.com/gitleaks/gitleaks) | | PII / PHI / PCI | [Microsoft Presidio](https://github.com/microsoft/presidio) | | Prompt 注入 | [ProtectAI llm-guard](https://github.com/protectai/llm-guard) + [Meta Prompt-Guard](https://huggingface.co/meta-llama/Prompt-Guard-86M) | | MCP 协议 | [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) | | 红队样本 | [garak](https://github.com/NVIDIA/garak), [PyRIT](https://github.com/Azure/PyRIT) | | 发布流水线 | [GoReleaser](https://goreleaser.com) | ## 状态 - ✅ **v0.1.1** — 第 1-6 阶段功能的生产级检测 - ✅ **5/5 攻击样本测试端到端通过** (rm -rf, 间接 prompt 注入, 机密信息窃取, 工具投毒, 工具 rug-pull) - ✅ **CI 绿灯**（涵盖 linux/macOS/windows） - ✅ **三种安装途径已上线**：brew, scoop, docker - 🚧 v0.1.2：APT 仓库（真正的 `apt install dvarapala`） - 🚧 第 7 阶段：速率限制、人工审批流程、OpenTelemetry、Web UI 完整路线图请参见 [TODO.md](TODO.md)。 ## 文档 | 文档 | 内容 | |---|---| | **[入门指南](docs/getting-started.md)** | 首次运行演练 | | **[架构](docs/architecture.md)** | 引擎、检测器、传输层如何协同工作 | | **[CLI 参考](docs/cli-reference.md)** | 每一个命令和标志 | | **[策略语言](docs/policy-language.md)** | YAML schema、匹配条件、动作 | | **[内置规则包](docs/built-in-rules.md)** | 每个规则包的作用及原因 | | **[部署：Claude Code](docs/deployment/claude-code.md)** | 主要用例 | | **[部署：Claude Desktop](docs/deployment/claude-desktop.md)** | macOS / Windows 应用 | | **[部署：Cursor](docs/deployment/cursor.md)** | Cursor IDE | | **[部署：Cline](docs/deployment/cline.md)** | VSCode 扩展 | | **[部署：Docker](docs/deployment/docker.md)** | 容器 + sidecar (Presidio, llm-guard) | | **[部署：Kubernetes](docs/deployment/kubernetes.md)** | Sidecar + Hub 清单文件 | ## 许可证 [MIT](LICENSE). 由 [TharVid](https://tharvid.in) 构建。

标签：AI网关, API安全, API密钥检测, CISA项目, DLL 劫持, Docker, Dvarapala, EVTX分析, Go语言, IP 地址批量处理, JSON-RPC代理, JSON输出, Lerna, MCP, MCP服务器, PII保护, 中间件, 大语言模型, 安全代理, 安全合规, 安全防御评估, 审计日志, 密钥泄露, 工具投毒检测, 提示词注入防护, 敏感数据脱敏, 数据泄露防护, 日志审计, 秘密泄露检测, 程序破解, 策略执行, 网关防护, 网络代理, 网络安全, 网络探测, 请求响应过滤, 请求拦截, 输入验证, 防篡改, 隐私保护, 零信任架构