内容
# 阻断
一个透明的安全代理，位于任何AI编码助手和它连接的MCP（模型上下文协议）服务器之间。它拦截每一个工具调用，根据您的安全策略进行评估，并记录每一个决定 — 让您对AI代理在您的机器上实际可以执行的操作具有可见性和控制权。
由 [Ishaani Prashant](https://github.com/mindxflayer) 构建。
---
## 功能介绍
当您将AI助手（如Claude Desktop、Cursor、Windsurf等）连接到像 `filesystem`、`github` 或 `bash` 这样的MCP服务器时，AI可以直接访问强大的工具。但是，没有内置的方法来监控、过滤或批准AI使用这些工具的操作。
阻断 解决了这个问题。它封装了任何MCP服务器，并作为一个透明的中间人：
```
AI IDE（Claude、Cursor等）
│
▼
┌─────────────────────┐
│ 阻断 │ ← 拦截每个请求
│ │ ← 评估策略规则
│ │ ← 记录到SQLite
│ │ ← 可选地请求批准
└──────────┬──────────┘
▼
真实的MCP服务器（filesystem、github、bash等）
```
AI IDE将其视为一个正常的MCP服务器。真实的MCP服务器也将其视为一个正常的客户端。双方都不知道阻断的存在。
---
## 功能特点
- **策略配置文件** — 定义每个工具的规则：`allow`、`deny`、`audit`、`judge`、`approve`、`sandbox`。使用glob模式匹配工具名称。
- **LLM风险评分** — 使用Google Gemini（Flash）或本地Ollama模型对每个工具调用进行注入、数据泄露或路径遍历风险评分。
- **人工批准门槛** — 可选地要求在高风险工具调用执行之前进行手动批准（通过CLI提示或本地Web仪表板）。
- **污染跟踪** — 标记来自不受信任源（例如`fetch`）的数据流向敏感接收器（例如`run_command`）。阻止混淆代理攻击。
- **工具模式锁定** — 指纹工具定义在首次运行时。如果下游服务器在会话期间更改或添加工具（rug-pull），阻断会阻止它。
- **Docker沙箱** — 将高风险命令路由到一个短暂的、网络隔离的Alpine Linux容器中。
- **审计日志** — 每个决定（允许、拒绝、原因、时间戳）都会记录到本地SQLite数据库中，并自动进行机密信息遮蔽。
---
## 快速入门
### 步骤1：安装
**从PyPI：**
```bash
pip install blockade
```
**从源码（GitHub克隆）：**
```bash
git clone https://github.com/mindxflayer/blockade.git
cd blockade
python -m venv .venv
# Windows
.\.venv\Scripts\activate
# Mac/Linux
source .venv/bin/activate
pip install -e .
```
### 步骤2：初始化
运行设置向导。它将要求您选择一个LLM提供商并输入您的API密钥：
```bash
blockade init
```
这会在您当前目录（或全局在 `~/.config/blockade/config.env`）中创建一个 `.env` 文件。
### 步骤3：配置您的AI IDE
请参阅下面的[IDE设置指南](#ide设置指南)以获取您特定的IDE。
---
## IDE设置指南
阻断 与任何支持MCP协议的AI IDE或代理一起工作。下面是针对流行工具的测试配置。
> **重要：** 替换 `C:/path/to/your/folder` 为您实际要访问的文件夹。如果路径包含空格，请用引号括起来。
---
### Claude Desktop
打开配置文件：
- **Windows：** `%APPDATA%\Claude\claude_desktop_config.json`
- **Mac：** `~/Library/Application Support/Claude/claude_desktop_config.json`
添加此配置：
```json
{
"mcpServers": {
"filesystem-secured": {
"command": "blockade",
"args": [
"wrap",
"npx", "-y",
"@modelcontextprotocol/server-filesystem",
"C:/path/to/your/folder"
],
"env": {
"JUDGE_PROVIDER": "gemini",
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}
```
重启Claude Desktop。您应该会在聊天窗口底部插件图标（🔌）下看到服务器列出，并带有绿色圆点。
---
### Google Antigravity（Gemini Code Assist）
打开或创建全局配置文件，位于：
```
~/.gemini/config/mcp_config.json
```
在Windows上，该文件位于：`C:\Users\<YourName>\.gemini\config\mcp_config.json`
添加此配置：
```json
{
"mcpServers": {
"filesystem-secured": {
"command": "blockade",
"args": [
"wrap",
"npx", "-y",
"@modelcontextprotocol/server-filesystem",
"C:/path/to/your/folder"
],
"env": {
"JUDGE_PROVIDER": "gemini",
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}
```
重启Antigravity。前往 **设置 → 自定义 → 已安装的MCP服务器** 并验证 `filesystem-secured` 显示绿色圆点。
**注意：** Antigravity具有内置的文件工具，可以绕过MCP。要获得完全覆盖，请使用阻断 来封装IDE没有内置的外部工具（例如 `fetch`、`github`、`database` 等）。
---
### Cursor
打开Cursor设置：
- 前往 **设置 → MCP** 或打开 `~/.cursor/mcp.json`
添加：
```json
{
"mcpServers": {
"filesystem-secured": {
"command": "blockade",
"args": [
"wrap",
"npx", "-y",
"@modelcontextprotocol/server-filesystem",
"C:/path/to/your/folder"
],
"env": {
"JUDGE_PROVIDER": "gemini",
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}
```
重启Cursor。
---
### Windsurf
打开MCP配置文件，位于：
- `~/.codeium/windsurf/mcp_config.json`
添加：
```json
{
"mcpServers": {
"filesystem-secured": {
"command": "blockade",
"args": [
"wrap",
"npx", "-y",
"@modelcontextprotocol/server-filesystem",
"C:/path/to/your/folder"
],
"env": {
"JUDGE_PROVIDER": "gemini",
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}
```
重启Windsurf。
---
### VS Code + Cline / Continue / Roo Code
这些扩展使用标准的MCP配置。检查扩展的设置面板，查找“MCP服务器”部分，并添加上述相同的JSON结构，使用 `"command": "blockade"`。
---
### CLI（直接使用）
您也可以直接从命令行运行阻断，而无需任何IDE：
```bash
blockade wrap npx -y @modelcontextprotocol/server-filesystem "C:/path/to/your/folder"
```
这将启动阻断作为stdio代理。您可以向其管道传输JSON-RPC消息进行测试：
```bash
echo {"jsonrpc":"2.0","method":"tools/call","id":1,"params":{"name":"read_file","arguments":{"path":"README.md"}}} | blockade wrap npx -y @modelcontextprotocol/server-filesystem .
```
---
## 策略配置
阻断 从 `~/.config/blockade/policies.yaml` 读取其策略。该文件在首次运行时会自动生成，并具有安全的默认设置。
您也可以在项目目录中放置一个 `policies.yaml` 文件，或使用 `MCP_POLICY_PATH` 环境变量指向自定义路径。
### 示例策略
```yaml
default_profile: default
profiles:
default:
tools:
"read_file": "allow"
"write_file": "approve_medium"
"run_command": "approve_high"
"search_files": "allow"
"list_directory": "allow"
"*": "judge"
```
### 可用操作
| 操作 | 功能 |
|---|---|
| `allow` | 放行并记录 |
| `deny` | 立即阻止 |
| `audit` | 与allow相同，但在日志中标记 |
| `judge` | 发送给LLM评估器进行风险评分。高风险时阻止 |
| `approve` | 始终需要人工批准 |
| `approve_medium` | 仅在评估器评为中等或更高风险时需要批准 |
| `approve_high` | 仅在评估器评为高风险时需要批准 |
| `sandbox` | 在Docker容器中执行，而不是在主机上 |
### Glob模式
工具名称支持glob匹配：
- `"read_*"` 匹配 `read_file`、`read_directory` 等。
- `"*"` 匹配所有（通配符，放在最后）
- `"github:*"` 匹配github服务器上的所有工具
---
## 查看审计日志
每个决定都存储在 `~/.config/blockade/audit.db` 的SQLite数据库中。
要查看最后10个决定：
```bash
python -c "import sqlite3; conn = sqlite3.connect('C:/Users/<YourName>/.config/blockade/audit.db'); [print(r) for r in conn.execute('SELECT timestamp, tool_name, profile, final_action FROM audit_logs ORDER BY id DESC LIMIT 10').fetchall()]"
```
---
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `JUDGE_PROVIDER` | `gemini` | 用于风险评分的LLM提供商（`gemini` 或 `ollama`） |
| `GEMINI_API_KEY` | — | 您的Google Gemini API密钥 |
| `APPROVAL_MODE` | `cli` | 人工批准界面（`cli` 或 `web`） |
| `MCP_PROFILE` | `default` | 使用的策略配置文件 |
| `MCP_POLICY_PATH` | `~/.config/blockade/policies.yaml` | 自定义策略文件路径 |
| `MCP_AUDIT_DB_PATH` | `~/.config/blockade/audit.db` | 审计数据库的自定义路径 |
| `MCP_SERVER_ID` | 自动生成 | 工具模式固定的唯一ID |
| `ALLOW_UNSANDBOXED_FALLBACK` | `false` | 如果为`true`，则在Docker不可用时本地运行沙箱命令 |
---
## 与其他方案的区别
大多数MCP安全讨论都集中在服务器端验证上。阻断 采用了一种不同的方法 — 它在客户端运行，位于AI和服务器之间，因此您无需修改或信任下游服务器。
| 功能 | 阻断 | 无防火墙 |
|---|---|---|
| 每个工具的允许/拒绝规则 | ✅ | ❌ |
| 每次调用的LLM风险评分 | ✅ | ❌ |
| 危险操作前的人工批准 | ✅ | ❌ |
| 污染跟踪（混淆代理防御） | ✅ | ❌ |
| 工具模式固定（rug-pull防御） | ✅ | ❌ |
| 完整的审计轨迹和机密信息遮蔽 | ✅ | ❌ |
| 风险命令的Docker沙箱 | ✅ | ❌ |
| 与任何MCP客户端配合使用，无需代码更改 | ✅ | — |
---
## 开发与测试
```bash
git clone https://github.com/mindxflayer/blockade.git
cd blockade
python -m venv .venv
.\.venv\Scripts\activate # Windows
pip install -e ".[dev]"
pytest
```
---
## 许可证
MIT — 请参阅 [LICENSE](LICENSE) 以获取详细信息。
