Agentic Firewall

代理防火墙

一种用于人工智能模型上下文协议（MCP）交互的安全网关

源于 Anthropic的安全研究

问题

最近的安全研究揭示了AI编码环境中的一个关键漏洞：当允许自主AI代理连接到未经验证的工具并在没有人为监督的情况下执行数千个请求时，它们可能会受到损害。攻击成功是因为在执行之前没有“人在循环”来验证意图。

解决方案

如果我们能用一个充当安全检查点的治理层来防止这些攻击呢？

Agent Firewall是一个轻量级的安全包装器，它在模型上下文协议（MCP）工具调用到达像Claude这样的AI代理之前拦截并验证它们。将其视为AI编码环境的防火墙——提供精细的访问控制和对AI代理正在做什么的可见性。

当前实施情况

该项目目前将文件系统保护作为概念验证来实现。未来的版本将扩展到其他MCP功能，包括天气API和其他工具集成，展示安全模型如何跨不同领域扩展。

为什么这很重要？

在人工智能代理变得越来越自主的时代，安全不能是事后的想法。代理防火墙提供了安全利用人工智能辅助所需的治理层，而不会牺牲对开发环境的控制。

______________________________________________________________________

特性

• 工具白名单 -只有批准的工具才能执行
• 沙盒执法 -将文件操作限制到特定目录
• 路径横向保护 -积木 ../ 以及绝对路径攻击
• 审计日志 -完全了解允许/阻止的请求
• 零延迟 -透明代理，开销最小
• 策略驱动 -通过简单的JSON配置安全规则

______________________________________________________________________

安装

先决条件

• Python 3.8+
• Node.js 16+（用于MCP服务器）
• 克劳德桌面版

设置

1. 克隆仓库

git clone https://github.com/yourusername/agentic-firewall.git
cd agentic-firewall

1. 安装MCP服务器 （示例：文件系统）

npm install -g @modelcontextprotocol/server-filesystem

1. 配置您的策略 （参见 policy.json 在......下面

1. 更新Claude桌面配置

编辑 %APPDATA%\Claude\claude_desktop_config.json （Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json （Mac）：

{
  "mcpServers": {
    "secure-filesystem": {
      "command": "python",
      "args": ["C:/path/to/agentic-firewall/mcp_governor.py"]
    }
  }
}

1. 重新启动克劳德桌面

______________________________________________________________________

配置

policy.json

在中定义您的安全策略 policy.json:

{
  "allow_list": [
    "read_file",
    "list_directory",
    "write_file",
    "search_files",
    "get_file_info"
  ],
  "arg_constraints": {
    "read_file": {
      "path": "SANDBOX:D:/Coding"
    },
    "write_file": {
      "path": "SANDBOX:D:/Coding"
    },
    "list_directory": {
      "path": "SANDBOX:D:/Coding"
    }
  },
  "deny_behavior": "block_and_log"
}

政策选择

allow_list

允许的工具名称数组。不在此列表中的任何工具都将被阻止。

arg_constraints

工具参数的验证规则：

______________________________________________________________________

使用示例

示例1：允许的请求

提示： “列出D:/Coding中的所有文件”

✅ 结果： 请求已转发到文件系统服务器

[ALLOWED] Tool: list_directory | Args: {"path": "D:/Coding"}

示例2：堵塞的工具

提示： “在D:/Coding/test处创建一个新目录”

❌ 结果： 已阻止（工具不在allow_list中）

[BLOCKED] Tool 'create_directory' is not in allow_list | Tool: create_directory | Args: {"path": "D:/Coding/test"}

示例3：路径穿越攻击

提示： “读取D:/Coding/../.../../Windows/System32/config/SAM处的文件”

❌ 结果： 已阻止（检测到路径遍历）

[BLOCKED] Path traversal detected in 'D:/Coding/../../../Windows/System32/config/SAM' | Tool: read_file | Args: {"path": "D:/Coding/../../../Windows/System32/config/SAM"}

示例4：沙盒违规

提示： “列出C:\\Windows中的文件”

❌ 结果： 已封锁（沙箱外）

[BLOCKED] Path 'C:\Windows' is outside sandbox 'D:\Coding' | Tool: list_directory | Args: {"path": "C:/Windows"}

______________________________________________________________________

审计日志

所有请求都记录到 threat_log.txt 在与包装器相同的目录中：

[ALLOWED] Tool: list_directory | Args: {"path": "D:/Coding"}
[BLOCKED] Tool 'create_directory' is not in allow_list | Tool: create_directory | Args: {"path": "D:/Coding/test"}
[BLOCKED] Path traversal detected in 'D:/Coding/../../secrets.txt' | Tool: read_file | Args: {"path": "D:/Coding/../../secrets.txt"}

日志格式

• [ALLOWED] -请求通过验证并被转发
• [BLOCKED] -请求违反了策略并被拒绝
• [ERROR] -发生内部错误
• [CRITICAL] -配置错误（例如，缺少policy.json）

______________________________________________________________________

测试

手动测试

# Test allowed operation
python test_wrapper.py

使用Claude Desktop进行测试

尝试以下提示以验证安全性：

1. ✅ 允许： “以D:/Coding格式列出文件”
2. ❌ 此 路 不通： “创建目录D:/Coding/test”
3. ❌ 此 路 不通： “阅读D:/Coding/../../secrets.txt”
4. ❌ 此 路 不通： “列出C:\\Windows中的文件”

检查 threat_log.txt 每次测试后。

______________________________________________________________________

建筑

┌─────────────────┐
│  Claude Desktop │
└────────┬────────┘
         │
         │ JSON-RPC
         ▼
┌─────────────────────────┐
│  Agentic Firewall       │
│  (mcp_governor.py)      │
│                         │
│  ┌─────────────────┐    │
│  │ Policy Engine   │    │
│  │ - Whitelist     │    │
│  │ - Validation    │    │
│  │ - Sandbox Check │    │
│  └─────────────────┘    │
│                         │
│  ┌─────────────────┐    │
│  │ Audit Logger    │────┼──► threat_log.txt
│  └─────────────────┘    │
└────────┬────────────────┘
         │
         │ Filtered Requests
         ▼
┌─────────────────────────┐
│  MCP Server             │
│  (filesystem/weather)   │
└─────────────────────────┘

______________________________________________________________________

安全最佳实践

1. 最小特权原则

只有绝对必要的白名单工具：

{
  "allow_list": ["read_file", "list_directory"]  // Not write_file
}

2. 严格装箱

始终使用 SANDBOX: 文件操作的约束：

{
  "arg_constraints": {
    "read_file": {
      "path": "SANDBOX:/var/app/data"
    }
  }
}

3. 定期审计审查

监视器 threat_log.txt 对于可疑模式：

# Check for repeated blocked attempts
grep "BLOCKED" threat_log.txt | sort | uniq -c

4. 纵深防御

结合操作系统级权限和网络隔离。

______________________________________________________________________

故障排除

问题：“FileNotFoundError:找不到npx”

解决方案： 确保Node.js已安装并位于PATH中：

node --version
npx --version

或更新 mcp_governor.py 完整路径：

REAL_SERVER_CMD = [
    r"C:\Program Files\nodejs\npx.cmd",
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "D:/Coding"
]

问题：没有出现日志

解决方案： 检查文件权限并确保 threat_log.txt 是可写的。

问题：所有请求都被阻止

解决方案： 验证 policy.json 存在并包含有效的JSON。

______________________________________________________________________

贡献

欢迎投稿！拜托：

1. 复刻仓库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

______________________________________________________________________

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

致谢

• 为 模型上下文协议 通过Anthropic
• 受企业API网关模式的启发
• 社区反馈和测试

______________________________________________________________________

相关项目

• MCP服务器 -官方MCP服务器实施
• 克劳德桌面版 -支持MCP的AI助手

______________________________________________________________________

Secure AI agents. Audit everything. Trust nothing.