BuildWithAbid/mcp-shield
GitHub: BuildWithAbid/mcp-shield
一个针对 Model Context Protocol 服务器的安全扫描器，检测提示注入、密钥泄露与供应链漏洞并生成评分报告。
Stars: 1 | Forks: 0
```
_____ __ _ __ __
____ ___ _________ / ___// /_ (_)__ / /___/ /
/ __ `__ \/ ___/ __ \ \__ \/ __ \/ / _ \/ / __ /
/ / / / / / /__/ /_/ / ___/ / / / / / __/ / /_/ /
/_/ /_/ /_/\___/ .___/ /____/_/ /_/_/\___/_/\__,_/
/_/
```
# mcp-shield
**Security scanner for Model Context Protocol (MCP) servers**
Find vulnerabilities, prompt injection, secrets leaks, and supply chain attacks in MCP servers — before your AI agent does.
[](https://github.com/BuildWithAbid/mcp-shield/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
[](https://www.npmjs.com/package/@buildwithabid/mcp-shield)
[Quick Start](#quick-start) • [Security Checks](#7-security-checks) • [MCP Server Mode](#mcp-server-mode) • [Documentation](#documentation) • [Contributing](#contributing)
## 为什么选择 mcp-shield？
MCP 服务器已成为 AI 应用程序的新攻击面。近期研究发现：
- **66% 的 MCP 服务器**至少存在一个安全漏洞
- **工具描述注入**是排名第一的攻击向量 — 恶意服务器嵌入隐藏指令来操纵 AI 代理
- **卷款跑路攻击**在用户批准后改变工具行为
- **供应链攻击**通过拼写错误劫持和恶意 npm 包不断增加
**mcp-shield** 是专为 MCP 生态系统设计的安全扫描器。它对任何 MCP 服务器包运行 7 项安全检查，生成评分报告，并可作为 CLI 工具和 MCP 服务器本身使用。
## 快速开始
### 安装与运行
```
# 直接使用 npx 运行（无需安装）
npx @buildwithabid/mcp-shield scan
# 或全局安装
npm install -g @buildwithabid/mcp-shield
```
### 扫描 MCP 服务器
```
# 扫描 npm 包
mcp-shield scan @modelcontextprotocol/server-filesystem
# 扫描本地项目
mcp-shield scan ./my-mcp-server
# 用于 CI/CD 的 JSON 输出
mcp-shield scan @some/mcp-server --format json
# 保存到文件的 Markdown 报告
mcp-shield scan @some/mcp-server --format markdown --output report.md
# 快速扫描（跳过耗时检查，如 rug-pull 检测）
mcp-shield scan @some/mcp-server --quick
```
### 示例输出
```
🛡️ mcp-shield v1.0.0 — MCP Security Scanner
Scanning: @example/mcp-server-db v2.1.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 CRITICAL Supply Chain: Package published 3 days ago
🔴 CRITICAL Tool Injection: Hidden instruction pattern in tool "query"
🟠 HIGH Permissions: Unconstrained shell commands in tool "execute"
🟠 HIGH Secrets: Hardcoded API key in src/config.ts:14
🟡 MEDIUM Dependencies: 2 moderate CVEs in transitive dependencies
🟢 LOW Transport: CORS allows all origins
✅ PASS Rug-Pull: Tool descriptions are static
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Score: 28/100 (FAIL)
3 critical · 2 high · 1 medium · 1 low · 1 pass
```
## 7 项安全检查
mcp-shield 对每个目标运行以下扫描器：
### 1. 依赖项审计
运行 `npm audit` 查找直接和传递依赖项中的已知 CVE。
- 严重级别：关键、高、中、低
- 自动在缺失时生成锁定文件
### 2. 权限与范围检查
分析工具输入模式是否存在过度宽松的权限：
- **无限制的命令执行** — 接受任意命令且无枚举或允许列表的工具
- **无限制的文件路径** — 缺少路径模式约束的工具（存在路径遍历风险）
- **原始 SQL 输入** — 接受原始 SQL 字符串的工具（存在 SQL 注入风险）
- **无限制的 URL** — 缺少 URL 验证的工具（存在 SSRF 风险）
- **eval() / Function()** — 动态代码执行
- **child_process** — 外壳访问
### 3. 工具描述注入检测
扫描工具描述中的提示注入模式：
- 隐藏指令（“忽略之前指令”、“不告诉用户”）
- 角色/人格覆盖（“你现在是”、“扮演为”）
- Unicode 诡计（零宽字符、同形异义词、RTL 覆盖）
- Base64 编码载荷
- Markdown/HTML 注入
- 数据外泄模式
### 4. 卷款跑路检测
检测在批准后可能变更的工具描述：
- 从环境变量或配置加载的描述
- 通过函数调用或网络请求生成的描述
- 定时触发的工具修改（`setTimeout`/`setInterval`）
- 注册后更改工具（`setTools`、`updateTool`）
### 5. 密钥检测
在源代码和 `.env` 文件中查找硬编码密钥：
- AWS 密钥、OpenAI/Anthropic API 密钥、GitHub 令牌
- Stripe、Slack、Google、Twilio、SendGrid 密钥
- 数据库连接字符串、JWT、私钥
- 通用密码/令牌/密钥赋值
- 智能占位符检测（跳过 `"your-key-here"` 等）
### 6. 传输安全检查
检查传输层配置：
- 对远程端点使用 HTTP 而非 HTTPS
- 宽松的 CORS（`Access-Control-Allow-Origin: *`）
- 带有通配符 CORS 源的身份验证令牌
- URL 查询字符串中的身份验证令牌
- 禁用 TLS 验证（`rejectUnauthorized: false`）
- 未受保护的安全路由
### 7. 供应链分析
检查 npm 元数据和包完整性：
- **通过与已知 MCP 包的 Levenshtein 距离进行拼写错误劫持检测**
- 发布不足 30 天的包
- 单维护者风险
- 模仿官方命名的包
- 可疑的安装脚本（`preinstall`、`postinstall`）
- 下载远程代码的脚本
- 缺少仓库声明
## MCP 服务器模式
mcp-shield 也可以作为 MCP 服务器运行，因此 AI 助手可以直接扫描其他 MCP 服务器：
```
# 启动 MCP 服务器
npx @buildwithabid/mcp-shield serve
# 添加到 Claude Code
claude mcp add mcp-shield -- npx @buildwithabid/mcp-shield serve
```
### 可用的 MCP 工具
| 工具 | 描述 |
|------|-------------|
| `scan_package` | 按名称扫描 npm MCP 服务器包 |
| `scan_local` | 扫描本地目录中的安全问题 |
| `get_report` | 获取上次扫描报告（JSON、Markdown 或终端格式） |
## 文档
### CLI 参考
```
Usage: mcp-shield scan [options]
Arguments:
target npm package name or local path to scan
Options:
-f, --format Output format: terminal, json, markdown (default: "terminal")
-o, --output Write report to file instead of stdout
-q, --quick Skip slow checks like rug-pull detection
-h, --help Display help
```
```
Usage: mcp-shield serve [options]
Start mcp-shield as an MCP server (stdio transport)
Options:
-h, --help Display help
```
### 输出格式
| 格式 | 标志 | 适用场景 |
|--------|------|----------|
| 终端 | `--format terminal`（默认） | 人类可读，带颜色和严重性图标 |
| JSON | `--format json` | CI/CD 流水线，程序化访问 |
| Markdown | `--format markdown` | GitHub 问题、拉取请求、维基 |
### 评分系统
每项发现从 100 分中扣除分数：
| 严重级别 | 扣分 | 示例 |
|----------|---------|---------|
| 关键 | -25 | eval() 使用、硬编码 AWS 密钥、拼写错误劫持 |
| 高 | -15 | 无限制的命令执行、提示注入 |
| 中 | -5 | 宽松的 CORS、缺少仓库声明 |
| 低 | -2 | 单维护者、CORS 在本地服务器 |
| 信息 | 0 | 信息性说明 |
| 通过 | 0 | 检查通过 |
**分数 ≥ 70** = 通过。**分数 < 70** = 失败（CI/CD 集成时退出代码为 1）。
### 架构
```
┌─────────────┐
│ CLI / MCP │ (index.ts / mcp-server.ts)
│ Server │
└──────┬───────┘
│
┌──────▼───────┐
│ Orchestrator │ (scanner/index.ts)
│ File Cache │ Collects files once, shares across scanners
└──────┬───────┘
│
┌────────┬───────┼───────┬────────┬────────┬────────┐
▼ ▼ ▼ ▼ ▼ ▼ ▼
┌────────┐┌───────┐┌──────┐┌───────┐┌───────┐┌───────┐┌───────┐
│Secrets ││ Deps ││ Tool ││ Perms ││Rug-Pull││ Trans ││Supply │
│ Leak ││ Audit ││ Desc ││ Check ││Detect ││ Sec ││ Chain │
└────────┘└───────┘└──────┘└───────┘└───────┘└───────┘└───────┘
│ │ │ │ │ │ │
└────────┴───────┴───────┴────────┴────────┴────────┘
│
┌──────▼───────┐
│ Reporter │ Terminal / JSON / Markdown
└──────────────┘
```
所有 7 个扫描器使用 `Promise.allSettled` 并发运行，共享单个文件缓存以获得最佳性能。
## 使用场景
### CI/CD 流水线
```
# 如果 MCP 服务器存在安全问题则构建失败
npx @buildwithabid/mcp-shield scan ./my-mcp-server --format json
# 分数低于 70 时退出代码 1
```
### 安装前检查
```
# 在安装前检查 MCP 服务器包
npx @buildwithabid/mcp-shield scan @unknown/mcp-server-database
```
### 安全审计
```
# 生成安全审查用的 Markdown 报告
npx @buildwithabid/mcp-shield scan @company/internal-mcp-server --format markdown --output audit-report.md
```
### AI 辅助扫描
```
# 让 Claude 在对话中扫描 MCP 服务器
claude mcp add mcp-shield -- npx @buildwithabid/mcp-shield serve
# 然后询问：“扫描 @modelcontextprotocol/server-filesystem 的安全问题”
```
## 贡献
欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取安装说明和指南。
### 需要帮助的方向
- **新的检测模式** — 提示注入技术、密钥格式、危险 API
- **实时服务器扫描** — 连接到正在运行的 MCP 服务器以测试工具响应
- **PyPI / pip 支持** — 扩展到 Python MCP 服务器
- **CI/CD 集成** — GitHub Actions 工作流、预提交钩子
- **文档** — 指南、教程、实际示例
## 相关项目
- [模型上下文协议](https://modelcontextprotocol.io) — 协议规范
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) — 官方 TypeScript SDK
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — 支持 MCP 的 AI 编码助手
## 许可证
[MIT](LICENSE) — 自由用于个人和商业用途。标签：AI安全, AMSI绕过, Chat Copilot, CI, GNU通用公共许可证, MCP, MCP服务器模式, MITM代理, Model Context Protocol, Node.js, npm包安全, NPM审计, Rug-pull攻击, TypeScript, 云安全监控, 供应链攻击, 动态检测, 威胁检测, 安全扫描, 安全报告, 安全插件, 密钥泄露, 工具描述注入, 提示注入, 提示注入防御, 时序注入, 源代码安全, 自动化攻击, 评分报告, 集群管理, 零日漏洞检测, 静态分析