yuga-hashimoto/mcp-guardian
GitHub: yuga-hashimoto/mcp-guardian
面向 MCP 协议的安全扫描器与运行时代理，用于检测服务配置漏洞并强制执行工具调用权限策略。
Stars: 0 | Forks: 0
# mcp-guardian
[](https://github.com/yuga-hashimoto/mcp-guardian/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
## 概述
**mcp-guardian** 通过以下方式帮助您保护 MCP server 部署：
1. **扫描** MCP server 配置中的已知漏洞模式
2. **强制执行** 通过透明代理对 tool call 实施运行时策略
3. **检测** 命令注入、路径遍历、SSRF、不安全配置和权限提升
## 安装
```
npm install mcp-guardian
```
或者全局安装以用于 CLI 使用：
```
npm install -g mcp-guardian
```
## 快速开始
### CLI 扫描器
```
# 扫描 MCP server 配置文件
mcp-guardian scan ./mcp-config.json
# 初始化默认 policy 文件
mcp-guardian init
# 根据 policy 检查配置
mcp-guardian check ./mcp-config.json --policy ./mcp-policy.json
```
### 编程 API
```
import { Scanner } from 'mcp-guardian';
const scanner = new Scanner();
const results = await scanner.scan({
mcpServers: {
myServer: {
command: 'node',
args: ['server.js'],
env: { API_KEY: 'hardcoded-secret' },
},
},
});
console.log(`Found ${results.vulnerabilities.length} issues`);
console.log(`Risk score: ${results.score}/100`);
```
## 功能特性
### 漏洞扫描器
检测 5 类安全问题：
| 类别 | 描述 | 严重程度 |
|----------|-------------|----------|
| 命令注入 | Shell 元字符、危险命令 (`eval`, `exec`) | Critical |
| 路径遍历 | `../` 序列、访问敏感文件 (`/etc/passwd`) | High |
| SSRF | 内部 IP 范围、云元数据端点 (`169.254.169.254`) | High |
| 不安全配置 | 硬编码机密、禁用 TLS、生产环境中开启调试模式 | Medium-Critical |
| 权限提升 | `sudo`/特权执行、危险 tool 模式 | High |
### 运行时代理
位于 LLM 客户端和 MCP server 之间的透明代理：
```
import { ProxyServer } from 'mcp-guardian';
const proxy = new ProxyServer({
policyPath: './mcp-policy.json',
target: 'http://localhost:3000',
});
await proxy.start({ port: 8080 });
```
- **Tool call 过滤** —— 阻止或允许特定的 tool call
- **参数清洗** —— 剔除参数中的危险模式
- **速率限制** —— 防止 tool call 被滥用
- **审计日志** —— 记录所有 tool 调用以供审查
### 策略引擎
为每个 server 和 tool 定义细粒度的权限：
```
{
"version": "1.0",
"defaultPolicy": "deny",
"servers": {
"myServer": {
"tools": {
"readFile": {
"permission": "allow",
"constraints": {
"pathPrefix": "/safe/directory/"
}
},
"executeCommand": {
"permission": "deny"
}
}
}
}
}
```
## 架构
```
src/
index.ts # Public API exports
types.ts # Core type definitions
cli.ts # CLI entry point
scanner/
index.ts # Scanner orchestrator
rules/
command-injection.ts
path-traversal.ts
ssrf.ts
insecure-config.ts
permission-escalation.ts
proxy/
index.ts # Runtime proxy server
policy/
types.ts # Policy type definitions
loader.ts # Policy file loader & validator
__tests__/
scanner.test.ts # Scanner test suite
```
## 开发
```
# 安装依赖
npm install
# Build
npm run build
# 运行测试
npm test
# 运行测试并生成 coverage
npm run test:coverage
# Watch 模式
npm run dev
```
## 贡献
欢迎贡献！请开启一个 issue 或提交 pull request。
1. Fork 仓库
2. 创建您的 feature 分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的更改 (`git commit -m 'feat: add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启一个 Pull Request
## 许可证
MIT License - 详情请参阅 [LICENSE](LICENSE) 文件。
标签：AI 安全, CISA项目, GNU通用公共许可证, IP 地址批量处理, Lerna, LLM 安全, MCP, MITM代理, Node.js, PE 加载器, RASP, SSRF 防护, TypeScript, 云安全监控, 命令注入检测, 安全代理, 安全插件, 暗色界面, 权限控制, 模型上下文协议, 沙箱, 策略执行, 网络安全, 网络安全审计, 自动化攻击, 请求响应过滤, 路径遍历检测, 隐私保护, 静态分析, 风险评分