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 malhunt

git clone https://github.com/andreafortuna/malhunt.git
cd malhunt
poetry install
poetry run malhunt --help

git clone https://github.com/andreafortuna/malhunt.git
cd malhunt
pip install -e .
malhunt --help

poetry run malhunt /path/to/memory.dump
poetry run malhunt /path/to/memory.dump --rules custom_rules.yar
poetry run malhunt /path/to/memory.dump --verbose

malhunt /path/to/memory.dump
malhunt /path/to/memory.dump --rules custom_rules.yar
malhunt /path/to/memory.dump --verbose

malhunt --help      # Show all options
malhunt --version   # Show version

Malhunt applies a systematic approach for malware discovery in memory:

1. Initialization - Validates memory dump and locates Volatility3 binary
2. Cache Cleanup - Removes old YARA rules (> 1 day) and temporary files
3. Rule Preparation - Downloads latest YARA rules from Yara‑Forge ZIP archive (or uses cached version)
   • Fetches yara-rules-full.yar from the Yara‑Forge release page
   • Filters incompatible YARA rules
   • Writes the result to malware_rules.yar in the user cache
4. Profile Identification - Detects OS variant from memory dump using Volatility3's windows.info plugin. 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.
5. Phase 1: YARA Scanning - 📊 Applies comprehensive YARA rules (3310+ rules) to memory
6. Phase 2: Malfind Scanning - 💉 Detects injected code and suspicious memory allocations
7. Phase 3: Network Scanning - 🌐 Analyzes network connections for malicious IPs
8. Artifact Collection - Dumps suspicious process memory and extracts handle information
9. Antivirus Scanning - 🛡️ Scans artifacts with ClamAV (if available)
10. 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 (.bin files)
• Process handles information (.handles files)
• 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: [email protected]

• Volatility3 Documentation
• YARA Documentation
• ClamAV Documentation

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.