🛡️ Malware Sandbox Analysis System

A comprehensive automated malware sandbox analysis platform with parallel processing and behavioral monitoring capabilities. This system provides intelligent malware analysis with real-time monitoring, advanced scheduling, and detailed behavioral insights for security research and threat detection.

🌟 Key Features

🔍 Multi-Engine Analysis: Support for multiple security analysis engines with comprehensive threat detection
⚡ Parallel Processing: Simultaneous analysis with 40%+ time savings and 1.7x speed improvement
📊 Behavioral Analysis: Deep behavioral monitoring with process tree construction and system activity tracking
🚀 RESTful API: Complete API interface for integration and automation
📈 Real-time Monitoring: Performance tracking, task status, and system health monitoring
🔧 Intelligent Management: Automatic sandbox management and resource optimization
🛡️ Isolated Environment: Secure sandbox execution with snapshot-based recovery
📋 Detailed Reports: Comprehensive analysis reports with behavioral insights and threat indicators

🏗️ System Architecture

Core Components

┌─────────────────────────────────────────────────────────────┐
│                    FastAPI Web Server                       │
│                     (Port: 8000)                           │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────┴───────────────────────────────────────┐
│                  Task Manager                               │
│              (Parallel Analysis Scheduler)                  │
└─────────────┬───────────────────────┬───────────────────────┘
              │                       │
    ┌─────────┴─────────┐   ┌─────────┴─────────┐
    │ Behavioral Engine │   │ Security Engines  │
    │ (Activity Monitor)│   │ (5 Parallel VMs)  │
    └─────────┬─────────┘   └─────────┬─────────┘
              │                       │
    ┌─────────┴─────────┐   ┌─────────┴─────────┐
    │ Sandbox Monitor   │   │ Analysis Pool     │
    │                   │   │ ┌───────────────┐ │
    └───────────────────┘   │ │ Sandbox VMs   │ │
                            │ │ - engine-1    │ │
                            │ │ - engine-2    │ │
                            │ │ - engine-3    │ │
                            │ │ - engine-4    │ │
                            │ │ - engine-5    │ │
                            │ └───────────────┘ │
                            └───────────────────┘

Technology Stack

Backend Framework: FastAPI + Python 3.11
Sandbox Environment: Isolated virtual machine execution
Async Processing: asyncio + Parallel Task Queue
Performance Monitoring: psutil + Custom Performance Monitor
Logging System: loguru
Configuration Management: YAML Configuration Files

✨ Supported Features

🔍 Malware Analysis

Multi-Engine Detection: Support for multiple security analysis engines
- Static analysis capabilities
- Dynamic behavior analysis
- Signature-based detection
- Heuristic analysis
- Machine learning detection
Behavioral Analysis: Comprehensive behavioral monitoring and tracking
- Process creation and termination
- File system operations
- Network connections
- Registry modifications
- Process tree construction
- System call monitoring

⚡ Parallel Processing Architecture

Intelligent Scheduling: Multiple analysis engines run simultaneously
Resource Pooling: Dynamic sandbox resource allocation and management
Performance Optimization: 40%+ time savings, 1.7x speed improvement
Error Isolation: Single analysis failure doesn't affect other analyses

📊 Real-time Monitoring

Performance Monitoring: Real-time tracking of CPU, memory, disk usage
Task Status: Detailed task execution status and progress
Threat Detection: Real-time threat detection and classification
System Health: Sandbox status and resource usage monitoring

🔧 Advanced Features

Intelligent File Processing: Automatic file type detection and validation
Sandbox Management: Automatic snapshot restoration and cleanup
Time Unification: All timestamps unified to local time format
Threat Intelligence: Intelligent threat classification and reporting
Report Generation: Comprehensive analysis reports with actionable insights
API Interface: Complete RESTful API

🚀 Usage

System Requirements

Windows 10/11 (Recommended)
Virtualization platform (for sandbox environment)
Python 3.11+
At least 16GB RAM
100GB+ available disk space

📦 Installation

Option 1: Download Release (Recommended)

Download Latest Release

# Download from GitHub releases
wget https://github.com/zcyberseclab/vmm/releases/latest/download/vmm-latest.tar.gz
tar -xzf vmm-latest.tar.gz
cd vmm-*

Install Dependencies
```
pip install -r requirements.txt
```

Option 2: Clone from Source

Clone the Repository

git clone https://github.com/zcyberseclab/vmm.git
cd vmm

Install Dependencies
```
pip install -r requirements.txt
```

⚙️ Configuration

Copy Configuration Template
```
cp config.yaml.example config.yaml
```

Configure Security Exclusions

# Add exclusions for analysis directory
Add-MpPreference -ExclusionPath "C:\path\to\vmm\uploads"

Prepare Sandbox Environment
- Create multiple Windows sandbox virtual machines
- Install security analysis engines on each VM
- Create baseline snapshots for each sandbox

Edit Configuration File

# Edit config.yaml file
# Configure sandbox names, credentials, analysis settings, etc.

🚀 Start the Service

# Start production server
uvicorn main:app --host 0.0.0.0 --port 8000

# Or start development server with auto-reload
python main.py

The service will be available at http://localhost:8000 (or the port specified in your config.yaml).

📡 API Usage Examples

Submit Sample for Analysis

curl -X POST "http://localhost:8000/api/analyze" \
     -H "X-API-Key: your-api-key" \
     -F "file=@malware.exe" \
     -F "filename=test_malware.exe"

Query Task Status

curl -H "X-API-Key: your-api-key" \
     "http://localhost:8000/api/task/{task_id}"

Get Analysis Results

curl -H "X-API-Key: your-api-key" \
     "http://localhost:8000/api/result/{task_id}"

System Health Check
```
curl "http://localhost:8000/api/health"
```
Interactive API Documentation
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

📈 Performance Statistics

System Performance Metrics

Performance statistics based on actual test data:

Metric	Value	Description
Parallel Analysis Time	390.7 seconds	Multi-engine simultaneous analysis
Performance Improvement	40.2%	Time savings compared to serial analysis
Speed Multiplier	1.7x	Parallel vs serial analysis speed
CPU Usage	7.5% → 11.2%	CPU usage change during analysis
Memory Usage	28.2% → 29.8%	Memory usage change during analysis
Event Collection	530+ events	Behavioral monitoring event count
Threat Detection	5+ engines	Multiple security engine results

Sandbox Startup Times

Startup and ready time statistics for each sandbox environment:

Sandbox Environment	Startup Time	System Ready Time	Total
Behavioral Monitor	~31 sec	~5 sec	~36 sec
Security Engine 1	~44 sec	~30 sec	~74 sec
Security Engine 2	~28 sec	~25 sec	~53 sec
Security Engine 3	~33 sec	~28 sec	~61 sec
Security Engine 4	~51 sec	~32 sec	~83 sec
Security Engine 5	~64 sec	~35 sec	~99 sec

Analysis Phase Duration

Phase	Average Duration	Description
Sandbox Startup	30-100 sec	Varies by different security engines
Sample Upload	2-5 sec	File transfer to sandbox environment
Sample Execution	5-10 sec	Malware execution time
Threat Detection	10-25 sec	Wait for security engine detection
Log Collection	5-15 sec	Collect analysis logs and reports
Sandbox Cleanup	10-20 sec	Snapshot restoration and resource cleanup
Behavioral Analysis	60-90 sec	Event collection and behavioral analysis

Concurrent Processing Capability

Configuration Item	Current Value	Maximum Value	Description
Concurrent Tasks	10	Configurable	Simultaneous analysis tasks
Queue Size	100	Configurable	Maximum queued task count
Sandbox Pool Size	6 Sandboxes	Scalable	Available sandbox environments
File Size Limit	100MB	Configurable	Single sample file size

🔧 Configuration

The main configuration file config.yaml contains the following sections:

Server Configuration: Port, upload directory, file size limits
Sandbox Configuration: Sandbox names, credentials, snapshot names
Analysis Configuration: Timeout settings, monitoring time, concurrency limits
Behavioral Monitoring: Event types, collection count, analysis options

Please refer to the comments in the config.yaml file for detailed configuration.

📝 Important Notes

Resource Requirements: The system needs sufficient CPU and memory to run multiple sandbox environments simultaneously
Network Isolation: Recommended to run in an isolated network environment to prevent malware propagation
Snapshot Management: Regularly update sandbox snapshots to keep the analysis environment clean
Log Monitoring: Monitor log file sizes and clean up old logs regularly
Security Protection: Ensure the host system has appropriate security protection measures

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

🐛 Troubleshooting

Common Issues

Virtualization platform not found
- Ensure virtualization software is properly installed
- Check that virtualization commands are accessible from PATH
Sandbox startup timeout
- Increase vm_startup_timeout in config.yaml
- Check sandbox environments have sufficient resources allocated
API key authentication failed
- Verify the API key in config.yaml matches the X-API-Key header
- Check for typos in the API key
File upload fails
- Check file size limits in config.yaml
- Ensure upload directory has write permissions

For more issues and solutions, please check the Issues page.

📚 Documentation

🔗 Related Projects

System Monitor Tools - System monitoring and analysis tools
Virtualization Platforms - Sandbox virtualization solutions
FastAPI - Modern web framework for building APIs

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

Microsoft Sysinternals team for system monitoring tools
Virtualization platform developers for sandbox technologies
FastAPI team for the excellent web framework
Security research community for threat analysis methodologies
All contributors who helped improve this project

📞 Support

📧 Email: support@zcyberseclab.com
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

⭐ If you find this project useful, please consider giving it a star on GitHub!

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github		.github
app		app
demo		demo
docs		docs
tools		tools
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
RELEASE.md		RELEASE.md
config.yaml		config.yaml
config.yaml.example		config.yaml.example
main.py		main.py
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup.py		setup.py
test_execution.py		test_execution.py

License

zcyberseclab/vmm

Folders and files

Latest commit

History

Repository files navigation