MCP-Claw-Analyzer

# 基于 MCP + OpenClaw 的智能化恶意代码自动化分析平台 ## 项目介绍 --- **参赛赛道**：全国大学生信息安全竞赛作品赛 **团队规模**：4人 **交付形态**：本地一键运行的可执行程序（Windows 平台（兼容家庭版），Linux 平台（主要针对Debian/Ubuntu）） --- ## 一、项目背景 恶意代码分析是网络安全领域的核心工作之一，然而传统分析方式面临三大痛点： - **专业门槛高**：需要资深逆向工程师手工操作多种工具，学习曲线陡峭； - **工具碎片化**：静态分析、动态沙箱、情报查询等工具各自独立，分析人员需在不同工具间反复切换，效率低下； - **环境搭建复杂**：专业分析环境依赖昂贵的商业沙箱或复杂的服务器配置，普通用户难以快速部署。 针对上述问题，我们设计并实现了**一个完全基于开源免费技术栈的本地化智能恶意代码分析平台**。用户只需在普通 Windows 或 Linux 电脑上下载并一键运行，即可获得覆盖"**预处理 → 静态分析 → 动态沙箱 → 情报关联 → 报告生成**"全流程的自动化分析能力。 --- ## 二、技术架构 本项目采用 **"三要素联动"架构**，将前端交互、AI Agent 调度与底层虚拟化隔离深度整合： | 层级 | 技术选型 | 核心职责 | |------|----------|----------| | **前端交互层** | Vue3 + Element Plus + ECharts | 样本上传、分析进度可视化、报告呈现 | | **核心调度层** | OpenClaw 兼容层 / 本地 Skill 注册器 + FastAPI | 任务编排、MCP 服务调用、结果聚合 | | **基础服务层** | Oracle VirtualBox + MCP Stdio 客户端 + 静态分析工具链 | 隔离沙箱环境、分析工具执行、任务状态管理 | ### 2.1 三要素联动设计 ```mermaid graph TB subgraph Virt[" VirtualBox — 隔离沙箱层 "] direction LR V1["内部网络模式<br/>与宿主机外网彻底隔离"] V2["VBoxManage CLI<br/>全生命周期自动化控制"] V3["Clean 快照恢复<br/>每次分析从干净环境启动"] end subgraph MCP[" MCP 协议 — 通信中间层 "] direction LR M1["JSON-RPC 2.0 over Stdio<br/>零网络依赖的本地进程通信"] M2["三类标准化服务接口<br/>静态分析 / 动态沙箱 / 情报关联"] M3["Fallback 回退机制<br/>MCP 不可用时自动占位保活"] end subgraph Agent[" OpenClaw AI Agent — 智能调度层 "] direction LR A1["任务智能编排<br/>五阶段流水线自动衔接"] A2["Skill 注册调度<br/>预处理 / 分析 / 报告统一管理"] A3["双模式自动切换<br/>OpenClaw 不可用 → 本地注册器回退"] end Agent -->|"调度指令"| MCP MCP -->|"工具调用"| Virt Virt -->|"分析结果"| MCP MCP -->|"数据回传"| Agent ``` ### 2.2 关键技术说明 **MCP（Model Context Protocol）** 是 Anthropic 提出的开放协议，旨在标准化 AI 模型与外部工具之间的通信。在本项目中，我们自实现了轻量级 MCP Stdio 客户端，通过 JSON-RPC 2.0 协议在本地子进程间通信，实现了零网络依赖的工具编排。当 MCP 服务未配置时，系统内置的 Fallback 机制自动返回结构化占位数据，确保分析流程完整可运行。 **VirtualBox 集成** 通过 `VBoxManage` 命令行工具实现虚拟机全生命周期管理，支持两种动态分析模式： - **guestcontrol 模式**：通过 VirtualBox Guest Additions 在虚拟机内直接执行命令； - **shared_folder 模式**：通过共享文件夹 + Windows 原生批处理脚本通信（无需 Guest Additions），两者互为回退。 --- ## 三、核心功能与实现 ### 3.1 全自动分析流水线 平台实现了 **5 阶段全自动分析流水线**，用户仅需上传样本即可获得完整分析报告： | 阶段 | 功能 | 实现方式 | |------|------|----------| | **① 样本预处理** | 哈希计算（MD5/SHA1/SHA256）、文件类型识别、香农熵值计算、PE 结构解析（导入表/区段/架构）、加壳检测（UPX/ASPack/Themida 等）、可疑字符串提取 | 本地 Python 实现 | | **② 静态分析** | Capa 行为规则引擎、YARA 规则匹配、FLOSS 字符串提取、pefile 深度解析 | MCP 服务调用 / 本地 Fallback | | **③ 动态沙箱分析** | VirtualBox 隔离虚拟机中执行样本 → 行为监控 → 日志回收 → 行为解析 | VBoxManage 直接控制 | | **④ 情报关联** | VirusTotal 离线缓存查询、IOC 提取与标签标注、威胁家族匹配 | MCP 服务调用 / 本地 Fallback | | **⑤ 报告生成** | 威胁评分（加权多指标 0-100）、JSON 结构化报告 + HTML 可视化报告 | 本地 Skill 实现 | ### 3.2 威胁评分引擎 自主研发了**加权多指标威胁评分系统**（0-100 分制），综合以下维度进行评分： | 指标类别 | 权重区间 | 评分依据 | |----------|:--------:|----------| | PE 结构异常 | +5 ~ +10 | 入口点异常、区段可疑 | | 熵值 | +8 ~ +25 | 高熵值暗示加壳/加密 | | 加壳检测 | +12 ~ +20 | 检测到已知壳特征 | | 可疑字符串 | +8 ~ +30 | URL、PowerShell、API 调用、IP 地址 | | 可疑导入 API | +4 ~ +20 | 网络/进程/注册表相关 API | | 行为指标 | +9 ~ +45 | 进程事件、网络连接 | | 情报标记 | +40 | VirusTotal 检出为恶意 | **威胁等级**：高风险（≥70）/ 中风险（≥35）/ 低风险（<35） ### 3.3 前端可视化 基于 Vue3 + Element Plus + ECharts 实现了三个核心页面： | 页面 | 功能 | |------|------| | **Dashboard** | 环境状态面板（VirtualBox/OpenClaw/快照三指标）、拖拽上传区、分析步骤时间轴 | | **Report** | 摘要卡片（威胁等级/评分/家族）、静态特征面板、动态行为可视化（进程树/ECharts 图表）、IOC 清单、处置建议 | | **About** | 开源致谢与项目信息 | 支持深色/浅色主题切换，Hash 路由模式，所有静态资源由 FastAPI 后端托管。 ### 3.4 REST API 后端基于 FastAPI 实现，提供 6 组 API 共 10 个端点： | 分组 | 端点 | 功能 | |------|------|------| | **上传** | `POST /api/upload/` | 样本上传（自动计算 MD5/SHA256） | | **分析** | `POST /api/analysis/start` | 启动分析任务 | | | `GET /api/analysis/status/{task_id}` | 查询分析状态（9 种状态机） | | **报告** | `GET /api/report/{task_id}` | 获取 JSON 报告 | | | `GET /api/report/{task_id}/export` | 导出 JSON | | | `GET /api/report/{task_id}/html` | 查看 HTML 报告 | | **环境** | `GET /api/environment/status` | VirtualBox/虚拟机/快照状态 | | **Agent** | `GET /api/agent/info` | OpenClaw 后端类型/已注册 Skill | | **VBox** | `GET /api/vbox/status` | 虚拟机详细状态 | | | `POST /api/vbox/restore` | 恢复快照 | | | `POST /api/vbox/execute` | 虚拟机内执行命令 | ### 3.5 任务状态机 ``` PENDING → PREPARING_ENV → STATIC_ANALYSIS → DYNAMIC_ANALYSIS → INTELLIGENCE → GENERATING_REPORT → COMPLETED ↘ 任意阶段异常 → FAILED ``` ### 3.6 VirtualBox 深度集成 | 能力 | 实现 | |------|------| | 环境诊断 | 启动时自动检测 VirtualBox 安装、虚拟机注册、快照可用性、Guest Additions 状态 | | 快照管理 | 恢复快照（带重试机制）、列出快照 | | 生命周期控制 | 无界面启动（30 次轮询等待）、强制关机 | | 命令执行 | guestcontrol 模式（需 Guest Additions）+ shared_folder 模式（纯文件共享） | | 数据交换 | 共享文件夹注入样本、回收日志 | | Guest Session | 多密码回退尝试、最长 120s 的 Session 等待 | | 互斥保护 | 基于 `asyncio.Lock` 的单任务互斥锁，状态机管理（IDLE/PREPARING/RUNNING/CLEANING） | --- ## 四、当前实现状态 ### 4.1 已完成的核心功能 | 模块 | 完成度 | 说明 | |------|:------:|------| | FastAPI 后端框架 | ✅ 100% | 完整 REST API，6 组 10 个端点，CORS 中间件 | | 样本上传 | ✅ 100% | 拖拽上传、自动哈希、12 位任务 ID 生成 | | 样本预处理 Skill | ✅ 100% | 哈希/熵值/PE/字符串/加壳检测，全部本地实现 | | 威胁评分引擎 | ✅ 100% | 加权多指标评分，3 级威胁等级 | | 报告生成 Skill | ✅ 100% | JSON + HTML 双格式，内联 CSS 样式 | | VirtualBox 控制 | ✅ 100% | 700+ 行 VBoxManage CLI 封装，跨平台编码适配 | | VM 生命周期管理 | ✅ 100% | 恢复快照→启动→注入→分析→回收→关机→恢复 | | 双模式动态分析 | ✅ 100% | guestcontrol / shared_folder，自动回退 | | MCP Stdio 客户端 | ✅ 100% | 自实现 JSON-RPC 2.0，零第三方 SDK 依赖 | | MCP Fallback | ✅ 100% | 无 MCP 时自动返回结构化占位数据 | | OpenClaw 兼容层 | ✅ 100% | 可选集成，不可用时回退 LocalAgentRegistry | | 前端 Dashboard | ✅ 100% | 环境面板、拖拽上传、步骤时间轴 | | 前端 Report | ✅ 100% | 摘要卡片、特征面板、行为可视化、IOC 清单 | | 前端 About | ✅ 100% | 开源致谢与项目信息 | | PyInstaller 打包 | ✅ 100% | spec 文件配置、frozen 路径适配、一键启动脚本 | | 环境检测工具 | ✅ 100% | VBox/VM/快照/Guest Additions 四维诊断 | ### 4.2 当前局限性（校赛演示版设计取舍） | 项目 | 当前状态 | 设计说明 | |------|----------|----------| | 数据持久化 | 内存存储（`TASKS = {}` dict） | 校赛演示版不引入数据库，重启后任务清空 | | MCP 服务实际接入 | 仅框架（命令可配，默认 Fallback） | 保证无外部依赖时也能完整演示 | | OpenClaw AI 调度 | 走本地回退路径 | 确保打包版无需额外安装 AI 框架 | | 动态行为解析 | 进程事件/网络连接返回占位数据 | 依赖虚拟机内 Sysmon/tshark 实际部署 | | 情报真实查询 | 返回 `family: "unknown"` | 离线缓存待填充真实样本数据 | | YARA 规则库 | 框架就绪，规则待扩充 | 当前无预置规则文件 | | 测试样本集 | 不存在独立样本目录 | 需准备比赛演示用样本 | | 单元测试 | 仅有 `test_api.py` 冒烟测试 | 待补充 | --- ## 五、创新点与优势 1. **MCP 协议的安全领域创新应用**：首次将 Model Context Protocol 应用于本地恶意代码分析工具编排，通过 JSON-RPC 2.0 over Stdio 实现零网络依赖的标准化服务调用，为安全工具链的互操作性提供了新范式。 2. **完全基于开源技术栈**：从 VirtualBox 隔离环境到分析工具链（Capa/YARA/pefile/FLOSS），所有组件均为开源免费，无商业授权风险，符合国家信息安全自主可控的战略方向。 3. **双模式动态分析 + 优雅回退**：同时支持 guestcontrol（需 Guest Additions）和 shared_folder（无需额外依赖）两种虚拟机交互模式，并设计了 MCP 服务、OpenClaw、Guest Additions 三级回退机制，确保系统在任何环境配置下都能完整运行。 4. **"云服务本地化"理念**：将通常需要商业云端沙箱才能实现的高级分析能力完整迁移到本地环境，全程无需联网，保护用户隐私与样本数据安全。 5. **一体化打包分发**：通过 PyInstaller 将全栈 Python 应用打包为单一可执行文件，内置前端静态资源托管，一键启动即可使用，工程化落地程度高。 --- ## 六、目前存在的不足 经过对现有系统的实际测试与评估，我们识别出以下亟待解决的核心问题： ### 6.1 系统稳定性不足 - **分析成功率不稳定**：同一份样本文件在先后的多次分析中可能出现不同的结果——有时全流程分析成功，有时却在虚拟机操作、日志回收等环节出现超时或失败。根本原因在于 VirtualBox Guest Session 的建立存在偶发性超时、共享文件夹心跳检测机制对环境差异敏感，以及部分操作缺少充分的错误恢复策略。 - **异常处理不够完善**：当 VBoxManage 命令返回非预期格式、虚拟机内脚本执行异常时，系统缺少自动重试与降级处理，直接导致任务失败。 ### 6.2 检测机制过于简陋 - **恶意程序检出率低**：当前静态分析主要依赖基础的 PE 结构解析、熵值计算和简单的字符串匹配。YARA 规则库尚未建立，Capa/FLOSS 等专业工具暂未接入主分析流水线（走 MCP Fallback 路径），导致大量恶意样本的核心行为特征无法被识别，整体检测能力有限。 - **误报率偏高**：正常 PE 文件（如常见的系统工具、安装程序等）在评分引擎下通常也能得到 **30–35 分**的威胁评分（中风险），这与实际恶意程序的评分差距不够显著。原因是评分引擎过度依赖熵值、可疑字符串等泛化指标——正常加壳或加密的合法软件也会产生高熵值与 URL/IP Pattern 字符串，而当前引擎未能有效区分"恶意行为特征"与"合法软件的工程特征"。 - **威胁评分区分度不足**：恶意样本的得分与无害样本的得分区间重叠较多，无法形成清晰的"安全 / 可疑 / 恶意"三级梯度，降低了报告的可信度和实用性。 --- ## 七、项目迭代方案（主要是AI提供的建议） 针对上述不足以及即将参加的全国大学生信息安全竞赛作品赛的要求，我们计划在以下方向进行迭代优化： ### 7.1 稳定性提升（对应 §6.1） | 迭代项 | 具体内容 | 优先级 | |--------|----------|:------:| | **VirtualBox 操作可靠性增强** | 为 VBoxManage 关键操作（快照恢复、Guest Session 建立、共享文件夹挂载）增加自动重试机制（最多 3 次），延长超时容忍阈值 | 🔴 高 | | **分析任务断点恢复** | 分析流程中每个阶段完成后保存中间状态，异常中断后可从失败阶段恢复而非全部重跑 | 🔴 高 | | **心跳检测机制优化** | 将 shared_folder 模式下的心跳轮询改为事件驱动（文件系统 Watch），减少检测延迟并提高稳定性 | 🟡 中 | | **全面异常捕获与降级** | 为 VBoxManage 调用添加输出解析容错，虚拟机操作失败时提供明确的错误原因提示而非简单报错 | 🟡 中 | ### 7.2 检测能力提升（对应 §6.2） | 迭代项 | 具体内容 | 优先级 | |--------|----------|:------:| | **威胁评分引擎重构** | 区分"工程特征指标"（熵值、加壳）与"恶意行为指标"（API调用组合、行为链），降低前者权重、提高后者权重，使正常软件基础分控制在 15 分以内，恶意样本显著拉开差距 | 🔴 高 | | **白名单机制引入** | 建立常见合法软件签名库（微软、Adobe、Google 等数字签名），白名单样本直接跳过或大幅降权 | 🔴 高 | | **YARA 规则库建设** | 编写 30+ 条 YARA 规则，覆盖常见恶意家族（WannaCry、Emotet、AgentTesla、FormBook、LokiBot 等）和行为特征（反调试、进程注入、凭证窃取等） | 🔴 高 | | **Capa/FLOSS 工具接入主流程** | 将 `mcp_services/` 下的 static_analyzer 封装接入编排器主流程，激活 Capa 行为规则匹配与 FLOSS 深度字符串提取，替代当前 Fallback 占位路径 | 🔴 高 | | **测试样本集准备** | 从 MalwareBazaar、VirusShare 等合规仓库收集 10-15 个典型样本（勒索软件、窃密木马、远控木马、键盘记录器等）及 5-8 个正常 PE 样本，用于评分引擎校准和检出率验证 | 🔴 高 | | **情报模块激活** | 填充本地离线缓存数据库，实现 IOC 自动提取、威胁家族关联标注、多源情报交叉验证 | 🟡 中 | | **动态行为解析增强** | 实现 Procmon 日志到进程树的自动解析、tshark pcap 到网络连接表的提取、注册表差异对比 | 🟡 中 | | **行为特征权重引入** | 将动态分析回收的进程事件、网络连接、注册表修改等行为指标正式接入评分引擎，作为高权重恶意判定依据 | 🟡 中 | ### 7.3 架构与功能扩展 | 迭代项 | 具体内容 | 优先级 | |--------|----------|:------:| | **PDF 报告导出** | 集成 WeasyPrint 或浏览器 Headless 模式，实现一键 PDF 导出 | 🟡 中 | | **多格式样本支持** | 扩展预处理 Skill，支持 Office 宏文档（.docm/.xlsm）、PDF、脚本文件（.vbs/.ps1/.js）的分析 | 🟡 中 | | **攻击链图谱可视化** | 基于进程树与网络连接，自动生成 ATT&CK 技术映射和攻击链时序图 | 🟡 中 | | **MCP 服务真实接入** | 将 `mcp_services/` 下的 static_analyzer、yara_manager、sample_library 封装为独立 MCP 服务进程，替代当前 Fallback 路径 | 🟡 中 | | **OpenClaw 生产级集成** | 解决打包版中 openclaw 包的依赖问题，实现真实 AI Agent 智能调度 | 🟢 低 | | **任务持久化** | 引入 SQLite 轻量数据库替代内存 dict，支持历史任务查询与分析记录持久保存 | 🟢 低 | | **批量分析模式** | 支持同时上传多个样本排队分析，显示队列状态与批量统计 | 🟢 低 | | **分析结果对比** | 支持同家族样本的横向对比视图，突出共性与差异 | 🟢 低 | ### 7.4 文档与测试 | 迭代项 | 具体内容 | 优先级 | |--------|----------|:------:| | **竞赛文档规范化** | 技术报告、需求规格说明书、创新点深度阐述、用户手册（图文并茂） | 🔴 高 | | **单元测试补齐** | 为核心模块（预处理 Skill、威胁评分、VBox 控制、MCP 客户端）编写 pytest 单元测试 | 🟡 中 | | **端到端测试** | 在纯净 Windows 10/11 家庭版环境中完成全流程验证 | 🟡 中 | | **演示视频录制** | 5 分钟竞赛演示视频（安装→启动→上传→分析→报告全流程） | 🔴 高 | ### 7.5 安全与合规 | 迭代项 | 具体内容 | 优先级 | |--------|----------|:------:| | **样本合规声明** | 整理所有使用样本来源、开源工具许可证合规文档 | 🔴 高 | | **安全加固** | 确认分析日志中不包含宿主机敏感信息，样本上传后进行完整性校验 | 🟡 中 | --- ## 八、技术栈总览 | 模块 | 技术选型 | 版本/说明 | |------|----------|-----------| | 后端框架 | FastAPI + Uvicorn | 最新稳定版 | | AI Agent | OpenClaw 兼容层 + 本地 Skill 注册器 | 双模式自动切换 | | 通信协议 | MCP (Model Context Protocol) over Stdio | JSON-RPC 2.0 自实现 | | 前端框架 | Vue3 + Vite | Vue 3.5.x | | UI 组件库 | Element Plus | 2.9.x | | 可视化图表 | ECharts | 5.6.x | | 状态管理 | Pinia | 2.3.x | | 隔离环境 | Oracle VirtualBox 7.x | VBoxManage CLI | | 打包分发 | PyInstaller | --onefile 模式 | | Python 版本 | 3.9+ | | | Node.js | 18+ | 仅前端构建时需 | ### 宿主机静态分析工具 | 工具 | 用途 | |------|------| | **pefile** | PE 文件结构解析（区段、导入/导出表、入口点、架构） | | **Capa** | FLARE 行为规则引擎，识别恶意代码高层行为能力（如进程注入、凭证窃取） | | **YARA** | 基于规则的恶意代码模式匹配，检测恶意家族与行为特征 | | **FLOSS** | 提取可执行文件中的明文字符串与解码后的混淆字符串 | ### 虚拟机内（Windows 分析环境）动态监控工具 | 工具 | 用途 | |------|------| | **Sysmon** | Windows 系统级进程创建、网络连接、文件操作、注册表修改的详细事件日志 | | **Procmon** | 实时监控进程/线程/文件系统/注册表活动，生成进程树与行为链 | | **tshark** | 命令行网络流量捕获工具，记录恶意样本运行期间的所有网络请求 | | **Regshot** | 注册表快照对比工具，捕获样本执行前后的注册表变更差异 | --- ## 九、合规声明 本项目所使用的恶意代码样本均来源于公开合规的恶意软件仓库（如 MalwareBazaar、VirusShare），仅用于学术研究与技术验证。分析过程完全在用户本地的 VirtualBox 隔离虚拟机中进行，虚拟机采用"内部网络"模式，与宿主机和外网完全隔离，样本不会主动传播或对用户系统造成危害。项目包含的开源工具均遵循其原始许可证（GPLv2、MIT、Apache 等），使用合规。