dissect.hypervisor 3.17.dev1__tar.gz → 3.17.dev3__tar.gz

dissect_hypervisor-3.17.dev3/.git-blame-ignore-revs

@@ -0,0 +1,6 @@
+# Formatting commits. You can ignore them during git-blame with `--ignore-rev` or `--ignore-revs-file`.
+#
+#   $ git config --add 'blame.ignoreRevsFile' '.git-blame-ignore-revs'
+#
+# Change linter to Ruff (#49)
+ad8ca2f4d8a8bebedc6da8505a33b7b6e5c553d5

{dissect_hypervisor-3.17.dev1/dissect.hypervisor.egg-info → dissect_hypervisor-3.17.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: dissect.hypervisor
-Version: 3.17.dev1
+Version: 3.17.dev3
 Summary: A Dissect module implementing parsers for various hypervisor disk, backup and configuration files
 Author-email: Dissect Team <dissect@fox-it.com>
 License: Affero General Public License v3

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/descriptor/c_hyperv.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from dissect.cstruct import cstruct
 
 hyperv_def = """

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/descriptor/hyperv.py

@@ -3,8 +3,7 @@
 from __future__ import annotations
 
 import struct
-from collections.abc import ItemsView, KeysView, ValuesView
-from typing import BinaryIO, Optional, Union
+from typing import TYPE_CHECKING, BinaryIO
 
 from dissect.util.stream import RangeStream
 
@@ -16,6 +15,9 @@ from dissect.hypervisor.descriptor.c_hyperv import (
 )
 from dissect.hypervisor.exceptions import InvalidSignature
 
+if TYPE_CHECKING:
+    from collections.abc import ItemsView, KeysView, ValuesView
+
 
 class HyperVFile:
     """HyperVFile implementation.
@@ -278,7 +280,7 @@ class HyperVStorageKeyTableEntry:
         return f"<HyperVStorageKeyTableEntry type={self.type} size={self.size}>"
 
     @property
-    def parent(self) -> Optional[HyperVStorageKeyTableEntry]:
+    def parent(self) -> HyperVStorageKeyTableEntry | None:
         """Return the entry parent, if there is any.
 
         Requires that all key tables are loaded.
@@ -333,8 +335,8 @@ class HyperVStorageKeyTableEntry:
             file_object = self.get_file_object()
             # This memoryview has no purpose, only do it so the return value type is consistent
             return memoryview(file_object.read(size))
-        else:
-            return self.raw[self.header.data_offset :]
+
+        return self.raw[self.header.data_offset :]
 
     @property
     def key(self) -> str:
@@ -343,7 +345,7 @@ class HyperVStorageKeyTableEntry:
         return self.raw.tobytes()[: self.header.data_offset - 1].decode("utf-8")
 
     @property
-    def value(self) -> Union[int, bytes, str]:
+    def value(self) -> int | bytes | str:
         """Return a Python native value for this entry."""
         data = self.data
 
@@ -369,6 +371,8 @@ class HyperVStorageKeyTableEntry:
         if self.type == KeyDataType.Bool:
             return struct.unpack("<I", data[:4])[0] != 0
 
+        raise TypeError(f"Unknown data type: {self.type}")
+
     @property
     def data_size(self) -> int:
         """Return the total amount of data bytes, including the key name.
@@ -427,10 +431,7 @@ class HyperVStorageKeyTableEntry:
 
         obj = {}
         for key, child in self.children.items():
-            if child.type == KeyDataType.Node:
-                value = child.as_dict()
-            else:
-                value = child.value
+            value = child.as_dict() if child.type == KeyDataType.Node else child.value
 
             obj[key] = value
 
@@ -466,13 +467,10 @@ class HyperVStorageFileObject:
         if n is not None and n < -1:
             raise ValueError("invalid number of bytes to read")
 
-        if n == -1:
-            read_length = self.size
-        else:
-            read_length = min(n, self.size)
+        read_length = self.size if n == -1 else min(n, self.size)
 
         self.file.fh.seek(self.offset)
         return self.file.fh.read(read_length)
 
-    def open(self, size: Optional[int] = None) -> BinaryIO:
+    def open(self, size: int | None = None) -> BinaryIO:
         return RangeStream(self.file.fh, self.offset, size or self.size)

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/descriptor/ovf.py

@@ -1,11 +1,16 @@
-from typing import Iterator, TextIO
-from xml.etree.ElementTree import Element
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final, TextIO
 
 from defusedxml import ElementTree
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from xml.etree.ElementTree import Element
+
 
 class OVF:
-    NS = {
+    NS: Final[dict[str, str]] = {
         "ovf": "http://schemas.dmtf.org/ovf/envelope/1",
         "rasd": "http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData",
     }
@@ -34,8 +39,7 @@ class OVF:
         for disk in self.xml.findall(self.DISK_DRIVE_XPATH, self.NS):
             resource = disk.find("{{{rasd}}}HostResource".format(**self.NS))
             xpath = resource.text
-            if xpath.startswith("ovf:"):
-                xpath = xpath[4:]
+            xpath = xpath.removeprefix("ovf:")
 
             if xpath.startswith("/disk/"):
                 disk_ref = xpath.split("/")[-1]

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/descriptor/pvs.py

@@ -1,8 +1,13 @@
-from typing import IO, Iterator
-from xml.etree.ElementTree import Element
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TextIO
 
 from defusedxml import ElementTree
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from xml.etree.ElementTree import Element
+
 
 class PVS:
     """Parallels VM settings file.
@@ -11,7 +16,7 @@ class PVS:
         fh: The file-like object to a PVS file.
     """
 
-    def __init__(self, fh: IO):
+    def __init__(self, fh: TextIO):
         self._xml: Element = ElementTree.fromstring(fh.read())
 
     def disks(self) -> Iterator[str]:

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/descriptor/vbox.py

@@ -1,13 +1,18 @@
-from typing import IO, Iterator
-from xml.etree.ElementTree import Element
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TextIO
 
 from defusedxml import ElementTree
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from xml.etree.ElementTree import Element
+
 
 class VBox:
     VBOX_XML_NAMESPACE = "{http://www.virtualbox.org/}"
 
-    def __init__(self, fh: IO):
+    def __init__(self, fh: TextIO):
         self._xml: Element = ElementTree.fromstring(fh.read())
 
     def disks(self) -> Iterator[str]:

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/descriptor/vmx.py

@@ -7,11 +7,10 @@ import base64
 import hashlib
 import hmac
 import re
-from typing import Dict, List
 from urllib.parse import unquote
 
 try:
-    import _pystandalone
+    import _pystandalone  # type: ignore
 
     HAS_PYSTANDALONE = True
 except ImportError:
@@ -44,8 +43,8 @@ PASS2KEY_MAP = {
 
 
 class VMX:
-    def __init__(self, vm_settings: Dict[str, str]):
-        self.attr = vm_settings
+    def __init__(self, attr: dict[str, str]):
+        self.attr = attr
 
     @classmethod
     def parse(cls, string: str) -> VMX:
@@ -56,19 +55,28 @@ class VMX:
     def encrypted(self) -> bool:
         """Return whether this VMX is encrypted.
 
-        Encrypted VMXs will have both a `encryption.keySafe` and `encryption.data` value.
-        The `encryption.keySafe` is a string encoded `KeySafe`, which is made up of key locators.
+        Encrypted VMXs will have both a ``encryption.keySafe`` and ``encryption.data`` value.
+        The ``encryption.keySafe`` is a string encoded ``KeySafe``, which is made up of key locators.
 
         For example:
+
+        .. code-block:: none
+
             vmware:key/list/(pair/(phrase/phrase_id/phrase_content,hmac,data),pair/(.../...,...,...))
 
-        A KeySafe must be a list of Pairs. Each Pair has a wrapped key, an HMAC type and some encrypted data.
+        A ``KeySafe`` must be a list of ``Pairs``. Each ``Pair`` has a wrapped key, an HMAC type and encrypted data.
         It's implementation specific how to unwrap a key. E.g. a phrase is just PBKDF2. The unwrapped key
-        can be used to unlock the encrypted Pair data. This will contain the final encryption key to decrypt
-        the data in `encryption.data`.
+        can be used to unlock the encrypted ``Pair`` data. This will contain the final encryption key to decrypt
+        the data in ``encryption.data``.
+
+        So, in summary, to unseal a ``KeySafe``:
 
-        So, in summary, to unseal a KeySafe:
-        Parse KeySafe -> iterate pairs -> unlock Pair -> unwrap key (e.g. Phrase) -> decrypt Pair data -> parse dict
+        - Parse ``KeySafe``
+        - Iterate pairs
+        - Unlock ``Pair``
+        - Unwrap key (e.g. ``Phrase``)
+        - Decrypt ``Pair`` data
+        - Parse dictionary
 
         The terms for unwrapping, unlocking and unsealing are taken from VMware.
         """
@@ -77,7 +85,7 @@ class VMX:
     def unlock_with_phrase(self, passphrase: str) -> None:
         """Unlock this VMX in-place with a passphrase if it's encrypted.
 
-        This will load the KeySafe from the current dictionary and attempt to recover the encryption key
+        This will load the ``KeySafe`` from the current dictionary and attempt to recover the encryption key
         from it using the given passphrase. This key is used to decrypt the encrypted VMX data.
 
         The dictionary is updated in-place with the encrypted VMX data.
@@ -92,7 +100,7 @@ class VMX:
         decrypted = _decrypt_hmac(key, encrypted, mac)
         self.attr.update(**_parse_dictionary(decrypted.decode()))
 
-    def disks(self) -> List[str]:
+    def disks(self) -> list[str]:
         """Return a list of paths to disk files"""
         dev_classes = ("scsi", "sata", "ide", "nvme")
         devices = {}
@@ -129,7 +137,7 @@ class VMX:
         return sorted(disk_files)
 
 
-def _parse_dictionary(string: str) -> Dict[str, str]:
+def _parse_dictionary(string: str) -> dict[str, str]:
     """Parse a VMX dictionary."""
     dictionary = {}
 
@@ -148,11 +156,11 @@ def _parse_dictionary(string: str) -> Dict[str, str]:
 
 
 class KeySafe:
-    def __init__(self, locators: List[Pair]):
+    def __init__(self, locators: list[Pair]):
         self.locators = locators
 
     def unseal_with_phrase(self, passphrase: str) -> bytes:
-        """Unseal this KeySafe with a passphrase and return the decrypted key."""
+        """Unseal this ``KeySafe`` with a passphrase and return the decrypted key."""
         for locator in self.locators:
             if not locator.has_phrase():
                 continue
@@ -170,7 +178,7 @@ class KeySafe:
 
     @classmethod
     def from_text(cls, text: str) -> KeySafe:
-        """Parse a KeySafe from a string."""
+        """Parse a ``KeySafe`` from a string."""
 
         # Key safes are a list of key locators. It's a key locator string with a specific prefix
         identifier, _, remainder = text.partition("/")
@@ -179,41 +187,41 @@ class KeySafe:
 
         # First part must be a list of pairs
         locators = _parse_key_locator(remainder)
-        if not isinstance(locators, list) and not all([isinstance(member, Pair) for member in locators]):
+        if not isinstance(locators, list) and not all(isinstance(member, Pair) for member in locators):
             raise ValueError("Invalid KeySafe string, not a list of pairs")
 
         return KeySafe(locators)
 
 
 class Pair:
-    def __init__(self, wrapped_key, mac: str, data: bytes):
+    def __init__(self, wrapped_key: Phrase, mac: str, data: bytes):
         self.wrapped_key = wrapped_key
         self.mac = mac
         self.data = data
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<Pair wrapped_key={self.wrapped_key} mac={self.mac}>"
 
     def has_phrase(self) -> bool:
-        """Return whether this Pair is a Phrase pair."""
+        """Return whether this ``Pair`` is a ``Phrase`` pair."""
         return isinstance(self.wrapped_key, Phrase)
 
     def _unlock(self, key: bytes) -> bytes:
-        """Decrypt the data in this Pair."""
+        """Decrypt the data in this ``Pair``."""
         return _decrypt_hmac(key, self.data, self.mac)
 
     def unlock(self, *args, **kwargs) -> bytes:
-        """Helper method to unlock this Pair for various wrapped keys.
+        """Helper method to unlock this ``Pair`` for various wrapped keys.
 
         Currently only supports `Phrase`.
         """
         if self.has_phrase():
             return self.unlock_with_phrase(*args, **kwargs)
-        else:
-            raise TypeError(f"Unable to unlock {self.key}")
+
+        raise TypeError(f"Unable to unlock {self.wrapped_key}")
 
     def unlock_with_phrase(self, passphrase: str) -> bytes:
-        """Unlock this Pair with a passphrase and return the decrypted data."""
+        """Unlock this ``Pair`` with a passphrase and return the decrypted data."""
         if not self.has_phrase():
             raise TypeError("Pair doesn't have a phrase protected key")
 
@@ -229,13 +237,13 @@ class Phrase:
         self.rounds = rounds
         self.salt = salt
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<Phrase id={self.id} pass2key={self.pass2key} cipher={self.cipher} rounds={self.rounds}>"
 
     def unwrap(self, passphrase: str) -> bytes:
         """Unwrap/generate the encryption key for a given passphrase.
 
-        VMware calls this unwrapping, but really it's a KDF with the properties of this Phrase.
+        VMware calls this unwrapping, but really it's a KDF with the properties of this ``Phrase``.
         """
         return hashlib.pbkdf2_hmac(
             PASS2KEY_MAP[self.pass2key],
@@ -246,13 +254,13 @@ class Phrase:
         )
 
 
-def _parse_key_locator(locator_string: str):
+def _parse_key_locator(locator_string: str) -> Pair | Phrase | list[Pair | Phrase]:
     """Parse a key locator from a string.
 
-    Key locators are string formatted data structures with a forward slash (/) separator. Each component is
-    prefixed with a type, followed by that types' specific data. Values between separators are url encoded.
+    Key locators are string formatted data structures with a forward slash (``/``) separator. Each component is
+    prefixed with a type, followed by that types' specific data. Values between separators are URL encoded.
 
-    Interally called `KeyLocator`.
+    Interally called ``KeyLocator``.
     """
 
     identifier, _, remainder = locator_string.partition("/")
@@ -261,7 +269,8 @@ def _parse_key_locator(locator_string: str):
         # Comma separated list in between braces
         # list/(member,member)
         return [_parse_key_locator(member) for member in _split_list(remainder)]
-    elif identifier == "pair":
+
+    if identifier == "pair":
         # Comma separated tuple with 3 members
         # pair/(key data,mac type,encrypted data)
         members = _split_list(remainder)
@@ -270,7 +279,8 @@ def _parse_key_locator(locator_string: str):
             unquote(members[1]),
             base64.b64decode(unquote(members[2])),
         )
-    elif identifier == "phrase":
+
+    if identifier == "phrase":
         # Serialized crypto dict, prefixed with an identifier
         # phrase/encoded id/encoded dict
         phrase_id, _, phrase_data = remainder.partition("/")
@@ -282,20 +292,19 @@ def _parse_key_locator(locator_string: str):
             int(crypto_dict["rounds"]),
             base64.b64decode(crypto_dict["salt"]),
         )
-    else:
-        # rawkey, ldap, script, role, fqid
-        raise NotImplementedError(f"Not implemented keysafe identifier: {identifier}")
+
+    # rawkey, ldap, script, role, fqid
+    raise NotImplementedError(f"Not implemented keysafe identifier: {identifier}")
 
 
-def _split_list(list_string: str) -> List[str]:
+def _split_list(value: str) -> list[str]:
     """Parse a key locator list from a string.
 
     Lists are wrapped by braces and separated by comma. They can contain nested lists/pairs,
     so we need to separate at the correct nest level.
     """
 
-    match = re.match(r"\((.+)\)", list_string)
-    if not match:
+    if not (match := re.match(r"\((.+)\)", value)):
         raise ValueError("Invalid list string")
 
     contents = match.group(1)
@@ -321,12 +330,12 @@ def _split_list(list_string: str) -> List[str]:
     return members
 
 
-def _parse_crypto_dict(dict_string: str) -> Dict[str, str]:
+def _parse_crypto_dict(dict_string: str) -> dict[str, str]:
     """Parse a crypto dict from a string.
 
-    Crypto dicts are encoded as `key=encoded_value:key=encoded_value`.
+    Crypto dicts are encoded as ``key=encoded_value:key=encoded_value``.
 
-    Internally called `CryptoDict`.
+    Internally called ``CryptoDict``.
     """
 
     crypto_dict = {}
@@ -360,7 +369,7 @@ def _decrypt_hmac(key: bytes, data: bytes, digest: str) -> bytes:
     return decrypted
 
 
-def _create_cipher(key: bytes, iv: bytes):
+def _create_cipher(key: bytes, iv: bytes) -> AES.CbcMode:
     """Create a cipher object.
 
     Dynamic based on the available crypto module.
@@ -377,7 +386,8 @@ def _create_cipher(key: bytes, iv: bytes):
             raise ValueError(f"Invalid key size: {len(key)}")
 
         return _pystandalone.cipher(cipher, key, iv)
-    elif HAS_PYCRYPTODOME:
+
+    if HAS_PYCRYPTODOME:
         return AES.new(key, AES.MODE_CBC, iv=iv)
-    else:
-        raise RuntimeError("No crypto module available")
+
+    raise RuntimeError("No crypto module available")

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/disk/c_hdd.py

@@ -1,7 +1,7 @@
 # References:
 # - https://src.openvz.org/projects/OVZ/repos/ploop/browse/include/ploop1_image.h
 # - https://github.com/qemu/qemu/blob/master/docs/interop/parallels.txt
-
+from __future__ import annotations
 
 from dissect.cstruct import cstruct
 

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/disk/c_qcow2.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from dissect.cstruct import cstruct
 
 qcow2_def = """
@@ -169,8 +171,9 @@ UNALLOCATED_SUBCLUSTER_TYPES = (
 )
 
 
-def ctz(value, size=32):
+def ctz(value: int, size: int = 32) -> int:
     """Count the number of zero bits in an integer of a given size."""
     for i in range(size):
         if value & (1 << i):
             return i
+    return 0

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/disk/c_vdi.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from dissect.cstruct import cstruct
 
 # https://www.virtualbox.org/browser/vbox/trunk/src/VBox/Storage/VDICore.h

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/disk/c_vhd.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from dissect.cstruct import cstruct
 
 vhd_def = """

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/disk/c_vhdx.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from uuid import UUID
 
 from dissect.cstruct import cstruct

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/disk/c_vmdk.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import struct
 
 from dissect.cstruct import cstruct

{dissect_hypervisor-3.17.dev1 → dissect_hypervisor-3.17.dev3}/dissect/hypervisor/disk/hdd.py

@@ -4,9 +4,8 @@ from bisect import bisect_right
 from dataclasses import dataclass
 from functools import cached_property
 from pathlib import Path
-from typing import BinaryIO, Iterator, Optional, Tuple, Union
+from typing import TYPE_CHECKING, BinaryIO
 from uuid import UUID
-from xml.etree.ElementTree import Element
 
 from defusedxml import ElementTree
 from dissect.util.stream import AlignedStream
@@ -14,6 +13,10 @@ from dissect.util.stream import AlignedStream
 from dissect.hypervisor.disk.c_hdd import SECTOR_SIZE, c_hdd
 from dissect.hypervisor.exceptions import InvalidHeaderError
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from xml.etree.ElementTree import Element
+
 DEFAULT_TOP_GUID = UUID("{5fbaabe3-6958-40ff-92a7-860e329aab41}")
 NULL_GUID = UUID("00000000-0000-0000-0000-000000000000")
 
@@ -76,7 +79,7 @@ class HDD:
         # If the path is relative, it's always relative to the HDD root
         return (root / path).open("rb")
 
-    def open(self, guid: Optional[Union[str, UUID]] = None) -> BinaryIO:
+    def open(self, guid: str | UUID | None = None) -> BinaryIO:
         """Open a stream for this HDD, optionally for a specific snapshot.
 
         If no snapshot GUID is provided, the "top" snapshot will be used.
@@ -154,7 +157,7 @@ class XMLEntry:
 
     @classmethod
     def _from_xml(cls, element: Element) -> XMLEntry:
-        raise NotImplementedError()
+        raise NotImplementedError
 
 
 @dataclass
@@ -213,7 +216,7 @@ class Image(XMLEntry):
 
 @dataclass
 class Snapshots(XMLEntry):
-    top_guid: Optional[UUID]
+    top_guid: UUID | None
     shots: list[Shot]
 
     @classmethod
@@ -307,7 +310,7 @@ class HDS(AlignedStream):
         parent: Optional file-like object for the parent HDS file.
     """
 
-    def __init__(self, fh: BinaryIO, parent: Optional[BinaryIO] = None):
+    def __init__(self, fh: BinaryIO, parent: BinaryIO | None = None):
         self.fh = fh
         self.parent = parent
 
@@ -357,7 +360,7 @@ class HDS(AlignedStream):
 
         return b"".join(result)
 
-    def _iter_runs(self, offset: int, length: int) -> Iterator[Tuple[int, int]]:
+    def _iter_runs(self, offset: int, length: int) -> Iterator[tuple[int, int]]:
         """Iterate optimized read runs for a given offset and read length.
 
         Args:
@@ -374,12 +377,9 @@ class HDS(AlignedStream):
             read_size = min(self.cluster_size - offset_in_cluster, length)
 
             bat_entry = bat[cluster_idx]
-            if bat_entry == 0:
-                # BAT entry of 0 means either a sparse or a parent read
-                # Use 0 to denote a sparse run for now to make calculations easier
-                read_offset = 0
-            else:
-                read_offset = (bat_entry * self._bat_multiplier * SECTOR_SIZE) + offset_in_cluster
+            # BAT entry of 0 means either a sparse or a parent read
+            # Use 0 to denote a sparse run for now to make calculations easier
+            read_offset = 0 if bat_entry == 0 else bat_entry * self._bat_multiplier * SECTOR_SIZE + offset_in_cluster
 
             if run_offset is None:
                 # First iteration