cyrenei/mcp-proxy-firewall

# Arbiter: MCP 防火墙 [](https://github.com/cyrenei/arbiter-mcp-firewall/actions/workflows/ci.yml) [](LICENSE) [](https://github.com/sponsors/cyrenei) 一个轻量级代理，位于 AI 代理和 MCP (Model Context Protocol) 服务器之间，在每次工具调用时强制执行默认拒绝授权、会话预算、漂移检测和结构化审计。 ## 为什么需要？ AI 代理以机器速度自主行动。一个配置错误的代理可以在生产数据库上运行 DDL、导出客户数据或提升权限，而中间没有人来阻止它。 像 Claude Code 这样的应用允许我们定义权限。但这要求我们信任 Claude Code。不言自明：**不要相信药房伙计告诉你背痛该吃什么；让他帮你缓解一下焦虑就好。** Arbiter 与开发工具无关，并强制执行： - **什么** - 代理可以做什么（默认拒绝的工具允许列表） - **多少** - 它能做多少（会话时间限制和调用预算） - **是否应该** - 是否应该做（漂移检测：当工具调用操作类型偏离会话范围时进行标记） - **知情权** - 你会知道（每个决策的结构化审计跟踪） 请参阅 [为什么 MCP 工具调用需要防火墙](docs/sphinx/understanding/why-agent-iam.md) 了解完整论述，或查看 [QuantumBank 案例研究](https://cyrenei.github.io/arbiter-mcp-firewall/case-study.html) 获取一个详细示例，展示了 2 个允许和 4 个被阻止的工具类别。 ## 限制 Arbiter 管理代理**被允许**做什么。 它不管理代理**可能尝试**做什么。它通过减少代理应用通常留 open 或要求的工具调用攻击面来保护平台。这很有价值。但是，一个足够聪明的黑客如果意图足够险恶，将能够欺骗模型入侵**任何**代理。这是一个更深层次的问题，需要比代理能够高性能处理更多的计算量。 ## Arbiter 适合谁？ 适合通过 MCP 部署 AI 代理并需要可自行托管的逐工具调用访问控制的团队。 Arbiter 不是身份提供商。它位于你的 IdP (Okta, Auth0, Keycloak) 下游，并对通过的内容执行策略。如果你需要跨数百个服务身份的集中式 NHI 管理，请查看 [Aembit](https://aembit.io)。如果你需要一个托管平台，这不是你要找的。Arbiter 是你自己运营的开源基础设施。 ## Arbiter + codejail Arbiter 在网络层控制工具调用。[codejail](https://github.com/cyrenei/code-jail) 在进程层控制工具*执行*。相同的策略语言，相同的治理 crates，不同的执行点。 当你的 MCP 工具在受信任的基础设施上运行，并且你只需要控制哪些调用能到达它们时，单独使用 Arbiter。当工具实现本身不可信时——AI 生成的代码、第三方 WASM 模块、任何你不会在非沙箱环境下运行的东西——添加 codejail。 ### 信任模型 | 角色 | 信任级别 | 理由 | |-------|------------|-----------| | **Operator** | 受信任 | 配置 Arbiter，编写策略文件，管理代理注册 | | **Policy file** | 权威 | 定义允许哪些工具；不验证正确性 | | **AI agent** | 不受信任 | 工具调用在转发之前被拦截、评估和审计记录 | | **Declared intent** | 咨询性 | 用于漂移检测，不用于强制执行；对抗性代理会撒谎 | Arbiter 是为平台运营商受信任但 AI 代理不受信任的场景设计的——运营商编写策略，代理在其中运行。 ## 免责声明 **本软件按原样提供，不提供任何保证且不支持。** 使用风险自负。没有付费层级，没有许可证密钥，也没有门控功能。本存储库中的所有内容均根据 Apache 2.0 免费开源。 ## 功能 - **代理身份与委派。** 注册具有信任级别和能力的代理；委派给范围缩小的子代理；级联停用 - **默认拒绝授权：** 策略引擎，评估代理身份、会话上下文、工具名称和参数约束 - **任务会话。** 每个任务的时间有限、预算上限、工具白名单会话 - **漂移检测：** 当工具调用操作类型偏离会话范围时进行标记或阻止（例如，在读范围的会话期间进行写入调用） - **OAuth 2.1 JWT 验证。** JWKS 缓存、多发行者支持、token 内省回退 - **MCP 协议解析：** 从 JSON-RPC 主体中提取工具名称、参数和资源 URI - **结构化审计日志。** JSONL 审计跟踪，自动对敏感字段进行参数脱敏 - **Prometheus 指标：** 请求计数、工具调用计数、延迟直方图、活跃会话仪表 - **基于环境的密钥。** Admin API key 和 token 签名密钥从 `ARBITER_ADMIN_API_KEY` 和 `ARBITER_SIGNING_SECRET` 环境变量加载；检测到默认值时启动警告；恒定时间 API key 比较以防止时序侧信道攻击 - **每代理会话上限：** 可配置的 `max_concurrent_sessions_per_agent`（默认 10）防止会话倍增攻击，即单个代理打开许多会话以绕过每会话速率限制 - **凭据擦除。** 当凭据注入处于活动状态时，上游响应会被扫描以查找 Arbiter 注入的确切密钥（多种编码：明文、URL 编码、JSON 转义、十六进制、base64），并在代理看到它们之前替换为 `[CREDENTIAL]` ## 架构 ``` Agent ──▶ Arbiter Proxy (:8080) ──▶ MCP Server │ ├── Middleware chain: tracing → metrics → audit → oauth │ → mcp-parse → session → policy → behavior → forward │ └── Admin API (:3000): agent registration, delegation, tokens ``` 请参阅 [架构](docs/sphinx/understanding/architecture.md) 了解完整的中间件链、crate 依赖图和数据流。 ## 安装 ``` curl -sSf https://raw.githubusercontent.com/cyrenei/arbiter-mcp-firewall/main/install.sh | sh ``` 下载适用于你平台的最新二进制文件（Linux/macOS, amd64/arm64），并进行 SHA256 验证。安装 `arbiter` 和 `arbiter-ctl`。不需要 sudo。 更新现有安装： ``` arbiter-ctl update ``` ## 快速开始 ``` docker compose up --build -d curl http://localhost:8080/health # → OK curl -X POST http://localhost:3000/agents \ -H "x-api-key: arbiter-quickstart-key" \ -H "Content-Type: application/json" \ -d '{"owner":"user:alice","model":"gpt-4","capabilities":["read"],"trust_level":"basic"}' ``` 完整演练：[快速开始](docs/sphinx/getting-started/quickstart.md) ## 配置 单个 TOML 文件，每个子系统都有相应部分： ``` [proxy] listen_port = 8080 upstream_url = "http://mcp-server:8081" [oauth] # jwks_cache_ttl_secs = 3600 # [[oauth.issuers]] # ... [policy] file = "policies.toml" [sessions] default_time_limit_secs = 3600 default_call_budget = 1000 max_concurrent_sessions_per_agent = 10 [audit] enabled = true file_path = "/var/log/arbiter/audit.jsonl" redaction_patterns = ["password", "secret", "token"] [admin] listen_port = 3000 # api_key 从 ARBITER_ADMIN_API_KEY 环境变量加载 (推荐) # signing_secret 从 ARBITER_SIGNING_SECRET 环境变量加载 (推荐) ``` 请参阅 [arbiter.example.toml](arbiter.example.toml) 获取完整参考。 ## 策略语言 ``` [[policies]] id = "allow-read-basic" effect = "allow" allowed_tools = ["read_file", "list_dir"] [policies.agent_match] trust_level = "basic" [policies.intent_match] keywords = ["read", "analyze"] ``` 完整参考：[策略语言](docs/sphinx/guides/policy.md) ## 项目结构 ``` crates/ ├── arbiter/ Integration binary; wires everything together ├── arbiter-proxy/ Async HTTP reverse proxy with middleware chain ├── arbiter-oauth/ OAuth 2.1 JWT validation middleware ├── arbiter-identity/ Agent identity model and in-memory registry ├── arbiter-lifecycle/ Agent lifecycle REST API (axum) ├── arbiter-cli/ CLI for agent management ├── arbiter-mcp/ MCP JSON-RPC request parser ├── arbiter-policy/ Deny-by-default policy engine ├── arbiter-session/ Task session management ├── arbiter-behavior/ Drift detection ├── arbiter-metrics/ Prometheus-compatible metrics └── arbiter-audit/ Structured audit logging with redaction ``` ## 从源代码构建 ``` cargo build --release ./target/release/arbiter --config arbiter.toml --log-level info ``` ## 状态 核心执行管道（策略引擎、会话管理、漂移检测、审计日志记录）已完成并经过测试。[QuantumBank 场景](https://cyrenei.github.io/arbiter-mcp-firewall/case-study.html) 演示了跨 6 个工具类别的端到端执行。 本项目按原样提供。 ## 许可证 [Apache License 2.0](LICENSE) ## 支持 [GitHub Issues](https://github.com/cyrenei/arbiter-mcp-firewall/issues)，无 SLA， 无保证响应时间。 联系方式：[arbitersecurity@proton.me](mailto:arbitersecurity@proton.me)

PGP Public Key

``` -----BEGIN PGP PUBLIC KEY BLOCK----- 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 =gMhW -----END PGP PUBLIC KEY BLOCK----- ```

标签：AI 安全, AI 智能体, API 安全, Claude, CSV导出, CVE检测, JSONLines, Lerna, Linux系统监控, LLM, MCP, Model Context Protocol, Python安全, RASP, Streamlit, Unmanaged PE, 中间件, 代理, 会话管理, 可视化界面, 审计日志, 异常检测, 攻击面缩减, 数据库保护, 无文件攻击, 权限管理, 模型安全, 模型越狱, 策略执行, 网络安全, 自定义请求头, 访问控制, 请求拦截, 防御默认, 防火墙, 隐私保护, 零信任