alexandriashai/mcp-guardian
GitHub: alexandriashai/mcp-guardian
一款 MCP 安全扫描器，用于检测 AI 工具描述中的 prompt injection 攻击及敏感信息泄露。
Stars: 5 | Forks: 1
# mcp-guardian
用于检测工具描述中 prompt injection 攻击的 MCP 安全扫描器。
## 检测内容
- **跨工具指令** - 尝试链式调用工具（“before using this tool”、“first call”、“you must execute”）
- **权限提升** - 尝试绕过安全限制（“ignore previous instructions”、“you are now”、“bypass security”）
- **数据泄露** - 尝试向外部发送数据（URL、“send to”、“upload to”）
- **隐蔽指令** - 隐藏在描述中的指令
- **敏感路径访问** - 引用 ~/.ssh、~/.aws、credentials 等
- **编码内容** - Base64、unicode 转义、十六进制编码（潜在的混淆行为）
## 安装
```
npm install mcp-guardian
```
## 使用方法
### CLI - 扫描 MCP 配置
```
# 自动检测 Claude Desktop config
npx mcp-guardian
# 显式 config 路径
npx mcp-guardian /path/to/claude_desktop_config.json
# JSON 输出
npx mcp-guardian --json
```
### CLI - 作为 MCP Server 运行
```
npx mcp-guardian --mcp
```
### Claude Desktop 集成
添加到你的 `claude_desktop_config.json`：
```
{
"mcpServers": {
"mcp-guardian": {
"command": "npx",
"args": ["-y", "mcp-guardian", "--mcp"]
}
}
}
```
### 库用法
```
import {
scanToolDescription,
scanToolDefinitions,
isDescriptionSafe,
verifyToolDefinitions,
} from "mcp-guardian";
// Scan a single tool description
const result = scanToolDescription("my_tool", "Tool description here");
if (result.status === "critical") {
console.error("Potential injection:", result.issues);
}
// Quick safety check
if (!isDescriptionSafe("Before using this tool, first call...")) {
console.warn("Suspicious description detected");
}
// Scan multiple tools
const tools = [
{ name: "tool1", description: "...", schema: {} },
{ name: "tool2", description: "...", schema: {} },
];
const serverResult = scanToolDefinitions(tools, "my-server");
// Tool pinning - detect changes
const pinResult = verifyToolDefinitions(tools);
if (pinResult.status === "changed") {
console.warn("Tool definitions changed:", pinResult.changedTools);
}
```
## 演示
使用内置的中毒工具示例立即体验 mcp-guardian：
```
npx mcp-guardian demo
```
此操作会扫描硬编码的示例，这些示例展示了真实的攻击模式 —— 无需配置文件。
**预期输出：**
```
✅ filesystem (14 tools)
✅ memory (9 tools)
🔴 suspicious-tool (4 tools)
└─ add: sensitive_path (~/.ssh)
└─ format_text: privilege_escalation ("You are now")
└─ search_docs: exfiltration (evil URL), sensitive_path (~/.aws/credentials)
Summary:
📊 Total tools: 27
✅ Clean: 2
⚠️ Warning: 0
🚨 Critical: 1
```
中毒服务器演示了已发表的安全研究中的真实攻击模式。详情请参阅 `examples/poisoned-server/README.md`。
## 检测模式
### 严重级别（38 种模式）
| 类别 | 示例 |
|----------|----------|
| 跨工具指令 | "before using this tool", "first call", "then execute", "always call" |
| 权限提升 | "ignore previous instructions", "override system", "you are now" |
| 数据泄露 | URL, "send to", "post to", "forward to", "upload to" |
### 警告级别（13 种模式）
| 类别 | 示例 |
|----------|----------|
| 敏感路径 | ~/.ssh, ~/.aws, /etc/passwd, .env, api_key |
| 编码内容 | Base64 字符串, unicode 转义, 十六进制编码 |
## Pre-commit 集成
### 使用 pre-commit 框架
添加到你的 `.pre-commit-config.yaml`：
```
repos:
- repo: https://github.com/alexandriashai/mcp-guardian
rev: v1.2.2
hooks:
- id: mcp-guardian
```
### 使用 Husky
添加到 `.husky/pre-commit`：
```
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx mcp-guardian --sync --quiet
```
### 使用 Lefthook
添加到 `lefthook.yml`：
```
pre-commit:
commands:
mcp-guardian:
glob: "claude_desktop_config.json"
run: npx mcp-guardian --sync {staged_files}
```
## 工具锁定
MCP Guardian 包含工具定义锁定功能 - 对工具定义进行 SHA-256 哈希校验以检测篡改：
```
import { verifyToolDefinitions, approveAllTools } from "mcp-guardian";
// Verify tools against stored baseline
const result = verifyToolDefinitions(tools);
// Status: "created" | "verified" | "changed" | "error"
if (result.status === "changed") {
console.log("Modified tools:", result.changedTools);
console.log("New tools:", result.newTools);
console.log("Removed tools:", result.removedTools);
}
// Re-approve all tools (after review)
approveAllTools(tools);
```
清单存储在 `~/.mcp-guardian/tool-manifest.json` 中。
## 研究参考
本工具参考了以下来源的 MCP 安全研究：
- [Invariant Labs - MCP 安全研究](https://invariantlabs.ai)
- [Microsoft - Prompt Injection 攻击](https://microsoft.com/security)
- [Palo Alto Unit 42 - AI 安全](https://unit42.paloaltonetworks.com)
- [Simon Willison - Prompt Injection](https://simonwillison.net)
## 许可证
MIT
标签：DNS 反向解析, GNU通用公共许可证, GraphQL安全矩阵, MCP, MITM代理, Node.js, 云安全监控, 人工智能, 安全扫描器, 文档结构分析, 暗色界面, 用户模式Hook绕过, 自动化攻击, 静态分析