Hunt malware in memory dumps with Volatility3
Malhunt is an automated malware hunting tool that analyzes memory dumps using Volatility3, applying YARA rules, code injection scanning, and network analysis to identify suspicious processes.
- 🔍 Memory Profile Detection - Automatic identification of Windows/Linux memory dumps
- 📋 YARA Rule Scanning - Apply multiple YARA rules for malware detection
- 💉 Injection Detection - Identify injected code and suspiciously allocated memory
- 🌐 Network Analysis - Detect suspicious network connections
- 📦 Artifact Collection - Extract and preserve suspicious process memory
- 🛡️ Antivirus Integration - Scan artifacts with ClamAV
- 📊 Comprehensive Reporting - Detailed logs and findings
- Python 3.9+
- Volatility3 (≥2.0.0)
- Git (optional; previously used for downloading YARA rules)
- ClamAV (optional, for antivirus scanning)
- Poetry (for development; users can use pip)
pip install volatility3 yara-python ruff loguru pyclamd requests pydantic
pip install malhuntgit clone https://github.com/andreafortuna/malhunt.git
cd malhunt
poetry install
poetry run malhunt --helpgit clone https://github.com/andreafortuna/malhunt.git
cd malhunt
pip install -e .
malhunt --helppoetry run malhunt /path/to/memory.dump
poetry run malhunt /path/to/memory.dump --rules custom_rules.yar
poetry run malhunt /path/to/memory.dump --verbosemalhunt /path/to/memory.dump
malhunt /path/to/memory.dump --rules custom_rules.yar
malhunt /path/to/memory.dump --verbosemalhunt --help # Show all options
malhunt --version # Show versionMalhunt applies a systematic approach for malware discovery in memory:
- Initialization - Validates memory dump and locates Volatility3 binary
- Cache Cleanup - Removes old YARA rules (> 1 day) and temporary files
- Rule Preparation - Downloads latest YARA rules from Yara‑Forge ZIP archive (or uses cached version)
- Fetches
yara-rules-full.yarfrom the Yara‑Forge release page - Filters incompatible YARA rules
- Writes the result to
malware_rules.yarin the user cache
- Fetches
- Profile Identification - Detects OS variant from memory dump
using Volatility3's
windows.infoplugin. Malhunt parses the plugin output and, if necessary, constructs and validates candidate profiles (falling back to suggested profiles or a small set of common names), mirroring the official Volatility3 recommendation for automatic detection. - Phase 1: YARA Scanning - 📊 Applies comprehensive YARA rules (3310+ rules) to memory
- Phase 2: Malfind Scanning - 💉 Detects injected code and suspicious memory allocations
- Phase 3: Network Scanning - 🌐 Analyzes network connections for malicious IPs
- Artifact Collection - Dumps suspicious process memory and extracts handle information
- Antivirus Scanning - 🛡️ Scans artifacts with ClamAV (if available)
- Reporting - Generates structured logs and preserves artifacts for investigation
src/malhunt/
├── __init__.py # Package initialization
├── __main__.py # CLI entry point
├── core.py # Main orchestration logic
├── volatility.py # Volatility3 wrapper
├── scanner.py # YARA/Malfind/Network scanners
├── artifacts.py # Artifact collection & antivirus
├── models.py # Data models
└── utils.py # Utility functions
Malhunt creates an <dump_name>_artifacts/ directory containing:
- Process memory dumps (
.binfiles) - Process handles information (
.handlesfiles) - Scan results and logs
If you're using the older v0.1 version with Volatility2, see MIGRATION.md for upgrade instructions.
cd /path/to/malhunt
# Install all dependencies including dev tools
poetry install
# Run tests
poetry run pytest tests/ -v
# Run with coverage
poetry run pytest tests/ --cov=src/malhunt --cov-report=html
# Code quality checks
poetry run black src/malhunt tests/
poetry run ruff check src/malhunt tests/
poetry run mypy src/malhunt# Install docs dependencies
poetry install --with docs
# Build Sphinx documentation
cd docs
make html
# Open _build/html/index.html# Via Poetry
poetry run malhunt /path/to/dump.vmem
# Via Python module
poetry run python3 -m malhunt /path/to/dump.vmem- Python 3.9+ (tested with 3.9, 3.10, 3.11)
- Volatility3 (≥2.0.0) - Memory forensics framework
- YARA-Python (≥4.3.0) - Malware identification engine
- Pydantic (≥2.0.0) - Data validation
- Loguru (≥0.7.0) - Structured logging
- Requests (≥2.32.0) - HTTP client for IP checking
- PyClamd (≥0.4.0) - ClamAV integration
- Git (optional) - previously used for cloning rules, no longer required
- ClamAV (optional) - Antivirus scanning support
- Poetry (≥1.0.0) - Project/dependency management
- Pytest (≥7.0.0) - Testing framework
- Black (≥23.0.0) - Code formatting
- Ruff (≥0.1.0) - Linting
- MyPy (≥1.0.0) - Type checking
Malhunt stores configuration and cached data in ~/.malhunt/:
malware_rules.yar- Merged YARA rules (auto-updated if > 1 day old)
Volatility3 execution can be customized via VolatilityConfig:
from pathlib import Path
from malhunt import Malhunt
from malhunt.volatility import VolatilityConfig
# Custom timeout and retry settings
config = VolatilityConfig(
timeout=600, # 10 minutes
retry_count=3, # Retry up to 3 times
retry_delay=2.0, # 2 seconds between retries
cache_results=True # Cache command results
)
mh = Malhunt(Path("dump.vmem"), vol_config=config)
mh.run_full_analysis()See TROUBLESHOOTING.md for common issues and solutions.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
MIT License - See LICENSE file for details
Andrea Fortuna - @andreafortuna
- Website: https://andreafortuna.org
- Email: andrea@andreafortuna.org
This tool is intended for authorized security testing and malware analysis only. Ensure you have proper authorization before analyzing memory dumps. The authors are not responsible for misuse or damage caused by this tool.