Forensic-Toolbox

Logo

A comprehensive suite for parsing Windows artifacts and Memory Analysis.

View the Project on GitHub Prof-GP/forensic-toolbox

🔍 Forensic Toolbox Issues Stars

Python License Platform

✨ Features

🎯 Automatic File Detection

Automatically identifies file types based on signatures and filenames - just point it at your evidence!

📁 Registry Analysis

Extract forensically significant data from Windows Registry hives:

⚡ Prefetch Parsing

Complete Windows Prefetch file parser with broad compatibility:

🔗 LNK File Analysis

Parse Windows shortcut files to uncover:

📋 EVTX Parsing

Parse Windows Event Logs from C:\Windows\System32\winevt\Logs:

🧠 Memory Analysis

NEW! Volatility 3 integration for memory dump analysis:

🚀 Installation

# Clone the repository
git clone https://github.com/Prof-GP/forensic-toolbox.git
cd forensic-toolbox

# Create virtual environment and install
make install

# Activate virtual environment
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

Manual Installation

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Install package
pip install -e .

Install with Optional Dependencies

# Install with all optional features (including compressed prefetch support)
make install-all

# Or manually
pip install -e ".[all]"

💻 Usage

Command Line Interface

Basic Usage

# Automatically detect and parse any supported file
forensic-toolbox evidence.lnk
forensic-toolbox CALC.EXE-12345.pf
forensic-toolbox SOFTWARE

Registry Analysis

# Specify registry type explicitly
forensic-toolbox REGISTRY_FILE --type SOFTWARE

# Export results to file
forensic-toolbox SOFTWARE --output results.json
forensic-toolbox NTUSER.DAT --output user_activity.csv

Process Multiple Files

forensic-toolbox file1.lnk file2.pf NTUSER.DAT

EVTX Parsing

# Parse specific event IDs
forensic-toolbox Security.evtx --evtx-event 4688

# Parse entire logs directory
forensic-toolbox C:\Logs

Memory Dump Analysis

# Auto-detect OS and run all forensic plugins
forensic-toolbox memory.dmp

# Priority plugins only (RECOMMENDED for fast analysis)
forensic-toolbox memory.vmem --vol-priority-only

# Specific plugins
forensic-toolbox memory.raw --vol-plugins windows.pslist.PsList windows.netscan.NetScan

# Specific categories (FAST - excludes scanning plugins)
forensic-toolbox memory.dmp --vol-categories processes network malware_indicators

# Include scanning plugins (SLOW - can take 30+ minutes)
forensic-toolbox memory.dmp --vol-categories processes processes_scan malware_scan

# Different output formats
forensic-toolbox memory.dmp --vol-format json      # JSON format
forensic-toolbox memory.dmp --vol-format csv       # CSV format
forensic-toolbox memory.dmp --vol-format markdown  # Markdown format

Short Command

Use ftb as shorthand for forensic-toolbox:

ftb SOFTWARE --output results.json

🐍 Python API

from Toolbox.toolbox_registry import ToolboxRegistry
from Toolbox.toolbox_prefetch import ToolboxPrefetch
from Toolbox.toolbox_lnk import ToolboxLnk
from Toolbox.toolbox_volatility import ToolboxVolatility

# Parse registry hive
reg = ToolboxRegistry('SOFTWARE', 'SOFTWARE')
results = reg.valuable_keys()
reg.print_results(results)

# Parse prefetch file
with ToolboxPrefetch('CALC.EXE-12345.pf') as parser:
    if parser.parse():
        parser.print_summary()

# Parse LNK file
lnk = ToolboxLnk('shortcut.lnk')

# Analyze memory dump
vol = ToolboxVolatility('memory.dmp')
vol.detect_os()
vol.run_forensic_analysis()
vol.print_summary()

📦 Supported File Types

Type Files Key Information Extracted
Registry Hives SOFTWARE, SYSTEM, SAM, NTUSER.DAT, SECURITY, USRCLASS.DAT Installed apps, autoruns, network profiles, USB devices, user activity, security policies
Prefetch Files .pf (XP through Win 11) Execution timestamps, run counts, loaded DLLs, accessed directories
Windows Shortcuts .lnk Target paths, timestamps, volume info, network shares, MAC addresses
Event Logs .evtx System events, user activity, PowerShell commands, security events
Memory Dumps .vmem, .raw, .mem, .dmp, .lime, .dump, .img, .bin, .dd Running processes, network connections, loaded DLLs, registry data, malware indicators

🧪 Memory Analysis Details

Memory Acquisition Methods

Recommended approach for VM analysis:

  1. Pause/Suspend the VM - Creates a .vmem file with full memory state
  2. Copy forensic artifacts to host - Ensure all analysis files are extracted first
  3. Analyze the .vmem file - Use this toolbox on the paused VM’s memory

Plugin Categories

Category Speed Description
processes ⚡ FAST Process listings, trees, command lines, DLLs
processes_scan 🐌 SLOW Hidden process scanning (30+ minutes)
network ⚡ FAST Network connections, sockets, netstat
registry ⚡ FAST Registry hives, UserAssist, registry keys
files 🐌 SLOW File object scanning
malware_indicators ⚡ FAST Code injection, kernel callbacks, SSDT hooks
malware_scan 🐌 SLOW VAD analysis, driver scanning (30+ minutes)
system_info ⚡ FAST OS information, services, drivers

Performance Tips

Example Output Structure

memory_volatility_output/
├── analysis_summary.json
├── windows_info_Info.txt
├── windows_pslist_PsList.txt
├── windows_pstree_PsTree.txt
├── windows_netscan_NetScan.txt
├── windows_cmdline_CmdLine.txt
└── ...

🎯 Use Cases

Use Case Description
Digital Forensics Extract evidence from Windows, Linux, and Mac systems
Incident Response Analyze program execution, user activity, and live memory
Malware Analysis Identify persistence mechanisms, code injection, and rootkits
System Auditing Review installed software and system configuration
Timeline Analysis Build execution timelines from multiple artifacts
Memory Forensics Analyze memory dumps for running processes, network connections, and hidden malware

📊 Output Formats

📝 Examples

Parse SOFTWARE Registry Hive

forensic-toolbox SOFTWARE --output software_analysis.json

Output includes:

Analyze Prefetch File

forensic-toolbox CHROME.EXE-12345ABC.pf

Output includes:

Parse LNK File

forensic-toolbox "Recent Document.lnk"

Output includes:

Parse EVTX File

forensic-toolbox Security.evtx

Output includes:

Analyze Memory Dump

forensic-toolbox memory.dmp

Output includes:

🛠️ Development

Running Tests

make test

Code Formatting

make format

Linting

make lint

Run All Checks

make check

📁 Project Structure

forensic-toolbox/
├── Toolbox/
│   ├── __init__.py
│   ├── toolbox_registry.py      # Registry hive parser
│   ├── toolbox_prefetch.py      # Prefetch file parser
│   ├── toolbox_lnk.py           # LNK file parser
│   ├── toolbox_evtx.py          # EVTX parser
│   └── toolbox_volatility.py    # Memory analysis (Volatility 3)
├── main.py                       # Main entry point
├── registry_mapping.py           # Forensic registry keys configuration
├── evtx_mapping.py               # Forensic event ID configuration
├── volatility_mapping.py         # Volatility plugins configuration
├── pyproject.toml                # Package configuration
├── requirements.txt              # Dependencies
├── Makefile                      # Build automation
└── README.md                     # This file

📋 Requirements

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

👤 Author

Prof-GP

🙏 Acknowledgments

💬 Support

For issues, questions, or contributions, please visit:

🔗 https://github.com/Prof-GP/forensic-toolbox/issues

Built with ❤️ for the digital forensics community