Skip to content
/ forensic-toolbox Public

A comprehensive Python toolbox for parsing Windows forensic artifacts including Registry hives, Prefetch files, Windows shortcuts (.lnk files) and WIndows Event Logs (.evtx).

prof-gp.github.io/forensic-toolbox/

License

MIT license
1 star 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

Prof-GP/forensic-toolbox

BranchesTags

Repository files navigation

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:

  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

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)
  • Volatility 3 command-line tool (for memory analysis)

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

About

A comprehensive Python toolbox for parsing Windows forensic artifacts including Registry hives, Prefetch files, Windows shortcuts (.lnk files) and WIndows Event Logs (.evtx).

prof-gp.github.io/forensic-toolbox/

Topics

threat-hunting digital-forensics memory-forensics log-parsing cli-tools forensics-tools incident-reponse

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages