vaultmcp/vault

# Vault — MCP Prompt 注入防火墙 Vault 是一个用于 MCP 的生产级 prompt 注入防火墙。它会在你的 agent 读取每个工具响应之前对其进行拦截，并通过三层检测进行扫描。 ## 要求 Vault 在生产环境中的 Layer 3 需要 LLM。有三个选项： - **Anthropic** (`claude-haiku-4-5-20251001`，推荐) — 设置 `ANTHROPIC_API_KEY` - **OpenAI-compatible** (`gpt-4o-mini`，或通过 vLLM/llama.cpp 自托管) — 设置 `OPENAI_API_KEY` - **Ollama** (本地，气隙隔离) — 设置 `OLLAMA_HOST=http://localhost:11434` 如果没有上述任何配置，Vault 将以离线模式运行（仅包含 L1+L2）。离线模式存在已知的局限性 — 详见 [局限性 §11](packages/LIMITATIONS.md)。 ### 使用 Ollama 进行离线运行 Ollama 允许你在本地运行 L3，无需依赖云端 — 这对于气隙隔离环境、无 API key 开发以及对成本敏感的 pipeline 非常有用。 ``` # 安装 Ollama 并拉取模型（一次性） curl -fsSL https://ollama.ai/install.sh | sh ollama pull llama3.2:3b # 使用 Ollama 作为 L3 后端运行 Vault export OLLAMA_HOST=http://localhost:11434 npx @aimcpvault/mcp-proxy -- npx -y @modelcontextprotocol/server-filesystem /data ``` 要使用不同的模型或远程 Ollama 实例： ``` export VAULT_LAYER3_PROVIDER=ollama export VAULT_LAYER3_MODEL=mistral:7b export VAULT_LAYER3_BASE_URL=http://gpu-box:11434 ``` **注意事项：** - 本 README 中测量出的 TPR 数据是基于 Anthropic Haiku 的。本地 3B 模型差异很大；在生产环境中依赖它们之前，请先运行评估工具。根据经验，在冒烟测试中，`llama3.2:3b` 漏掉了隐蔽的 role-hijack 和 multi-turn-setup 攻击，而 Haiku 则能捕捉到这些攻击。 - 可达性是在首次扫描时验证的，而不是在启动时。如果 Ollama 未运行，Vault 会在每次请求时记录 `vault: layer-3 failed (...)` 并回退到 L1+L2。 - **延迟：** 默认的 L3 超时时间为 15 秒，旨在吸收本地 3B 模型在 CPU 上的冷启动延迟。如果你在较慢的硬件或更大的模型上运行，请通过 `VAULT_LAYER3_TIMEOUT_MS=30000` 进一步增加超时时间。Ollama 加载模型后的首次扫描时间可能比稳定状态长得多 — 后续调用通常在 1–2 秒内完成。 - **安全性：** 默认 URL 为 `http://localhost:11434`。如果你设置了 `VAULT_LAYER3_BASE_URL=http://0.0.0.0:11434` 或指向远程主机，工具响应内容（可能包含敏感数据）将通过网络发送到该主机。请仅指向受信任的本地网络 Ollama 实例。 ## 链上信誉检查器 `vault inspect` 会读取你的 Claude Desktop MCP 配置，并报告 Vault 为你配置的每个服务器积累的链上信誉。 ``` npx @aimcpvault/mcp-proxy inspect # vault inspect（3 个 MCP server） # 配置： /Users/you/Library/Application Support/Claude/claude_desktop_config.json # 网络： Sepolia (testnet) # 合约： 0x3A977E4D8BA43367cc41BB4695feFF4615fec189 # # TRUSTED filesystem [stdio:npx:@modelcontextprotocol/server-filesystem] # score=0.980 scans=412 blocks=2 maliciousRate=0.5% # NEW git [stdio:uvx:mcp-server-git] # score=1.000 scans=0 blocks=0 maliciousRate=0.0% # UNTRUSTED sketchy [stdio:npx:some-untrusted-pkg] # score=0.400 scans=83 blocks=14 maliciousRate=16.9% ``` **信任阈值（透明，无魔法数字）：** - `TRUSTED` score ≥ 0.95 且 totalScans ≥ 100 - `UNTRUSTED` maliciousRate ≥ 0.10 - `CAUTION` totalScans ≥ 10 且 maliciousRate ≥ 0.01 - `NEW` totalScans < 10 **Flags：** - `--config ` 覆盖 Claude Desktop 配置路径 - `--rpc ` 和 `--contract ` 指向不同的网络/部署 - `--json` 每个服务器输出一条 JSON 记录（适用于 CI / 脚本） - `--strict` 如果有任何服务器为 UNTRUSTED 则退出码为 1 — 在 CI 检查中很有用 目前的信誉合约位于 **Base Sepolia (testnet)**。主网部署待定；在主网上线之前，检查器将继续默认使用 Sepolia，并在每次运行时打印黄色警告。 ## 本地扫描历史记录（主动启用） Vault 可以将每次扫描持久化到本地 SQLite 数据库 (`~/.vault/scans.db`) 中，以便你查看被拦截的内容、按工具/服务器/结论进行搜索，并查看本地仪表板。 **默认关闭。** 使用 `VAULT_PERSIST=1` 启用： ``` VAULT_PERSIST=1 npx @aimcpvault/mcp-proxy -- npx -y @modelcontextprotocol/server-filesystem /data # vault: 正在将扫描历史记录持久化到 /Users/you/.vault/scans.db（设置 VAULT_PERSIST=0 以禁用） ``` **从 CLI 查询：** ``` npx @aimcpvault/mcp-proxy history # last 50 npx @aimcpvault/mcp-proxy history --verdict malicious # only blocks npx @aimcpvault/mcp-proxy history --since 7d --json # last week, JSON npx @aimcpvault/mcp-proxy history --server stdio:npx:@modelcontextprotocol/server-filesystem ``` **浏览仪表板：** ``` npx @aimcpvault/mcp-proxy dashboard # vault dashboard: http://127.0.0.1:9876 ``` 带有判定结果卡片、每日堆叠柱状图（30 天）、热门工具以及最近扫描表的深色主题单页仪表板。每 5 秒自动刷新一次（可通过 `--refresh ` 配置）。 **隐私保证：** - 默认关闭 — 除非设置 `VAULT_PERSIST=1`，否则不会写入任何数据。 - 所有数据都保留在本地。仪表板和历史记录读取器都直接从 `~/.vault/scans.db` 提供服务；不会上传任何内容。 - 内容预览在存储前会经过 regex 脱敏处理（API keys、GitHub/AWS tokens、JWTs、电子邮件、类似 SSN 的字符串、类似信用卡的数字、通用的 `password:` / `token:` header）。这是一个尽力而为的过滤器；如果你需要更强的保证，请保持关闭持久化。 - 30 天滚动保留期。使用 `VAULT_RETENTION_DAYS=` 覆盖（设置为 `0` 则禁用清理）。 - 使用 `VAULT_PERSIST_PATH=/path/to/scans.db` 覆盖数据库路径。 ``` # 封装任意 MCP server — 无需更改您的 agent 配置 npx @aimcpvault/mcp-proxy -- npx -y @modelcontextprotocol/server-filesystem /path/to/data ``` ## 测量性能 以下所有数据均可从提交在此 repo 中的测试工具重现。每项数据都附有测量时所基于的 commit 和数据集作为脚注。 | 指标 | 值 | 来源 | |---|---|---| | TPR — v2 留出集（启用 L3，80 次攻击） | **100%** (80 / 80) · 95% 置信区间下限 95.5%+ | [^holdout-l3] | | TPR — 仅 L1+L2，无 API key | 实质性降低（生产环境中必需 L3） | [^holdout-degraded] | | 误报率（良性内容被标记） | **0.0%** (0 / 100) | [^holdout-l3] | | L1 延迟 (p50 / p99) | 0.03 ms / 0.53 ms | [^holdout-l3] | | L2 延迟 (p50 / p99) | 11.05 ms / 69.75 ms | [^holdout-l3] | | L3 延迟 (p50 / p99) | 1541 ms / 3499 ms | [^holdout-l3] | | 持续吞吐量（单个 proxy） | 100 req/s，30,000 次请求中 0 错误 | [^load] | | 稳态内存 (RSS) | 预热后 135–180 MB，未观察到内存泄漏 | [^load] | | 500 KB 响应扫描时间 | ~25 秒（受限于 embedder，见局限性 §14） | [^edge] | [^holdout-l3]: `packages/eval/results/eval-clean-baseline-v2-L3-enabled-2026-05-21.md` — 在检测代码被冻结在 commit `8d230e4` 后，针对构建的 v2 留出集进行的一次性评估。数据集：`packages/eval/datasets/holdout-v2-novel/`（50 次攻击）+ `packages/eval/datasets/holdout-v2-paraphrase/`（30 次攻击）+ `packages/eval/datasets/benign-v2/`（100 条记录）。已启用 L3（Anthropic Haiku 4.5）。在构建留出集和运行评估之间没有进行调整。 [^holdout-degraded]: 如果没有 `ANTHROPIC_API_KEY`，Vault 仅运行 L1+L2。在 v2 novel 留出集（旨在位于 L2 检测范围之外的攻击）上，TPR 接近 0%；在 paraphrase 攻击上约为 7%。L3 是针对分布外攻击的检测骨干。离线模式限制请参阅 `packages/LIMITATIONS.md` §11。 [^load]: `packages/eval/load/report.md` — 100 req/s × 300 秒 × 单个 stdio proxy 实例 × ~200 字节的 stub-MCP 响应，仅限 L1+L2。超过 100 req/s 后的断崖式下降尚未测量。 [^edge]: `packages/proxy/test/edge-cases.test.ts` 场景 4。延迟受到 L2 embedder 迭代约 140 个流式数据块的限制；L1 在任何大小下都保持在亚毫秒级。见局限性 §14。 ## Vault 能捕获的内容 启用 L3 后（已设置 Anthropic API key），Vault 在我们包含 80 条记录的公开结构泛化评估中捕获了 100% 的攻击，而在 100 份良性文档中的误报率为 0%。检测方法和数据集是公开的 — 详见 `/packages/eval/`。 按类别划分（80 次攻击，holdout-v2 结构泛化评估，2026-05-21）： | 攻击类别 | 捕获 / 总计 | TPR | |---|---|---| | exfiltration | 60 / 60 | 100.0% | | instruction_override | 13 / 13 | 100.0% | | multi_turn_setup | 6 / 6 | 100.0% | | encoded_payload | 1 / 1 | 100.0% | 数据来自 `packages/eval/results/eval-clean-baseline-v2-L3-enabled-2026-05-21.md`，启用了 L3（Anthropic Haiku 4.5）。数据集：`packages/eval/datasets/holdout-v2-novel/`（50 次攻击）和 `packages/eval/datasets/holdout-v2-paraphrase/`（30 次攻击），经验证与检测语料库不重叠。延迟和吞吐量背景请参见[测量性能](#measured-performance)。 ## Vault 无法捕获的内容 - **用户发起的越狱** — 根据设计，这不在范围内。Vault 位于 agent 和上游 MCP 服务器之间，而不是位于用户和 agent 之间。用户直接键入的越狱是模型提供商的责任，而不是 proxy 的责任。 - **真正新颖的注入模式** — 远离所有已知示例进行改写的攻击（L2 余弦距离 > 0.50 且未设置 L3 key）会逃避检测。该语料库涵盖了 2022–2024 年发布的攻击文献；截止日期之后的新技术可能未被包含在内。请参阅 [`packages/LIMITATIONS.md`](packages/LIMITATIONS.md) §3。 - **无 L3 的协议编码数据** — 返回 Pub/Sub 消息、SQS payloads、二进制 blob 或加密内容的 MCP 工具在禁用 L3 时会产生误报（该流量类别的误报率约为 40%）。见局限性 §11。 - **跨会话拆分的多轮攻击** — Vault 独立扫描每个 MCP 响应。在会话 A 中建立、在会话 B 中激活的潜伏指令不在 Vault 的检测窗口内。见局限性 §10。 - **图像/音频嵌入的指令** — Vault 仅支持文本。工具响应中的二进制内容（图像、音频文件、PDF）未扫描即转发给 agent。如果你的 MCP 服务器返回图像数据或视觉模型输入，Vault 无法对隐藏在该内容中的指令提供保护。 完整的差距分类法：[`packages/LIMITATIONS.md`](packages/LIMITATIONS.md) — 15 个章节，涵盖多语言、语义、结构、规范化、自引用、协议编码和规模差距。[`packages/SECURITY_MODEL.md`](packages/SECURITY_MODEL.md) 将每个差距映射到其留下的威胁。 ## 离线模式（无 API key） 当 `ANTHROPIC_API_KEY` 和 `OPENAI_API_KEY` 均未设置时，Vault 以离线模式运行： - Layer 0 (decoder) 和 Layer 1 (heuristics) 正常运行 - Layer 2 (embedding similarity) 正常运行 - Layer 3 (LLM judge) 被禁用 **适用于：** - 开发环境和本地测试 - agent 未运行生产流量的 CI/CD pipeline - 气隙隔离或离线部署 **不适用于：** - 返回 Pub/Sub、SQS 或 webhook payloads 的生产级 MCP 服务器 - 返回二进制内容（图像、加密 blob）的工具 - 任何误报率高于 5% 的不可接受部署 具体的误报测量数据和理由请参见[局限性 §11](packages/LIMITATIONS.md)。 ## 成本透明度 Layer 3（LLM judge）针对落入 L2 不确定区域的响应调用 Anthropic Haiku 4.5。估算： | 场景 | L3 调用率 | 预估每次请求成本 | |---|---|---| | 评估留出集（对抗性数据集） | ~91% | ~$0.0005 | | 真实 MCP 流量（预期） | ~20–% | ~$0.0001–0.0002 | | 100 个良性请求/小时（稳定状态） | 20–40% | 总计 ~$0.002–0.004/hr | - **不确定区域请求约 ~$0.0005**（Haiku 4.5 输入 + 当前定价下的小量输出） - **生产环境中 100 req/hr 约为 ~$0.04/hr**（真实流量下 20–40% 的 L3 调用率） - **无 API key 时为 $0** — 仅包含 L1+L2，在新型分布外攻击中 TPR 降至接近 0%，协议编码流量上的误报率升至 ~40%。请参阅上方的[离线模式](#offline-mode-no-api-key)。除非明确传入 `--allow-degraded`，否则评估工具将拒绝在此模式下运行。 我们评估中较高的 L3 调用率 (91%) 反映了对抗性数据集 — 几乎每个条目都是根据设计落入 L2 不确定区域的攻击。真实的 MCP 流量（大部分是干净的正常工具输出）具有低得多的 L3 调用率。 在运行之前设置 `ANTHROPIC_API_KEY`。如果没有它，Vault 在启动时会发出 `WARNING: Layer 3 unavailable — degraded mode` 消息，并回退到仅使用 L1+L2。 ## 为什么需要 每个 MCP 工具响应都是对你的 agent 上下文窗口的直接写入。恶意文件、受损的 API 或被投毒的搜索结果可能会在任务执行期间重定向你的 agent — 窃取敏感信息、覆盖文件或转而使用其他工具。MCP 没有针对此类攻击的传输级保护。Vault 增加了一层检测过程；该过程是否适合你的威胁模型，取决于 [`packages/LIMITATIONS.md`](packages/LIMITATIONS.md) 中记录的差距。 ## 工作原理 Vault 位于你的 agent host 和上游 MCP 服务器之间，拦截每个 `tools/call` 响应，并通过分层的检测 pipeline 运行： ``` Agent ──► Vault Proxy ──► MCP Server │ ▼ ┌─────────────────────────────────────────────┐ │ L1 Regex (<1ms) heuristics + unicode │ │ L2 Embeddings (~8ms) bge-small cosine sim │ │ L3 LLM judge (~1s) haiku-4.5 disambiguation│ └─────────────────────────────────────────────┘ │ ▼ clean → forward malicious → block/warn ``` **Layer 1 — Heuristics** (p50 0.02 ms, p99 0.53 ms[^holdout-l3])：针对英文指令覆盖、unicode 标签走私 (U+E0000–U+E007F)、bidi 控制字符 (U+202A–U+202E, U+2066–U+2069)、零宽字符密度、HTML 注释、长 HTML 实体序列和 Markdown 链接锚点的 Regex 模式。高可信度匹配会短路直接返回 — 无需 L2/L3 成本。L1 仅支持英文；见局限性 §1。 **Layer 2 — Embeddings** (p50 8.29 ms, p99 53.06 ms[^holdout-l3])：使用 `bge-small-en-v1.5`（完全在设备上运行，无网络调用，~30 MB WASM）针对精心策划的 31 种攻击类别的语料库进行余弦相似度比对。距离在 0.35 以内的匹配会被拦截；边缘情况升级至 L3。该语料库是公开的；改写后距离超过 0.35 的对手可逃避 L2 — 该类别交由 L3 处理。 **Layer 3 — LLM Judge**（调用时约 1 秒）：Claude Haiku 4.5（或使用 OpenAI key 的 GPT-4o-mini）处理模棱两可的情况。仅在 L2 不确定时运行 — 通常小于 5% 的请求。需要 `ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY`。**如果没有 key，L3 将被禁用，TPR 会降至上述报告的 L1+L2 水平。** ### Capability 防火墙 除了注入检测，Vault 还会追踪污点：进入 agent 上下文的工具响应会被标记，如果这些 token 随后出现在对敏感工具（网络请求、文件写入、shell 执行）的调用中，该调用将被拦截限制。 ``` VAULT_CAPABILITY=1 # enable taint tracking + gate VAULT_CAPABILITY_MODE=block # or: warn ``` ### Manifest 校验 Vault 会在首次连接时对每个 MCP 服务器的工具 manifest 进行指纹记录，并对随后的任何漂移（新工具、更改的 schema、版本更新）发出警报。这是一种供应链保护，防止受损的服务器静默添加 `delete_all` 工具。 ``` VAULT_MANIFEST_CHECK=on # default — warn on drift VAULT_MANIFEST_CHECK=strict # treat drift as error ``` ### 可选：链上证明（主动启用） 当操作员选择启用时（`VAULT_ATTEST=1` + 一个有资金的 hot wallet），扫描结论可以通过 Base 上的 [EAS](https://attest.sh) 在链上进行证明。然后，每个 MCP 服务器都会积累一个公开的、仅限追加的信誉评分，任何 agent 都可以在连接前进行查询。默认关闭 — 使用 proxy 不依赖任何链。 ## 安装 ``` # npm / npx（无需安装） npx @aimcpvault/mcp-proxy -- # 或全局安装 npm install -g @aimcpvault/mcp-proxy mcp-proxy -- npx -y @modelcontextprotocol/server-filesystem /data ``` ### Claude Code / Claude Desktop 集成 最快的方法是使用 `vault init` — 它会自动检测你现有的 MCP 配置，并用 proxy 包装每个服务器： ``` npx @aimcpvault/mcp-proxy && vault-init ``` `vault init` 在写入前会显示 diff 预览，将原始配置备份到 `.vault-backup`，并且是幂等的（重新运行会跳过已包装的服务器）。还原命令：`vault-init unwrap`。 或者手动包装： ``` // ~/.claude/mcp_settings.json (or claude_desktop_config.json) { "mcpServers": { "filesystem": { "command": "npx", "args": [ "@aimcpvault/mcp-proxy", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path" ] } } } ``` ### 检查服务器的信誉 `vault-check` 二进制文件打包在 proxy 内部 — 无需单独安装： ``` # 如果您已安装 @aimcpvault/mcp-proxy，则表示已安装 npx --package=@aimcpvault/mcp-proxy@next vault-check stdio:npx:@modelcontextprotocol/server-filesystem npx --package=@aimcpvault/mcp-proxy@next vault-check --all # scores every server in your MCP config(s) npx --package=@aimcpvault/mcp-proxy@next vault-check --json | jq . ``` 一旦我们在 GitHub 上发布签名版本，独立的 `vault-check` 二进制文件（Homebrew tap、curl 管道安装脚本）计划在 **v0.3** 版本推出。 信誉来自 Base 上的 EAS 证明，由扫描相同服务器的每个 Vault 部署汇总而来。分数范围为 0–1000（越高 = 越安全）。主动启用的证明路径已在上方“可选：链上证明”中记录；连续公开数据流将随 v0.3 推出。 ### 将信誉徽章添加到你的 MCP 服务器 README 中 如果你维护着一个 MCP 服务器，可以将其实时 Vault 信誉分数作为徽章嵌入 — 与 shields.io 的样式相同。随着新的证明在链上落定，该徽章会自动更新。 ```  ``` 将 `your-server-name` 替换为 Vault 用于你的服务器的标识符 — 对于通过 npm 启动的服务器，通常是包名（例如 `@modelcontextprotocol/server-filesystem`），或者是 HTTP/SSE 服务器的完整 URL。尚无证明的服务器将显示为中性的“未排名”徽章。 ### 公共信誉 API 由相同的链上数据支持、开启 CORS 且无需身份验证的读取 endpoint： | Endpoint | 返回 | |---|---| | `GET https://vaultmcp.io/api/score/:server` | 单个服务器的分数、扫描、拦截、basescan 链接 | | `GET https://vaultmcp.io/api/leaderboard?n=10` | 按扫描次数排名的前 N 个服务器 | | `GET https://vaultmcp.io/api/threats/recent?n=20` | 最近的 ThreatRecord 证明 | | `GET https://vaultmcp.io/badge/:server.svg` | SVG 信誉徽章 | 所有 endpoint 都接受可选的 `?network=base|base-sepolia` 查询参数。已设置缓存 header；预期有 60 秒的边缘缓存。 ### HTTP/SSE 模式 ``` # 通过 HTTP 代理远程 MCP server npx @aimcpvault/mcp-proxy --transport http \ --upstream https://mcp.example.com/v1 \ --port 8800 ``` ## 配置 所有配置均通过环境变量进行： ``` # 检测 VAULT_MODE=block # block (default) | warn | log VAULT_LAYER2_THRESHOLD=0.35 # cosine distance cutoff for L2 VAULT_LAYER3_PROVIDER=anthropic # anthropic | openai | custom VAULT_LAYER3_MODEL=claude-haiku-4-5-20251001 # model override VAULT_LAYER3_TIMEOUT_MS=5000 # judge call timeout # Keys（BYO — Vault 绝不存储或转发它们） ANTHROPIC_API_KEY=sk-ant-... OPENAI_API_KEY=sk-... # Capability firewall VAULT_CAPABILITY=1 VAULT_CAPABILITY_MODE=block VAULT_TAINT_MIN_OVERLAP=32 VAULT_SENSITIVE_TOOL_PATTERNS=^my_custom_sensitive_tool # Manifest verification VAULT_MANIFEST_CHECK=on # on | off | strict # Audit log VAULT_AUDIT_LOG=/var/log/vault-mcp.jsonl # On-chain attestation（可选，默认关闭 — 完整的托管 feed 将在 v0.3 中推出） VAULT_ATTEST=1 VAULT_ATTESTER_PRIVATE_KEY=0x... # fund with ~0.05 ETH on Base VAULT_EAS_ADDRESS=0x4200000000000000000000000000000000000021 VAULT_SCAN_RECEIPT_SCHEMA=0x... # register via packages/contracts VAULT_THREAT_RECORD_SCHEMA=0x... # Telemetry（设置 URL 时默认开启） VAULT_TELEMETRY=1 VAULT_TELEMETRY_URL=https://your-collector.example.com/ingest VAULT_TELEMETRY=0 # opt out ``` ## 审计日志 每个结论都会写入一个仅限追加的 JSONL 文件中： ``` VAULT_AUDIT_LOG=/var/log/vault-mcp.jsonl # 使用内置 CLI 查看 npx vault-audit /var/log/vault-mcp.jsonl npx vault-audit --type detection --verdict malicious npx vault-audit --tool read_file --since 1h npx vault-audit --raw | jq . ``` ## 检测模式 | 模式 | 行为 | |---------|-------------------------------------------------------------| | `block` | 恶意内容被替换为错误响应（默认） | | `warn` | 返回原始内容，并在前面加上警告 | | `log` | 内容通过；检测结果仅记录在审计日志中 | ## 隐私 Vault 绝不会将原始内容发送到任何地方。遥测 pipeline 仅传输内容和参数的 SHA-256 哈希值、结论标签、延迟测量值和模式名称。原始文本永远不会离开 proxy 进程。 完整的数据清单请参见 [PRIVACY.md](packages/proxy/PRIVACY.md)。 要完全禁用遥测：`VAULT_TELEMETRY=0`。 ## 项目结构 ``` packages/ proxy/ # @aimcpvault/mcp-proxy — the core proxy (this is what you install) corpus/ # @vaultmcp/corpus — curated attack/clean embedding corpus contracts/ # @vaultmcp/contracts — VaultReputation.sol + EAS schema registration collector/ # @vaultmcp/collector — telemetry ingest + aggregation server eval/ # @vaultmcp/eval — detection benchmarks vs. competitors demo-site/ # Next.js demo + live threat feed ``` ## 评估方法 — 如何重现 上方的[测量性能](#measured-performance)数据来自提交在此 repo 中的测试工具和数据集。重现步骤： ``` # 克隆并安装 git clone https://github.com/vaultmcp/vault.git cd vault pnpm install # 运行 eval（仅限 L1+L2，无需 API key） pnpm --filter @vaultmcp/eval run eval -- --set both # 要包含 L3，请先导出 API key export ANTHROPIC_API_KEY=sk-ant-... pnpm --filter @vaultmcp/eval run eval -- --set both ``` 输出将存放在 `packages/eval/results/eval-.{md,json}` 中。每次运行都会打印 TPR、FPR、各分类细分、各层归因、延迟百分位数，以及按严重程度划分的最严重的假阴性 和假阳性。 留出集数据集位于 `packages/eval/datasets/holdout-attacks/` — 包含跨越 `published-papers`、`garak-probes`、`blog-pocs`、`owasp-llm`、`encoded-payloads`、`multi-turn` 和 `roleplay-jailbreak` 的 188 条记录。良性数据集（110 条记录）位于 `packages/eval/datasets/benign/`。两者都有描述来源的 `MANIFEST.md` 文件。 **鼓励操作员编写自己的攻击并提交 pull request。** 按照 JSON schema 在 `packages/eval/datasets/holdout-attacks/` 下添加一个新文件，更新 `MANIFEST.md`，然后发起 PR。测试工具会自动识别新文件。 自我红队 (`packages/eval/red-team/`) 是诚实评估的另一半：包含 38 个精心设计的绕过尝试，其中 9 个在我们的 P2 修复后仍然通过了 L1+L2。它们在 [`packages/LIMITATIONS.md`](packages/LIMITATIONS.md) 中进行了分类。 ## 开发 ``` # 前提条件：Node 20+、pnpm 9+、Foundry 1.7+（仅用于 contracts） # 安装 pnpm install # 以 dev mode 运行 proxy（封装 MCP filesystem server） pnpm --filter @aimcpvault/mcp-proxy dev -- npx -y @modelcontextprotocol/server-filesystem /tmp # 运行所有测试 pnpm -r test # Typecheck pnpm -r typecheck # 构建所有 packages pnpm -r build # 运行 eval benchmark pnpm --filter @vaultmcp/eval run eval # Contracts（需要 Foundry） cd packages/contracts forge test forge build ``` ## 安全 Vault 是一个纵深防御层，而不是一个完整的解决方案。没有任何 regex 或 embedding 模型能捕获所有攻击 — 对手可以精心构造能够逃避任何单一检测策略的 payload。我们在公开的 v2 留出集上测量的检测结果是 **100% TPR / 0.0% FPR**（80 次攻击，启用 L3，95% 置信区间下限为 95.5%+）。如果没有 L3，在新型分布外攻击上的 TPR 接近 0% — L3 是检测的骨干。分层方法提高了门槛；操作员应将 Vault 视为更广泛的安全态势中的一层。 详情： - [`packages/LIMITATIONS.md`](packages/LIMITATIONS.md) — 测量出的差距、红队证据，以及计划中与已接受的缓解措施。 - [`packages/SECURITY_MODEL.md`](packages/SECURITY_MODEL.md) — Vault 能防御的威胁、不能防御的威胁、假设，以及攻击者仍然需要做的事情。 - [`SECURITY.md`](SECURITY.md) — 漏洞报告政策。 报告漏洞：请发起一个 [GitHub Security Advisory](../../security/advisories/new)（首选）或直接发送电子邮件给维护者。我们的目标是在 48 小时内进行分类，并在确认严重漏洞后的 7 天内发布补丁。 ## 许可证 MIT

标签：AI风险缓解, MITM代理, Petitpotam