mcp-firewall
使用说明（Markdown 格式）：
- 项目简介
- mcp-firewall 是一个 MCP 服务器实现的安全网关/代理，位于客户端与下游 MCP 服务器之间，负责对传入的请求进行策略判定、对输出进行脱敏/截断、并可在需要时对下游进行沙箱执行与供链校验。
- 主要功能点
- 策略引擎（Policy Engine）：基于规则对工具调用、资源读取等操作进行允许/拒绝/提示（需要人机审批）。
- 数据脱敏（Redaction）：对输入输出中的敏感信息进行正则化脱敏。
- 沙箱执行（Sandboxing）：可对下游执行环境进行名称空间/Landlock 等沙箱化处理（Linux 平台）。
- 供链校验（Supply Chain）：可进行哈希校验和路径白名单校验，确保下游二进制和资源的完整性。
- 审计日志（Audit Logging）：对请求/响应过程进行详细日志记录，包含策略决策、哈希验证、脱敏、超时等信息。
- 资源与工具路由：代理对下游的资源读取和工具调用进行路由和聚合，统一暴露给 MCP 客户端。
- Explain 工具：提供 explain_effective_policy 等工具，用于显示当前的策略、脱敏模式、工作流和 provenance 信息。
- 安装步骤
- 该工具基于 Go 语言实现，常用安装步骤如下：
- 安装 Go 环境：请确保本机已安装 Go 1.20+（具体版本以仓库要求为准）。
- 获取代码：将仓库克隆到本地或下载源码。
- 构建执行文件：在仓库根目录执行 go build ./cmd/mcp-firewall（生成可执行文件）。
- 如需本地发布或集成测试，可使用提供的测试用例与示例下游服务器进行联合测试。
- 该工具基于 Go 语言实现，常用安装步骤如下：
- 服务器配置（MCP 服务器给 MCP 客户端使用的配置信息）
说明：MCP 客户端需要知道要连接的 MCP 服务器的启动命令及参数，以便启动并通过 MCP 协议与之通信。配置格式建议使用 JSON，包含服务器名称、启动命令与参数等字段。以下为示例描述，实际数值请按你的环境与下游 MCP 服务器实现调整。
示例（JSON）:
{
"server": "echoserver",
"command": "./testdata/echoserver/echoserver",
"args": ["--verbose"],
"env": ["FOO=bar"],
"timeout": "10s",
"downstream_config": {
"downstream_alias": "echoserver",
"command": "./testdata/echoserver/echoserver",
"args": ["--verbose"],
"env": ["FOO=bar"],
"timeout": "10s",
"sandbox": "strict",
"hash": ""
}
}
注释说明：
- server: MCP 客户端要连接的 MCP 服务器的逻辑名称（用于日志、追踪及路由）。
- command: 启动下游 MCP 服务器的可执行程序路径（在本例中是一个模拟的 echо 服务器例子）。
- args: 启动命令的参数数组。
- env: 启动环境变量数组，形如 "KEY=value"。
- timeout: 下游服务器调用的超时设置（全局默认或按 downstream 逐条配置）。
- downstream_config: 进一步对该下游的具体配置进行描述，包含沙箱设置、哈希等字段，便于在 MCP 客户端读取配置时知道要连接的下游信息。
- 基本使用方法
- 启动与连接
- 构建完成后运行 mcp-firewall 二进制，服务器将监听并等待 MCP 客户端建立连接。
- 客户端需要提供要连接的 MCP 服务器的启动信息（如上面的 JSON 示例），包括 downstream 的 command、args、环境等。
- 配置与管理
- 通过配置文件/环境变量来设定策略、脱敏规则、超时、沙箱及供链参数。支持本地覆盖（workspace）以便在工作区中合并本地 overrides。
- 使用 explain_effective_policy 工具查看当前有效策略、工作流以及 provenance 信息。
- 使用场景
- 使用 MCP 客户端连接到 mcp-firewall 的 upstream 端，接入经过策略执行的工具调用与资源读取，获取经过脱敏与截断处理的结果。
- 维护与安全
- 结合审计日志与 provenance 信息，追踪策略变更、局部覆盖、下游哈希验证及沙箱能力的使用情况。
- 启动与连接