highflame-ai/ramparts
GitHub: highflame-ai/ramparts
Ramparts 是一款面向Model Context Protocol（MCP）服务器和AI智能体技能的安全扫描器，用于发现间接攻击向量和配置漏洞。
Stars: 87 | Forks: 17
# Ramparts：面向 MCP 服务器与 AI 智能体技能的安全扫描器
*一款快速、轻量的安全扫描器，专为智能体技术栈设计——覆盖 Model Context Protocol (MCP) 服务器与 AI 智能体技能（Claude Code 命令、[agentskills.io](https://github.com/agentskills/agentskills) 包、Cursor / Codex / Windsurf / Gemini 等效工具）——内置漏洞检测能力。*
[](https://crates.io/crates/ramparts)
[](https://github.com/highflame-ai/ramparts)
[](LICENSE)
[](https://www.rust-lang.org/)
[](https://github.com/highflame-ai/ramparts/actions)
[](https://github.com/highflame-ai/ramparts/actions)
[](https://github.com/highflame-ai/ramparts/releases)
## 概述
**Ramparts** 扫描 AI 智能体最为信任的两个层面：其通过网络通信的 **MCP 服务器**，以及从磁盘加载并按名执行的 **技能文件**。两者都会将不可信的指令和工具授权引入智能体的运行循环；Ramparts 为此应用相同的安全流水线（YARA、LLM 分析、OWASP MCP Top 10 标签）进行检测。
- **MCP 扫描** 覆盖 [Model Context Protocol](https://modelcontextprotocol.io) ——一种开放标准，允许 AI 助手通过工具调用连接数据库、文件系统和 API。Ramparts 能发现服务器的工具、资源和提示词，并审计其中存在的提示词注入、工具投毒、密钥泄露、路径遍历、命令注入、跨域权限提升、供应链 CVE（通过 OSV.dev）等问题。
- **技能扫描** 覆盖智能体作为命名能力加载的 markdown/YAML 文件——包括 Claude Code 自定义斜杠命令、Cursor / Codex / Windsurf / Gemini 等效工具，以及**对 [agentskills.io](https://github.com/agentskills/agentskills) 包的首要支持**（包含 `scripts/`、`references/`、`assets/` 同级目录的 `
/SKILL.md` 目录结构）。每个技能正文都作为一个合成的 MCP 提示词，通过相同的分析器运行；捆绑脚本通过 YARA 扫描；名称与目录不匹配的问题将作为高严重性欺骗发现暴露；同时会验证 agentskills.io 的名称和字符集规则。
Ramparts 正在积极开发中。请阅读我们的[发布博客](https://www.getjavelin.com/blogs/ramparts-mcp-scan)。
### 安全挑战
MCP 与技能构成的攻击面非常广泛。MCP 服务器暴露了文件系统、数据库、API 和系统命令——若缺乏适当分析，可能通过工具投毒、命令注入和数据泄露成为攻击向量。智能体技能具有相同的风险特征（智能体可能遵循的不可信指令），同时还有其独特之处：技能文件中的 `allowed-tools` 授权可能授予无限制的 `Bash` 权限；敏感的 `@` 引用可能将凭证内联到提示词上下文；名称冲突可能使一个技能在智能体路由中覆盖另一个技能；而捆绑脚本会携带任意可执行代码。📚 **[安全特性与攻击向量](docs/security-features.md)** 详细记录了 Ramparts 提供的所有检测器——涵盖 MCP 和技能扫描。
### Ramparts 的功能
Ramparts 通过以下方式提供对 MCP 与技能生态系统的**安全扫描**：
1. **MCP 服务器发现与分析** ——扫描 MCP 端点以发现工具、资源和提示词；支持多传输协议（HTTP、SSE、stdio、subprocess），具备智能回退和会话管理
2. **技能扫描** ——将相同的威胁模型应用于磁盘上的智能体技能文件（Claude Code 命令、agentskills.io 包（包括捆绑的 `scripts/` 和 `references/`）、Cursor / Codex / Windsurf / Gemini 变体）
3. **静态分析 (YARA)** ——在两个扫描表面提供超过 25 条预/后扫描规则，包括 9 条专门针对技能的规则（提示词注入变种、凭证收割、工具链泄露、系统操纵、权限滥用）
4. **LLM 驱动的分析** ——识别静态规则无法捕捉的复杂语义问题（如工具描述隐瞒真实行为、隐蔽的权限请求等）
5. **跨域分析** ——检测跨越多个域的工具，这是一个上下文劫持/注入向量
6. **供应链覆盖** ——查询 OSV.dev 以获取通过 npx/uvx 启动的 stdio MCP 服务器中的已知 CVE
7. **结构化技能启发式规则** ——过于宽泛的 `allowed-tools` 授权、模糊/通用的触发器、敏感的 `@` 引用、嵌入的 base64/hex 载荷、技能名称冲突
8. **agentskills.io 规范验证** ——目录与 `name:` 字段不匹配（欺骗）、规范名称规则违规、未知的 frontmatter 字段
9. **OWASP MCP Top 10 标签** ——每个发现都映射到版本化的 OWASP MCP Top 10 条目；在终端、JSON、SARIF 和 markdown 报告输出中可见
10. **多种输出格式** ——终端、JSON、**SARIF 2.1.0**（适用于 GitHub Advanced Security / GitLab / Azure DevOps）以及详细的 markdown 报告
## 目标用户
- **MCP 用户** ——在连接前扫描第三方 MCP 服务器；在生产环境部署前验证本地服务器
- **MCP 开发者** ——确保您的工具、资源和提示词不会向 AI 智能体暴露漏洞
- **技能作者** ——在发布前根据规范验证 agentskills.io 包；捕获 `.claude/commands/` 或捆绑 `scripts/` 中过于宽泛的工具授权和敏感文件引用
- **智能体运维人员** ——扫描团队编写或安装的技能；检查是否有包在具有欺骗性的目录名下被替换；将发现暴露到现有的 SARIF/代码扫描工作流中
## 使用场景
- **安全审计** ——全面评估 MCP 服务器的安全态势或技能代码库的安全性
- **开发辅助** ——在构建 MCP 服务器或编写技能时获得快速反馈
- **CI/CD 集成** ——对添加技能或更改 MCP 服务器配置的 PR 进行门控（SARIF 可直接流入 GitHub 代码扫描、GitLab、Azure DevOps）
- **合规性** ——通过带有 OWASP MCP Top 10 标签的证据，满足 AI 智能体部署的安全要求
## 快速开始
**安装**
```
cargo install ramparts
```
Ramparts 有两个顶层扫描面。选择与您所保护内容相匹配的一个（或两者都选）。
### 1. 扫描 MCP 服务器
```
# A specific MCP server (HTTP)
ramparts scan https://api.githubcopilot.com/mcp/ --auth-headers "Authorization: Bearer $TOKEN"
# stdio / subprocess MCP servers
ramparts scan "stdio:npx:mcp-server-commands"
ramparts scan "stdio:python3:/path/to/mcp_server.py"
# Auto-discover and scan every MCP server in your IDE configs
# (Cursor, Windsurf, VS Code, Claude Desktop, Claude Code, Cline)
ramparts scan-config
# Generate a detailed markdown report (scan_YYYYMMDD_HHMMSS.md)
ramparts scan-config --report
# Or walk a checked-in configs-only repo (great for CI)
ramparts scan-config --root ./ide-configs
```
### 2. 扫描 AI 智能体技能
```
# A single skill file or every *.md skill under a directory
ramparts skills scan ./.claude/commands
# An agentskills.io bundle directory — picks up SKILL.md +
# walks sibling scripts/ and references/ through YARA
ramparts skills scan ./my-skill-bundle
# Auto-discover skills across every supported ecosystem at the user
# and workspace level (.claude/, .cursor/, .codex/, .windsurf/,
# .gemini/, .openai/, ~/.skills/, probe-gated ./skills/).
# Add extra roots without rebuilding via RAMPARTS_SKILL_ROOTS=path1,path2.
ramparts skills scan-config
# SARIF output for code-scanning ingestion
ramparts skills scan ./.claude/commands --format sarif > skills.sarif
```
**开箱即用的技能格式：**
- **Claude Code 自定义斜杠命令** ——位于 `.claude/commands/` 下的扁平 `.md` 文件（支持用户级和工作区级）
- **[agentskills.io](https://github.com/agentskills/agentskills) 包** ——
包含 `/SKILL.md` 的目录，可选的同级 `scripts/`（`.py` / `.sh`
/ `.bash` / `.zsh` / `.js` / `.mjs` / `.cjs` / `.ts` / `.rb` / `.pl` / `.ps1`），
`references/`（`.md`）和 `assets/`。包模式还会根据规范验证 `name:` 字段与父目录名是否一致，以及是否遵循 1–64 字符长度、
`[a-z0-9-]` 字符集的规则，并将名称与目录不匹配的问题作为高严重性欺骗发现（`AgentskillsNameMismatch`）暴露。
- **Cursor / OpenAI Codex / Windsurf / Gemini** 技能仓库，其采用相同的
markdown + YAML frontmatter 格式——通过共享的 frontmatter 字段和各自生态系统的点目录发现根路径进行支持。
### 作为 MCP 服务器运行 (stdio)
```
ramparts mcp-stdio
```
发布到 Docker MCP Toolkit 时，请将容器命令配置为 `ramparts mcp-stdio`，以便工具包通过 stdio 连接。使用 `MCP-Dockerfile` 将其设为默认值。
## 输出示例
**单服务器扫描：**
```
ramparts scan https://api.githubcopilot.com/mcp/ --auth-headers "Authorization: Bearer $TOKEN"
```
```
RAMPARTS
MCP Security Scanner
Version: 0.7.0
Current Time: 2025-08-04 07:32:19 UTC
Git Commit: 9d0c37c
🌐 GitHub Copilot MCP Server
✅ All tools passed security checks
└── push_files ✅ passed
└── create_or_update_file ⚠️ 2 warnings
│ └── 🟠 HIGH (LLM): Tool allowing directory traversal attacks
│ └── 🟠 HIGH (YARA): EnvironmentVariableLeakage
└── get_secret_scanning_alert ⚠️ 1 warning
│ └── 🟠 HIGH (YARA): EnvironmentVariableLeakage
Summary:
• Tools scanned: 83
• Security issues: 3 findings
```
**IDE 配置扫描：**
```
ramparts scan-config --report
```
```
🔍 Found 3 IDE config files:
✓ vscode IDE: /Users/user/.vscode/mcp.json
✓ claude IDE: /Users/user/Library/Application Support/Claude/claude_desktop_config.json
✓ cursor IDE: /Users/user/.cursor/mcp.json
📁 vscode IDE config: /Users/user/.vscode/mcp.json (2 servers)
└─ github-copilot [HTTP]: https://api.githubcopilot.com/mcp/
└─ local-tools [STDIO]: stdio:python[local-mcp-server]
🌍 MCP Servers Security Scan Summary
────────────────────────────────────────────────────────────
📊 Scan Summary:
• Servers: 2 total (2 ✅ successful, 0 ❌ failed)
• Resources: 81 tools, 0 resources, 2 prompts
• Security: ✅ All servers passed security checks
📄 Detailed report generated: scan_20250804_073225.md
```
**技能扫描（agentskills.io 包）：**
```
ramparts skills scan ./my-skill
```
```
Path: ./my-skill
❌ 1 skill scanned, 4 findings (2 CRITICAL, 2 HIGH) · 0.6s
⚠️ evil-skill (4 findings)
source: ./my-skill/SKILL.md
[HIGH] SecretsLeakage in scripts/exfil.py [OWASP: MCP06, MCP09]
Detects potential exposure of sensitive information like API keys, passwords, and tokens
[CRITICAL] SSHKeyExposure in scripts/exfil.py [OWASP: MCP06]
Detects SSH keys, authorized_keys files, and SSH configuration access
[CRITICAL] SSHKeyExposure in references/api.md [OWASP: MCP06]
Detects SSH keys, authorized_keys files, and SSH configuration access
[HIGH] AgentskillsNameMismatch [OWASP: MCP02]
SKILL.md declares `name: evil-skill` but its parent directory is `my-skill/`.
agentskills.io requires the name to match the parent directory; the mismatch may
indicate a deceptively-named bundle.
```
（`AgentskillsNameMismatch` 来自 agentskills.io 规范验证；`SecretsLeakage` / `SSHKeyExposure` 行是捆绑脚本的 YARA 发现——
Ramparts 自动扫描了 `scripts/exfil.py` 和 `references/api.md`。）
## 贡献
我们欢迎对 Ramparts 的贡献。如果您有建议、错误报告或功能请求，请在我们的 GitHub 仓库中提交 issue。
## 文档
- 📖 **[CLI 参考](docs/cli.md)** ——所有命令（scan, scan-config, skills scan, skills scan-config, replay, server, mcp-stdio）、选项和用法示例
- 🛡️ **[安全特性与攻击向量](docs/security-features.md)** ——Ramparts 提供的所有检测器，涵盖 MCP + 技能扫描
- ⚙️ **[配置参考](docs/configuration.md)** ——完整的配置文件文档 + 技能发现根路径配置
- 🔍 **[故障排除指南](docs/troubleshooting.md)** ——常见问题的解决方案
- 📚 **[详细特性](docs/features.md)** ——每项功能在底层是如何工作的
## 其他资源
- [需要帮助？](https://github.com/highflame-ai/ramparts/issues)
- [MCP 协议文档](https://modelcontextprotocol.io/)
// 示例文件夹已移除以减少分支差异；请参阅配置文档。
- [配置指南](docs/configuration.md)标签：AI安全, Chat Copilot, DNS信息、DNS暴力破解, DNS枚举, GraphQL安全矩阵, LLM分析, MCP协议扫描, OWASP安全标准, Rust编程, YARA规则, 代理技能扫描, 可视化界面, 安全扫描器, 攻击向量分析, 网络安全工具, 聊天机器人, 通知系统, 间接攻击防护