ntmemoryapi 2.3.0__tar.gz → 2.5.0__tar.gz

{ntmemoryapi-2.3.0 → ntmemoryapi-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ntmemoryapi
-Version: 2.3.0
+Version: 2.5.0
 Summary: Add your description here
 Requires-Dist: psutil>=7.2.2
 Requires-Python: >=3.13

{ntmemoryapi-2.3.0 → ntmemoryapi-2.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ntmemoryapi"
-version = "2.3.0"
+version = "2.5.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.13"

{ntmemoryapi-2.3.0 → ntmemoryapi-2.5.0}/src/ntmemoryapi/__init__.py

@@ -9,6 +9,7 @@ import os
 import typing
 import ctypes
 import psutil
+import functools
 
 # Local imports
 from . import misc
@@ -24,7 +25,6 @@ syscall_wrapper = misc.DirectSyscallWrapper()
 PROCESS_ID = 1
 PROCESS_NAME = 2
 
-
 # ==-------------------------------------------------------------------== #
 # C-consts                                                                #
 # ==-------------------------------------------------------------------== #
@@ -150,6 +150,10 @@ def list_processes(include_process_information: int = PROCESS_ID | PROCESS_NAME)
     return processes
 
 
+# ==-------------------------------------------------------------------== #
+# Private functions                                                       #
+# ==-------------------------------------------------------------------== #
+@functools.lru_cache()
 def _get_be_buffer(soure_c_type: typing.Any) -> ctypes.BigEndianStructure:
     """Create buffer to hold data in big-endian format."""
 
@@ -164,6 +168,333 @@ def _get_be_buffer(soure_c_type: typing.Any) -> ctypes.BigEndianStructure:
     return BigEndianValue
 
 
+def _unbounded_array_getitem(array: ctypes.Array, index: int | slice) -> None:
+    """Array `__getitem__` function override to make array able to get out of bound values."""
+
+    # Get array process reference
+    array_process = array.__dict__.get("_process_")
+
+    # Get array base address
+    array_address = array.__dict__.get("_address_")
+
+    # If array process is not defined
+    if array_process is None:
+        return super(type(array), array).__getitem__(index)
+
+    # Get array value type
+    array_value_type = array._type_
+
+    # Get array value type size
+    array_value_type_size = ctypes.sizeof(array_value_type)
+
+    # If index is integer
+    if isinstance(index, int):
+
+        # If valus is not out of bound
+        if 0 <= index < len(array):
+            array_value = super(type(array), array).__getitem__(index)
+
+        # if valus is out of bound
+        else:
+            array_value = array._process_.read_into_buffer(array_address + array_value_type_size * index, array_value_type())
+
+        # Resolve final value
+        match array_value:
+
+            # If value is array
+            case ctypes.Array():
+
+                # Save process reference into value
+                array_value._process_ = array_process
+
+                # Save address into value
+                array_value._address_ = array_address + array_value_type_size * index
+
+                # Override array `__getitem__` to make it boudless.
+                array_value.__class__.__getitem__ = _unbounded_array_getitem
+
+                return array_value
+
+            # If value is structure or union
+            case ctypes.Structure() | ctypes.Union():
+
+                # Save proess reference into value
+                array_value._process_ = array_process
+
+                # Save address into value
+                array_value._address_ = array_address + array_value_type_size * index
+
+                return array_value
+
+            # If value is container pointer
+            case ctypes._Pointer():
+
+                # Read value into buffer and return it
+                return array_process.read_into_buffer(ctypes.cast(array_value, ctypes.c_void_p).value, array_value._type_())
+
+            # If value is simple c-type data
+            case ctypes._SimpleCData():
+                return array_value.value
+
+            # If type is not c-type data
+            case _:
+                return array_value
+
+    # If index is slice
+    if isinstance(index, slice):
+
+        # Array length
+        array_length = len(array)
+
+        # Slice start and stop values
+        start = index.start or 0
+        stop = index.stop or array_length
+
+        # List of read array values
+        array_values = []
+
+        # If slice start is smaller than slice stop
+        if start > stop:
+            raise RuntimeError("Array slice start `%s` can't be grater that slice stop `%s`" % (start, stop))
+
+        # Iterate slice range and collect array value
+        while start != stop:
+
+            # If start is out of array bound at left side
+            if start < 0:
+
+                # Find read batch size
+                read_batch_size = abs(start - min(stop, 0))
+
+                # Read batch until array start or slice stop
+                read_batch = array._process_.read_into_buffer(array_address + array_value_type_size * start, (array_value_type * read_batch_size)())
+
+                # Extend array values with read batch
+                array_values.extend(read_batch[:])
+
+                # Move start pointer
+                start += read_batch_size
+
+            # If start is out of array bound at right side
+            elif start >= array_length:
+
+                # Find read batch size
+                read_batch_size = abs(start - stop)
+
+                # Read batch until array start or slice stop
+                read_batch = array._process_.read_into_buffer(array_address + array_value_type_size * start, (array_value_type * read_batch_size)())
+
+                # Extend array values with read batch
+                array_values.extend(read_batch[:])
+
+                # Move start pointer
+                start += read_batch_size
+
+            # If array value is already read
+            else:
+
+                # Append value to array values
+                array_values.append(array[start])
+
+                # Move start pointer
+                start += 1
+
+        # Finalize array values
+        for offset, index in enumerate(range(len(array_values)), index.start or 0):
+
+            match array_values[index]:
+
+                # If value is array
+                case ctypes.Array():
+
+                    # Save process reference into value
+                    array_values[index]._process_ = array_process
+
+                    # Save address into value
+                    array_values[index]._address_ = array_address + array_value_type_size * offset
+
+                    # Override array `__getitem__` to make it boudless.
+                    array_values[index].__class__.__getitem__ = _unbounded_array_getitem
+
+                # If value is structure or union
+                case ctypes.Structure() | ctypes.Union():
+
+                    # Save proess reference into value
+                    array_values[index]._process_ = array_process
+
+                    # Save address into value
+                    array_values[index]._address_ = array_address + array_value_type_size * offset
+
+                # If value is container pointer
+                case ctypes._Pointer():
+
+                    # Read value into buffer and return it
+                    array_values[index] = array_process.read_into_buffer(ctypes.cast(array_values[index], ctypes.c_void_p).value, array_values[index]._type_())
+
+                # If value is simple c-type data
+                case ctypes._SimpleCData():
+                    array_values[index] = array_values[index].value
+
+        return array_values
+
+
+# ==-------------------------------------------------------------------== #
+# Meta classes                                                            #
+# ==-------------------------------------------------------------------== #
+class _AutoStructureMeta(type(ctypes.Structure)):
+
+    def __new__[T](cls: T, name: str, bases: tuple[type, ...], attributes: dict[str, typing.Any]) -> T:
+        """Overload that invokes of new class creation to hide generic fields is they are defined."""
+
+        # Extra attributes
+        extra_attributes = {}
+
+        # Check if struct if generic-typed
+        if any(isinstance(item[1], int) for item in attributes.get("_fields_", [])):
+            extra_attributes["_generized_"] = attributes.pop("_fields_")
+
+        return super().__new__(cls, name, bases, attributes | extra_attributes)
+
+    def __getitem__[T](cls: T, generics: tuple[typing.Any, ...]) -> T:
+        """Overload that invokes on tries to unwrap generic class."""
+
+        # If structure is not generized
+        if not hasattr(cls, "_generized_"):
+            raise RuntimeError("Unable to init `%s` object due the no generic fields, use regular brackets syntax instead" % cls.__name__)
+
+        # If only one generic time passed
+        if not isinstance(generics, tuple):
+            generics = (generics,)
+
+        # Unwarp generic types and replace fields with template types
+        fields = []
+        for field in cls._generized_:
+
+            # If field is simple generic value
+            if len(field) == 2 and isinstance(field[1], int):
+                fields.append((field[0], generics[field[1]]))
+
+            # If field is complex generic value
+            elif len(field) == 3 and isinstance(field[1], int):
+
+                # Get generic wrapper
+                generic_wrapper = field[-1]
+
+                # If generic wrapper is array size
+                if isinstance(generic_wrapper, int):
+                    fields.append((field[0], (generics[field[1]] * generic_wrapper)))
+
+                # If generic wrapper is container
+                else:
+                    fields.append((field[0], generic_wrapper(generics[field[1]])))
+
+            # If field is not generic value
+            else:
+                fields.append(field)
+
+        return type(
+            "%s_%s" % (cls.__name__, "_".join(getattr(item, "__name__", str(item)) for item in generics)),
+            cls.__bases__,
+            {
+                key: value for key, value in cls.__dict__.items()
+                if key not in {"_generized_", "_fields_", "__dict__", "__weakref__"}
+            } | {"_fields_": fields}
+        )
+
+    def __call__[T](cls: T, *args: typing.Any, **kwargs: typing.Any):
+        """Overload that invokes on tries to create of class instance."""
+
+        # If try tp init without type templates
+        if "_generized_" in cls.__dict__:
+            raise RuntimeError("Unable to init `%s` object due the structure fields `%s` are generic and have to be typed using square brackets syntax" % (
+                cls.__name__,
+                ", ".join(item[0] for item in cls._generized_ if isinstance(item[1], int))
+            ))
+
+        return super().__call__(*args, **kwargs)
+
+
+class AutoStructure(ctypes.Structure, metaclass=_AutoStructureMeta):
+    """Sturcture to automatic dereference pointers located at virtual process memory."""
+
+    def __init__(self, *args: typing.Any, **kwargs: typing.Any) -> None:
+        """Init instance passing `*args` and `**kwargs` into parent initializer."""
+
+        # Sturcture metadata
+        self._address_: int = 0
+        self._process_: Process | None = None
+
+        # Pass `*args` and `**kwargs` to origianl structure initializer
+        super().__init__(*args, **kwargs)
+
+    def __invert__[T](self: T) -> T:
+        """Remove process link from the object to allow get raw field values without auto-RPM magic."""
+
+        # If processs link is already empty
+        if not isinstance(self._process_, Process):
+            return self
+
+        # Copy current object copy
+        instance_copy = self.__class__.from_buffer_copy(self)
+
+        # Erase instance proess reference
+        instance_copy._process_ = None
+
+        return instance_copy
+
+    def __getattribute__(self, name: str) -> typing.Any:
+        """Access objectr field if it exists."""
+
+        # Get field from parrent object
+        field = super().__getattribute__(name)
+
+        # If process reference is not defined
+        if (process := object.__getattribute__(self, "__dict__").get("_process_")) is None:
+            return field
+
+        # If field is complex type value
+        match field:
+
+            # If field is array
+            case ctypes.Array():
+
+                # Save process reference into field
+                field._process_ = process
+
+                # Save address into field
+                field._address_ = self._address_ + getattr(self.__class__, name).offset
+
+                # Override array `__getitem__` to make it boudless.
+                field.__class__.__getitem__ = _unbounded_array_getitem
+
+                return field
+
+            # If field is structure or union
+            case ctypes.Structure() | ctypes.Union():
+
+                # Save proess reference into field
+                field._process_ = process
+
+                # Save address into field
+                field._address_ = self._address_ + getattr(self.__class__, name).offset
+
+                return field
+
+            # If field is container pointer
+            case ctypes._Pointer():
+
+                # Read value into buffer and return it
+                return process.read_into_buffer(ctypes.cast(field, ctypes.c_void_p).value, field._type_())
+
+            # If field is simple c-type data
+            case ctypes._SimpleCData():
+                return field.value
+
+            # If type is not c-type data
+            case _:
+                return field
+
+
 # ==-------------------------------------------------------------------== #
 # Classes                                                                 #
 # ==-------------------------------------------------------------------== #
@@ -215,7 +546,7 @@ class Process:
             if not self.is_64bit():
                 raise RuntimeError("Unable to list modules for not 64 bit process using `%s` method, use another one method instead")
 
-            # If procewss PEB retrieve failed
+            # If process PEB retrieve failed
             if not (process_peb := self.get_information().peb):
                 raise RuntimeError("Process `%s` PEB address is null-value" % self.name)
 
@@ -380,11 +711,15 @@ class Process:
 
         return process_basic_information
 
-    def get_module(self, name: str) -> structs.MODULEENTRY32:
+    def get_module(self, name: str, method: typing.Literal["pebwalk", "snapshot"] = "pebwalk") -> structs.MODULEENTRY32:
         """Get process module information."""
 
+        # If method is not allowed
+        if method.lower() not in [item.lower() for item in allowed_methods] if (allowed_methods := typing.get_args(self.list_modules.__annotations__["method"])) else True:
+            raise ValueError("Method literal is invalid, expected one of: `%s`" % ", ".join(allowed_methods))
+
         # Process modules enumeration
-        for module in self.list_modules():
+        for module in self.list_modules(method):
 
             # If module have a required name
             if module.name.lower() == name.strip().lower():
@@ -520,7 +855,7 @@ class Process:
             try:
 
                 # Read bytes into pre-allocated buffer
-                self.read_into_buffer(region.base_address, read_memory_buffer, region.size)
+                self.read_into_buffer(region.base_address, read_memory_buffer, region.size, discard_metadata=True)
 
             except Exception:
                 continue
@@ -643,7 +978,7 @@ class Process:
 
         return bytes(buffer)
 
-    def read_into_buffer(self, address: int, buffer: typing.Any, read_bytes_size: int | None = None) -> typing.Any:
+    def read_into_buffer[T](self, address: int, buffer: T, read_bytes_size: int | None = None, discard_metadata: bool = False) -> T:
         """Read value located at given address into buffer. Buffer have to be able passed at `ctypes.byref` and `ctypes.sizeof`. Read bytes size can be changed by passing `read_bytes_size` argument."""
 
         # If read size is invalid
@@ -654,6 +989,12 @@ class Process:
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer), ctypes.sizeof(buffer) if read_bytes_size is None else read_bytes_size, None)):
             raise errors.MemoryReadError(result, address)
 
+        # Save process reference and read address
+        if not discard_metadata:
+
+            buffer._process_ = self
+            buffer._address_ = address
+
         return buffer
 
     def write_int8(self, address: int, value: int) -> None: