reaatech/tool-use-firewall

# 🔥 tool-use-firewall AI 代理与 MCP 服务器之间的策略执行层。 [](https://github.com/reaatech/tool-use-firewall/actions/workflows/ci.yml) [](https://github.com/reaatech/tool-use-firewall) [](LICENSE) ## 概述 `tool-use-firewall` 是一个关键的安全代理，位于 AI 代理和 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器之间。它会拦截工具调用，执行安全策略，并为危险操作提供人工审批机制。 ### 核心功能 - **策略引擎** — 根据工具名称、参数和自定义规则进行阻止、允许或要求审批 - **速率限制** — 具有内存限制的全局、按工具和按会话的令牌桶 - **参数验证** — 正则表达式、shell 安全性和 SQL 注入检查 - **只读模式** — 使用紧急突破绕过令牌阻止写入操作 - **成本追踪** — 为昂贵的工具调用强制执行会话预算 - **审计日志** — 脱敏后的结构化日志输出至 stderr 或文件（绝不输出至 stdout） - **审批工作流** — 具有超时处理的多级人工审批链 - **安全正则表达式** — 为所有用户配置的模式提供 ReDoS 保护 ## 快速入门 ### 前置条件 - Node.js ≥ 20 - pnpm ≥ 9 ### 安装 ``` pnpm install tool-use-firewall ``` ### 使用 ``` npx tool-use-firewall \ --config ./policies/default.yaml \ --upstream node ./your-mcp-server.js ``` 启用审批 API（需要身份验证 — API 默认绑定到 `127.0.0.1`）： ``` export APPROVAL_API_TOKEN="$(openssl rand -hex 32)" npx tool-use-firewall \ --config ./policies/default.yaml \ --upstream node ./your-mcp-server.js \ --approval-port 8080 ``` 将以下内容添加到策略 YAML 中以启用审批 API： ``` approval_api: token_env: APPROVAL_API_TOKEN bind_host: 127.0.0.1 # optional, defaults to 127.0.0.1 ``` 如果设置了 `--approval-port` 但没有提供相应的 `approval_api.token_env`，代理将拒绝启动，以避免暴露未经身份验证的 API。 在字面量 `--` 之后向上游 MCP 服务器传递参数： ``` npx tool-use-firewall \ --config ./policies/default.yaml \ --upstream node -- ./your-mcp-server.js --port 9000 ``` ### 策略配置 创建一个 `policies/default.yaml` 文件： ``` version: '1.0' settings: default_action: block read_only: false rate_limits: global: requests_per_minute: 120 burst_capacity: 20 per_tool: database_execute: requests_per_minute: 10 burst_capacity: 3 validation: rules: - id: no_shell_injection type: shell_safe tools: ['execute_command'] argument: 'cmd' rules: - id: block_drop_table type: block tools: ['database_execute'] conditions: - argument: query pattern: 'DROP\\s+TABLE' flags: 'i' priority: 100 description: 'Prevent DROP TABLE operations' approvals: default_timeout_ms: 300000 max_pending_approvals: 1000 required_for: - tools: ['file_write', 'database_execute'] approvers: ['security-team'] min_approvals: 1 ``` ## 架构 ``` AI Agent → tool-use-firewall → Upstream MCP Server │ ├─ Policy Engine (block/allow/approve) ├─ Rate Limiter (token buckets) ├─ Argument Validator (regex/SQL/shell) ├─ Read-Only Check ├─ Cost Tracker └─ Audit Logger (redacted) ``` 代理使用 stdio JSON-RPC 与代理和上游 MCP 服务器进行通信。审批 API 作为独立的 HTTP 服务器运行。 ## 安全 有关我们的安全策略和漏洞报告流程，请参阅 [SECURITY.md](SECURITY.md)。 - **存储限制** — 所有有状态组件均实现了基于 TTL/容量的驱逐机制。无界的 `Map` 使用被视为一种安全漏洞。 - **ReDoS 保护** — 来自配置的所有正则表达式在编译前均经过验证。 - **时序安全比较** — Bearer token 和绕过令牌使用 `crypto.timingSafeEqual`。 - **敏感数据脱敏** — 审计日志和 API 响应会自动对密码、API 密钥、电子邮件和 Bearer token 进行脱敏处理。 - **输入验证** — JSON-RPC 消息、审批 API 主体和 CLI 参数均经过 schema 验证。 ## 开发 ``` # 安装依赖 pnpm install # 构建 pnpm build # 运行测试 pnpm test # 运行测试并生成覆盖率 pnpm test:coverage # Lint pnpm lint # 类型检查 pnpm typecheck ``` ## 文档 - [ARCHITECTURE.md](ARCHITECTURE.md) — 技术设计和资源管理模式 - [DEV_PLAN.md](DEV_PLAN.md) — 路线图和当前阶段 - [CONTRIBUTING.md](CONTRIBUTING.md) — 贡献指南和提交规范 - [AGENTS.md](AGENTS.md) — 针对本代码库进行工作的 AI 代理指南 ## 许可证 MIT © [reaatech](https://github.com/reaatech)

标签：AI安全, Chat Copilot, CISA项目, DOE合作, GNU通用公共许可证, Lerna, LLM工具安全, MCP, MITM代理, Model Context Protocol, Node.js, pnpm, ReDoS防护, Streamlit, tool-use-firewall, 人工审批, 代理, 参数校验, 只读模式, 命令注入, 安全代理, 安全网关, 审计日志, 开源, 成本控制, 无文件攻击, 正则表达式安全, 策略执行, 网络安全, 自动化攻击, 访问控制, 请求响应过滤, 防火墙, 限速, 隐私保护