ntfsdump

An efficient tool for extracting files, directories, and alternate data streams directly from NTFS image files.

🚀 Overview

ntfsdump allows digital forensic investigators and incident responders to seamlessly extract records from disk images without needing to mount them. By leveraging powerful backend libraries like pytsk3 and libyal, it supports reading from standard disk image formats (RAW, E01, VHD(x), VMDK) and reliably dumps NTFS structures.

📦 Features

Direct Extraction: Avoid mounting overhead by extracting files directly from NTFS partitions.
Support Multiple Formats: Read from .raw, .e01, .vhd, .vhdx, and .vmdk.
Recursive Directory Dumping: Extract entire folders seamlessly.
Alternate Data Stream (ADS): Supports extracting hidden alternate data streams.
Intelligent Path Reconstruction: When outputting single files embedded deep in directories with an absolute path (e.g. \Windows\System32...), ntfsdump reconstructs the directory structure in the output destination folder to keep artifacts perfectly organized.
Glob & Wildcard Queries: Basic support for extracting matched artifacts (e.g. .*).
Use as a CLI or Python Module: Highly flexible to integrate into other automated tools.

⚙️ Execution Environment

Python: Compatible with Python 3.13+.
Precompiled Binaries: Available for both Windows and Linux in the GitHub releases section.

📂 Installation

# From PyPI
pip install ntfsdump

# Form GitHub Releases (Precompiled Binaries)
chmod +x ./ntfsdump
./ntfsdump --help

🛠️ Requirements & File Prerequisites

The image file must meet the following conditions:

Formats: raw, e01, vhd, vhdx, vmdk.
File System: NTFS.
Partition Table: GPT (MBR will usually be auto-detected, but GPT is officially supported).

💻 Usage

Command Line Interface

You can pass arguments directly into the CLI. Output paths can be either file paths or directory paths.

ntfsdump [OPTIONS] <IMAGE> [PATHS...]

Options:

--help, -h: Show help message.
--version, -V: Display program version.
--quiet, -q: Suppress stdout output.
--no-log: Prevent log file creation.
--flat: Extract all artifacts purely into a single folder without reconstructing directories.
--volume, -n: Target specific NTFS volume number (default: auto-detects main OS volume).
--format, -f: Image file format (default: raw). Options: raw, e01, vhd, vhdx, vmdk.
--output, -o: Directory or file to save exported outputs.

Examples

Dump a single file:

ntfsdump -o ./dump ./path/to/your/image.raw /$MFT

Dump an entire directory recursively:

ntfsdump -o ./dump ./path/to/your/image.raw /Windows/System32/winevt/Logs

Extracting from split E01 images (Provide the starting segment .E01):

ntfsdump --format=e01 -o ./dump ./path/to/your/image.E01 /Windows/System32/winevt/Logs

Using with ntfsfind over standard input (pipe):

ntfsfind '.*\.evtx' ./image.raw | ntfsdump -o ./dump ./image.raw

Note: Any absolute path (starting with / or \) passed over stdin via tools like ntfsfind will automatically be cleaned, and the folder hierarchy will be rebuilt faithfully inside your local output directory (./dump/Windows/System32/winevt/Logs/System.evtx).

Python Module

You can incorporate ntfsdump logic into your own scripts.

from ntfsdump import ntfsdump

ntfsdump(
    image='./path/to/your/image.raw',
    paths=['/Windows/System32/winevt/Logs'],
    output='./dump',
    volume=2,
    format='raw'
)

🔍 Query Syntax

ntfsdump utilizes UNIX-like path separators (/) for queries. Paths are case-sensitive relative to the target volume structure.

File: /$MFT -> extracts $MFT
ADS: /$Extend/$UsnJrnl:$J -> extracts the $J ADS file from $UsnJrnl.
Directory: /Windows/System32/winevt/Logs -> extracts all event logs recursively.
Prefix Expansion: /Windows/Prefetch/.* -> extracts all files located in the Prefetch dir.

📝 Logs

By default, an execution log (e.g. ntfsdump_20240101_153205_1234.log) is generated in the current directory to safely record which files were successfully dumped or failed.
To disable logging entirely, append the --no-log flag.

🤝 Contributing

We welcome reports, issues, and feature requests. Please do so on the GitHub repository. 🍣 🍣 🍣

📜 License

Released under the LGPLv3+ License.

sumeshi/ntfsdump