https://github.com/sumeshi/ntfsdump
An efficient tool for extracting files, directories, and alternate data streams directly from NTFS image files.
https://github.com/sumeshi/ntfsdump
dfir e01 forensics ntfs python raw sleuthkit vhd vhdx vmdk
Last synced: 3 months ago
JSON representation
An efficient tool for extracting files, directories, and alternate data streams directly from NTFS image files.
- Host: GitHub
- URL: https://github.com/sumeshi/ntfsdump
- Owner: sumeshi
- License: gpl-3.0
- Created: 2020-07-08T16:27:00.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-02-21T20:08:46.000Z (over 2 years ago)
- Last Synced: 2026-01-25T16:20:50.352Z (4 months ago)
- Topics: dfir, e01, forensics, ntfs, python, raw, sleuthkit, vhd, vhdx, vmdk
- Language: Python
- Homepage: https://pypi.org/project/ntfsdump/
- Size: 231 KB
- Stars: 22
- Watchers: 2
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ntfsdump
[](LICENSE)
[](https://badge.fury.io/py/ntfsdump)
[](https://pypi.org/project/ntfsdump/)
[](https://github.com/sumeshi/ntfsdump/actions/workflows/test.yaml)
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](https://github.com/sumeshi/ntfsdump/releases) section.
## 📂 Installation
```bash
# 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.
```bash
ntfsdump [OPTIONS] [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:
```bash
ntfsdump -o ./dump ./path/to/your/image.raw /$MFT
```
Dump an entire directory recursively:
```bash
ntfsdump -o ./dump ./path/to/your/image.raw /Windows/System32/winevt/Logs
```
Extracting from split E01 images (Provide the starting segment `.E01`):
```bash
ntfsdump --format=e01 -o ./dump ./path/to/your/image.E01 /Windows/System32/winevt/Logs
```
Using with [ntfsfind](https://github.com/sumeshi/ntfsfind) over standard input (pipe):
```bash
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.
```python
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](https://github.com/sumeshi/ntfsdump). :sushi: :sushi: :sushi:
## 📜 License
Released under the [LGPLv3+](LICENSE) License.
Powered by:
- [pytsk](https://github.com/py4n6/pytsk)
- [libewf](https://github.com/libyal/libewf)
- [libvhdi](https://github.com/libyal/libvhdi)
- [libvmdk](https://github.com/libyal/libvmdk)