ntfsdump 3.2.0__tar.gz → 3.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ntfsdump
-Version: 3.2.0
+Version: 3.3.1
 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
@@ -43,6 +43,7 @@ It supports common forensic image formats such as RAW, E01, VHD/VHDX, and VMDK t
 - 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
+- Reads Hyper-V checkpoint chains (`VHDX`/`AVHDX` differencing disks) without merging or converting them
 - Read paths from standard input for integration with tools such as `ntfsfind`
 - Use as a command-line tool or Python library
 
@@ -61,7 +62,7 @@ chmod +x ./ntfsdump
 
 ## Supported Input
 
-- Image formats: `RAW`, `E01`, `VHD`, `VHDX`, `VMDK` (auto-detected), plus VMware VM directories, VMX and VMSD
+- Image formats: `RAW`, `E01`, `VHD`, `VHDX` (including Hyper-V `AVHDX` differencing disks), `VMDK` (auto-detected), plus VMware VM directories, VMX and VMSD
 - File system: `NTFS`
 - Partition tables: GPT and MBR are both supported
 
@@ -83,6 +84,7 @@ disk.raw
 evidence.E01
 disk.vhd
 disk.vhdx
+disk.avhdx
 disk.vmdk
 vm.vmsd
 /path/to/vm/
@@ -195,6 +197,20 @@ 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`).*
 
+#### Hyper-V checkpoints (VHDX/AVHDX)
+
+`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 /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.
+- 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.
+
 
 ### Python Module
 

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

@@ -27,6 +27,7 @@ It supports common forensic image formats such as RAW, E01, VHD/VHDX, and VMDK t
 - 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
+- Reads Hyper-V checkpoint chains (`VHDX`/`AVHDX` differencing disks) without merging or converting them
 - Read paths from standard input for integration with tools such as `ntfsfind`
 - Use as a command-line tool or Python library
 
@@ -45,7 +46,7 @@ chmod +x ./ntfsdump
 
 ## Supported Input
 
-- Image formats: `RAW`, `E01`, `VHD`, `VHDX`, `VMDK` (auto-detected), plus VMware VM directories, VMX and VMSD
+- Image formats: `RAW`, `E01`, `VHD`, `VHDX` (including Hyper-V `AVHDX` differencing disks), `VMDK` (auto-detected), plus VMware VM directories, VMX and VMSD
 - File system: `NTFS`
 - Partition tables: GPT and MBR are both supported
 
@@ -67,6 +68,7 @@ disk.raw
 evidence.E01
 disk.vhd
 disk.vhdx
+disk.avhdx
 disk.vmdk
 vm.vmsd
 /path/to/vm/
@@ -179,6 +181,20 @@ 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`).*
 
+#### Hyper-V checkpoints (VHDX/AVHDX)
+
+`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 /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.
+- 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.
+
 
 ### Python Module
 

ntfsdump-3.3.1/src/ntfsdump/__about__.py

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

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

@@ -36,6 +36,9 @@ examples:
 
   ntfsdump image.raw /$MFT --log ./case.log
       enable logging to an explicit file (logging is disabled by default).
+
+  ntfsdump ./HyperVM/Disk_0.avhdx /$MFT
+      read a Hyper-V checkpoint chain (VHDX/AVHDX) without merging it.
 """
 
 
@@ -238,6 +241,7 @@ def _run(args) -> None:
         snapshot=args.snapshot,
         disk=args.disk,
         flat=args.flat,
+        quiet=args.quiet,
     )
 
 
@@ -245,7 +249,6 @@ def main(argv: Optional[Iterable[str]] = None) -> int:
     parser = create_parser()
     args = parser.parse_args(argv)
 
-    MetaData.quiet = args.quiet
     configure_logging(args.log)
 
     try:

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

@@ -3,6 +3,7 @@ from pathlib import Path
 from typing import Optional, Union
 
 from ntfsdump.image import ImageFile
+from ntfsdump.logger import MetaData
 
 
 def ntfsdump(
@@ -14,6 +15,7 @@ def ntfsdump(
     snapshot=None,
     disk: Optional[int] = None,
     flat: bool = False,
+    quiet: bool = False,
 ) -> None:
     """A tool for extracting files from an NTFS volume on a disk image.
 
@@ -27,7 +29,10 @@ def ntfsdump(
         snapshot (optional): VMware snapshot ID to read. Defaults to None.
         disk (Optional[int], optional): VMware virtual disk ID to read. Defaults to None.
         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.
     """
+    MetaData.quiet = quiet
     img = ImageFile(
         source,
         volume=volume,

{ntfsdump-3.2.0 → ntfsdump-3.3.1}/src/ntfsdump/formats/detect.py

@@ -8,10 +8,20 @@ import pyvmdk
 from ntfsdump.errors import NtfsDumpError
 
 
-def _is_vhdx(path: Path) -> bool:
+VHDX_SIGNATURE = b'vhdxfile'
+VHDX_SUFFIXES = ('.vhdx', '.avhdx')
+
+
+def is_vhdx_file(path) -> bool:
+    """Whether ``path`` starts with the VHDX file type identifier.
+
+    Hyper-V base VHDX and differencing AVHDX images share this signature; they
+    are distinguished by the presence of a parent locator / differential disk
+    type, which is handled by the VHDX chain resolver rather than detection.
+    """
     try:
-        with path.open('rb') as f:
-            return f.read(8) == b'vhdxfile'
+        with Path(path).open('rb') as f:
+            return f.read(8) == VHDX_SIGNATURE
     except OSError:
         return False
 
@@ -46,7 +56,7 @@ def detect_image_format(path) -> str:
 
     try:
         if pyvhdi.check_file_signature(str(p)):
-            return 'vhdx' if _is_vhdx(p) else 'vhd'
+            return 'vhdx' if is_vhdx_file(p) else 'vhd'
     except Exception:
         pass
 
@@ -60,4 +70,10 @@ def detect_image_format(path) -> str:
     if _is_vmdk_descriptor(p):
         return 'vmdk'
 
+    # VHDX/AVHDX can also be recognized by their file signature (e.g. a .vhdx
+    # file with a non-standard extension), or by the .vhdx/.avhdx extension
+    # itself (e.g. a file whose signature check was inconclusive).
+    if p.suffix.lower() in VHDX_SUFFIXES or is_vhdx_file(p):
+        return 'vhdx'
+
     return 'raw'

ntfsdump-3.3.1/src/ntfsdump/formats/vhd.py

@@ -0,0 +1,110 @@
+# coding: utf-8
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+import pytsk3
+import pyvhdi
+
+from ntfsdump.errors import NtfsDumpError
+from ntfsdump.formats.base import FormatHandler, BaseImgInfo
+from ntfsdump.formats.detect import is_vhdx_file
+
+_WINDOWS_ABSOLUTE_RE = re.compile(r'^[A-Za-z]:[\\/]')
+
+
+@dataclass
+class VhdChain:
+    """A logical VHD/VHDX disk resolved from its parent (differencing) chain."""
+
+    handle: "pyvhdi.file"
+    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.
+    """
+    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
+
+
+def _safe_close(handle) -> None:
+    try:
+        handle.close()
+    except Exception:
+        pass
+
+
+def open_vhdx_chain(path: Path, _seen: Optional[List[Path]] = None) -> VhdChain:
+    """Open ``path`` and recursively attach its parent, without merging.
+
+    Hyper-V checkpoints are differencing VHDX/AVHDX files that reference their
+    parent from the VHDX metadata (parent locator). The chain is linked with
+    ``set_parent()`` so that unallocated blocks fall back to the parent image.
+    No merge, conversion or checkpoint operation is performed.
+    """
+    path = Path(path)
+    seen = list(_seen or [])
+    resolved = path.resolve()
+
+    is_vhdx = is_vhdx_file(path)
+    family = 'VHDX' if is_vhdx else 'VHD'
+    parent_label = 'AVHDX' if is_vhdx else 'VHD'
+
+    if resolved in seen:
+        chain = ' -> '.join(p.name for p in seen + [resolved])
+        raise NtfsDumpError(
+            f"Circular {family} parent reference detected: {chain}"
+        )
+    seen.append(resolved)
+
+    handles: List["pyvhdi.file"] = []
+    try:
+        handle = pyvhdi.file()
+        handles.append(handle)
+        handle.open(str(path), mode='r')
+
+        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_chain = open_vhdx_chain(parent, seen)
+            handles.extend(parent_chain.handles)
+            try:
+                handle.set_parent(parent_chain.handle)
+            except Exception as exc:
+                raise NtfsDumpError(
+                    f"Unable to attach parent {parent_label}: "
+                    f"{parent_filename} ({exc})"
+                ) from exc
+    except NtfsDumpError:
+        for item in handles:
+            _safe_close(item)
+        raise
+    except Exception as exc:
+        for item in handles:
+            _safe_close(item)
+        raise NtfsDumpError(f"Unable to open {family} image: {path} ({exc})") from exc
+
+    return VhdChain(handle=handles[0], handles=handles)
+
+
+class VHDHandler(FormatHandler):
+    def get_img_info(self, path: str) -> pytsk3.Img_Info:
+        chain = open_vhdx_chain(Path(path))
+        return BaseImgInfo(chain.handle, keepalive=chain.handles)

ntfsdump-3.3.1/src/ntfsdump/sources/__init__.py

@@ -0,0 +1,24 @@
+# coding: utf-8
+from ntfsdump.sources.resolver import (
+    EwfSource,
+    FileSource,
+    RawSource,
+    Source,
+    SourceResolver,
+    VhdSource,
+    VhdxSource,
+    VmdkSource,
+    VmwareSource,
+)
+
+__all__ = [
+    "EwfSource",
+    "FileSource",
+    "RawSource",
+    "Source",
+    "SourceResolver",
+    "VhdSource",
+    "VhdxSource",
+    "VmdkSource",
+    "VmwareSource",
+]

{ntfsdump-3.2.0 → ntfsdump-3.3.1}/src/ntfsdump/sources/resolver.py

@@ -33,6 +33,49 @@ class FileSource(Source):
         return handler.get_img_info(str(self.path))
 
 
+class RawSource(FileSource):
+    """A raw disk image."""
+
+    format = 'raw'
+
+
+class EwfSource(FileSource):
+    """An EWF/E01 image (possibly split across multiple segments)."""
+
+    format = 'e01'
+
+
+class VhdSource(FileSource):
+    """A VHD image (conectix)."""
+
+    format = 'vhd'
+
+
+class VhdxSource(FileSource):
+    """A VHDX/AVHDX source, chain-aware for Hyper-V differencing disks.
+
+    Mirrors :class:`VmdkSource`: the parent (checkpoint) chain is resolved
+    from the VHDX metadata without merging or converting the image.
+    """
+
+    format = 'vhdx'
+
+
+class VmdkSource(FileSource):
+    """A VMDK source, chain-aware for split extents and snapshot chains."""
+
+    format = 'vmdk'
+
+
+_SOURCE_CLASSES = {
+    'raw': RawSource,
+    'e01': EwfSource,
+    'vhd': VhdSource,
+    'vhdx': VhdxSource,
+    'vmdk': VmdkSource,
+}
+
+
 class VmwareSource(Source):
     """A VMware VM directory, VMX or VMSD resolved into a logical disk."""
 
@@ -109,7 +152,10 @@ class SourceResolver:
             )
 
         resolved_format = self._resolve_format(path, image_format)
-        return FileSource(path, resolved_format)
+        source_cls = _SOURCE_CLASSES.get(resolved_format)
+        if source_cls is None:
+            raise NtfsDumpError(f"Unknown image format: {resolved_format}")
+        return source_cls(path, resolved_format)
 
     def _resolve_format(self, path: Path, image_format: Optional[str]) -> str:
         if image_format is not None:

ntfsdump-3.3.1/tests/ntfsdump/test_core.py

@@ -0,0 +1,45 @@
+# coding: utf-8
+import pytest
+
+from ntfsdump import core
+from ntfsdump.logger import MetaData
+
+
+def test_ntfsdump_resets_leaked_quiet_state(tmp_path, monkeypatch):
+    # A previous ntfsfind(verbose=True) call may leave MetaData.quiet=True
+    # in the same process; core.ntfsdump() must reset it explicitly.
+    monkeypatch.setattr(MetaData, 'quiet', True)
+
+    with pytest.raises(Exception):
+        core.ntfsdump(source=str(tmp_path), paths=['/$MFT'])
+
+    assert MetaData.quiet is False
+
+
+def test_ntfsdump_quiet_flag_is_applied(tmp_path, monkeypatch):
+    monkeypatch.setattr(MetaData, 'quiet', False)
+
+    with pytest.raises(Exception):
+        core.ntfsdump(source=str(tmp_path), paths=['/$MFT'], quiet=True)
+
+    assert MetaData.quiet is True
+
+
+def test_cli_passes_quiet_to_core(monkeypatch):
+    from ntfsdump import cli
+
+    captured = {}
+
+    def fake_ntfsdump(**kwargs):
+        captured.update(kwargs)
+
+    monkeypatch.setattr(cli, 'ntfsdump', fake_ntfsdump)
+    monkeypatch.setattr(
+        cli.SourceResolver,
+        'resolve',
+        lambda self, source, **kwargs: object(),
+    )
+
+    cli.main([str('/nonexistent'), '/$MFT', '--quiet'])
+
+    assert captured['quiet'] is True

{ntfsdump-3.2.0 → ntfsdump-3.3.1}/tests/ntfsdump/test_detect.py

@@ -5,7 +5,7 @@ import pytest
 
 from ntfsdump.errors import NtfsDumpError
 from ntfsdump.formats import get_format_handler
-from ntfsdump.formats.detect import detect_image_format
+from ntfsdump.formats.detect import detect_image_format, is_vhdx_file
 
 
 def _write(path: Path, data: bytes) -> Path:
@@ -36,6 +36,29 @@ def test_detect_vhdx(tmp_path: Path):
     assert detect_image_format(image) == 'vhdx'
 
 
+def test_detect_vhdx_by_signature_only(tmp_path: Path):
+    # Signature wins even without a .vhdx/.avhdx extension.
+    image = _write(tmp_path / 'disk.bin', b'vhdxfile' + b'\x00' * 8192)
+    assert detect_image_format(image) == 'vhdx'
+
+
+def test_detect_avhdx_by_extension_only(tmp_path: Path):
+    # Extension is accepted when the signature check is inconclusive.
+    image = _write(tmp_path / 'Disk_0.avhdx', b'\x00' * 8192)
+    assert detect_image_format(image) == 'vhdx'
+
+
+def test_detect_avhdx(tmp_path: Path):
+    image = _write(tmp_path / 'Disk_0.avhdx', b'vhdxfile' + b'\x00' * 8192)
+    assert detect_image_format(image) == 'vhdx'
+    assert is_vhdx_file(image) is True
+
+
+def test_is_vhdx_file_false_for_vhd(tmp_path: Path):
+    image = _write(tmp_path / 'disk.vhd', b'conectix' + b'\x00' * 512)
+    assert is_vhdx_file(image) is False
+
+
 def test_detect_vmdk_descriptor(tmp_path: Path):
     image = _write(
         tmp_path / 'Windows.vmdk',

{ntfsdump-3.2.0 → ntfsdump-3.3.1}/tests/ntfsdump/test_source.py

@@ -5,7 +5,16 @@ import pytest
 
 from ntfsdump.errors import NtfsDumpError
 from ntfsdump.image import is_ntfs_volume_description
-from ntfsdump.sources import FileSource, SourceResolver, VmwareSource
+from ntfsdump.sources import (
+    EwfSource,
+    FileSource,
+    RawSource,
+    SourceResolver,
+    VhdSource,
+    VhdxSource,
+    VmdkSource,
+    VmwareSource,
+)
 
 SECTOR = 512
 FIXTURES = Path(__file__).parent / 'fixtures' / 'vmware'
@@ -149,3 +158,32 @@ def test_snapshot_option_rejected_for_plain_file(tmp_path: Path):
 
     with pytest.raises(NtfsDumpError, match="VMware SOURCE"):
         SourceResolver().resolve(image, snapshot='1')
+
+
+@pytest.mark.parametrize('image_format, expected', [
+    ('raw', RawSource),
+    ('e01', EwfSource),
+    ('vhd', VhdSource),
+    ('vhdx', VhdxSource),
+    ('vmdk', VmdkSource),
+])
+def test_resolver_returns_format_specific_source(
+    tmp_path: Path, image_format: str, expected
+):
+    image = tmp_path / 'image.bin'
+    image.write_bytes(b'\x00' * 64)
+
+    source = SourceResolver().resolve(image, image_format=image_format)
+
+    assert type(source) is expected
+    assert source.format == image_format
+
+
+def test_resolver_detects_avhdx_as_vhdx_source(tmp_path: Path):
+    image = tmp_path / 'Disk_0.avhdx'
+    image.write_bytes(b'vhdxfile' + b'\x00' * 64)
+
+    source = SourceResolver().resolve(image)
+
+    assert isinstance(source, VhdxSource)
+    assert source.format == 'vhdx'

ntfsdump-3.3.1/tests/ntfsdump/test_vhd_real.py

@@ -0,0 +1,98 @@
+# coding: utf-8
+"""End-to-end tests using real pyvhdi handles (no mocks).
+
+Minimal dynamic/differential VHD images are crafted on the fly so that the
+differencing-disk parent fallback is exercised through the real libvhdi
+implementation.
+"""
+import struct
+import uuid
+from pathlib import Path
+
+SECTOR = 512
+BLOCK_SIZE = 2 * 1024 * 1024
+MAX_ENTRIES = 1
+MARKER_OFFSET = 64 * SECTOR
+
+
+def _vhd_checksum(data: bytes) -> int:
+    return (~sum(data)) & 0xFFFFFFFF
+
+
+def _make_footer(disk_type: int, disk_uuid: uuid.UUID) -> bytes:
+    f = bytearray(512)
+    f[0:8] = b'conectix'
+    struct.pack_into('>IIQ', f, 8, 0, 0x00010000, 512)
+    f[28:32] = b'ntfs'
+    struct.pack_into('>II', f, 32, 0x00010000, 0x00000002)
+    struct.pack_into('>QQ', f, 40, BLOCK_SIZE, BLOCK_SIZE)
+    struct.pack_into('>HBBH', f, 56, 0xFF, 16, 63, 0)
+    struct.pack_into('>I', f, 60, disk_type)  # 3=dynamic 4=differencing
+    f[68:84] = disk_uuid.bytes
+    struct.pack_into('>I', f, 64, _vhd_checksum(bytes(f)))
+    return bytes(f)
+
+
+def _make_dynamic_header(
+    parent_uuid: 'uuid.UUID | None' = None,
+    parent_name: str = '',
+) -> bytes:
+    h = bytearray(1024)
+    h[0:8] = b'cxsparse'
+    struct.pack_into('>Q', h, 8, 0xFFFFFFFFFFFFFFFF)
+    struct.pack_into('>Q', h, 16, 3 * SECTOR)
+    struct.pack_into('>II', h, 24, 0x00010000, MAX_ENTRIES)
+    struct.pack_into('>I', h, 32, BLOCK_SIZE)
+    if parent_uuid is not None:
+        h[40:56] = parent_uuid.bytes
+    if parent_name:
+        encoded = parent_name.encode('utf-16-be')
+        h[64:64 + len(encoded)] = encoded
+    h[576:580] = b'W2ku'
+    struct.pack_into('>I', h, 36, _vhd_checksum(bytes(h)))
+    return bytes(h)
+
+
+def _make_vhd(
+    path: Path,
+    disk_type: int,
+    disk_uuid: uuid.UUID,
+    bat_entry: int,
+    block_data: bytes,
+    parent_uuid: 'uuid.UUID | None' = None,
+    parent_name: str = '',
+) -> None:
+    path.write_bytes(
+        _make_footer(disk_type, disk_uuid)
+        + _make_dynamic_header(parent_uuid, parent_name)
+        + struct.pack('>I', bat_entry)
+        + b'\x00' * (SECTOR - 4)
+        + b'\xff' * SECTOR
+        + block_data
+        + _make_footer(disk_type, disk_uuid)
+    )
+
+
+def test_real_vhd_differential_parent_fallback(tmp_path: Path):
+    from ntfsdump.formats.vhd import VHDHandler
+
+    base_uuid = uuid.uuid4()
+    base_block = bytearray(BLOCK_SIZE)
+    base_block[MARKER_OFFSET:MARKER_OFFSET + 10] = b'PARENTDATA'
+    _make_vhd(
+        tmp_path / 'base.vhd', 3, base_uuid, 4, bytes(base_block),
+    )
+
+    # The differencing disk has its block unmapped (BAT = 0xffffffff), so any
+    # read must fall back to the parent through set_parent().
+    _make_vhd(
+        tmp_path / 'child.vhd', 4, uuid.uuid4(), 0xFFFFFFFF, b'\x00' * BLOCK_SIZE,
+        parent_uuid=base_uuid, parent_name='base.vhd',
+    )
+
+    img_info = VHDHandler().get_img_info(str(tmp_path / 'child.vhd'))
+    try:
+        assert img_info.get_size() == BLOCK_SIZE
+        assert img_info.read(MARKER_OFFSET, 10) == b'PARENTDATA'
+    finally:
+        img_info.close()

ntfsdump-3.3.1/tests/ntfsdump/test_vhdx_chain.py

@@ -0,0 +1,229 @@
+# coding: utf-8
+from pathlib import Path
+
+import pytest
+
+import ntfsdump.formats.vhd as vhd
+from ntfsdump.errors import NtfsDumpError
+from ntfsdump.formats.vhd import VHDHandler, open_vhdx_chain
+
+VHDX_HEADER = b'vhdxfile' + b'\x00' * 64
+VHD_HEADER = b'\x00' * 64
+
+
+class FakeVhdiFile:
+    files = {}
+
+    def __init__(self):
+        self._rec = None
+
+    def open(self, path, mode='r'):
+        self._rec = self.files[str(Path(path).resolve())]
+
+    def get_parent_filename(self):
+        return self._rec.get("parent_filename")
+
+    def get_identifier(self):
+        return self._rec.get("identifier")
+
+    def get_parent_identifier(self):
+        return self._rec.get("parent_identifier")
+
+    def get_media_size(self):
+        return self._rec.get("media_size", 0)
+
+    def set_parent(self, parent):
+        if self._rec.get("parent_identifier") != parent.get_identifier():
+            raise OSError("mismatch in parent identifier")
+        self._parent = parent
+
+    def seek(self, offset):
+        pass
+
+    def read(self, size):
+        return b"\x00" * size
+
+    def close(self):
+        pass
+
+
+@pytest.fixture
+def fake_vhdi(monkeypatch):
+    FakeVhdiFile.files = {}
+    monkeypatch.setattr(vhd.pyvhdi, 'file', FakeVhdiFile)
+    yield FakeVhdiFile.files
+    FakeVhdiFile.files = {}
+
+
+def _make(
+    path: Path,
+    registry: dict,
+    *,
+    parent_filename=None,
+    media_size=0,
+    identifier=None,
+    parent_identifier=None,
+    vhdx=True,
+) -> Path:
+    path.write_bytes(VHDX_HEADER if vhdx else VHD_HEADER)
+    registry[str(path.resolve())] = {
+        "parent_filename": parent_filename,
+        "identifier": identifier,
+        "parent_identifier": parent_identifier,
+        "media_size": media_size,
+    }
+    return path
+
+
+def test_base_only(tmp_path: Path, fake_vhdi):
+    base = _make(tmp_path / 'base.vhdx', fake_vhdi, media_size=4096)
+    chain = open_vhdx_chain(base)
+
+    assert len(chain.handles) == 1
+    assert chain.handle.get_media_size() == 4096
+
+
+def test_base_plus_child(tmp_path: Path, fake_vhdi):
+    _make(
+        tmp_path / 'base.vhdx', fake_vhdi,
+        media_size=4096, identifier='base-id',
+    )
+    child = _make(
+        tmp_path / 'base-000001.avhdx', fake_vhdi,
+        parent_filename='base.vhdx',
+        media_size=4096, identifier='child-id', parent_identifier='base-id',
+    )
+    chain = open_vhdx_chain(child)
+
+    assert len(chain.handles) == 2
+    assert chain.handle.get_media_size() == 4096
+    # The child must actually be linked to the parent handle so that
+    # unallocated blocks fall back to it.
+    assert chain.handle._parent is chain.handles[1]
+
+
+def test_base_plus_two_levels(tmp_path: Path, fake_vhdi):
+    _make(
+        tmp_path / 'base.vhdx', fake_vhdi,
+        media_size=4096, identifier='base-id',
+    )
+    _make(
+        tmp_path / 'base-000001.avhdx', fake_vhdi,
+        parent_filename='base.vhdx',
+        media_size=4096, identifier='c1-id', parent_identifier='base-id',
+    )
+    c2 = _make(
+        tmp_path / 'base-000002.avhdx', fake_vhdi,
+        parent_filename='base-000001.avhdx',
+        media_size=4096, identifier='c2-id', parent_identifier='c1-id',
+    )
+    chain = open_vhdx_chain(c2)
+
+    assert len(chain.handles) == 3
+    assert chain.handle._parent is chain.handles[1]
+    assert chain.handles[1]._parent is chain.handles[2]
+
+
+def test_missing_parent_raises(tmp_path: Path, fake_vhdi):
+    child = _make(
+        tmp_path / 'base-000001.avhdx', fake_vhdi,
+        parent_filename='missing.vhdx',
+        media_size=4096, identifier='child-id', parent_identifier='base-id',
+    )
+
+    with pytest.raises(
+        NtfsDumpError, match="Parent AVHDX was not found: missing.vhdx"
+    ):
+        open_vhdx_chain(child)
+
+
+def test_circular_parent_raises(tmp_path: Path, fake_vhdi):
+    _make(
+        tmp_path / 'a.avhdx', fake_vhdi,
+        parent_filename='b.avhdx',
+        media_size=4096, identifier='a-id', parent_identifier='b-id',
+    )
+    _make(
+        tmp_path / 'b.avhdx', fake_vhdi,
+        parent_filename='a.avhdx',
+        media_size=4096, identifier='b-id', parent_identifier='a-id',
+    )
+
+    with pytest.raises(
+        NtfsDumpError, match="Circular VHDX parent reference detected"
+    ):
+        open_vhdx_chain(tmp_path / 'a.avhdx')
+
+
+def test_windows_absolute_parent(tmp_path: Path, fake_vhdi):
+    _make(
+        tmp_path / 'base.vhdx', fake_vhdi,
+        media_size=8192, identifier='base-id',
+    )
+    child = _make(
+        tmp_path / 'vm.avhdx', fake_vhdi,
+        parent_filename='C:\\VMs\\Base\\base.vhdx',
+        media_size=8192, identifier='child-id', parent_identifier='base-id',
+    )
+    chain = open_vhdx_chain(child)
+
+    assert len(chain.handles) == 2
+
+
+def test_relative_parent_path_with_parent_directory(tmp_path: Path, fake_vhdi):
+    (tmp_path / 'base').mkdir()
+    _make(
+        tmp_path / 'base' / 'base.vhdx', fake_vhdi,
+        media_size=4096, identifier='base-id',
+    )
+    (tmp_path / 'child').mkdir()
+    child = _make(
+        tmp_path / 'child' / 'vm.avhdx', fake_vhdi,
+        parent_filename='../base/base.vhdx',
+        media_size=4096, identifier='child-id', parent_identifier='base-id',
+    )
+    chain = open_vhdx_chain(child)
+
+    assert len(chain.handles) == 2
+    assert chain.handle._parent is chain.handles[1]
+
+
+def test_parent_identifier_mismatch_raises(tmp_path: Path, fake_vhdi):
+    _make(
+        tmp_path / 'base.vhdx', fake_vhdi,
+        media_size=4096, identifier='base-id',
+    )
+    child = _make(
+        tmp_path / 'vm.avhdx', fake_vhdi,
+        parent_filename='base.vhdx',
+        media_size=4096, identifier='child-id', parent_identifier='wrong-id',
+    )
+
+    with pytest.raises(
+        NtfsDumpError, match="Unable to attach parent AVHDX: base.vhdx"
+    ):
+        open_vhdx_chain(child)
+
+
+def test_non_vhdx_missing_parent_message(tmp_path: Path, fake_vhdi):
+    child = _make(
+        tmp_path / 'legacy.vhd', fake_vhdi,
+        parent_filename='missing.vhd',
+        media_size=4096, identifier='child-id', parent_identifier='base-id',
+        vhdx=False,
+    )
+
+    with pytest.raises(
+        NtfsDumpError, match="Parent VHD was not found: missing.vhd"
+    ):
+        open_vhdx_chain(child)
+
+
+def test_vhd_handler_reads_logical_disk(tmp_path: Path, fake_vhdi):
+    base = _make(tmp_path / 'base.vhdx', fake_vhdi, media_size=4096)
+
+    img_info = VHDHandler().get_img_info(str(base))
+
+    assert img_info.get_size() == 4096
+    assert img_info.read(0, 4) == b'\x00\x00\x00\x00'
+    img_info.close()

ntfsdump-3.3.1/tests/ntfsdump/test_vhdx_real.py

@@ -0,0 +1,217 @@
+# coding: utf-8
+"""End-to-end VHDX/AVHDX tests using real pyvhdi handles (no mocks).
+
+Minimal dynamic + differential VHDX images are crafted byte-by-byte (VHDX
+structures: file type identifier, image headers, region tables with CRC-32C,
+metadata region with parent locator, BAT) so that the Hyper-V checkpoint
+parent fallback is exercised through the real libvhdi implementation.
+"""
+import struct
+import uuid
+from pathlib import Path
+
+from pathlib import Path
+
+SECTOR = 512
+BLOCK_SIZE = 1024 * 1024
+DISK_SIZE = 4 * 1024 * 1024
+NUM_BLOCKS = DISK_SIZE // BLOCK_SIZE
+PAYLOAD_OFFSET = 3 * 1024 * 1024
+METADATA_OFFSET = 1024 * 1024
+BAT_OFFSET = 2 * 1024 * 1024
+
+GUID_BAT = bytes([0x66, 0x77, 0xC2, 0x2D, 0x23, 0xF6, 0x00, 0x42,
+                  0x9D, 0x64, 0x11, 0x5E, 0x9B, 0xFD, 0x4A, 0x08])
+GUID_METADATA = bytes([0x06, 0xA2, 0x7C, 0x8B, 0x90, 0x47, 0x9A, 0x4B,
+                       0xB8, 0xFE, 0x57, 0x5F, 0x05, 0x0F, 0x88, 0x6E])
+GUID_FILE_PARAMS = bytes([0x37, 0x67, 0xA1, 0xCA, 0x36, 0xFA, 0x43, 0x4D,
+                          0xB3, 0xB6, 0x33, 0xF0, 0xAA, 0x44, 0xE7, 0x6B])
+GUID_LOGICAL_SECTOR = bytes([0x1D, 0xBF, 0x41, 0x81, 0x6F, 0xA9, 0x09, 0x47,
+                             0xBA, 0x47, 0xF2, 0x33, 0xA8, 0xFA, 0xAB, 0x5F])
+GUID_PHYSICAL_SECTOR = bytes([0xC7, 0x48, 0xA3, 0xCD, 0x5D, 0x44, 0x71, 0x44,
+                              0x9C, 0xC9, 0xE9, 0x88, 0x52, 0x51, 0xC5, 0x56])
+GUID_DISK_ID = bytes([0xAB, 0x12, 0xCA, 0xBE, 0xE6, 0xB2, 0x23, 0x45,
+                      0x93, 0xEF, 0xC3, 0x09, 0xE0, 0x00, 0xC7, 0x46])
+GUID_DISK_SIZE = bytes([0x24, 0x42, 0xA5, 0x2F, 0x1B, 0xCD, 0x76, 0x48,
+                        0xB2, 0x11, 0x5D, 0xBE, 0xD8, 0x3B, 0xF4, 0xB8])
+GUID_PARENT_LOCATOR_ITEM = bytes([0x2D, 0x5F, 0xD3, 0xA8, 0x0B, 0xB3, 0x4D, 0x45,
+                                  0xAB, 0xF7, 0xD3, 0xD8, 0x48, 0x34, 0xAB, 0x0C])
+# Parent locator type indicator (b04aefb7-d19e-4fea-b789-25b8e9445913).
+GUID_PARENT_LOCATOR_TYPE = bytes([0xB7, 0xEF, 0x4A, 0xB0, 0x9E, 0xD1, 0x81, 0x4A,
+                                  0xB7, 0x89, 0x25, 0xB8, 0xE9, 0x44, 0x59, 0x13])
+
+
+def crc32c(data: bytes) -> int:
+    # libvhdi uses CRC-32C (Castagnoli polynomial 0x82f63b78).
+    table = []
+    for index in range(256):
+        checksum = index
+        for _ in range(8):
+            checksum = (0x82F63B78 ^ (checksum >> 1)) if (checksum & 1) else (checksum >> 1)
+        table.append(checksum)
+    checksum = 0xFFFFFFFF
+    for byte in data:
+        checksum = table[(checksum ^ byte) & 0xFF] ^ (checksum >> 8)
+    return checksum ^ 0xFFFFFFFF
+
+
+def crc32(data: bytes) -> int:
+    return crc32c(data)
+
+
+def file_type_identifier() -> bytes:
+    return b'vhdxfile' + b'\x00' * 56
+
+
+def image_header(file_size: int, sequence: int,
+                 data_write_uuid: 'uuid.UUID | None' = None) -> bytes:
+    h = bytearray(4096)
+    h[0:4] = b'head'
+    struct.pack_into('<Q', h, 8, sequence)
+    h[16:32] = uuid.uuid4().bytes
+    # VHDX: set_parent compares the child's parent_linkage GUID against the
+    # parent's data write identifier.
+    h[32:48] = (data_write_uuid.bytes_le if data_write_uuid
+                else uuid.uuid4().bytes)
+    h[48:64] = uuid.uuid4().bytes
+    struct.pack_into('<H', h, 64, 0)            # log format version
+    struct.pack_into('<H', h, 66, 1)            # format version
+    struct.pack_into('<I', h, 68, 0)            # log size
+    struct.pack_into('<Q', h, 72, 0)            # log offset
+    struct.pack_into('<I', h, 4, crc32(bytes(h)))
+    return bytes(h)
+
+
+def region_table(metadata_offset: int, bat_offset: int) -> bytes:
+    # libvhdi validates the CRC32 over the whole 64KB region table area
+    # (header with checksum zeroed + padding).
+    t = bytearray(64 * 1024)
+    t[0:4] = b'regi'
+    struct.pack_into('<I', t, 8, 2)             # number of entries
+    struct.pack_into('<16sQII', t, 16, GUID_METADATA,
+                     metadata_offset, 1024 * 1024, 1)
+    struct.pack_into('<16sQII', t, 48, GUID_BAT,
+                     bat_offset, 1024 * 1024, 1)
+    struct.pack_into('<I', t, 4, crc32(bytes(t)))
+    return bytes(t)
+
+
+def parent_locator_item(parent_name: str, parent_uuid: uuid.UUID) -> bytes:
+    key0 = 'absolute_win32_path\x00'.encode('utf-16-le')
+    key1 = 'parent_linkage\x00'.encode('utf-16-le')
+    val0 = parent_name.encode('utf-16-le') + b'\x00\x00'
+    val1 = ('{' + str(parent_uuid) + '}\x00').encode('utf-16-le')
+
+    item = bytearray()
+    item += GUID_PARENT_LOCATOR_TYPE
+    item += struct.pack('<HH', 0, 2)            # reserved, entry count
+    base = 20 + 2 * 12                          # 2 entries x 12 bytes
+    item += struct.pack('<IIHH', base, base + len(key0), len(key0), len(val0))
+    item += struct.pack('<IIHH', base + len(key0) + len(val0),
+                        base + len(key0) + len(val0) + len(key1),
+                        len(key1), len(val1))
+    item += key0 + val0 + key1 + val1
+    return bytes(item)
+
+
+def metadata_region(block_size: int, disk_size: int, disk_uuid: uuid.UUID,
+                    differential: bool, parent_item: bytes = b'') -> bytes:
+    items = [
+        (GUID_FILE_PARAMS,
+         struct.pack('<II', block_size, 2 if differential else 0)),
+        (GUID_DISK_SIZE, struct.pack('<Q', disk_size)),
+        (GUID_LOGICAL_SECTOR, struct.pack('<I', SECTOR)),
+        (GUID_PHYSICAL_SECTOR, struct.pack('<I', SECTOR)),
+        (GUID_DISK_ID, disk_uuid.bytes_le),
+    ]
+    if parent_item:
+        items.append((GUID_PARENT_LOCATOR_ITEM, parent_item))
+
+    table_size = 32 + 32 * len(items)
+    blob = bytearray()
+    offsets = []
+    # VHDX spec/libvhdi require item offsets to be >= 64KB within the region.
+    pos = max(64 * 1024, (table_size + 7) & ~7)
+    for guid, data in items:
+        offsets.append(pos)
+        pos = (pos + len(data) + 7) & ~7
+
+    region = bytearray(1024 * 1024)
+    region[0:8] = b'metadata'                    # metadata table header
+    struct.pack_into('<H', region, 8, 0)         # reserved
+    struct.pack_into('<H', region, 10, len(items))
+    entry_offset = 32
+    for index, ((guid, data), offset) in enumerate(zip(items, offsets)):
+        struct.pack_into('<16sIII', region, entry_offset + 32 * index,
+                         guid, offset, len(data), 0)
+    start = offsets[0]
+    for (guid, data), offset in zip(items, offsets):
+        rel = offset - start
+        if len(blob) < rel:
+            blob += b'\x00' * (rel - len(blob))
+        blob += data
+    region[start:start + len(blob)] = blob
+    return bytes(region)
+
+
+def bat_region(entries):
+    bat = bytearray(1024 * 1024)
+    for index, entry in enumerate(entries):
+        struct.pack_into('<Q', bat, 8 * index, entry)
+    return bytes(bat)
+
+
+def make_vhdx(path: Path, disk_uuid: uuid.UUID, differential: bool,
+              parent_name: str = '', parent_uuid: uuid.UUID = None,
+              marker: bool = False,
+              data_write_uuid: 'uuid.UUID | None' = None) -> None:
+    f = bytearray()
+    f += file_type_identifier()
+    f += b'\x00' * (0x10000 - len(f))
+    f += image_header(0, 1, data_write_uuid)     # placeholder file size
+    f += b'\x00' * (0x20000 - len(f))
+    f += image_header(0, 2, data_write_uuid)
+    f += b'\x00' * (0x30000 - len(f))
+    f += region_table(METADATA_OFFSET, BAT_OFFSET)
+    f += b'\x00' * (0x40000 - len(f))
+    f += region_table(METADATA_OFFSET, BAT_OFFSET)
+    f += b'\x00' * (METADATA_OFFSET - len(f))
+
+    if differential:
+        locator = parent_locator_item(parent_name, parent_uuid)
+        f += metadata_region(BLOCK_SIZE, DISK_SIZE, disk_uuid, True, locator)
+        f += bat_region([0] * NUM_BLOCKS)
+    else:
+        f += metadata_region(BLOCK_SIZE, DISK_SIZE, disk_uuid, False)
+        entries = [(PAYLOAD_OFFSET // (1024 * 1024) + i) << 20 | 6
+                   for i in range(NUM_BLOCKS)]
+        f += bat_region(entries)
+        f += b'\x00' * (PAYLOAD_OFFSET - len(f))
+        for i in range(NUM_BLOCKS):
+            block = bytearray(BLOCK_SIZE)
+            if marker and i == 0:
+                block[128 * 1024:128 * 1024 + 10] = b'PARENTDATA'
+            f += bytes(block)
+
+    path.write_bytes(bytes(f))
+
+
+def test_real_vhdx_differential_parent_fallback(tmp_path: Path):
+    from ntfsdump.formats.vhd import VHDHandler
+
+    base_uuid = uuid.uuid4()
+    make_vhdx(
+        tmp_path / 'base.vhdx', base_uuid, False, marker=True,
+        data_write_uuid=base_uuid,
+    )
+    make_vhdx(
+        tmp_path / 'diff.avhdx', uuid.uuid4(), True,
+        parent_name='base.vhdx', parent_uuid=base_uuid,
+    )
+
+    img_info = VHDHandler().get_img_info(str(tmp_path / 'diff.avhdx'))
+    try:
+        assert img_info.get_size() == 4 * 1024 * 1024
+        assert img_info.read(128 * 1024, 10) == b'PARENTDATA'
+    finally:
+        img_info.close()

ntfsdump-3.2.0/src/ntfsdump/__about__.py

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

ntfsdump-3.2.0/src/ntfsdump/formats/vhd.py

@@ -1,10 +0,0 @@
-# coding: utf-8
-import pyvhdi
-import pytsk3
-from ntfsdump.formats.base import FormatHandler, BaseImgInfo
-
-class VHDHandler(FormatHandler):
-    def get_img_info(self, path: str) -> pytsk3.Img_Info:
-        vhdi_file = pyvhdi.file()
-        vhdi_file.open(path, mode='r')
-        return BaseImgInfo(vhdi_file)

ntfsdump-3.2.0/src/ntfsdump/sources/__init__.py

@@ -1,9 +0,0 @@
-# coding: utf-8
-from ntfsdump.sources.resolver import (
-    FileSource,
-    Source,
-    SourceResolver,
-    VmwareSource,
-)
-
-__all__ = ["FileSource", "Source", "SourceResolver", "VmwareSource"]