ntfsdump 3.1.0__tar.gz → 3.2.0__tar.gz

{ntfsdump-3.1.0 → ntfsdump-3.2.0}/.github/workflows/publish-binary-pypi.yaml

@@ -9,9 +9,9 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v6
     - name: Set up Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v6
       with:
         python-version: '3.13'
     - name: Install dependencies

{ntfsdump-3.1.0 → ntfsdump-3.2.0}/.github/workflows/publish-release.yaml

@@ -15,13 +15,13 @@ jobs:
         python-version: ['3.13']
     steps:
       - name: checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v6
 
       - name: install python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
-      
+
       - name: Install dependencies
         run: |
           pip install uv
@@ -30,17 +30,26 @@ jobs:
       - name: run python
         run: |
           uv run ntfsdump -h
-      
+
       - name: build
         run: |
           uv run python -m nuitka --standalone --onefile --follow-imports --include-distribution-metadata=ntfsdump -o ntfsdump.exe --output-dir=dist --assume-yes-for-downloads src/ntfsdump/cli.py
 
-      
       - name: verify
         run: |
           dist/ntfsdump.exe -h
           dist/ntfsdump.exe --version
-      
+
+      - name: collect third-party licenses
+        run: |
+          mkdir -p dist/third-party-licenses
+          curl -fsSL -o dist/third-party-licenses/COPYING.LESSER-libewf.txt https://raw.githubusercontent.com/libyal/libewf/main/COPYING.LESSER
+          curl -fsSL -o dist/third-party-licenses/COPYING.LESSER-libvhdi.txt https://raw.githubusercontent.com/libyal/libvhdi/main/COPYING.LESSER
+          curl -fsSL -o dist/third-party-licenses/COPYING.LESSER-libvmdk.txt https://raw.githubusercontent.com/libyal/libvmdk/main/COPYING.LESSER
+          curl -fsSL -o dist/third-party-licenses/LICENSE-pytsk3-apache-2.0.txt https://raw.githubusercontent.com/py4n6/pytsk/master/LICENSE
+          cp LICENSE dist/third-party-licenses/LICENSE-ntfsdump-mit.txt
+        shell: bash
+
       - name: create tag
         id: create_tag
         if: startsWith(github.ref, 'refs/heads/master')
@@ -53,17 +62,22 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         shell: bash
 
-      - name: rename asset
+      - name: package release zip
         if: startsWith(github.ref, 'refs/heads/master')
-        run: mv dist/ntfsdump.exe dist/ntfsdump-windows-x64-v${{ steps.create_tag.outputs.version }}.exe
+        run: |
+          mkdir -p dist/stage
+          cp dist/ntfsdump.exe dist/stage/
+          cp -r dist/third-party-licenses dist/stage/
+          cd dist/stage
+          uv run python -m zipfile -c ../ntfsdump-windows-x64-v${{ steps.create_tag.outputs.version }}.zip ntfsdump.exe third-party-licenses/
         shell: bash
 
       - name: create release
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v2
         if: startsWith(github.ref, 'refs/heads/master')
         with:
           tag_name: v${{ steps.create_tag.outputs.version }}
-          files: dist/ntfsdump-windows-x64-v${{ steps.create_tag.outputs.version }}.exe
+          files: dist/ntfsdump-windows-x64-v${{ steps.create_tag.outputs.version }}.zip
           name: Release v${{ steps.create_tag.outputs.version }}
           body: 'This release was automatically created by GitHub Actions.'
         env:
@@ -77,14 +91,12 @@ jobs:
         python-version: ['3.13']
     steps:
       - name: checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v6
 
       - name: install python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
-      
-
 
       - name: Install dependencies
         run: |
@@ -99,22 +111,35 @@ jobs:
       - name: build
         run: |
           uv run python -m nuitka --standalone --onefile --follow-imports --include-distribution-metadata=ntfsdump -o ntfsdump --output-dir=dist --assume-yes-for-downloads src/ntfsdump/cli.py
-      
+
       - name: verify
         run: |
           dist/ntfsdump -h
           dist/ntfsdump --version
 
-      - name: rename asset
+      - name: collect third-party licenses
+        run: |
+          mkdir -p dist/third-party-licenses
+          curl -fsSL -o dist/third-party-licenses/COPYING.LESSER-libewf.txt https://raw.githubusercontent.com/libyal/libewf/main/COPYING.LESSER
+          curl -fsSL -o dist/third-party-licenses/COPYING.LESSER-libvhdi.txt https://raw.githubusercontent.com/libyal/libvhdi/main/COPYING.LESSER
+          curl -fsSL -o dist/third-party-licenses/COPYING.LESSER-libvmdk.txt https://raw.githubusercontent.com/libyal/libvmdk/main/COPYING.LESSER
+          curl -fsSL -o dist/third-party-licenses/LICENSE-pytsk3-apache-2.0.txt https://raw.githubusercontent.com/py4n6/pytsk/master/LICENSE
+          cp LICENSE dist/third-party-licenses/LICENSE-ntfsdump-mit.txt
+
+      - name: package release zip
         if: startsWith(github.ref, 'refs/heads/master')
-        run: mv dist/ntfsdump dist/ntfsdump-linux-x64-v${{ needs.build-windows.outputs.version }}
-        shell: bash
+        run: |
+          mkdir -p dist/stage
+          cp dist/ntfsdump dist/stage/
+          cp -r dist/third-party-licenses dist/stage/
+          cd dist/stage
+          uv run python -m zipfile -c ../ntfsdump-linux-x64-v${{ needs.build-windows.outputs.version }}.zip ntfsdump third-party-licenses/
 
       - name: upload asset to release
         if: startsWith(github.ref, 'refs/heads/master')
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v2
         with:
           tag_name: v${{ needs.build-windows.outputs.version }}
-          files: dist/ntfsdump-linux-x64-v${{ needs.build-windows.outputs.version }}
+          files: dist/ntfsdump-linux-x64-v${{ needs.build-windows.outputs.version }}.zip
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{ntfsdump-3.1.0 → ntfsdump-3.2.0}/.github/workflows/test.yaml

@@ -3,8 +3,9 @@ name: pytest
 on:
   push:
     branches:
+      - master
       - develop
-      # - 'feature/**'
+  pull_request:
 
 jobs:
   pytest:
@@ -12,13 +13,13 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.13']
+        python-version: ['3.13', '3.14']
     steps:
       - name: checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v6
 
       - name: install python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 

{ntfsdump-3.1.0 → ntfsdump-3.2.0}/.gitignore

@@ -136,4 +136,11 @@ dmypy.json
 NtfsDumpView.*/
 
 /tests/ntfsdump/cache/*
-!/tests/ntfsdump/cache/.gitkeep
+!/tests/ntfsdump/cache/.gitkeep
+
+.serena
+.tokensave
+GOAL.md
+CHANGES.md
+TASKS.md
+AGENTS.md

ntfsdump-3.2.0/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.5
+Name: ntfsdump
+Version: 3.2.0
+Summary: A command-line tool for efficiently extracting files, directories, and alternate data streams directly from NTFS image files.
+Project-URL: Homepage, https://github.com/sumeshi/ntfsdump
+Project-URL: Repository, https://github.com/sumeshi/ntfsdump
+Author-email: sumeshi <sum3sh1@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: libewf-python==20240506
+Requires-Dist: libvhdi-python==20260901
+Requires-Dist: libvmdk-python==20260714
+Requires-Dist: pytsk3==20260715
+Description-Content-Type: text/markdown
+
+# ntfsdump
+
+[![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)
+[![PyPI Version](https://img.shields.io/pypi/v/ntfsdump)](https://pypi.org/project/ntfsdump/)
+[![pytest](https://img.shields.io/github/actions/workflow/status/sumeshi/ntfsdump/test.yaml)](https://github.com/sumeshi/ntfsdump/blob/master/.github/workflows/test.yaml)
+
+![ntfsdump logo](https://gist.githubusercontent.com/sumeshi/c2f430d352ae763273faadf9616a29e5/raw/baa85b045e0043914218cf9c0e1d1722e1e7524b/ntfsdump.svg)
+
+A command-line tool for efficiently extracting files, directories, and alternate data streams directly from NTFS image files.
+
+## Overview
+
+`ntfsdump` is a command-line tool and Python library for extracting files, directories, and alternate data streams from NTFS volumes in disk images without mounting them.
+
+It supports common forensic image formats such as RAW, E01, VHD/VHDX, and VMDK through `pytsk3` and libraries from the `libyal` project.
+
+
+## Features
+
+- Extract files directly from NTFS volumes in disk images
+- Dump a single file, multiple files, or an entire directory recursively
+- Extract alternate data streams (ADS)
+- Reconstruct the original directory structure in the output directory
+- Supports `RAW`, `E01`, `VHD`, `VHDX`, and `VMDK ` image formats
+- Automatically detects the input image format by signature
+- Accepts a VMware VM directory, VMX or VMSD directly, without converting images
+- Lists and reads VMware snapshots (`--list-snapshots`, `--snapshot`)
+- Selects a virtual disk when a VM has more than one (`--list-disks`, `--disk`)
+- Reads split VMDK extents and VMDK snapshot/delta chains without merging them
+- Read paths from standard input for integration with tools such as `ntfsfind`
+- Use as a command-line tool or Python library
+
+
+## Installation
+
+```bash
+# From PyPI
+pip install ntfsdump
+
+# From GitHub Releases (Precompiled Binaries)
+chmod +x ./ntfsdump
+./ntfsdump --help
+```
+
+
+## Supported Input
+
+- Image formats: `RAW`, `E01`, `VHD`, `VHDX`, `VMDK` (auto-detected), plus VMware VM directories, VMX and VMSD
+- File system: `NTFS`
+- Partition tables: GPT and MBR are both supported
+
+
+## Usage
+
+### Command Line Interface
+
+You can pass arguments directly to the CLI. The output path can be either a file path or a directory path.
+
+```bash
+ntfsdump [OPTIONS] SOURCE [PATH...]
+```
+
+`SOURCE` may be an image file, a VMware VM directory, a VMX or a VMSD:
+
+```text
+disk.raw
+evidence.E01
+disk.vhd
+disk.vhdx
+disk.vmdk
+vm.vmsd
+/path/to/vm/
+```
+
+**Options**:
+- `--help`, `-h`: Show help message.
+- `--version`, `-V`: Display program version.
+- `--quiet`, `-q`: Suppress normal stdout output. Errors are still written to stderr.
+- `--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).
+- `--snapshot`, `-s`: Read the NTFS as it was at the given VMware snapshot. The ID is the snapshot UID shown by `--list-snapshots`. Without it, the VM's current state is read.
+- `--disk`, `-d`: Read a specific VMware virtual disk by ID (default: auto-select when unique).
+- `--list-snapshots`: List VMware snapshots found in the SOURCE and exit.
+- `--list-disks`: List VMware virtual disks found in the SOURCE and exit.
+- `--image-format`: Force the image format instead of auto-detection. Options: `raw`, `e01`, `vhd`, `vhdx`, `vmdk`.
+- `--log [FILE]`: Enable logging. Optionally specify a log file path.
+- `--output`, `-o`: Directory or file to save exported outputs.
+
+
+#### Examples
+
+Dump a single file (format is auto-detected):
+
+```bash
+ntfsdump -o ./dump /path/to/your/image.raw /$MFT
+ntfsdump -o ./dump /path/to/your/evidence.E01 /Windows/System32/config/SYSTEM
+```
+
+Dump an entire directory recursively:
+
+```bash
+ntfsdump -o ./dump /path/to/your/image.raw /Windows/System32/winevt/Logs
+```
+
+Force the format for a file without a recognizable signature:
+
+```bash
+ntfsdump --image-format raw /path/to/your/evidence.bin /$MFT
+```
+
+#### VMware Snapshots (`--list-snapshots`, `-s/--snapshot`)
+
+`ntfsdump` can read the NTFS volume **as it was at a specific VMware snapshot**, directly from the delta VMDK chain — without reverting the VM, cloning disks, or merging snapshots.
+
+First, list the snapshots recorded in the VM's `VMSD` metadata:
+
+```bash
+ntfsdump ./WindowsVM --list-snapshots
+ID  NAME          CREATED              PARENT
+1   Initialized   2026-09-01 12:33:43  -
+5   NetConnect    2026-09-02 02:25:08  1
+6   PrepareTools  2026-09-10 17:46:35  5
+7   SetConfigs    2026-09-25 00:51:39  5
+```
+
+- `ID` is VMware's own snapshot UID. Always take it from this listing — it is the only valid identifier.
+- `PARENT` shows the snapshot lineage, so you can follow the history of the VM.
+
+Then pass the ID with `-s` / `--snapshot` to read any point in time:
+
+```bash
+# Read the SYSTEM registry hive as it was at snapshot 5.
+ntfsdump ./WindowsVM -s 5 /Windows/System32/config/SYSTEM
+
+# Snapshot 5, second virtual disk (see disk selection below).
+ntfsdump ./WindowsVM -s 5 -d 1 /Evidence
+```
+
+Notes:
+
+- Without `-s`, the VM's **current state** is read (which may itself already be a delta chain after taking a snapshot).
+- Only snapshot **IDs** are accepted; selecting by display name is not supported.
+- If the VM directory has no `VMSD` (no snapshot metadata), a plain `--list-snapshots` reports `No VMware snapshot metadata was found.` rather than pretending the VMDK chain is a snapshot list.
+
+#### Virtual Disk Selection (`--list-disks`, `-d/--disk`)
+
+For VMs with more than one virtual disk, list them first:
+
+```bash
+ntfsdump ./WindowsVM --list-disks
+ID  NODE     SIZE     VMDK
+0   nvme0:0  100 GiB  Windows10_22H2(x64).vmdk
+1   scsi0:1  500 GiB  Data.vmdk
+```
+
+Then select a disk with `-d` / `--disk`:
+
+```bash
+# Read the second virtual disk.
+ntfsdump ./WindowsVM -d 1 /Evidence
+```
+
+- With a **single** disk, it is selected automatically.
+- With **multiple** disks, `ntfsdump` refuses to guess and asks you to choose with `--list-disks` + `-d`.
+
+#### Snapshot Delta VMDK Chains
+
+Even a bare VMDK inside the VM directory is understood: parents are resolved automatically from the descriptors, so pointing at a delta file reads the whole chain (base + deltas) as one logical disk:
+
+```bash
+ntfsdump ./WindowsVM/Windows-000003.vmdk /$MFT
+```
+
+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
+
+# Image format is auto-detected. Pass image_format='raw' to force it.
+ntfsdump(
+    source='./path/to/your/image.raw',
+    paths=['/Windows/System32/winevt/Logs'],
+    output='./dump',
+    volume=2,
+)
+
+# VMware VM directory, snapshot and disk selection.
+ntfsdump(
+    source='./WindowsVM',
+    paths=['/Windows/System32/config/SYSTEM'],
+    output='./dump',
+    snapshot='3',
+    disk=1,
+)
+```
+
+
+## Query Syntax
+
+`ntfsdump` uses UNIX-like path separators (`/`) for queries. Depending on the image and backend behavior, path matching may be case-sensitive.
+
+- **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` directory.
+
+
+## Logs
+
+Logging is disabled by default and no log file is created. To record which files were successfully dumped or failed, enable it explicitly:
+
+```bash
+# Auto-generated name in the current directory (e.g. ntfsdump_20260921_153000.log)
+ntfsdump image.raw /$MFT --log
+
+# Explicit log path
+ntfsdump image.raw /$MFT --log ./case.log
+```
+
+
+## Contributing
+
+We welcome bug reports, issues, and feature requests. Please submit them on the [GitHub repository](https://github.com/sumeshi/ntfsdump). :sushi: :sushi: :sushi:
+
+
+## License
+
+ntfsdump is released under the [MIT](LICENSE) License.
+
+
+### Third-party licenses
+
+The standalone binaries distributed via GitHub Releases bundle the following third-party libraries.
+
+
+#### LGPL-3.0-or-later
+
+The following libyal libraries are licensed under the [GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later)](https://www.gnu.org/licenses/lgpl-3.0.html).
+You may obtain, modify, and rebuild them from their upstream sources in accordance with the LGPL.
+
+- [libewf / libewf-python](https://github.com/libyal/libewf)
+  - Bundled version: [`libewf-python==20240506`](https://pypi.org/project/libewf-python/20240506/) (source: https://github.com/libyal/libewf/releases/tag/20240506)
+  - License text: https://github.com/libyal/libewf/blob/main/COPYING.LESSER
+- [libvhdi / libvhdi-python](https://github.com/libyal/libvhdi)
+  - Bundled version: [`libvhdi-python==20260901`](https://pypi.org/project/libvhdi-python/20260901/) (source: https://github.com/libyal/libvhdi/releases/tag/20260901)
+  - License text: https://github.com/libyal/libvhdi/blob/main/COPYING.LESSER
+- [libvmdk / libvmdk-python](https://github.com/libyal/libvmdk)
+  - Bundled version: [`libvmdk-python==20260714`](https://pypi.org/project/libvmdk-python/20260714/) (source: https://github.com/libyal/libvmdk/releases/tag/20260714)
+  - License text: https://github.com/libyal/libvmdk/blob/main/COPYING.LESSER
+
+
+#### Apache-2.0
+
+- [pytsk / pytsk3](https://github.com/py4n6/pytsk) — licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+  - Bundled version: [`pytsk3==20260715`](https://pypi.org/project/pytsk3/20260715/)
+  - License text: https://github.com/py4n6/pytsk/blob/master/LICENSE