Angwyn/safemcp-gateway
GitHub: Angwyn/safemcp-gateway
一款零依赖的 MCP 协议安全网关，通过拦截 JSON-RPC 流量防御 AI agent 面临的路径遍历、命令注入和 SSRF 攻击。
Stars: 0 | Forks: 0
# 🛡️ SafeMCP Gateway
一个零依赖、本地优先的安全网关和 Model Context Protocol (MCP) 的 stdio 代理。它作为一个隔离屏障，运行在 AI 客户端（如 Claude Code、Cursor 或 VS Code）与直接与你的文件系统、shell 和本地网络交互的目标 MCP 服务器之间。
通过在标准输入/输出流中拦截并验证 JSON-RPC 2.0 帧，SafeMCP 能够在安全漏洞（如路径遍历、命令注入和 Server-Side Request Forgery (SSRF)）危及宿主机之前对其进行缓解。
## 🚀 核心功能
* 📁 **路径遍历防护：** 自动清理并规范化文件路径参数，验证所有目录操作是否限制在你配置的工作区文件夹内。
* ⚙️ **子进程执行守卫：** 禁用 shell 元字符，并将二进制执行限制在明确的命令白名单中。
* 🌐 **SSRF 网络拦截：** 防止 agent 访问私有本地子网、环回适配器和云元数据服务（例如，位于 `169.254.169.254` 的 AWS IMDSv2 接口）。
* ⏳ **令牌桶限流：** 控制系统命令的执行频率，以防止自动化循环和 payload 洪水。
* 🪵 **取证审计日志：** 生成包含匿名化参数的结构化 JSONL 审计日志，以确保开发者隐私和合规性。
* 📦 **零依赖核心：** 完全基于 Node.js 核心模块构建，保证绝对零漏洞的供应链。
## 🛠️ 技术栈
## 📦 快速开始
### 前置条件
* **Node.js**：18.0.0 或更高版本。
* **TypeScript**：全局安装或作为开发依赖安装以进行编译。
### 项目结构
确保你的本地项目目录符合以下布局：
```
safemcp-gateway/
├── src/
│ └── safemcp-gateway.ts # Core proxy logic and security rules
├── dist/ # Compiled JavaScript output (Git-ignored)
├── .gitignore # Untracked files and build directories
├── LICENSE # MIT License parameters
├── package.json # Node.js project metadata and scripts
├── tsconfig.json # Strict TypeScript compiler configurations
└── README.md # Project documentation
```
### 分步安装说明
1. **克隆仓库：**
```
git clone https://github.com/angwyn/safemcp-gateway.git
cd safemcp-gateway
```
2. **安装开发依赖：**
*(SafeMCP 使用零生产依赖。NPM 包仅用于 TypeScript 开发工具)。*
```
npm install
```
3. **构建生产网关：**
```
npm run build
```
编译后的执行文件将输出到 dist/safemcp-gateway.js。
## 💡 使用说明
### SafeMCP 如何融入开发者工作流
```
[ AI Client ] [ SafeMCP Gateway ] [ Target MCP Server ]
(Cursor) (Local Process) (e.g., Postgres)
| | |
|---- (1) JSON-RPC Request -------->| |
| "tools/call: query_db" | |
| |-- (2) Run Security Checks |
| | - Path traversal? No. |
| | - Command injection? No. |
| | - SSRF exploit? No. |
| | |
| |==== IF VALID =====================|
| |---- (3) Forward Request --------->|
| |<--- (4) Raw Response -------------|
|<--- (5) Unmodified Response ------| |
| |===================================|
| | |
| |==== IF INVALID ===================|
|<--- (6) JSON-RPC Error -32602 ----| |
| "Access Denied" | |
```
SafeMCP 充当任何可执行命令的安全包装器。双横线分隔符 (--) 用于将网关配置参数与目标服务器命令行隔离开来。
### Claude Desktop 集成
要将官方的 Anthropic filesystem 服务器封装在 SafeMCP 安全层内，请更新你本地的 claude_desktop_config.json 配置文件：
```
{
"mcpServers": {
"secure-filesystem": {
"command": "node",
"args": [
"/absolute/path/to/safemcp-gateway/dist/safemcp-gateway.js",
"--workspace",
"/path/to/safe/workspace",
"--",
"npx",
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/safe/workspace"
]
}
}
}
```
### Cursor 编辑器集成
要在你的 Cursor 编辑器环境中注册一个安全的 PostgreSQL 服务器：
1. 打开 **Settings** -> **Features** -> **MCP**。
2. 点击 **+ Add New MCP Server**。
3. 将类型设置为 command。
4. 在命令窗口中输入执行字符串：
```
node /path/to/safemcp-gateway/dist/safemcp-gateway.js --workspace /path/to/workspace -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost:5432/db
```
### 使用与测试验证
激活后，SafeMCP 会在后台静默运行，仅当工具参数违反安全规则时才进行干预。
#### 示例 1：解析安全工作区查询（允许）
当编程助手请求位于根目录内的合法文件时，网关会立即转发该请求。
* **来自客户端的传入请求：**
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "read_file",
"arguments": { "path": "src/index.ts" }
},
"id": 1
}
* **SafeMCP 操作：** 匹配配置标准，写入审计日志条目，并将命令转发到目标文件系统服务器。
#### 示例 2：阻止目录遍历（已拦截）
当 prompt 注入 payload 试图强制工具逃逸其沙盒时，SafeMCP 会检测到遍历并拒绝该请求。
* **来自客户端的传入请求：**
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "read_file",
"arguments": { "path": "../../../../../etc/passwd" }
},
"id": 2
}
* **SafeMCP 响应：**
{
"jsonrpc": "2.0",
"id": 2,
"error": {
"code": -32602,
"message": "Access Denied: Path traversal attempt detected outside authorized workspace."
}
}
## 🪵 JSONL 审计
每个经过过滤的请求都会被追加到本地的 safemcp-audit.jsonl 文件中。参数值被规范化为加密匿名签名，以确保 PII 和企业机密永远不会泄露：
```
{"timestamp":"2026-07-01T11:20:05.123Z","status":"ALLOWED","method":"tools/call","tool":"read_file","param_hash":"a4f6e1b...92"}
{"timestamp":"2026-07-01T11:22:14.582Z","status":"BLOCKED","method":"tools/call","tool":"read_file","reason":"PATH_TRAVERSAL","attempted_payload":"../../../../../etc/passwd"}
```
## 🤝 贡献
我们欢迎 contributions 来帮助改进 SafeMCP 的默认安全策略。
1. Fork 该仓库并创建你的功能分支：git checkout -b feature/enhanced-ssrf-signatures。
2. 确保任何新的验证代码**仅使用原生 Node.js 库**，以保持我们的零依赖设计。
3. 验证更改在 UNIX 和 Windows 环境中是否都能正确运行。
4. 提交 Pull Request，详细说明你的更改所针对的具体漏洞模式。
## 📄 许可证
该项目采用 MIT 许可证授权 - 详情请参阅 LICENSE 文件。
标签：AI代理安全, CISA项目, MCP协议, MITM代理, TypeScript, 安全插件, 安全网关, 网络安全审计, 自动化攻击, 防御防护