MCP-Claw-Analyzer

# Tool List ## Project Introduction --- **Competition Track**: National College Student Information Security Competition Work Competition **Team Size**: 4 people **Delivery Form**: Local one-click executable program (Windows platform (compatible with Home Edition), Linux platform (mainly for Debian/Ubuntu)) --- ## I. Project Background Malware analysis is one of the core tasks in the field of network security. However, traditional analysis methods face three major pain points: - **High Professional Threshold**: Requires experienced reverse engineers to manually operate multiple tools, with a steep learning curve; - **Tool Fragmentation**: Static analysis, dynamic sandbox, intelligence query, and other tools are independent of each other, requiring analysts to switch between different tools repeatedly, resulting in low efficiency; - **Complex Environment Setup**: Professional analysis environments rely on expensive commercial sandboxes or complex server configurations, making it difficult for ordinary users to deploy quickly. To address these issues, we designed and implemented **a localized intelligent malware analysis platform based entirely on open-source free technology stacks**. Users only need to download and run on a regular Windows or Linux computer with one click to obtain a full-process automated analysis capability covering **"preprocessing → static analysis → dynamic sandbox → intelligence association → report generation"**. --- ## II. Technical Architecture This project adopts a **"three-element linkage" architecture**, deeply integrating front-end interaction, AI Agent scheduling, and underlying virtualization isolation: | Level | Technology Selection | Core Responsibility | |------|----------|----------| | **Front-end Interaction Layer** | Vue3 + Element Plus + ECharts | Sample upload, analysis progress visualization, report presentation | | **Core Scheduling Layer** | OpenClaw compatible layer / local Skill registrar + FastAPI | Task orchestration, MCP service invocation, result aggregation | | **Basic Service Layer** | Oracle VirtualBox + MCP Stdio client + static analysis toolchain | Isolated sandbox environment, analysis tool execution, task status management | ### 2.1 Three-Element Linkage Design ```mermaid graph TB subgraph Virt[" VirtualBox — Isolated Sandbox Layer "] direction LR V1["Internal network mode<br/>thoroughly isolated from the host machine's external network"] V2["VBoxManage CLI<br/>full-life cycle automated control"] V3["Clean snapshot recovery<br/>starting from a clean environment every time"] end subgraph MCP[" MCP Protocol — Communication Intermediate Layer "] direction LR M1["JSON-RPC 2.0 over Stdio<br/>zero-network dependency local process communication"] M2["Three types of standardized service interfaces<br/>static analysis / dynamic sandbox / intelligence association"] M3["Fallback mechanism<br/>automatic fallback to a placeholder when MCP is unavailable"] end subgraph Agent[" OpenClaw AI Agent — Intelligent Scheduling Layer "] direction LR A1["Task intelligent orchestration<br/>five-stage pipeline automatic connection"] A2["Skill registration and scheduling<br/>preprocessing / analysis / report unified management"] A3["Dual-mode automatic switching<br/>OpenClaw unavailable → local registrar fallback"] end Agent -->|"scheduling instruction"| MCP MCP -->|"tool invocation"| Virt Virt -->|"analysis result"| MCP MCP -->|"data return"| Agent ``` ### 2.2 Key Technology Description **MCP (Model Context Protocol)** is an open protocol proposed by Anthropic, aiming to standardize communication between AI models and external tools. In this project, we self-implemented a lightweight MCP Stdio client, using the JSON-RPC 2.0 protocol for local inter-process communication, achieving zero-network dependency tool orchestration. When the MCP service is not configured, the system's built-in Fallback mechanism automatically returns structured placeholder data to ensure the analysis process is complete and runnable. **VirtualBox Integration** is achieved through the `VBoxManage` command-line tool, realizing full-life cycle management of virtual machines, supporting two dynamic analysis modes: - **guestcontrol mode**: executing commands directly in the virtual machine through VirtualBox Guest Additions; - **shared_folder mode**: communicating through shared folders + Windows native batch scripts (no Guest Additions required), with both modes serving as fallbacks for each other. --- ## III. Core Functions and Implementation ### 3.1 Fully Automated Analysis Pipeline The platform implements a **5-stage fully automated analysis pipeline**, and users only need to upload samples to obtain a complete analysis report: | Stage | Function | Implementation Method | |------|------|----------| | **① Sample Preprocessing** | Hash calculation (MD5/SHA1/SHA256), file type identification, Shannon entropy calculation, PE structure parsing (import table/section/architecture), packing detection (UPX/ASPack/Themida, etc.), suspicious string extraction | Local Python implementation | | **② Static Analysis** | Capa behavior rule engine, YARA rule matching, FLOSS string extraction, pefile deep parsing | MCP service invocation / local Fallback | | **③ Dynamic Sandbox Analysis** | Executing samples in VirtualBox isolated virtual machines → behavior monitoring → log collection → behavior parsing | VBoxManage direct control | | **④ Intelligence Association** | VirusTotal offline cache query, IOC extraction and labeling, threat family matching | MCP service invocation / local Fallback | | **⑤ Report Generation** | Threat scoring (weighted multi-indicator 0-100), JSON structured report + HTML visual report | Local Skill implementation | ### 3.2 Threat Scoring Engine A **weighted multi-indicator threat scoring system** (0-100 score) was independently developed, comprehensively scoring from the following dimensions: | Indicator Category | Weight Interval | Scoring Basis | |----------|:--------:|----------| | PE structure anomaly | +5 ~ +10 | Entry point anomaly, section suspicion | | Entropy | +8 ~ +25 | High entropy implies packing/encryption | | Packing detection | +12 ~ +20 | Detection of known shell characteristics | | Suspicious string | +8 ~ +30 | URL, PowerShell, API call, IP address | | Suspicious import API | +4 ~ +20 | Network/process/registry-related API | | Behavior indicator | +9 ~ +45 | Process event, network connection | | Intelligence marker | +40 | VirusTotal detected as malicious | **Threat Level**: High risk (≥70) / Medium risk (≥35) / Low risk (<35) ### 3.3 Front-end Visualization Three core pages were implemented based on Vue3 + Element Plus + ECharts: | Page | Function | |------|------| | **Dashboard** | Environment status panel (VirtualBox/OpenClaw/snapshot three indicators), drag-and-drop upload area, analysis step timeline | | **Report** | Summary card (threat level/scoring/family), static feature panel, dynamic behavior visualization (process tree/ECharts chart), IOC list, disposal suggestion | | **About** | Open-source acknowledgment and project information | Supports dark/light theme switching, hash routing mode, and all static resources are hosted by the FastAPI back-end. ### 3.4 REST API The back-end is implemented based on FastAPI, providing 6 groups of APIs with 10 endpoints: | Group | Endpoint | Function | |------|------|------| | **Upload** | `POST /api/upload/` | Sample upload (automatic calculation of MD5/SHA256) | | **Analysis** | `POST /api/analysis/start` | Start analysis task | | | `GET /api/analysis/status/{task_id}` | Query analysis status (9 status machines) | | **Report** | `GET /api/report/{task_id}` | Get JSON report | | | `GET /api/report/{task_id}/export` | Export JSON | | | `GET /api/report/{task_id}/html` | View HTML report | | **Environment** | `GET /api/environment/status` | VirtualBox/virtual machine/snapshot status | | **Agent** | `GET /api/agent/info` | OpenClaw back-end type/registered Skill | | **VBox** | `GET /api/vbox/status` | Virtual machine detailed status | | | `POST /api/vbox/restore` | Restore snapshot | | | `POST /api/vbox/execute` | Execute command in virtual machine | ### 3.5 Task Status Machine ``` PENDING → PREPARING_ENV → STATIC_ANALYSIS → DYNAMIC_ANALYSIS → INTELLIGENCE → GENERATING_REPORT → COMPLETED ↘ Any stage exception → FAILED ``` ### 3.6 VirtualBox Deep Integration | Capability | Implementation | |------|------| | Environment diagnosis | Automatic detection of VirtualBox installation, virtual machine registration, snapshot availability, Guest Additions status during startup | | Snapshot management | Restore snapshot (with retry mechanism), list snapshots | | Life cycle control | Headless startup (30 pollings waiting), forced shutdown | | Command execution | guestcontrol mode (requires Guest Additions) + shared_folder mode (pure file sharing) | | Data exchange | Shared folder injects samples, collects logs | | Guest Session | Multiple password fallback attempts, 120s Session waiting | | Mutual exclusion protection | Based on `asyncio.Lock` single-task mutex lock, status machine management (IDLE/PREPARING/RUNNING/CLEANING) | --- ## IV. Current Implementation Status ### 4.1 Completed Core Functions | Module | Completion | Description | |------|:------:|------| | FastAPI back-end framework | ✅ 100% | Complete REST API, 6 groups 10 endpoints, CORS middleware | | Sample upload | ✅ 100% | Drag-and-drop upload, automatic hash, 12-bit task ID generation | | Sample preprocessing Skill | ✅ 100% | Hash/entropy/PE/string/packing detection, all locally implemented | | Threat scoring engine | ✅ 100% | Weighted multi-indicator scoring, 3-level threat level | | Report generation Skill | ✅ 100% | JSON + HTML dual format, inline CSS style | | VirtualBox control | ✅ 100% | 700+ line VBoxManage CLI encapsulation, cross-platform code adaptation | | VM life cycle management | ✅ 100% | Restore snapshot → start → inject → analyze → collect → shut down → restore | | Dual-mode dynamic analysis | ✅ 100% | guestcontrol / shared_folder, automatic fallback | | MCP Stdio client | ✅ 100% | Self-implemented JSON-RPC 2.0, zero third-party SDK dependency | | MCP Fallback | ✅ 100% | Automatic return of structured placeholder data when MCP is unavailable | | OpenClaw compatible layer | ✅ 100% | Optional integration, fallback to LocalAgentRegistry when unavailable | | Front-end Dashboard | ✅ 100% | Environment panel, drag-and-drop upload, step timeline | | Front-end Report | ✅ 100% | Summary card, feature panel, behavior visualization, IOC list | | Front-end About | ✅ 100% | Open-source acknowledgment and project information | | PyInstaller packaging | ✅ 100% | spec file configuration, frozen path adaptation, one-click startup script | | Environment detection tool | ✅ 100% | VBox/VM/snapshot/Guest Additions four-dimensional diagnosis | ### 4.2 Current Limitations (Design Trade-offs for School Competition Demo) | Item | Current Status | Design Description | |------|----------|----------| | Data persistence | In-memory storage (`TASKS = {}` dict) | School competition demo does not introduce database, task clearing after restart | | MCP service actual access | Only framework (commands can be configured, default Fallback) | Ensures complete demonstration without external dependencies | | OpenClaw AI scheduling | Walks local fallback path | Ensures packaged version does not require additional AI framework installation | | Dynamic behavior parsing | Process events/network connections return placeholder data | Depends on actual deployment of Sysmon/tshark in virtual machines | | Intelligence real query | Returns `family: "unknown"` | Offline cache to be filled with real sample data | | YARA rule library | Framework ready, rules to be expanded | Currently no preset rule file | | Test sample set | No independent sample directory | Need to prepare competition demo samples | | Unit testing | Only `test_api.py` smoke test | To be supplemented | --- ## V. Innovation Points and Advantages 1. **Innovative Application of MCP Protocol in Security Domain**: For the first time, the Model Context Protocol is applied to local malware analysis tool orchestration, achieving zero-network dependency standardized service invocation through JSON-RPC 2.0 over Stdio, providing a new paradigm for the interoperability of security toolchains. 2. **Completely Based on Open-Source Technology Stack**: From VirtualBox isolated environment to analysis toolchain (Capa/YARA/pefile/FLOSS), all components are open-source and free, without commercial authorization risk, aligning with the national strategy of information security autonomy and controllability. 3. **Dual-Mode Dynamic Analysis + Elegant Fallback**: Supports both guestcontrol (requires Guest Additions) and shared_folder (no additional dependencies) virtual machine interaction modes, and designs MCP service, OpenClaw, Guest Additions three-level fallback mechanism, ensuring the system can run completely in any environment configuration. 4. **"Cloud Service Localization" Concept**: Completely migrates high-level analysis capabilities that usually require commercial cloud-end sandboxes to the local environment, without networking, protecting user privacy and sample data security. 5. **Integrated Packaging and Distribution**: Packs the full-stack Python application into a single executable file through PyInstaller, with built-in front-end static resource hosting, one-click startup, and high engineering landing degree. --- ## VI. Current Shortcomings After actual testing and evaluation of the existing system, we identified the following core issues to be addressed: ### 6.1 Insufficient System Stability - **Unstable Analysis Success Rate**: The same sample file may have different results in multiple analyses - sometimes the entire process analysis is successful, sometimes it fails in virtual machine operation, log collection, and other links. The root cause is that VirtualBox Guest Session establishment has occasional timeouts, shared folder heartbeat detection mechanism is sensitive to environmental differences, and some operations lack sufficient error recovery strategies. - **Insufficient Exception Handling**: When VBoxManage command returns non-expected format, virtual machine script execution exception, the system lacks automatic retry and downgrade processing, directly leading to task failure. ### 6.2 Detection Mechanism is Too Simple - **Low Malware Detection Rate**: Current static analysis mainly relies on basic PE structure parsing, entropy calculation, and simple string matching. YARA rule library has not been established, Capa/FLOSS and other professional tools have not been connected to the main analysis pipeline (walking MCP Fallback path), resulting in the core behavior characteristics of a large number of malicious samples cannot be identified, and the overall detection ability is limited. - **High False Positive Rate**: Normal PE files (such as common system tools, installers, etc.) can also get **30-35** threat scores under the scoring engine (medium risk), which is not significantly different from the actual malicious program scoring. The reason is that the scoring engine overly relies on entropy, suspicious strings, and other generalized indicators - normal packing or encryption of legitimate software will also produce high entropy and URL/IP Pattern strings, while the current engine fails to effectively distinguish between "malicious behavior characteristics" and "legitimate software engineering characteristics". - **Threat Scoring Distinguishability is Insufficient**: The score of malicious samples and harmless samples overlaps greatly, unable to form a clear "security / suspicious / malicious" three-level gradient, reducing the credibility and practicality of the report. --- ## VII. Project Iteration Plan (mainly suggestions provided by AI) To address the above shortcomings and the requirements of the upcoming National College Student Information Security Competition Work Competition, we plan to iterate and optimize in the following directions: ### 7.1 Stability Improvement (corresponding to §6.1) | Iteration Item | Specific Content | Priority | |--------|----------|:------:| | **VirtualBox Operation Reliability Enhancement** | Add automatic retry mechanism (up to 3 times) for critical VBoxManage operations (snapshot recovery, Guest Session establishment, shared folder mounting), extend timeout tolerance threshold | 🔴 High | | **Analysis Task Breakpoint Recovery** | Save intermediate state after each stage of analysis process, can recover from failed stage instead of re-running all | 🔴 High | | **Heartbeat Detection Mechanism Optimization** | Change shared_folder mode heartbeat polling to event-driven (file system Watch), reduce detection delay and improve stability | 🟡 Medium | | **Comprehensive Exception Capture and Downgrade** | Add output parsing fault tolerance for VBoxManage calls, provide clear error reason prompt instead of simple error reporting | 🟡 Medium | ### 7.2 Detection Capability Improvement (corresponding to §6.2) | Iteration Item | Specific Content | Priority | |--------|----------|:------:| | **Threat Scoring Engine Reconstruction** | Distinguish between "engineering characteristics indicators" (entropy, packing) and "malicious behavior indicators" (API call combination, behavior chain), reduce the weight of the former, increase the weight of the latter, make the basic score of normal software control within 15 points, and significantly open up the gap for malicious samples | 🔴 High | | **Introduction of Whitelist Mechanism** | Establish a common legitimate software signature library (Microsoft, Adobe, Google, etc. digital signatures), whitelist samples directly skip or greatly reduce weight | 🔴 High | | **YARA Rule Library Construction** | Write 30+ YARA rules, covering common malicious families (WannaCry, Emotet, AgentTesla, FormBook, LokiBot, etc.) and behavior characteristics (anti-debugging, process injection, credential theft, etc.) | 🔴 High | | **Capa/FLOSS Tool Access to Main Process** | Encapsulate static_analyzer under `mcp_services/` and access to the orchestrator main process, activate Capa behavior rule matching and FLOSS deep string extraction, replace the current Fallback placeholder path | 🔴 High | | **Test Sample Set Preparation** | Collect 10-15 typical samples (ransomware, spyware, remote control Trojan, keylogger, etc.) and 5-8 normal PE samples from MalwareBazaar, VirusShare and other compliant warehouses, for scoring engine calibration and detection rate verification | 🔴 High | | **Intelligence Module Activation** | Fill local offline cache database, realize IOC automatic extraction, threat family association labeling, multi-source intelligence cross-validation | 🟡 Medium | | **Dynamic Behavior Parsing Enhancement** | Realize Procmon logs to process tree automatic parsing, tshark pcap to network connection table extraction, registry difference comparison | 🟡 Medium | | **Behavior Characteristics Weight Introduction** | Dynamically analyze the recovered process events, network connections, registry modifications and other behavioral indicators to access the scoring engine as high-weight malicious judgment basis | 🟡 Medium | 7.3 Architecture and Function Extension | Iteration Item | Specific Content | Priority | |--------|----------|:------:| | **PDF Report Export** | Integrate WeasyPrint or browser Headless mode to achieve one-click PDF export | 🟡 Medium | | **Multi-format Sample Support** | Extend preprocessing Skill to support Office macro documents (.docm/.xlsm), PDFs, script files (.vbs/.ps1/.js) analysis | 🟡 Medium | | **Attack Chain Visualization** | Automatically generate ATT&CK technology mapping and attack chain timeline based on process tree and network connections | 🟡 Medium | | **MCP Service Real Access** | Encapsulate static_analyzer, yara_manager, and sample_library under `mcp_services/` as independent MCP service processes, replacing the current Fallback path | 🟡 Medium | | **OpenClaw Production-level Integration** | Solve the dependency issue of the openclaw package in the packaged version and implement real AI Agent intelligent scheduling | 🟢 Low | | **Task Persistence** | Introduce SQLite lightweight database to replace in-memory dict, supporting historical task query and analysis record persistence | 🟢 Low | | **Batch Analysis Mode** | Support uploading multiple samples for queuing analysis, displaying queue status and batch statistics | 🟢 Low | | **Analysis Result Comparison** | Support horizontal comparison view of samples from the same family, highlighting commonality and differences | 🟢 Low | ### 7.4 Documentation and Testing | Iteration Item | Specific Content | Priority | |--------|----------|:------:| | **Competition Document Standardization** | Technical report, requirement specification, innovation depth explanation, user manual (with images) | 🔴 High | | **Unit Test Completion** | Write pytest unit tests for core modules (preprocessing Skill, threat scoring, VBox control, MCP client) | 🟡 Medium | | **End-to-End Testing** | Complete full-process verification in a clean Windows 10/11 Home environment | 🟡 Medium | | **Demo Video Recording** | 5-minute competition demo video (installation → startup → upload → analysis → report full process) | 🔴 High | ### 7.5 Security and Compliance | Iteration Item | Specific Content | Priority | |--------|----------|:------:| | **Sample Compliance Declaration** | Organize all used sample sources and open-source tool license compliance documents | 🔴 High | | **Security Hardening** | Confirm that analysis logs do not contain sensitive information of the host machine, and perform integrity verification after sample upload | 🟡 Medium | --- ## 8. Technology Stack Overview | Module | Technology Selection | Version/Description | |------|----------|-----------| | Backend Framework | FastAPI + Uvicorn | Latest stable version | | AI Agent | OpenClaw compatible layer + local Skill registrar | Dual-mode automatic switching | | Communication Protocol | MCP (Model Context Protocol) over Stdio | JSON-RPC 2.0 self-implementation | | Frontend Framework | Vue3 + Vite | Vue 3.5.x | | UI Component Library | Element Plus | 2.9.x | | Visualization Chart | ECharts | 5.6.x | | State Management | Pinia | 2.3.x | | Isolation Environment | Oracle VirtualBox 7.x | VBoxManage CLI | | Packaging and Distribution | PyInstaller | --onefile mode | | Python Version | 3.9+ | | | Node.js | 18+ | Only required for frontend build | ### Host Machine Static Analysis Tools | Tool | Purpose | |------|------| | **pefile** | PE file structure parsing (sections, import/export tables, entry points, architecture) | | **Capa** | FLARE behavior rule engine, identifying high-level behavioral capabilities of malicious code (e.g., process injection, credential theft) | | **YARA** | Rule-based malicious code pattern matching, detecting malicious families and behavioral characteristics | | **FLOSS** | Extracting plaintext strings and decoded obfuscated strings from executable files | ### Virtual Machine (Windows Analysis Environment) Dynamic Monitoring Tools | Tool | Purpose | |------|------| | **Sysmon** | Windows system-level process creation, network connections, file operations, registry modification event logs | | **Procmon** | Real-time monitoring of process/thread/registry activities, generating process tree and behavioral chain | | **tshark** | Command-line network traffic capture tool, recording all network requests during malicious sample execution | | **Regshot** | Registry snapshot comparison tool, capturing registry changes before and after sample execution | --- ## 9. Compliance Statement All malicious code samples used in this project are sourced from publicly compliant malware repositories (such as MalwareBazaar, VirusShare), and are used solely for academic research and technical verification. The analysis process is conducted entirely in a user's local VirtualBox isolated virtual machine, which operates in an "internal network" mode, completely isolated from the host machine and the external network. Samples will not actively propagate or cause harm to the user's system. The open-source tools included in the project comply with their original licenses (GPLv2, MIT, Apache, etc.), and their use is compliant.