ToolFence

一个本地、默认拒绝的 MCP 工具调用防火墙。

ToolFence 将最小权限策略和人工审批置于 AI 代理与 stdio MCP 服务器之间。它允许安全操作，阻止危险操作，并在需要人工决策的调用转发前询问——无需修改 MCP 客户端或服务器的代码。

ALLOW  Read ./src/index.ts
DENY   Read ~/.ssh/id_rsa
ASK    Run npm install
DENY   Run sudo rm -rf ...

为什么选择 ToolFence

• 语义化策略： 将常见的 Filesystem、Shell、Git 和 HTTP 工具调用标准化为 fs.read、shell.exec、git.write、net.request 等操作，然后匹配路径、精确的命令参数、主机和 HTTP 方法。

• 确定性执行： deny 覆盖其他所有匹配，多资源请求作为一个整体评估，未知或模糊的操作默认拒绝。

• 人工审批： 使用经过身份验证的本地 Broker 进行一次性或会话决策；会话审批绑定到工具 Schema，当 Schema 变化时失效。

• 隐私优先的审计： 记录工具身份、受影响的资源、策略决策和结果哈希，但不存储原始参数或结果。

• 可测试的策略： 通过 CLI 生成、验证、解释和回归测试 YAML 策略。

Related MCP server: cordon

状态

版本 0.2.0 是第一个稳定的开源版本。它包括通过本地 Broker 实现的可取消审批、保守的 Filesystem/Shell/Git/HTTP 适配器、策略创建和开发命令、Schema 绑定的会话审批以及真实的 MCP 集成测试。

ToolFence 并非针对恶意 MCP 服务器进程的沙箱：上游进程仍然以当前用户的操作系统权限运行。

由于 ToolFence 启动用户配置的进程并中介 Shell、Git 和 HTTP 功能，npm 包被透明地声明为双用途。请参阅 DISCLOSURE 了解预期的合法用途和安全边界。

安装

npm 包名为 toolfence-mcp；命令为 toolfence。

npm install -g toolfence-mcp

对于本地开发：

npm install
npm run build
npm link

快速开始

创建一份保守的入门策略，审核它，然后包装任何 stdio MCP 服务器：

toolfence policy init
toolfence policy check --policy ./toolfence.yaml

生成的文件永远不会替换现有策略。有关更广泛的注释示例，请参阅 examples/policy.yaml。

toolfence wrap \
  --policy ./toolfence.yaml \
  --server filesystem \
  --workspace "$PWD" \
  -- npx -y @modelcontextprotocol/server-filesystem "$PWD"

MCP 客户端配置如下所示：

{
  "mcpServers": {
    "filesystem": {
      "command": "toolfence",
      "args": [
        "wrap",
        "--policy", "/absolute/path/policy.yaml",
        "--server", "filesystem",
        "--workspace", "/absolute/path/project",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/absolute/path/project"
      ]
    }
  }
}

ToolFence 保留 stdout 用于 MCP JSON-RPC 消息。诊断信息和上游 stderr 保持在 stderr 上。在单独的终端中启动每个用户的 Broker 和审批终端：

toolfence broker
toolfence approvals

wrap 默认使用 Broker。如果 Broker 缺失、不兼容、未经过身份验证、断开连接或超时，ask 决策将默认拒绝。仅当希望直接通过 /dev/tty 审批时才使用 --approval tty。toolfence status 验证 Broker 连接性、协议版本和 Socket 权限。

策略

version: 1
default: ask

rules:
  - id: deny-dotenv
    effect: deny
    operations: [fs.read, fs.write]
    resources: ["**/.env", "**/.env.*"]

  - id: allow-workspace-read
    effect: allow
    operations: [fs.read]
    resources: ["${workspace}/**"]

  - id: allow-tests
    effect: allow
    operations: [shell.exec]
    commands:
      - [npm, test]

  - id: allow-git-inspection
    effect: allow
    operations: [git.read]

  - id: allow-read-api
    effect: allow
    operations: [net.request]
    hosts: ["api.example.com", "*.internal.example.com"]
    methods: [GET, HEAD]

规则按确定性顺序评估：

1. 每个匹配的 deny 规则覆盖所有其他匹配。当任何请求的资源受到保护时，拒绝资源规则匹配。

2. 否则，第一个匹配的规则胜出。

3. 如果没有匹配，则使用 default。

允许和询问资源规则要求每个请求的资源都匹配，因此多文件调用不能使用一个允许的路径来携带未授权的路径。

文件系统路径在匹配前会被规范化，包括现有的符号链接。允许的命令使用精确的 argv 匹配；复合或带引号的 shell 字符串不被视为安全的 argv，并回退到默认决策。

支持的 v0.2 操作包括 fs.read、fs.write、fs.delete、shell.exec、git.read、git.write、git.remote、net.request 和 unknown。模糊的 Git 命令、无效的 URL 和未识别的工具将回退到 shell.exec 或 unknown 并默认拒绝。

策略开发

toolfence policy init [--policy ./toolfence.yaml]
toolfence policy check --policy ./examples/policy.yaml
toolfence policy explain --policy ./examples/policy.yaml --action ./action.json
toolfence policy test --policy ./examples/policy.yaml --cases ./policy-cases.yaml

init 创建一份保守的策略，不会覆盖现有文件。check 验证 YAML、严格的 Schema 规则、变量、重复 ID 和无效的网络字段组合。explain 打印匹配的规则和最终决策。test 运行声明式测试用例，并在任何不匹配时以非零退出。

审计日志

默认审计文件是工作区下的 .toolfence/audit.jsonl。它记录操作名称、受影响的路径、工具身份、最终策略决策以及上游结果的 SHA-256 哈希。原始工具参数、命令参数和原始结果被有意省略，以减少机密泄漏。

使用 --audit /path/to/audit.jsonl 选择不同的路径。

安全边界

ToolFence v0.2 在工具调用跨越此代理时减少意外或提示注入导致的工具误用。它不能阻止上游服务器进程直接读取文件、环境变量或网络。进程隔离、环境过滤和网络控制属于后续沙箱阶段。

当前其他限制：

• 仅支持 stdio 传输

• 本地 Broker 支持仅限 POSIX；Windows 仍为非交互式且默认拒绝

• JSON-RPC 批量消息被拒绝

• 尚无输出秘密编辑功能；原始结果原样转发

• HTTP MCP 适配器必须暴露重定向目标（例如作为 redirectUrl）供 ToolFence 重新评估

开发

架构、威胁模型、安全不变式和 v0.2 实现计划在 开发指南 中维护。

npm run typecheck
npm test
npm run build
npm pack --dry-run
npm audit --omit=dev

完整的验证策略在 TESTING.md 中，发布/安全审核记录在 REVIEW.md 中。在贡献、报告漏洞或发布版本之前，请参阅 CONTRIBUTING.md、SECURITY.md、CHANGELOG.md 和 RELEASING.md。

许可证

MIT