vdiskprobe 1.0.0__py3-none-any.whl

vdiskprobe/__init__.py

@@ -0,0 +1,29 @@
+# Copyright (c) 2026 IsArvin.
+# This file is part of VDiskProbe. Please refer to the LICENCE file for licence information.
+
+"""Public package exports for VDiskProbe."""
+
+from vdiskprobe.api import build_default_registry, detect, detect_path, detect_url, inspect_source
+from vdiskprobe.detectors import DetectorRegistry, FormatDetector
+from vdiskprobe.errors import VDiskProbeError, InvalidSourceError, RemoteSourceError
+from vdiskprobe.info import ImageInfo
+from vdiskprobe.log import configure_logging, get_logger
+from vdiskprobe.source import ByteSource
+from vdiskprobe.version import __version__
+
+__all__ = [
+    "ByteSource",
+    "DetectorRegistry",
+    "FormatDetector",
+    "ImageInfo",
+    "VDiskProbeError",
+    "InvalidSourceError",
+    "RemoteSourceError",
+    "build_default_registry",
+    "configure_logging",
+    "detect",
+    "detect_path",
+    "detect_url",
+    "get_logger",
+    "inspect_source",
+]

vdiskprobe/__main__.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2026 IsArvin.
+# This file is part of VDiskProbe. Please refer to the LICENCE file for licence information.
+
+"""Module entry point for ``python -m vdiskprobe``."""
+
+from vdiskprobe.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vdiskprobe/api.py

@@ -0,0 +1,119 @@
+# Copyright (c) 2026 IsArvin.
+# This file is part of VDiskProbe. Please refer to the LICENCE file for licence information.
+
+"""High-level convenience API for VDiskProbe."""
+
+import os
+
+from vdiskprobe.detectors import build_default_registry as _build_default_registry
+from vdiskprobe.detectors.base import DetectorRegistry
+from vdiskprobe.errors import InvalidSourceError
+from vdiskprobe.http_source import HttpRangeReader, is_http_url
+from vdiskprobe.info import ImageInfo
+from vdiskprobe.source import ByteSource
+
+_DEFAULT_REGISTRY = None
+_HTTP_READER_CLASS = HttpRangeReader
+
+
+def get_default_registry() -> DetectorRegistry:
+    """Return the process-wide default detector registry.
+
+    Returns
+    -------
+    DetectorRegistry
+        Detector registry instance populated with the built-in detectors.
+    """
+    global _DEFAULT_REGISTRY
+    if _DEFAULT_REGISTRY is None:
+        _DEFAULT_REGISTRY = _build_default_registry()
+    return _DEFAULT_REGISTRY
+
+
+def inspect_source(source: object, registry: DetectorRegistry | None = None, name: str | None = None) -> ImageInfo:
+    """Inspect an arbitrary byte source.
+
+    Parameters
+    ----------
+    source : object
+        Seekable file-like object, random-access reader, or ``ByteSource``.
+    registry : DetectorRegistry, optional
+        Explicit detector registry. The built-in default registry is used
+        when omitted.
+    name : str, optional
+        Friendly source name shown in detection results.
+
+    Returns
+    -------
+    ImageInfo
+        Detected image information record.
+    """
+    byte_source = source if isinstance(source, ByteSource) else ByteSource(source, name=name)
+    active_registry = registry or get_default_registry()
+    return active_registry.detect(byte_source)
+
+
+def detect(source: object, registry: DetectorRegistry | None = None, name: str | None = None) -> ImageInfo:
+    """Detect the image format of an arbitrary byte source.
+
+    Parameters
+    ----------
+    source : object
+        Seekable file-like object, random-access reader, or ``ByteSource``.
+    registry : DetectorRegistry, optional
+        Explicit detector registry.
+    name : str, optional
+        Friendly source name shown in the resulting ``ImageInfo``.
+
+    Returns
+    -------
+    ImageInfo
+        Detected image information record.
+    """
+    return inspect_source(source, registry=registry, name=name)
+
+
+def detect_url(url: str, registry: DetectorRegistry | None = None) -> ImageInfo:
+    """Detect the image format of an HTTP or HTTPS URL."""
+    if not is_http_url(url):
+        # URL syntax only; this literal is never used for a network request.
+        # noinspection HttpUrlsUsage
+        raise InvalidSourceError("url must use http:// or https://")
+    reader = _HTTP_READER_CLASS(url)
+    return inspect_source(reader, registry=registry, name=url)
+
+
+def detect_path(path: str | os.PathLike[str], registry: DetectorRegistry | None = None) -> ImageInfo:
+    """Detect the image format of a filesystem path or HTTP/HTTPS URL.
+
+    Parameters
+    ----------
+    path : str
+        Path or URL to an image file.
+    registry : DetectorRegistry, optional
+        Explicit detector registry.
+
+    Returns
+    -------
+    ImageInfo
+        Detected image information record.
+    """
+    # Both str and PathLike[str] are valid; PyCharm cannot resolve the generic union overload.
+    # noinspection PyTypeChecker
+    path = os.fspath(path)
+    if is_http_url(path):
+        return detect_url(path, registry=registry)
+    with open(path, "rb") as handle:
+        info = inspect_source(handle, registry=registry, name=path)
+    return info
+
+
+def build_default_registry() -> DetectorRegistry:
+    """Create a new detector registry with the built-in detectors.
+
+    Returns
+    -------
+    DetectorRegistry
+        Fresh detector registry instance.
+    """
+    return _build_default_registry()

vdiskprobe/cli.py

@@ -0,0 +1,195 @@
+# Copyright (c) 2026 IsArvin.
+# This file is part of VDiskProbe. Please refer to the LICENCE file for licence information.
+
+"""Command-line interface for VDiskProbe."""
+
+import argparse
+from decimal import Decimal
+import json
+import logging
+import os
+import sys
+from typing import TextIO
+
+from vdiskprobe.info import ImageInfo
+from vdiskprobe.api import detect_path, get_default_registry
+from vdiskprobe.errors import VDiskProbeError
+from vdiskprobe.log import configure_logging
+from vdiskprobe.version import __version__
+
+SIZE_UNITS = ("bytes", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line argument parser.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured parser instance.
+    """
+    parser = argparse.ArgumentParser(
+        prog="vdiskprobe", description="Detect VM image formats using VDiskProbe.", add_help=False
+    )
+    parser.add_argument("-h", "--help", action="help", help="Show this message and exit.")
+    parser.add_argument("path", nargs="?", help="Path or HTTP/HTTPS URL to the VM image.")
+    parser.add_argument("--json", action="store_true", help="Print JSON output.")
+    parser.add_argument("--list-formats", action="store_true", help="List built-in formats and exit.")
+    parser.add_argument(
+        "-V", "--version", action="version", version="%(prog)s {0}".format(__version__), help="Print version and exit."
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="count", default=0, help="Increase log verbosity. Repeat for debug logs."
+    )
+    parser.add_argument("-q", "--quiet", action="store_true", help="Only log errors.")
+    return parser
+
+
+def resolve_log_level(args: argparse.Namespace) -> int:
+    """Resolve the effective CLI log level.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed command-line arguments.
+
+    Returns
+    -------
+    int
+        Logging level constant.
+    """
+    if args.quiet:
+        return logging.ERROR
+    if args.verbose >= 2:
+        return logging.DEBUG
+    if args.verbose == 1:
+        return logging.INFO
+    return logging.WARNING
+
+
+def format_size(value: int) -> str:
+    """Format a byte count with an IEC unit and the exact byte value."""
+    size = int(value)
+    abs_size = abs(size)
+    unit_index = 0
+    try:
+        scaled = float(abs_size)
+    except OverflowError:
+        scaled = Decimal(abs_size)
+    while unit_index + 1 < len(SIZE_UNITS) and scaled >= 1024.0:
+        scaled /= 1024
+        unit_index += 1
+    if unit_index == 0:
+        readable = "{0} bytes".format(size)
+    else:
+        if scaled >= 100 or scaled == int(scaled):
+            number = format(scaled, ".0f")
+        elif scaled >= 10:
+            number = format(scaled, ".1f")
+        else:
+            number = format(scaled, ".2f")
+        if "." in number:
+            number = number.rstrip("0").rstrip(".")
+        if size < 0:
+            number = "-{0}".format(number)
+        readable = "{0} {1}".format(number, SIZE_UNITS[unit_index])
+    return "{0} ({1} bytes)".format(readable, size)
+
+
+def print_formats(stream: TextIO) -> None:
+    """Write the built-in detector list to a stream.
+
+    Parameters
+    ----------
+    stream : object
+        Text output stream.
+    """
+    write = getattr(stream, "write")
+    registry = get_default_registry()
+    for metadata in registry.describe_formats():
+        aliases = metadata.get("aliases") or []
+        alias_suffix = ""
+        if aliases:
+            alias_suffix = " (aliases: {0})".format(", ".join(aliases))
+        mode = "read-only" if metadata.get("read_only") else "read-write"
+        line = "{0}: {1} [{2}]{3}".format(metadata["format"], metadata["description"], mode, alias_suffix)
+        write(line)
+        write(os.linesep)
+
+
+def print_human(info: ImageInfo, stream: TextIO) -> None:
+    """Write a human-readable detection report.
+
+    Parameters
+    ----------
+    info : ImageInfo
+        Detected image information record.
+    stream : object
+        Text output stream.
+    """
+    write = getattr(stream, "write")
+    lines = [
+        "path: {0}".format(info.source_name or "<unknown>"),
+        "format: {0}".format(info.format),
+        "description: {0}".format(info.description),
+    ]
+    if info.virtual_size is not None:
+        lines.append("virtual_size: {0}".format(format_size(info.virtual_size)))
+    if info.file_size is not None:
+        lines.append("file_size: {0}".format(format_size(info.file_size)))
+    if info.disk_size is not None:
+        lines.append("disk_size: {0}".format(format_size(info.disk_size)))
+    if info.cluster_size is not None:
+        lines.append("cluster_size: {0}".format(format_size(info.cluster_size)))
+    lines.extend(
+        [
+            "read_only: {0}".format("yes" if info.read_only else "no"),
+            "confidence: {0:.2f}".format(info.confidence),
+            "detector: {0}".format(info.detector),
+        ]
+    )
+    if info.aliases:
+        lines.append("aliases: {0}".format(", ".join(info.aliases)))
+    if info.details:
+        for key in sorted(info.details):
+            lines.append("{0}: {1}".format(key, info.details[key]))
+    write(os.linesep.join(lines))
+    write(os.linesep)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the VDiskProbe CLI.
+
+    Parameters
+    ----------
+    argv : list, optional
+        Command-line argument list. ``None`` means to use ``sys.argv``.
+
+    Returns
+    -------
+    int
+        Process exit code.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    configure_logging(resolve_log_level(args))
+    if args.list_formats:
+        print_formats(sys.stdout)
+        return 0
+    if not args.path:
+        parser.error("the following arguments are required: path")
+    try:
+        info = detect_path(args.path)
+    except OSError as exc:
+        sys.stderr.write("vdiskprobe: unable to read {0}: {1}{2}".format(args.path, exc, os.linesep))
+        return 1
+    except VDiskProbeError as exc:
+        sys.stderr.write("vdiskprobe: {0}{1}".format(exc, os.linesep))
+        return 1
+    if args.json:
+        payload = json.dumps(info.to_dict(), sort_keys=True, indent=2)
+        sys.stdout.write(payload)
+        sys.stdout.write(os.linesep)
+    else:
+        print_human(info, sys.stdout)
+    return 0

vdiskprobe/detectors/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) 2026 IsArvin.
+# This file is part of VDiskProbe. Please refer to the LICENCE file for licence information.
+
+"""Detector registry and built-in formats."""
+
+from vdiskprobe.detectors.base import DetectorRegistry, FormatDetector
+from vdiskprobe.detectors.formats import BUILTIN_DETECTORS
+
+
+def build_default_registry() -> DetectorRegistry:
+    """Return an independent registry containing the built-in detectors."""
+    return DetectorRegistry(BUILTIN_DETECTORS)

vdiskprobe/detectors/_format_helpers.py

@@ -0,0 +1,296 @@
+# Copyright (c) 2026 IsArvin.
+# This file is part of VDiskProbe. Please refer to the LICENCE file for licence information.
+
+"""Parsing helpers for built-in image format detectors."""
+
+import re
+import struct
+import sys
+import uuid
+
+from vdiskprobe.errors import RangeNotSupportedError
+from vdiskprobe.source import ByteSource
+
+CLOOP_HEADER_OFFSET = 128
+CLOOP_MAX_BLOCK_SIZE = 64 * 1024 * 1024
+DMG_SECTOR_COUNT_OFFSET = 492
+SECTOR_SIZE = 512
+VHDX_FILE_PARAMETERS_GUID = uuid.UUID("CAA16737-FA36-4D43-B3B6-33F0AA44E76B").bytes_le
+VHDX_METADATA_REGION_GUID = uuid.UUID("8B7CA206-4790-4B9A-B8FE-575F050F886E").bytes_le
+VHDX_REGION_TABLE_OFFSETS = (196608, 262144)
+VHDX_VIRTUAL_DISK_SIZE_GUID = uuid.UUID("2FA54224-CD1B-4876-B211-5DBED83BF4B8").bytes_le
+VHDX_MAX_TABLE_ENTRIES = 2047
+VHDX_METADATA_TABLE_ENTRY_SIZE = 32
+VMDK_DESCRIPTOR_READ_SIZE = 64 * 1024
+QCOW_MAGIC = b"QFI\xfb"
+QED_MAGIC = b"QED\x00"
+VHDX_MAGIC = b"vhdxfile"
+VDI_SIGNATURE = 3201962111
+VMDK_MAGICS = (b"KDMV", b"COWD", b"VMDK")
+VPC_COOKIES = (b"conectix", b"connectix")
+VPC_DYNAMIC_COOKIE = b"cxsparse"
+PARALLELS_MAGICS = (b"WithoutFreeSpace", b"WithouFreSpacExt")
+BOCHS_MAGIC: bytes = b"Bochs Virtual HD Image"
+BOCHS_SPARSE_MAGIC = 38177486
+LUKS_MAGIC = b"LUKS\xba\xbe"
+DMG_MAGIC = b"koly"
+CLOOP_MAGIC = b"#!/bin/sh\n#V2.0 Format\nmodprobe cloop file=$0 && mount -r -t iso9660 /dev/cloop $1\n"
+VMDK_EXTENT_RE = re.compile(b"^[ \\t]*(?:RW|RDONLY|NOACCESS)[ \\t]+(\\d+)[ \\t]+\\S+", re.IGNORECASE | re.MULTILINE)
+
+
+def read_u32be(data: bytes) -> int:
+    """Read a big-endian unsigned 32-bit integer."""
+    return struct.unpack(">I", data)[0]
+
+
+def read_u16be(data: bytes) -> int:
+    """Read a big-endian unsigned 16-bit integer."""
+    return struct.unpack(">H", data)[0]
+
+
+def read_u64be(data: bytes) -> int:
+    """Read a big-endian unsigned 64-bit integer."""
+    return struct.unpack(">Q", data)[0]
+
+
+def read_u8(data: bytes) -> int:
+    """Read an unsigned 8-bit integer."""
+    return struct.unpack("B", data)[0]
+
+
+def read_u32le(data: bytes) -> int:
+    """Read a little-endian unsigned 32-bit integer."""
+    return struct.unpack("<I", data)[0]
+
+
+def read_u64le(data: bytes) -> int:
+    """Read a little-endian unsigned 64-bit integer."""
+    return struct.unpack("<Q", data)[0]
+
+
+def read_u16le(data: bytes) -> int:
+    """Read a little-endian unsigned 16-bit integer."""
+    return struct.unpack("<H", data)[0]
+
+
+def nonzero(value: int | None) -> int | None:
+    """Return an integer value only when it carries useful metadata."""
+    if value:
+        return value
+    return None
+
+
+def sector_bytes(sectors: int | None) -> int | None:
+    """Convert a sector count to bytes."""
+    if sectors is None:
+        return None
+    return int(str(sectors)) * SECTOR_SIZE
+
+
+def is_power_of_two(value: int) -> bool:
+    """Return whether a positive integer is a power of two."""
+    return value > 0 and (not value & value - 1)
+
+
+def is_valid_qed_cluster_size(value: int) -> bool:
+    """Return whether a QED cluster size is in the valid format range."""
+    return 4096 <= value <= 64 * 1024 * 1024 and is_power_of_two(value)
+
+
+def looks_like_vmdk_descriptor(data: bytes) -> bool:
+    """Check whether text resembles a VMDK descriptor file."""
+    cleaned = data.replace(b"\x00", b"")
+    if b"# Disk DescriptorFile" in cleaned:
+        return True
+    return b"createType=" in cleaned and b"CID=" in cleaned
+
+
+def startswith_any(data: bytes, candidates: tuple) -> bool:
+    """Check whether a string starts with any candidate prefix."""
+    for candidate in candidates:
+        if data.startswith(candidate):
+            return True
+    return False
+
+
+def vmdk_descriptor_virtual_size(data: bytes) -> int | None:
+    """Extract a virtual disk size from VMDK descriptor extent lines."""
+    total_sectors = 0
+    digit_limit = sys.get_int_max_str_digits() or sys.int_info.default_max_str_digits
+    for match in VMDK_EXTENT_RE.finditer(data.replace(b"\x00", b"")):
+        digits = match.group(1)
+        if len(digits) > digit_limit:
+            return None
+        total_sectors += int(digits)
+    result = total_sectors * SECTOR_SIZE if total_sectors else None
+    if result is not None:
+        try:
+            if len(str(result)) > digit_limit:
+                return None
+        except ValueError:
+            return None
+    return result
+
+
+def vmdk_sparse_sizes(header: bytes) -> tuple[int | None, int | None]:
+    """Extract VMDK sparse extent capacity and grain size when present."""
+    if header.startswith(b"KDMV") and len(header) >= 28:
+        return sector_bytes(nonzero(read_u64le(header[12:20]))), sector_bytes(nonzero(read_u64le(header[20:28])))
+    if header[:4] in (b"COWD", b"VMDK") and len(header) >= 20:
+        return sector_bytes(nonzero(read_u32le(header[12:16]))), sector_bytes(nonzero(read_u32le(header[16:20])))
+    return None, None
+
+
+def vdi_header_sizes(header: bytes, major: int, minor: int) -> tuple[int | None, int | None]:
+    """Read size fields only from recognised VDI header layouts."""
+    if (major, minor) == (0, 2):
+        offset = 352
+    elif major == 1:
+        offset = 368
+    else:
+        return None, None
+    if len(header) < offset + 12:
+        return None, None
+    return nonzero(read_u64le(header[offset : offset + 8])), nonzero(read_u32le(header[offset + 8 : offset + 12]))
+
+
+def vpc_footer_virtual_size(footer: bytes) -> int | None:
+    """Extract the current VHD size from a 512-byte footer."""
+    if len(footer) < 56:
+        return None
+    return nonzero(read_u64be(footer[48:56]))
+
+
+def vpc_footer_disk_type(footer: bytes) -> int | None:
+    """Extract the VHD disk type code when available."""
+    if len(footer) < 64:
+        return None
+    return nonzero(read_u32be(footer[60:64]))
+
+
+def vpc_subformat_from_type(disk_type: int | None) -> str | None:
+    """Map a VHD footer disk type to a readable subformat name."""
+    if disk_type == 2:
+        return "fixed"
+    if disk_type == 3:
+        return "dynamic"
+    if disk_type == 4:
+        return "differencing"
+    return None
+
+
+def vpc_dynamic_cluster_size(dynamic_header: bytes) -> int | None:
+    """Extract the VHD dynamic block size when a dynamic header is present."""
+    if len(dynamic_header) < 36 or dynamic_header[:8] != VPC_DYNAMIC_COOKIE:
+        return None
+    return nonzero(read_u32be(dynamic_header[32:36]))
+
+
+def read_optional_metadata(source: ByteSource, offset: int, size: int) -> bytes:
+    """Skip metadata probes outside the source or the platform's seek range."""
+    if offset > sys.maxsize - size:
+        return b""
+    source_size = source.get_size()
+    if source_size is not None and offset >= source_size:
+        return b""
+    try:
+        return source.read(offset, size)
+    except RangeNotSupportedError:
+        return b""
+
+
+def vpc_dynamic_header(source: ByteSource, footer: bytes) -> bytes:
+    """Follow the VHD footer's dynamic-header pointer when available."""
+    offset = read_u64be(footer[16:24]) if len(footer) >= 24 else 0
+    if offset == 0xFFFFFFFFFFFFFFFF:
+        return b""
+    return read_optional_metadata(source, offset or 512, 36)
+
+
+def vhdx_metadata_region(source: ByteSource) -> tuple[int, int] | None:
+    """Return the VHDX metadata region entry from either region table copy."""
+    for table_offset in VHDX_REGION_TABLE_OFFSETS:
+        header = read_optional_metadata(source, table_offset, 16)
+        if len(header) < 16 or header[:4] != b"regi":
+            continue
+        entry_count = read_u32le(header[8:12])
+        if entry_count > VHDX_MAX_TABLE_ENTRIES:
+            continue
+        entries = read_optional_metadata(source, table_offset + 16, entry_count * 32)
+        for index in range(entry_count):
+            entry = entries[index * 32 : (index + 1) * 32]
+            if len(entry) < 32 or entry[:16] != VHDX_METADATA_REGION_GUID:
+                continue
+            offset = read_u64le(entry[16:24])
+            length = read_u32le(entry[24:28])
+            if offset and length:
+                return offset, length
+    return None
+
+
+def vhdx_metadata_sizes(source: ByteSource) -> tuple[int | None, int | None]:
+    """Extract VHDX virtual disk and payload block sizes from metadata."""
+    metadata_region = vhdx_metadata_region(source)
+    if metadata_region is None:
+        return None, None
+    metadata_offset, metadata_length = metadata_region
+    header = read_optional_metadata(source, metadata_offset, 32)
+    if len(header) < 32 or header[:8] != b"metadata":
+        return None, None
+    entry_count = read_u16le(header[10:12])
+    if entry_count > VHDX_MAX_TABLE_ENTRIES:
+        return None, None
+    virtual_size = None
+    cluster_size = None
+    entries = read_optional_metadata(source, metadata_offset + 32, entry_count * VHDX_METADATA_TABLE_ENTRY_SIZE)
+    for index in range(entry_count):
+        entry = entries[index * VHDX_METADATA_TABLE_ENTRY_SIZE : (index + 1) * VHDX_METADATA_TABLE_ENTRY_SIZE]
+        if len(entry) < VHDX_METADATA_TABLE_ENTRY_SIZE:
+            continue
+        item_id = entry[:16]
+        item_offset = read_u32le(entry[16:20])
+        item_length = read_u32le(entry[20:24])
+        if item_length == 0 or item_offset + item_length > metadata_length:
+            continue
+        if item_id == VHDX_FILE_PARAMETERS_GUID and item_length >= 4:
+            item = read_optional_metadata(source, metadata_offset + item_offset, 4)
+            if len(item) >= 4:
+                cluster_size = nonzero(read_u32le(item))
+        elif item_id == VHDX_VIRTUAL_DISK_SIZE_GUID and item_length >= 8:
+            item = read_optional_metadata(source, metadata_offset + item_offset, 8)
+            if len(item) >= 8:
+                virtual_size = nonzero(read_u64le(item))
+    return virtual_size, cluster_size
+
+
+def bochs_header_sizes(header: bytes) -> tuple[int | None, int | None]:
+    """Extract Bochs growing-image size metadata."""
+    if len(header) < 84:
+        return None, None
+    version = read_u32le(header[64:68])
+    cluster_size = nonzero(read_u32le(header[80:84]))
+    virtual_size = None
+    if version == 65536 and len(header) >= 92:
+        virtual_size = nonzero(read_u64le(header[84:92]))
+    elif version == 131072 and len(header) >= 96:
+        virtual_size = nonzero(read_u64le(header[88:96]))
+    return virtual_size, cluster_size
+
+
+def cloop_sizes(source: ByteSource) -> tuple[int | None, int | None]:
+    """Extract cloop block count and block size when the header is complete."""
+    header = read_optional_metadata(source, CLOOP_HEADER_OFFSET, 8)
+    if len(header) < 8:
+        return None, None
+    cluster_size = read_u32be(header[:4])
+    block_count = read_u32be(header[4:8])
+    if cluster_size == 0 or cluster_size % SECTOR_SIZE or cluster_size > CLOOP_MAX_BLOCK_SIZE:
+        return None, None
+    return int(block_count) * cluster_size, cluster_size
+
+
+def cluster_size_from_bits(cluster_bits: int) -> int | None:
+    """Convert a qcow cluster bit count to bytes."""
+    if cluster_bits < 0 or cluster_bits > 63:
+        return None
+    return int(1) << cluster_bits