ntfsdump 3.3.1__tar.gz → 3.3.2__tar.gz

ntfsdump-3.3.2/.github/workflows/test.yaml

@@ -0,0 +1,52 @@
+name: pytest
+
+on:
+  push:
+    branches:
+      - master
+      - develop
+  pull_request:
+
+jobs:
+  pytest:
+    name: Run tests with pytest
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.13', '3.14']
+    steps:
+      - name: checkout
+        uses: actions/checkout@v6
+
+      - name: install python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: setup uv
+        run: |
+          pip install uv
+          uv sync
+
+      - name: run unit tests
+        run: uv run pytest --ignore=tests/ntfsdump/test__init__.py
+
+      - name: cache NTFS sample archive
+        id: ntfs-sample
+        uses: actions/cache@v4
+        with:
+          path: tests/ntfsdump/cache/ntfs.tgs
+          key: ntfs-sample-79b3b6f3fa173fd0d2a05d0d2693afd0
+
+      - name: download NTFS sample with retries
+        if: steps.ntfs-sample.outputs.cache-hit != 'true'
+        run: |
+          mkdir -p tests/ntfsdump/cache
+          curl --fail --location --retry 5 --retry-all-errors --retry-delay 2 \
+            --connect-timeout 15 --max-time 120 \
+            --output tests/ntfsdump/cache/ntfs.tgs.tmp \
+            'https://github.com/msuhanov/ntfs-samples/blob/master/ntfs.tgz?raw=true'
+          mv tests/ntfsdump/cache/ntfs.tgs.tmp tests/ntfsdump/cache/ntfs.tgs
+
+      - name: run sample image E2E tests
+        run: uv run pytest tests/ntfsdump/test__init__.py

{ntfsdump-3.3.1 → ntfsdump-3.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ntfsdump
-Version: 3.3.1
+Version: 3.3.2
 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
@@ -94,15 +94,20 @@ vm.vmsd
 - `--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).
+- `--flat`: Extract all artifacts purely into a single folder without reconstructing directories. Directory names are joined into the filename with `_` (e.g. `/Windows/System32/cmd.exe` -> `Windows_System32_cmd.exe`) so that same-name files from different directories stay apart.
+- `--volume`, `-n`: Target the NTFS partition address shown in analysis logs (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.
+- `--output`, `-o`: Output directory (default: current directory). An existing file is used as a file output.
+- `--output-file`: Save one file or ADS to the path given by `-o`, including a new filename.
+
+In directory output, conflicting filenames receive a unique suffix. File output
+replaces an existing file only after extraction succeeds. Failed extraction
+preserves existing files.
 
 
 #### Examples
@@ -110,10 +115,16 @@ vm.vmsd
 Dump a single file (format is auto-detected):
 
 ```bash
-ntfsdump -o ./dump /path/to/your/image.raw /$MFT
+ntfsdump -o ./dump /path/to/your/image.raw '/$MFT'
 ntfsdump -o ./dump /path/to/your/evidence.E01 /Windows/System32/config/SYSTEM
 ```
 
+Save a single file under a different name:
+
+```bash
+ntfsdump --output-file -o ./SYSTEM.bin /path/to/your/image.raw /Windows/System32/config/SYSTEM
+```
+
 Dump an entire directory recursively:
 
 ```bash
@@ -123,7 +134,37 @@ 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
+ntfsdump --image-format raw /path/to/your/evidence.bin '/$MFT'
+```
+
+#### Windows Artifacts
+
+These examples use `image.raw` and save the original directory structure under
+`./dump`. Replace `Alice` with the profile directory in your image. Quote paths
+to preserve `$`, spaces, and wildcard queries when running from a shell.
+
+```bash
+# NTFS metadata: MFT, transaction log, and USN Journal
+ntfsdump -o ./dump image.raw '/$MFT' '/$LogFile' '/$Extend/$UsnJrnl:$J'
+
+# System registry hives and their transaction logs
+ntfsdump -o ./dump image.raw '/Windows/System32/config'
+
+# User registry hives and their transaction logs (prefix expansion)
+ntfsdump -o ./dump image.raw '/Users/Alice/NTUSER.DAT.*' \
+  '/Users/Alice/AppData/Local/Microsoft/Windows/UsrClass.dat.*'
+
+# Windows event logs
+ntfsdump -o ./dump image.raw '/Windows/System32/winevt/Logs'
+
+# Prefetch and Amcache
+ntfsdump -o ./dump image.raw '/Windows/Prefetch' '/Windows/AppCompat/Programs/Amcache.hve.*'
+
+# System Resource Usage Monitor (SRUM)
+ntfsdump -o ./dump image.raw '/Windows/System32/sru'
+
+# User shortcuts and Jump Lists
+ntfsdump -o ./dump image.raw '/Users/Alice/AppData/Roaming/Microsoft/Windows/Recent'
 ```
 
 #### VMware Snapshots (`--list-snapshots`, `-s/--snapshot`)
@@ -186,9 +227,14 @@ ntfsdump ./WindowsVM -d 1 /Evidence
 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
+ntfsdump ./WindowsVM/Windows-000003.vmdk '/$MFT'
 ```
 
+Keep VMDK parents and data files within the initial disk's directory and its
+subdirectories; symlinks and junctions are not followed. VMX/VMSD disk references
+must stay within the VM directory. Update copied metadata to use local paths
+when necessary.
+
 Using with [ntfsfind](https://github.com/sumeshi/ntfsfind) over standard input (pipe):
 
 ```bash
@@ -202,12 +248,12 @@ ntfsfind '.*\.evtx' ./image.raw | ntfsdump -o ./dump ./image.raw
 `ntfsdump` can read Hyper-V checkpoint (differencing disk) chains directly. Both a base `VHDX` and an `AVHDX` differencing disk are auto-detected, and either can be passed as `SOURCE`:
 
 ```bash
-ntfsdump ./HyperVM/Disk_0.avhdx /$MFT
+ntfsdump ./HyperVM/Disk_0.avhdx '/$MFT'
 ntfsdump ./HyperVM/Disk_0.avhdx /Windows/System32/config/SYSTEM
 ```
 
 - The parent chain is resolved automatically from the VHDX metadata (parent locator), so pointing at any disk in the chain reads the whole chain as one logical disk.
-- Parent images are looked up next to the child image; absolute Windows parent paths are reduced to their basename.
+- Parents can use relative or absolute paths. For copied Windows images, place parents next to the child to use the filename fallback.
 - Images are never merged or converted — nothing is written to the source directory.
 - Checkpoint listing (`--list-checkpoints`) is not yet available, and `-s` / `--snapshot` remains VMware-only.
 
@@ -254,10 +300,10 @@ Logging is disabled by default and no log file is created. To record which files
 
 ```bash
 # Auto-generated name in the current directory (e.g. ntfsdump_20260921_153000.log)
-ntfsdump image.raw /$MFT --log
+ntfsdump image.raw '/$MFT' --log
 
 # Explicit log path
-ntfsdump image.raw /$MFT --log ./case.log
+ntfsdump image.raw '/$MFT' --log ./case.log
 ```
 
 

{ntfsdump-3.3.1 → ntfsdump-3.3.2}/README.md

@@ -78,15 +78,20 @@ vm.vmsd
 - `--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).
+- `--flat`: Extract all artifacts purely into a single folder without reconstructing directories. Directory names are joined into the filename with `_` (e.g. `/Windows/System32/cmd.exe` -> `Windows_System32_cmd.exe`) so that same-name files from different directories stay apart.
+- `--volume`, `-n`: Target the NTFS partition address shown in analysis logs (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.
+- `--output`, `-o`: Output directory (default: current directory). An existing file is used as a file output.
+- `--output-file`: Save one file or ADS to the path given by `-o`, including a new filename.
+
+In directory output, conflicting filenames receive a unique suffix. File output
+replaces an existing file only after extraction succeeds. Failed extraction
+preserves existing files.
 
 
 #### Examples
@@ -94,10 +99,16 @@ vm.vmsd
 Dump a single file (format is auto-detected):
 
 ```bash
-ntfsdump -o ./dump /path/to/your/image.raw /$MFT
+ntfsdump -o ./dump /path/to/your/image.raw '/$MFT'
 ntfsdump -o ./dump /path/to/your/evidence.E01 /Windows/System32/config/SYSTEM
 ```
 
+Save a single file under a different name:
+
+```bash
+ntfsdump --output-file -o ./SYSTEM.bin /path/to/your/image.raw /Windows/System32/config/SYSTEM
+```
+
 Dump an entire directory recursively:
 
 ```bash
@@ -107,7 +118,37 @@ 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
+ntfsdump --image-format raw /path/to/your/evidence.bin '/$MFT'
+```
+
+#### Windows Artifacts
+
+These examples use `image.raw` and save the original directory structure under
+`./dump`. Replace `Alice` with the profile directory in your image. Quote paths
+to preserve `$`, spaces, and wildcard queries when running from a shell.
+
+```bash
+# NTFS metadata: MFT, transaction log, and USN Journal
+ntfsdump -o ./dump image.raw '/$MFT' '/$LogFile' '/$Extend/$UsnJrnl:$J'
+
+# System registry hives and their transaction logs
+ntfsdump -o ./dump image.raw '/Windows/System32/config'
+
+# User registry hives and their transaction logs (prefix expansion)
+ntfsdump -o ./dump image.raw '/Users/Alice/NTUSER.DAT.*' \
+  '/Users/Alice/AppData/Local/Microsoft/Windows/UsrClass.dat.*'
+
+# Windows event logs
+ntfsdump -o ./dump image.raw '/Windows/System32/winevt/Logs'
+
+# Prefetch and Amcache
+ntfsdump -o ./dump image.raw '/Windows/Prefetch' '/Windows/AppCompat/Programs/Amcache.hve.*'
+
+# System Resource Usage Monitor (SRUM)
+ntfsdump -o ./dump image.raw '/Windows/System32/sru'
+
+# User shortcuts and Jump Lists
+ntfsdump -o ./dump image.raw '/Users/Alice/AppData/Roaming/Microsoft/Windows/Recent'
 ```
 
 #### VMware Snapshots (`--list-snapshots`, `-s/--snapshot`)
@@ -170,9 +211,14 @@ ntfsdump ./WindowsVM -d 1 /Evidence
 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
+ntfsdump ./WindowsVM/Windows-000003.vmdk '/$MFT'
 ```
 
+Keep VMDK parents and data files within the initial disk's directory and its
+subdirectories; symlinks and junctions are not followed. VMX/VMSD disk references
+must stay within the VM directory. Update copied metadata to use local paths
+when necessary.
+
 Using with [ntfsfind](https://github.com/sumeshi/ntfsfind) over standard input (pipe):
 
 ```bash
@@ -186,12 +232,12 @@ ntfsfind '.*\.evtx' ./image.raw | ntfsdump -o ./dump ./image.raw
 `ntfsdump` can read Hyper-V checkpoint (differencing disk) chains directly. Both a base `VHDX` and an `AVHDX` differencing disk are auto-detected, and either can be passed as `SOURCE`:
 
 ```bash
-ntfsdump ./HyperVM/Disk_0.avhdx /$MFT
+ntfsdump ./HyperVM/Disk_0.avhdx '/$MFT'
 ntfsdump ./HyperVM/Disk_0.avhdx /Windows/System32/config/SYSTEM
 ```
 
 - The parent chain is resolved automatically from the VHDX metadata (parent locator), so pointing at any disk in the chain reads the whole chain as one logical disk.
-- Parent images are looked up next to the child image; absolute Windows parent paths are reduced to their basename.
+- Parents can use relative or absolute paths. For copied Windows images, place parents next to the child to use the filename fallback.
 - Images are never merged or converted — nothing is written to the source directory.
 - Checkpoint listing (`--list-checkpoints`) is not yet available, and `-s` / `--snapshot` remains VMware-only.
 
@@ -238,10 +284,10 @@ Logging is disabled by default and no log file is created. To record which files
 
 ```bash
 # Auto-generated name in the current directory (e.g. ntfsdump_20260921_153000.log)
-ntfsdump image.raw /$MFT --log
+ntfsdump image.raw '/$MFT' --log
 
 # Explicit log path
-ntfsdump image.raw /$MFT --log ./case.log
+ntfsdump image.raw '/$MFT' --log ./case.log
 ```
 
 

ntfsdump-3.3.2/src/ntfsdump/__about__.py

@@ -0,0 +1,2 @@
+# coding: utf-8
+__version__ = "3.3.2"

{ntfsdump-3.3.1 → ntfsdump-3.3.2}/src/ntfsdump/cli.py

@@ -63,15 +63,23 @@ def create_parser() -> argparse.ArgumentParser:
     )
     parser.add_argument(
         "--flat", action="store_true",
-        help="save files flatly instead of reconstructing the tree (default: False)."
+        help=(
+            "save files flatly, joining the directory names into the filename "
+            "with '_' (e.g. Windows_System32_cmd.exe), instead of "
+            "reconstructing the tree (default: False)."
+        )
     )
     parser.add_argument(
         "--output", "-o", type=str, default=".",
-        help="output destination directory or file path (default: current dir '.')."
+        help="output directory or existing file; use --output-file for a new file (default: current dir '.')."
+    )
+    parser.add_argument(
+        "--output-file", action="store_true",
+        help="treat --output/-o as a file path; requires one file or ADS query."
     )
     parser.add_argument(
         "--volume", "-n", type=int, default=None,
-        help="target NTFS volume number (default: auto-detect main OS volume)."
+        help="target NTFS partition address shown in analysis logs (default: auto-detect main OS volume)."
     )
     parser.add_argument(
         "--snapshot", "-s", type=str, default=None,
@@ -242,6 +250,7 @@ def _run(args) -> None:
         disk=args.disk,
         flat=args.flat,
         quiet=args.quiet,
+        output_file=args.output_file,
     )
 
 

{ntfsdump-3.3.1 → ntfsdump-3.3.2}/src/ntfsdump/core.py

@@ -4,6 +4,7 @@ from typing import Optional, Union
 
 from ntfsdump.image import ImageFile
 from ntfsdump.logger import MetaData
+from ntfsdump.errors import NtfsDumpError
 
 
 def ntfsdump(
@@ -16,6 +17,7 @@ def ntfsdump(
     disk: Optional[int] = None,
     flat: bool = False,
     quiet: bool = False,
+    output_file: bool = False,
 ) -> None:
     """A tool for extracting files from an NTFS volume on a disk image.
 
@@ -31,8 +33,12 @@ def ntfsdump(
         flat (bool, optional): reconstruct directory tree or not. Defaults to False.
         quiet (bool, optional): suppress progress lines on stdout.
             Errors are still written to stderr. Defaults to False.
+        output_file (bool, optional): treat output as a file path. Requires one file or ADS query.
     """
     MetaData.quiet = quiet
+    output_path = Path(output).absolute()
+    if (output_file or output_path.is_file()) and len(paths) != 1:
+        raise NtfsDumpError("File output requires a single file or ADS query.")
     img = ImageFile(
         source,
         volume=volume,
@@ -40,7 +46,5 @@ def ntfsdump(
         snapshot=snapshot,
         disk=disk,
     )
-    output_dir = Path(output).resolve()
-
     for query in paths:
-        img.main_volume.dump_files(query, output_dir, flat)
+        img.main_volume.dump_files(query, output_path, flat, output_file=output_file)

{ntfsdump-3.3.1 → ntfsdump-3.3.2}/src/ntfsdump/formats/vhd.py

@@ -22,22 +22,52 @@ class VhdChain:
     handles: List["pyvhdi.file"] = field(default_factory=list)
 
 
-def _parent_path(child: Path, parent_filename: str) -> Path:
-    """Resolve a parent filename relative to the child image.
-
-    VHDX parent locators may contain absolute Windows paths (e.g.
-    ``C:\\VMs\\Base\\disk.vhdx``). Those cannot be resolved on other
-    platforms, so only the basename is used and looked up next to the child.
+def _parent_candidates(child: Path, parent_filename: str) -> List[Path]:
+    """Candidate paths for a parent disk referenced by ``parent_filename``.
+
+    A Windows absolute path from the original host (e.g.
+    ``C:\\VMs\\Base\\disk.vhdx``) is tried verbatim first — but only when it
+    is actually usable as an absolute path on this platform, so that a POSIX
+    run never resolves it relative to the current working directory. Next,
+    the drive-stripped path is tried relative to the child directory (covers
+    copied trees that keep their subdirectory structure), and the basename
+    fallback stays last for images copied together "flat".
     """
     normalized = parent_filename.replace('\\', '/')
 
-    if _WINDOWS_ABSOLUTE_RE.match(parent_filename) or normalized.startswith('//'):
-        return child.parent / Path(normalized).name
-
-    parent = Path(normalized)
-    if parent.is_absolute():
-        return parent
-    return child.parent / parent
+    if _WINDOWS_ABSOLUTE_RE.match(parent_filename):
+        candidates: List[Path] = []
+        verbatim = Path(parent_filename)
+        if verbatim.is_absolute():
+            candidates.append(verbatim)
+        stripped = normalized.split(':', 1)[1].lstrip('/')
+        candidates.append(child.parent / stripped)
+        candidates.append(child.parent / Path(normalized).name)
+    elif normalized.startswith('//'):
+        # UNC paths from the original host are only looked up by basename.
+        candidates = [child.parent / Path(normalized).name]
+    else:
+        parent = Path(normalized)
+        if parent.is_absolute():
+            candidates = [parent]
+        else:
+            candidates = [child.parent / parent]
+
+    unique: List[Path] = []
+    for candidate in candidates:
+        if candidate not in unique:
+            unique.append(candidate)
+    return unique
+
+
+def _resolve_parent(child: Path, parent_filename: str, parent_label: str) -> Path:
+    """Pick the first existing candidate parent path."""
+    for candidate in _parent_candidates(child, parent_filename):
+        if candidate.exists():
+            return candidate
+    raise NtfsDumpError(
+        f"Parent {parent_label} was not found: {parent_filename}"
+    )
 
 
 def _safe_close(handle) -> None:
@@ -78,11 +108,7 @@ def open_vhdx_chain(path: Path, _seen: Optional[List[Path]] = None) -> VhdChain:
 
         parent_filename = handle.get_parent_filename()
         if parent_filename:
-            parent = _parent_path(path, parent_filename)
-            if not parent.exists():
-                raise NtfsDumpError(
-                    f"Parent {parent_label} was not found: {parent_filename}"
-                )
+            parent = _resolve_parent(path, parent_filename, parent_label)
             parent_chain = open_vhdx_chain(parent, seen)
             handles.extend(parent_chain.handles)
             try:

ntfsdump-3.3.2/src/ntfsdump/formats/vmdk.py

@@ -0,0 +1,149 @@
+# coding: utf-8
+from dataclasses import dataclass, field
+from os.path import abspath
+from pathlib import Path, PureWindowsPath
+from typing import BinaryIO, List, Optional
+
+import pytsk3
+import pyvmdk
+
+from ntfsdump.errors import NtfsDumpError
+from ntfsdump.formats.base import FormatHandler, BaseImgInfo
+from ntfsdump.image_paths import confined_image_path
+
+
+@dataclass
+class VmdkChain:
+    """A logical VMDK disk resolved from a descriptor and its parent chain."""
+
+    handle: "pyvmdk.handle"
+    handles: List["pyvmdk.handle"] = field(default_factory=list)
+    extent_files: List[BinaryIO] = field(default_factory=list)
+
+
+def _parent_candidates(child: Path, parent_filename: str, root: Path) -> List[Path]:
+    """Map parent hints to local paths inside the initial disk directory."""
+    normalized = parent_filename.replace('\\', '/')
+    windows_path = PureWindowsPath(normalized)
+    if windows_path.drive:
+        candidates: List[Path] = []
+        if len(windows_path.drive) == 2 and windows_path.root:
+            stripped = normalized.split(':', 1)[1].lstrip('/')
+            candidates.append(child.parent / stripped)
+        candidates.append(child.parent / windows_path.name)
+    elif normalized.startswith('/'):
+        candidates = [child.parent / Path(normalized).name]
+    else:
+        candidates = [child.parent / normalized]
+
+    unique: List[Path] = []
+    for candidate in candidates:
+        # Check lexical containment before any filesystem access.
+        candidate = Path(abspath(candidate))
+        if candidate.is_relative_to(root) and candidate not in unique:
+            unique.append(candidate)
+    return unique
+
+
+def _resolve_parent(child: Path, parent_filename: str, root: Path) -> Path:
+    """Pick a local parent without following symlinks or Windows junctions."""
+    for candidate in _parent_candidates(child, parent_filename, root):
+        try:
+            candidate = confined_image_path(child.parent, str(candidate), root)
+        except NtfsDumpError:
+            continue
+        if candidate.is_file():
+            return candidate
+    raise NtfsDumpError(f"Parent VMDK was not found: {parent_filename}")
+
+
+def _safe_close(handle) -> None:
+    try:
+        handle.close()
+    except Exception:
+        pass
+
+
+def open_vmdk_chain(
+    path: Path,
+    _seen: Optional[List[Path]] = None,
+    _root: Optional[Path] = None,
+) -> VmdkChain:
+    """Open ``path`` and recursively attach its parent VMDK, without merging.
+
+    Validated extent files are passed to libvmdk as file objects so that they
+    are treated as a single logical disk. Snapshot/delta chains
+    are linked through ``set_parent()`` so that unallocated blocks fall back to
+    the parent image. Parents must stay within the initial disk directory;
+    absolute and UNC hints are mapped to local candidates. No temporary RAW
+    or merged VMDK is created.
+    """
+    path = Path(path)
+    seen = list(_seen or [])
+    resolved = path.resolve()
+    root = _root if _root is not None else resolved.parent
+
+    if resolved in seen:
+        chain = ' -> '.join(p.name for p in seen + [resolved])
+        raise NtfsDumpError(f"Circular VMDK parent reference detected: {chain}")
+    seen.append(resolved)
+
+    handles: List["pyvmdk.handle"] = []
+    extent_files: List[BinaryIO] = []
+    try:
+        handle = pyvmdk.handle()
+        handles.append(handle)
+        handle.open(str(path), mode='r')
+        with resolved.open('rb') as descriptor_file:
+            embedded_descriptor = descriptor_file.read(4) == b'KDMV'
+        for extent in handle.extent_descriptors:
+            if embedded_descriptor and handle.disk_type in (
+                pyvmdk.disk_types.MONOLITHIC_SPARSE, pyvmdk.disk_types.STREAM_OPTIMIZED,
+            ):
+                # Embedded extents use the source itself even after it is renamed.
+                extent_path = resolved
+            else:
+                extent_path = confined_image_path(resolved.parent, extent.filename, root)
+            extent_files.append(extent_path.open('rb'))
+        handle.open_extent_data_files_as_file_objects(extent_files)
+
+        parent_filename = handle.get_parent_filename()
+        if parent_filename:
+            parent = _resolve_parent(resolved, parent_filename, root)
+            parent_chain = open_vmdk_chain(parent, seen, root)
+            handles.extend(parent_chain.handles)
+            extent_files.extend(parent_chain.extent_files)
+            try:
+                handle.set_parent(parent_chain.handle)
+            except Exception as exc:
+                raise NtfsDumpError(
+                    f"Unable to attach parent VMDK: {parent_filename} ({exc})"
+                ) from exc
+    except NtfsDumpError:
+        for item in handles + extent_files:
+            _safe_close(item)
+        raise
+    except Exception as exc:
+        for item in handles + extent_files:
+            _safe_close(item)
+        raise NtfsDumpError(f"Unable to open VMDK: {path} ({exc})") from exc
+
+    return VmdkChain(handle=handles[0], handles=handles, extent_files=extent_files)
+
+
+def probe_media_size(path: Path) -> Optional[int]:
+    """Return the logical size of a VMDK descriptor, or None if unavailable."""
+    try:
+        handle = pyvmdk.handle()
+        handle.open(str(path), mode='r')
+        size = handle.get_media_size()
+        handle.close()
+        return int(size)
+    except Exception:
+        return None
+
+
+class VMDKHandler(FormatHandler):
+    def get_img_info(self, path: str) -> pytsk3.Img_Info:
+        chain = open_vmdk_chain(Path(path))
+        return BaseImgInfo(chain.handle, keepalive=chain.handles + chain.extent_files)