Forensic Toolbox

A comprehensive Python toolkit for parsing forensic artifacts including Registry hives, Prefetch files, Windows shortcuts (.lnk files), Windows Event Logs (.evtx), and Memory Dumps. New tools added periodically

Features

Automatic File Detection: Automatically identifies file types based on signatures and filenames
Registry Analysis: Extracts forensically significant data from Windows Registry hives
- SOFTWARE, SYSTEM, SAM, NTUSER, SECURITY, USRCLASS hives
- Autoruns, network profiles, USB devices, user activity, and more
Prefetch Parsing: Complete Windows Prefetch file parser
- Supports Windows XP through Windows 11
- Handles compressed prefetch files (Windows 10+)
- Extracts execution timestamps, run counts, loaded files, and directories
LNK File Analysis: Parses Windows shortcut files
- Extracts target information, timestamps, volume data
- Decodes extra data blocks (TrackerData, ConsoleData, etc.)
- Identifies potential MAC addresses in GUIDs
EVTX Parsing: Parses evtx logs from C:\Windows\System32\winevt\Logs
- Looks all the commonly used Event IDs
- Can individually parse powershell logs to see commands
- Add your own Event IDs to Mappings or pass in command line
- Output to Json and CSV
Memory Analysis (NEW): Volatility 3 integration for memory dump analysis
- Auto-detects OS type (Windows, Linux, Mac)
- Runs curated forensically relevant plugins
- Categories: processes, network, files, registry, malware indicators, system info
- Output formats: text (default), JSON, CSV, markdown
- Separate file per plugin for easy analysis
- Timeout handling for long-running plugins

Installation

Quick Install (Recommended)

# 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

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

# 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

# Enable verbose output
forensic-toolbox evidence.lnk --verbose

# EVTX parsing
forensic-toolbox Security.evtx --evtx-event 4688
forensic-toolbox C:\Logs

# Memory dump analysis (auto-detect OS and run all forensic plugins)
forensic-toolbox memory.dmp

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

# Memory dump with specific plugins
forensic-toolbox memory.raw --vol-plugins windows.pslist.PsList windows.netscan.NetScan

# Memory dump with 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

# Output in different formats (default is text)
forensic-toolbox memory.dmp --vol-format json     # JSON format
forensic-toolbox memory.dmp --vol-format csv      # CSV format for spreadsheet tools
forensic-toolbox memory.dmp --vol-format markdown # Markdown format for documentation

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

Registry Hives

SOFTWARE: System information, installed applications, autoruns, network profiles
SYSTEM: Computer name, network interfaces, USB devices, services
SAM: Local user accounts, login history
NTUSER.DAT: User-specific activity (recent documents, typed paths, UserAssist)
SECURITY: Security policy settings, audit configuration
USRCLASS.DAT: User shell bags and file associations

Prefetch Files (.pf)

Windows XP (version 17)
Windows Vista/7 (version 23)
Windows 8/8.1 (version 26)
Windows 10/11 (version 30)
Compressed prefetch files (Windows 10+)

Windows Shortcuts (.lnk)

Target information and paths
Creation, access, and modification timestamps
Volume information and serial numbers
Network share information
Extra data blocks (console properties, tracker data, etc.)

Windows Event Logs (.evtx)

Individual Log parsing with Event IDs
Separate Event ID mappings for Easy additions
Parse entire Logs directory and provides outputs
Look for Event ID via specfic dates

Memory Dumps

Memory Acquisition Methods

The toolbox accepts memory dumps from any source. Recommended approach for VM analysis:

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

Alternative methods (not recommended):

Live memory dumping tools (may miss transient data)
Crash dumps (incomplete memory capture)

Supported Formats

Supported Formats: .vmem, .raw, .mem, .dmp, .lime, .dump, .img, .bin, .dd
Supported OS: Windows, Linux, Mac (auto-detected)
Plugin Categories:
- processes (FAST): Process listings, trees, command lines, DLLs
- processes_scan (SLOW): Hidden process scanning - can take 30+ minutes
- network: Network connections, sockets, netstat
- registry: Registry hives, UserAssist, registry keys
- files (SLOW): File object scanning
- malware_indicators (FAST): Code injection detection, kernel callbacks, SSDT hooks
- malware_scan (SLOW): VAD analysis, driver scanning - can take 30+ minutes
- system_info: OS information, services, drivers
Output: Separate file per plugin (text, JSON, CSV, or markdown format)
Features: OS auto-detection, timeout handling, priority plugins for fast analysis

Performance Tips:

Use --vol-priority-only for quick triage (completes in 1-5 minutes)
Use --vol-categories processes network malware_indicators for fast comprehensive analysis
Avoid processes_scan, malware_scan, and files categories unless you need deep scanning
Scanning plugins (psscan, modscan, driverscan, filescan) can take 10-60+ minutes on large dumps

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

Python 3.7+
python-registry>=1.3.1
python-evtx>=0.8.0
pyxpress>=0.1.0 (optional, for compressed prefetch files)
windowsprefetch>=4.0.3
Volatility 3 command-line tool (for memory analysis)
- Download from: https://github.com/volatilityfoundation/volatility3
- Ensure vol.exe or vol3 is in your system PATH
- Alternative: pip install volatility3 (then use python -m volatility3)

Use Cases

Digital Forensics: Extract evidence from systems (Windows, Linux, Mac)
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

Console: Human-readable formatted output
JSON: Machine-readable structured data
CSV: Spreadsheet-compatible format

Examples

Parse SOFTWARE Registry Hive

forensic-toolbox SOFTWARE --output software_analysis.json

Output includes:

Installed applications
Autorun entries
Network profiles
System version information
USB device history

Analyze Prefetch File

forensic-toolbox CHROME.EXE-12345ABC.pf

Output includes:

Executable name and hash
Run count and last execution times
Referenced DLLs and files
Accessed directories
Volume information

Parse LNK File

forensic-toolbox "Recent Document.lnk"

Output includes:

Target file path
Timestamps (created, modified, accessed)
Volume serial number
Network share information
MAC address (if present in tracker data)

Parse EVTX File

forensic-toolbox "Security.evtx"

Output includes:

Processing Event Count
Extracted Events
Event Information for Analysis
Information if Event Count to large

Analyze Memory Dump

forensic-toolbox memory.dmp

Output includes:

OS detection results (Windows/Linux/Mac)
Separate output file per plugin in memory_volatility_output/ directory
Analysis summary with plugin execution statistics
Plugin results in text format (or JSON/CSV/markdown with --vol-format):
- Process listings and trees (pslist, pstree)
- Network connections (netscan, netstat)
- Command line arguments (cmdline)
- Loaded DLLs and modules
- File objects in memory
- Malware indicators (malfind, vadinfo)
- Registry hive locations
- And many more forensically relevant artifacts

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
└── ...

License

MIT License - See LICENSE file for details

Contributing

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

Author

Prof-GP - practical4n6@gmail.com

Acknowledgments

python-registry library by Willi Ballenthin
python-evtx library for EVTX parsing
Volatility Foundation for Volatility 3 framework
Microsoft documentation on Windows file formats
Digital forensics community

Support

For issues, questions, or contributions, please visit: https://github.com/Prof-GP/forensic-toolbox/issues

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Forensic Toolbox

Features

Installation

Quick Install (Recommended)

Manual Installation

Install with Optional Dependencies

Usage

Command Line Interface

Short Command

Python API

Supported File Types

Registry Hives

Prefetch Files (.pf)

Windows Shortcuts (.lnk)

Windows Event Logs (.evtx)

Memory Dumps

Memory Acquisition Methods

Supported Formats

Development

Running Tests

Code Formatting

Linting

Run All Checks

Project Structure

Requirements

Use Cases

Output Formats

Examples

Parse SOFTWARE Registry Hive

Analyze Prefetch File

Parse LNK File

Parse EVTX File

Analyze Memory Dump

License

Contributing

Author

Acknowledgments

Support