angelica-han/MCP-Security-Analysis-Multi-Agent

# MCP 安全分析多智能体 一个由 LangGraph 驱动的多智能体系统，用于分析 MCP (Model Context Protocol) 项目目录中的安全漏洞，并生成带有证据支撑的报告。 ## 功能介绍 将其指向任何 MCP 服务端/客户端项目目录，它将会： 1. **扫描目录** — 盘点所有源文件并过滤掉干扰信息 2. **分析项目概况** — 了解项目暴露了哪些 MCP 功能，以及信任边界在哪里 3. **提取代码特征** — 使用静态分析（AST + 正则表达式）查找危险模式，如 shell 调用、文件访问和网络请求 4. **运行风险智能体** — 专门的智能体并行扫描不同的漏洞类别（目前已有四个可用，计划推出第五个） 5. **评估质量** — Evaluator 会检查每项发现是否都有真实证据；低置信度的发现会被标记或退回重新扫描 6. **生成报告** — 输出结构化的 Markdown + JSON，包含证据链、攻击路径和修复建议 ## 风险类别 | 智能体 | 检测内容 | |---|---| | Prompt 注入 | 进入系统提示词或工具描述的用户/远程内容 | | 命令执行 | `shell=True`、命令拼接、未经验证的参数 | | 文件访问 | 路径遍历、敏感目录读取、缺少白名单 | | 网络请求 | SSRF、任意 URL、内网访问 | | 生命周期 *(计划中)* | 会话状态泄漏、清理不完整、日志泄漏 | ## 技术栈 - **LangGraph** — 多智能体编排（StateGraph、条件路由、反馈循环） - **Pydantic** — 用于所有智能体间数据的类型化 schema；防止产生虚构证据 - **Python AST 模块** — 确定性的代码特征提取（无需 LLM 猜测） - **LangChain / LLM 层** *(V2)* — 用于功能分析、supervisor 路由和报告生成的语义解释；所有 V1 智能体均为确定性的基于规则的实现 ## 项目结构 ``` mcp_security_agent/ ├── schemas.py # All data structures (GraphState, RiskFinding, etc.) ├── graph.py # LangGraph graph: nodes, edges, conditional routing ├── cli.py # Command-line entry point ├── agents/ │ ├── functional.py # Capability analysis agent │ ├── risk_prompt_injection.py │ ├── risk_command.py │ ├── risk_file.py │ ├── risk_network.py │ ├── risk_lifecycle.py │ ├── evaluator.py │ └── reporter.py └── tools/ ├── file_inventory.py # Directory walker and file filter ├── ast_scanner.py # Python AST-based feature extraction └── regex_scanner.py # Pattern matching for JS/TS and config files results/ # Output reports land here (gitignored) sample_mcp_server/ # Deliberately vulnerable MCP server used as scan target tests/fixtures/ # Test fixtures ``` ## 快速开始 ``` # 安装依赖 pip install langgraph pydantic # 针对示例漏洞服务器运行完整 pipeline python -m mcp_security_agent.graph ``` 目前不需要 API key — 当前的风险智能体使用确定性的静态分析（AST + 正则表达式），而不是 LLM 调用。报告会写入 `results/` 目录。 ## 当前状态 | 组件 | 状态 | |---|---| | 项目结构 | ✅ 完成 | | Pydantic schema | ✅ 完成 | | LangGraph 图 | ✅ 完成 — 所有节点已连接，完整 pipeline 端到端运行 | | 目录盘点 | ✅ 完成 | | 代码特征提取（AST 扫描器） | ✅ 完成 | | 风险智能体：命令、文件、网络、Prompt 注入 | ✅ 完成 — 真正的静态分析逻辑 | | 功能分析智能体 (`functional.py`) | ✅ 完成 — 基于规则，从 AST 特征推断项目类型 + 敏感功能 | | Supervisor 路由 | ✅ 完成 — 仅根据检测到的功能激活相关的扫描类别 | | Evaluator 智能体 | ✅ 完成 — 置信度阈值、基于邻近度的去重、覆盖盲区检测、重运行循环 | | Reporter 智能体 | ✅ 完成 — 包含严重性分组、行动计划 (P0/P1/P2)、覆盖说明的结构化 Markdown | | 风险智能体：生命周期 | ⏳ 计划中 — 会话状态泄漏、清理不完整、日志泄漏 | | 正则表达式扫描器（针对 JS/TS 目标） | ⏳ 计划中 | | CLI 入口点 | ⏳ 计划中 | ## 设计原则 - **证据优先：** 每个 `RiskFinding` 都必须包含文件路径、代码行范围和代码片段 — 没有证据的发现会被 Evaluator 拒绝 - **确定性优先于 LLM：** 文件扫描、AST 解析和正则表达式匹配作为普通的 Python 工具运行；LLM 仅负责语义解释和风险说明 - **结构化输出：** 所有智能体输出都是类型化的 Pydantic 模型，而不是自由文本 — 这使得自动化测试和下游处理成为可能 - **可重放：** 图可以从中间 JSON 重新生成报告，便于调试和演示

标签：DLL 劫持, GraphQL安全矩阵, LangGraph, PyRIT, Python, 多智能体系统, 大语言模型, 安全专业人员, 安全扫描器, 无后门, 网络安全审计, 自动化payload嵌入, 逆向工具, 错误基检测, 静态代码分析