ntmemoryapi 2.2.4__tar.gz → 2.3.0__tar.gz

ntmemoryapi-2.3.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.3
+Name: ntmemoryapi
+Version: 2.3.0
+Summary: Add your description here
+Requires-Dist: psutil>=7.2.2
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+

ntmemoryapi-2.3.0/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "ntmemoryapi"
+version = "2.3.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "psutil>=7.2.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"

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

@@ -6,18 +6,20 @@
 # +-------------------------------------+
 
 import os
+import typing
 import ctypes
 import psutil
 
 # Local imports
-from .misc import *
-from .embed import *
-from .errors import *
+from . import misc
+from . import embed
+from . import errors
+from . import structs
 
 # ==-------------------------------------------------------------------== #
 # Static and global variables, constans                                   #
 # ==-------------------------------------------------------------------== #
-syscall_wrapper = DirectSyscallWrapper()
+syscall_wrapper = misc.DirectSyscallWrapper()
 
 PROCESS_ID = 1
 PROCESS_NAME = 2
@@ -72,126 +74,6 @@ TH32CS_SNAPMODULE = 0x00000008
 # ==-------------------------------------------------------------------== #
 # C-structs                                                               #
 # ==-------------------------------------------------------------------== #
-class CLIENT_ID(ctypes.Structure):
-    """Client-ID structure that required to open process."""
-
-    _fields_ = [
-        ("unique_process", ctypes.c_void_p),
-        ("unique_thread", ctypes.c_void_p),
-    ]
-
-
-class OBJECT_ATTRIBUTES(ctypes.Structure):
-    """Object attributes structure that can be applied to objects or object handles."""
-
-    _fields_ = [
-        ("length", ctypes.c_ulong),
-        ("root_directory", ctypes.c_void_p),
-        ("object_name", ctypes.c_void_p),
-        ("attributes", ctypes.c_ulong),
-        ("security_descriptor", ctypes.c_void_p),
-        ("security_quality_of_service", ctypes.c_void_p),
-    ]
-
-
-class MODULEENTRY32(ctypes.Structure):
-    """Module entry structure, describes an entry from a list of the modules belonging to the specified process."""
-
-    _fields_ = [
-        ("dw_size", ctypes.c_ulong),
-        ("module_id", ctypes.c_ulong),
-        ("process_id", ctypes.c_ulong),
-        ("glbl_cnt_usage", ctypes.c_ulong),
-        ("proc_cnt_usage", ctypes.c_ulong),
-        ("mod_base_addr", ctypes.c_void_p),
-        ("mod_base_size", ctypes.c_ulong),
-        ("h_module", ctypes.c_void_p),
-        ("sz_module", ctypes.c_char * 256),
-        ("sz_exe_path", ctypes.c_char * 260),
-    ]
-
-    @property
-    def name(self) -> str:
-        """Process module name."""
-
-        return self.sz_module.decode()
-
-    @property
-    def base(self) -> int:
-        """Process module base address."""
-
-        return self.mod_base_addr
-
-    @property
-    def size(self) -> int:
-        """Process module base address."""
-
-        return self.mod_base_size
-
-
-class MEMORY_BASIC_INFORMATION(ctypes.Structure):
-    """Memory basic information structure that containg information about a range of pages in the virtual address space of a proces"""
-
-    _fields_ = [
-        ("m_base_address", ctypes.c_void_p),
-        ("m_allocation_base", ctypes.c_void_p),
-        ("m_allocation_protect", ctypes.c_ulong),
-        ("m_partition_id", ctypes.c_ushort),
-        ("m_region_size", ctypes.c_size_t),
-        ("m_state", ctypes.c_ulong),
-        ("m_protect", ctypes.c_ulong),
-        ("m_type", ctypes.c_ulong),
-    ]
-
-    @property
-    def base_address(self) -> int:
-        """Memory region base address."""
-
-        return self.m_base_address
-
-    @property
-    def allocation_base(self) -> int:
-        """Memory region allocation base."""
-
-        return self.m_allocation_base
-
-    @property
-    def allocation_protect(self) -> int:
-        """Memory region allocation protect."""
-
-        return self.m_allocation_protect
-
-    @property
-    def partition_id(self) -> int:
-        """Memory region partition ID."""
-
-        return self.m_partition_id
-
-    @property
-    def size(self) -> int:
-        """Memory region size."""
-
-        return self.m_region_size
-
-    @property
-    def state(self) -> int:
-        """Memory region state."""
-
-        return self.m_state
-
-    @property
-    def protect(self) -> int:
-        """Memory region protect."""
-
-        return self.m_protect
-
-    @property
-    def type(self) -> int:
-        """Memory region type."""
-
-        return self.m_type
-
-
 class PatternScanBuffer(ctypes.Structure):
     """Structure that containing pointer to array received from SIMD KMP after call of `scanAOB` function."""
 
@@ -219,10 +101,10 @@ class PatternScanBuffer(ctypes.Structure):
 # ==-------------------------------------------------------------------== #
 # Syscalls                                                                #
 # ==-------------------------------------------------------------------== #
-syscall_wrapper = DirectSyscallWrapper()
+syscall_wrapper = misc.DirectSyscallWrapper()
 
 _nt_close = syscall_wrapper.wrap("NtClose", result_type=ctypes.c_ulong, arguments_types=[ctypes.c_void_p])
-_nt_open_process = syscall_wrapper.wrap("NtOpenProcess", result_type=ctypes.c_ulong, arguments_types=[ctypes.c_void_p, ctypes.c_ulong, ctypes.POINTER(OBJECT_ATTRIBUTES), ctypes.POINTER(CLIENT_ID)])
+_nt_open_process = syscall_wrapper.wrap("NtOpenProcess", result_type=ctypes.c_ulong, arguments_types=[ctypes.c_void_p, ctypes.c_ulong, ctypes.POINTER(structs.OBJECT_ATTRIBUTES), ctypes.POINTER(structs.CLIENT_ID)])
 
 _nt_read_virtual_memory = syscall_wrapper.wrap("NtReadVirtualMemory", result_type=ctypes.c_ulong, arguments_types=[ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_ulong, ctypes.POINTER(ctypes.c_ulong)])
 _nt_write_virtual_memory = syscall_wrapper.wrap("NtWriteVirtualMemory", result_type=ctypes.c_ulong, arguments_types=[ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_ulong, ctypes.POINTER(ctypes.c_ulong)])
@@ -291,20 +173,20 @@ class Process:
     # ==--------------------------------== #
     # Public methods                       #
     # ==--------------------------------== #
-    def __init__(self, name_or_pid: str | int, access: int = PROCESS_ALL_ACCESS) -> None:
+    def __init__(self, name_or_pid: str | int, access_flags: int = PROCESS_ALL_ACCESS) -> None:
         """Initialize instance to manipulate process."""
 
         # Open process by it's ID or it's name
         match name_or_pid:
 
             case str():
-                self.handle, self.pid, self.name = self.__init_with_name(name_or_pid, access)
+                self.handle, self.pid, self.name, self.access_flags = *self.__init_with_name(name_or_pid, access_flags), access_flags
 
             case int():
-                self.handle, self.pid, self.name = self.__init_with_pid(name_or_pid, access)
+                self.handle, self.pid, self.name, self.access_flags = *self.__init_with_pid(name_or_pid, access_flags), access_flags
 
             case _:
-                raise OpenProcessError("Invalid `name_or_pid` argument value, have to be `int` or `str` type")
+                raise errors.OpenProcessError("Invalid `name_or_pid` argument value, have to be `int` or `str` type")
 
         # Try create file at temp directory to load SIMD KMP .dll (Module to blazingly fast pattern scaning)
         try:
@@ -319,54 +201,118 @@ class Process:
         # Load library
         self.__kmp = ctypes.WinDLL(appdata + "\\simdkmp.dll")
 
-    def list_modules(self) -> list[MODULEENTRY32]:
+    def list_modules(self, method: typing.Literal["pebwalk", "snapshot"] = "pebwalk") -> list[structs.MODULEENTRY32]:
         """List all of the modules loaded to process."""
 
-        # Modules snapshot functions
-        close_handle = ctypes.windll.kernel32.CloseHandle
-        module32_next = ctypes.windll.kernel32.Module32Next
-        module32_first = ctypes.windll.kernel32.Module32First
-        create_tool_help32_snapshot = ctypes.windll.kernel32.CreateToolhelp32Snapshot
+        def list_modules_peb() -> list[structs.MODULEENTRY32]:
+            """Innter function to list process modules using syscall wraps and manual PEB struct walking."""
 
-        # Create snapshot to iterate process modules
-        if (snapshot := create_tool_help32_snapshot(TH32CS_SNAPMODULE, self.pid)) == -1:
-            raise ctypes.WinError(descr="Unable to create snapshot for `%s` PID" % self.pid)
+            # If privileges are insufficient to list process modules
+            if not self.access_flags & PROCESS_VM_READ:
+                raise ctypes.WinError(descr="Unable to list process modules, insufficient privilages")
 
-        # Result list of process modules
-        process_modules = []
+            # If process is not 64-bit
+            if not self.is_64bit():
+                raise RuntimeError("Unable to list modules for not 64 bit process using `%s` method, use another one method instead")
 
-        # Process modules enumeration
-        try:
+            # If procewss PEB retrieve failed
+            if not (process_peb := self.get_information().peb):
+                raise RuntimeError("Process `%s` PEB address is null-value" % self.name)
 
-            # Modules entry to iterate process modules
-            modules_entry = MODULEENTRY32()
-            modules_entry.dw_size = ctypes.sizeof(MODULEENTRY32)
+            # Result list of process modules
+            process_modules = []
 
-            # Retrieve first process module snapshot
-            if not module32_first(snapshot, ctypes.byref(modules_entry)):
-                raise ctypes.WinError(descr="Unable to get first proces module to save to snapshot for `%s` PID" % self.pid)
+            # Get PEB_LDR_DATA by fixed offset
+            process_peb_ldr = self.read_uint64(process_peb + 0x18)
 
-            # Iterate all of the process modules using snapshot
-            while True:
+            # Get pointer to linked list head to collect all loaded modules information
+            process_peb_modules_ll = self.read_uint64(list_head := process_peb_ldr + 0x20)
 
-                # Create copy of module entry
-                ctypes.memmove(ctypes.byref(module_entry_copy := MODULEENTRY32()), ctypes.byref(modules_entry), ctypes.sizeof(MODULEENTRY32))
+            # Get node from modules linked list
+            modules_ll_node = self.read_uint64(process_peb_modules_ll)
 
-                # Save process module to list
-                process_modules.append(module_entry_copy)
+            # Iterator through all of the modules
+            while modules_ll_node and modules_ll_node != list_head:
 
-                # snapshot is over
-                if not module32_next(snapshot, ctypes.byref(modules_entry)):
-                    break
+                # Read module information
+                module = self.read_into_buffer(modules_ll_node, structs.LDR_DATA_TABLE_ENTRY())
+
+                # Get module on disk path
+                module_name = module.read_name(self)
+
+                # Save process module information to list
+                process_modules.append(structs.MODULEENTRY32(
+                    mod_base_addr=module.dll_base,
+                    sz_exe_path=module_name.encode(),
+                    sz_module=module_name.split("\\")[-1].encode(),
+                ))
+
+                # Update node pointer
+                modules_ll_node = module.flink
+
+            return process_modules
+
+        def list_modules_snapshot() -> list[structs.MODULEENTRY32]:
+            """Inner function to list process modules using standart WinAPI methods."""
+
+            # Result list of process modules
+            process_modules = []
+
+            # Modules snapshot functions
+            close_handle = ctypes.windll.kernel32.CloseHandle
+            module32_next = ctypes.windll.kernel32.Module32Next
+            module32_first = ctypes.windll.kernel32.Module32First
+            create_tool_help32_snapshot = ctypes.windll.kernel32.CreateToolhelp32Snapshot
+
+            # Create snapshot to iterate process modules
+            if (snapshot := create_tool_help32_snapshot(TH32CS_SNAPMODULE, self.pid)) == -1:
+                raise ctypes.WinError(descr="Unable to create snapshot for `%s` PID" % self.pid)
+
+            # Process modules enumeration
+            try:
+
+                # Modules entry to iterate process modules
+                modules_entry = structs.MODULEENTRY32()
+                modules_entry.dw_size = ctypes.sizeof(structs.MODULEENTRY32)
+
+                # Retrieve first process module snapshot
+                if not module32_first(snapshot, ctypes.byref(modules_entry)):
+                    raise ctypes.WinError(descr="Unable to get first proces module to save to snapshot for `%s` PID" % self.pid)
+
+                # Iterate all of the process modules using snapshot
+                while True:
 
-        finally:
+                    # Create copy of module entry
+                    ctypes.memmove(ctypes.byref(module_entry_copy := structs.MODULEENTRY32()), ctypes.byref(modules_entry), ctypes.sizeof(structs.MODULEENTRY32))
 
-            # Close snapshot handle
-            close_handle(snapshot)
+                    # Save process module information to list
+                    process_modules.append(module_entry_copy)
 
-        return process_modules
+                    # snapshot is over
+                    if not module32_next(snapshot, ctypes.byref(modules_entry)):
+                        break
 
-    def list_memory_regions(self, allowed_states: list[int] = [], allowed_protects: list[int] = [], allowed_types: list[int] = [], memory_regions_filter: typing.Callable[[MEMORY_BASIC_INFORMATION], bool] | None = None) -> list[MEMORY_BASIC_INFORMATION]:
+            finally:
+
+                # Close snapshot handle
+                close_handle(snapshot)
+
+            return process_modules
+
+        # 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))
+
+        # List modules with selected find method
+        match method:
+
+            case "pebwalk":
+                return list_modules_peb()
+
+            case "snapshot":
+                return list_modules_snapshot()
+
+    def list_memory_regions(self, allowed_states: list[int] = [], allowed_protects: list[int] = [], allowed_types: list[int] = [], memory_regions_filter: typing.Callable[[structs.MEMORY_BASIC_INFORMATION], bool] | None = None) -> list[structs.MEMORY_BASIC_INFORMATION]:
         """List all of the aviable process memory regions."""
 
         # Result list of memory regions
@@ -377,7 +323,7 @@ class Process:
         while True:
 
             # Prepare arguments
-            memory_basic_information = MEMORY_BASIC_INFORMATION()
+            memory_basic_information = structs.MEMORY_BASIC_INFORMATION()
 
             # Try to get memory region information using it's address
             if (result := _nt_virtual_query_memory(self.handle, current_address, 0, ctypes.byref(memory_basic_information), ctypes.sizeof(memory_basic_information), None)):
@@ -387,7 +333,7 @@ class Process:
                     break
 
                 else:
-                    raise NtError("NtVirtualQueryMemory failed with status: 0x%s" % hex(result)[2:].upper())
+                    raise errors.NtError("NtVirtualQueryMemory failed with status: 0x%s" % hex(result)[2:].upper())
 
             # Move to next memory region
             if (next_address := current_address + memory_basic_information.size) <= current_address:
@@ -414,7 +360,27 @@ class Process:
 
         return memory_regions
 
-    def get_module(self, name: str) -> MODULEENTRY32:
+    def get_information(self) -> structs.PROCESS_BASIC_INFORMATION_64:
+        """Gets process information."""
+
+        # If privileges are insufficient to query proess information
+        if not self.access_flags & PROCESS_QUERY_INFORMATION:
+            raise ctypes.WinError(descr="Unable to query process information, insufficient privilages")
+
+        # If process is not 64-bit
+        if not self.is_64bit():
+            raise RuntimeError("Unable to get process information for not 64 bit process using, method is not yet implemented")
+
+        # Prepare arguments
+        process_basic_information = structs.PROCESS_BASIC_INFORMATION_64()
+
+        # Try to get process information
+        if (result := _nt_query_information_process(self.handle, 0, ctypes.byref(process_basic_information), ctypes.sizeof(process_basic_information), None)):
+            raise errors.NtError("NtVirtualQueryMemory failed with status: 0x%s" % hex(result)[2:].upper())
+
+        return process_basic_information
+
+    def get_module(self, name: str) -> structs.MODULEENTRY32:
         """Get process module information."""
 
         # Process modules enumeration
@@ -426,15 +392,15 @@ class Process:
 
         raise ValueError("Module with `%s` name not found" % name)
 
-    def get_memory_region(self, address: int) -> MEMORY_BASIC_INFORMATION:
+    def get_memory_region(self, address: int) -> structs.MEMORY_BASIC_INFORMATION:
         """Get memory region information located at given address."""
 
         # Prepare arguments
-        memory_basic_information = MEMORY_BASIC_INFORMATION()
+        memory_basic_information = structs.MEMORY_BASIC_INFORMATION()
 
         # Try to get memory region information using it's address
         if (result := _nt_virtual_query_memory(self.handle, address, 0, ctypes.byref(memory_basic_information), ctypes.sizeof(memory_basic_information), None)):
-            raise NtError("NtVirtualQueryMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise errors.NtError("NtVirtualQueryMemory failed with status: 0x%s" % hex(result)[2:].upper())
 
         return memory_basic_information
 
@@ -445,8 +411,8 @@ class Process:
         wow64_info = ctypes.c_void_p()
 
         # Try to query process information
-        if (result := _nt_query_information_process(self.handle, 26, ctypes.byref(wow64_info), ctypes.sizeof(wow64_info), ctypes.byref(ctypes.c_ulong()))):
-            raise NtError("NtQueryInformationProcess failed with status: 0x%s" % hex(result)[2:].upper())
+        if (result := _nt_query_information_process(self.handle, 0x1A, ctypes.byref(wow64_info), ctypes.sizeof(wow64_info), ctypes.byref(ctypes.c_ulong()))):
+            raise errors.NtError("NtQueryInformationProcess failed with status: 0x%s" % hex(result)[2:].upper())
 
         return wow64_info.value is None
 
@@ -459,7 +425,7 @@ class Process:
 
         # Try to allocate process memory
         if (result := _nt_allocate_virtual_memory(self.handle, ctypes.byref(allocation_address), 0, ctypes.byref(allocation_size), memory_type, memory_protect)):
-            raise NtError("NtAllocateVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise errors.NtError("NtAllocateVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
 
         return allocation_address.value or 0, allocation_size.value or 0
 
@@ -472,7 +438,7 @@ class Process:
 
         # Try to deallocate process memory
         if (result := _nt_free_virtual_memory(self.handle, ctypes.byref(allocation_address), ctypes.byref(allocation_size), memory_type)):
-            raise NtError("NtFreeVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise errors.NtError("NtFreeVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
 
         return allocation_size.value or 0
 
@@ -485,11 +451,11 @@ class Process:
 
         # Try to change memory protection
         if (result := _nt_protect_virtual_memory(self.handle, ctypes.byref(protect_address), ctypes.byref(protect_size), memory_protect, ctypes.byref(memory_old_protect := ctypes.c_ulong()))):
-            raise NtError("NtProtectVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise errors.NtError("NtProtectVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
 
         return memory_old_protect.value or 0
 
-    def pattern_scan(self, pattern: str, allowed_states: list[int] = [MEM_COMMIT], allowed_protects: list[int] = [PAGE_READWRITE], allowed_types: list[int] = [], start_address: int | None = None, end_address: int | None = None, return_first: int | None = None, memory_regions_filter: typing.Callable[[MEMORY_BASIC_INFORMATION], bool] | None = None, finalize_regions_callback: typing.Callable[[list[MEMORY_BASIC_INFORMATION]], None] | None = None) -> list[int]:
+    def pattern_scan(self, pattern: str, allowed_states: list[int] = [MEM_COMMIT], allowed_protects: list[int] = [PAGE_READWRITE], allowed_types: list[int] = [], start_address: int | None = None, end_address: int | None = None, return_first: int | None = None, memory_regions_filter: typing.Callable[[structs.MEMORY_BASIC_INFORMATION], bool] | None = None, finalize_regions_callback: typing.Callable[[list[structs.MEMORY_BASIC_INFORMATION]], None] | None = None, buffered: bool = True) -> list[int]:
         """Scan process and return address that validates given pattern hex byte mask, use `??` to wildcard byte, for example - "14 00 00 00 DB FF ?? ?? FF FF 00 00"."""
 
         # Validate given pattern
@@ -554,10 +520,10 @@ class Process:
             try:
 
                 # Read bytes into pre-allocated buffer
-                self.read_into_buffer(region.base_address, region.size, ctypes.c_void_p(ctypes.addressof(read_memory_buffer)))
+                self.read_into_buffer(region.base_address, read_memory_buffer, region.size)
 
             except Exception:
-                pass
+                continue
 
             # Pattern scan region using SIMD KMP algorithm
             self.__kmp.scanAOB(ctypes.c_void_p(ctypes.addressof(read_memory_buffer)), region.size, pattern.strip().encode(), ctypes.c_uint64(region.base_address), ctypes.c_uint64(return_first if return_first is not None else 0), ctypes.byref(scan_result := PatternScanBuffer()))
@@ -583,7 +549,7 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer := ctypes.c_int8()), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+            raise errors.MemoryReadError(result, address)
 
         return buffer.value
 
@@ -592,7 +558,7 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_int16)() if big_endian else ctypes.c_int16()), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+            raise errors.MemoryReadError(result, address)
 
         return buffer.value
 
@@ -601,7 +567,7 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_int32)() if big_endian else ctypes.c_int32()), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+            raise errors.MemoryReadError(result, address)
 
         return buffer.value
 
@@ -610,7 +576,7 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_int64)() if big_endian else ctypes.c_int64()), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+            raise errors.MemoryReadError(result, address)
 
         return buffer.value
 
@@ -619,7 +585,7 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer := ctypes.c_uint8()), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+            raise errors.MemoryReadError(result, address)
 
         return buffer.value
 
@@ -628,7 +594,7 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_uint16)() if big_endian else ctypes.c_uint16()), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+            raise errors.MemoryReadError(result, address)
 
         return buffer.value
 
@@ -637,7 +603,7 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_uint32)() if big_endian else ctypes.c_uint32()), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+            raise errors.MemoryReadError(result, address)
 
         return buffer.value
 
@@ -646,7 +612,7 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_uint64)() if big_endian else ctypes.c_uint64()), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+            raise errors.MemoryReadError(result, address)
 
         return buffer.value
 
@@ -655,7 +621,7 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_float)() if big_endian else ctypes.c_float()), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+            raise errors.MemoryReadError(result, address)
 
         return buffer.value
 
@@ -664,7 +630,7 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_double)() if big_endian else ctypes.c_double()), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+            raise errors.MemoryReadError(result, address)
 
         return buffer.value
 
@@ -673,109 +639,106 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_int8 * size)() if big_endian else (ctypes.c_int8 * size)()), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+            raise errors.MemoryReadError(result, address)
 
         return bytes(buffer)
 
-    def read_buffer(self, address: int, buffer: typing.Any) -> typing.Any:
-        """Read size of buffer byte value located at given address to buffer. Buffer have to be able passed at `ctypes.byref` and `ctype.sizeof`."""
+    def read_into_buffer(self, address: int, buffer: typing.Any, read_bytes_size: int | None = None) -> typing.Any:
+        """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
+        if read_bytes_size is not None and read_bytes_size <= 0:
+            raise ValueError("Unable to read value into buffer due the invalid size: `%s`" % read_bytes_size)
 
         # If result failed
-        if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer), ctypes.sizeof(buffer), None)):
-            raise MemoryReadError(result, address)
+        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)
 
         return buffer
 
-    def read_into_buffer(self, address: int, size: int, buffer_pointer: int) -> None:
-        """Read bytes array of variadic size located at given address into pre-allocated internal buffer by pointer."""
-
-        # If result failed
-        if (result := _nt_read_virtual_memory(self.handle, address, buffer_pointer, size, None)):
-            raise MemoryReadError(result, address)
-
     def write_int8(self, address: int, value: int) -> None:
         """Write 1 byte signed integer value at given address."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer := ctypes.c_int8(value)), ctypes.sizeof(buffer), None)):
-            raise MemoryWriteError(result, address)
+            raise errors.MemoryWriteError(result, address)
 
     def write_int16(self, address: int, value: int, big_endian: bool = False) -> None:
         """Write 2 byte signed integer value at given address."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_int16(value)) if big_endian else ctypes.c_int16(value)), ctypes.sizeof(buffer), None)):
-            raise MemoryWriteError(result, address)
+            raise errors.MemoryWriteError(result, address)
 
     def write_int32(self, address: int, value: int, big_endian: bool = False) -> None:
         """Write 4 byte signed integer value at given address."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_int32(value)) if big_endian else ctypes.c_int32(value)), ctypes.sizeof(buffer), None)):
-            raise MemoryWriteError(result, address)
+            raise errors.MemoryWriteError(result, address)
 
     def write_int64(self, address: int, value: int, big_endian: bool = False) -> None:
         """Write 8 byte signed integer value at given address."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_int64(value)) if big_endian else ctypes.c_int64(value)), ctypes.sizeof(buffer), None)):
-            raise MemoryWriteError(result, address)
+            raise errors.MemoryWriteError(result, address)
 
     def write_uint8(self, address: int, value: int) -> None:
         """Write 1 byte unsigned integer value at given address."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer := ctypes.c_uint8(value)), ctypes.sizeof(buffer), None)):
-            raise MemoryWriteError(result, address)
+            raise errors.MemoryWriteError(result, address)
 
     def write_uint16(self, address: int, value: int, big_endian: bool = False) -> None:
         """Write 2 byte unsigned integer value at given address."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_uint16(value)) if big_endian else ctypes.c_uint16(value)), ctypes.sizeof(buffer), None)):
-            raise MemoryWriteError(result, address)
+            raise errors.MemoryWriteError(result, address)
 
     def write_uint32(self, address: int, value: int, big_endian: bool = False) -> None:
         """Write 4 byte unsigned integer value at given address."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_uint32(value)) if big_endian else ctypes.c_uint32(value)), ctypes.sizeof(buffer), None)):
-            raise MemoryWriteError("NtWriteVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise errors.MemoryWriteError("NtWriteVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
 
     def write_uint64(self, address: int, value: int, big_endian: bool = False) -> None:
         """Write 8 byte unsigned integer value at given address."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_uint64(value)) if big_endian else ctypes.c_uint64(value)), ctypes.sizeof(buffer), None)):
-            raise MemoryWriteError(result, address)
+            raise errors.MemoryWriteError(result, address)
 
     def write_float32(self, address: int, value: float | int, big_endian: bool = False) -> float:
         """Write 4 byte floating-point digit value at given address."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_float(value)) if big_endian else ctypes.c_float(value)), ctypes.sizeof(buffer), None)):
-            raise MemoryWriteError(result, address)
+            raise errors.MemoryWriteError(result, address)
 
     def write_float64(self, address: int, value: float | int, big_endian: bool = False) -> float:
         """Write 8 byte floating-point digit value at given address."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer := _get_be_buffer(ctypes.c_double(value)) if big_endian else ctypes.c_double(value)), ctypes.sizeof(buffer), None)):
-            raise MemoryWriteError(result, address)
+            raise errors.MemoryWriteError(result, address)
 
     def write_bytes(self, address: int, value: bytes, big_endian: bool = False) -> None:
         """Write bytes array of variadic size at given address."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, value[::-1] if big_endian else value, len(value), None)):
-            raise MemoryWriteError(result, address)
+            raise errors.MemoryWriteError(result, address)
 
     def write_buffer(self, address: int, buffer: typing.Any) -> None:
-        """Write size of buffer byte value at given address. Buffer have to be able passed at `ctypes.byref` and `ctype.sizeof`."""
+        """Write size of buffer byte value at given address. Buffer have to be able passed at `ctypes.byref` and `ctypes.sizeof`."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer), ctypes.sizeof(buffer), None)):
-            raise MemoryWriteError(result, address)
+            raise errors.MemoryWriteError(result, address)
 
     def close(self) -> None:
         """Close opened process using it's handle, have to be called once on stop interacting with process."""
@@ -786,7 +749,7 @@ class Process:
     # ==--------------------------------== #
     # Private methods                      #
     # ==--------------------------------== #
-    def __init_with_pid(self, pid: int, access: int, listed_processes: list[dict[str, int | str]] | None = None) -> tuple[int, int, str]:
+    def __init_with_pid(self, pid: int, access_flags: int, listed_processes: list[dict[str, int | str]] | None = None) -> tuple[int, int, str]:
         """Open process handle by it's ID with desired access."""
 
         # Iterate all of the processes
@@ -799,22 +762,22 @@ class Process:
                 break
 
         else:
-            raise OpenProcessError("Process with `%s` ID not found" % pid)
+            raise errors.OpenProcessError("Process with `%s` ID not found" % pid)
 
         # Prepare arguments
-        object_attributes = OBJECT_ATTRIBUTES()
-        object_attributes.length = ctypes.sizeof(OBJECT_ATTRIBUTES)
+        object_attributes = structs.OBJECT_ATTRIBUTES()
+        object_attributes.length = ctypes.sizeof(structs.OBJECT_ATTRIBUTES)
 
-        client_id = CLIENT_ID()
+        client_id = structs.CLIENT_ID()
         client_id.unique_process = pid
 
         # Try to open process using it's ID
-        if (result := _nt_open_process(ctypes.byref(handle := ctypes.c_void_p()), access, ctypes.byref(object_attributes), ctypes.byref(client_id))):
-            raise NtError("NtOpenProcess failed with status: 0x%s" % hex(result)[2:].upper())
+        if (result := _nt_open_process(ctypes.byref(handle := ctypes.c_void_p()), access_flags, ctypes.byref(object_attributes), ctypes.byref(client_id))):
+            raise errors.NtError("NtOpenProcess failed with status: 0x%s" % hex(result)[2:].upper())
 
         return handle.value, pid, process_name
 
-    def __init_with_name(self, name: str, access: int) -> tuple[int, int, str]:
+    def __init_with_name(self, name: str, access_flags: int) -> tuple[int, int, str]:
         """Open process hanle by it's name with desired access."""
 
         # Iterate all of the processes using snapshot
@@ -822,6 +785,6 @@ class Process:
 
             # If process have a reqired name
             if process["name"].lower() == name.strip().lower():
-                return self.__init_with_pid(process["id"], access, listed_processes)
+                return self.__init_with_pid(process["id"], access_flags, listed_processes)
 
-        raise OpenProcessError("Process with `%s` name not found" % name)
+        raise errors.OpenProcessError("Process with `%s` name not found" % name)

ntmemoryapi-2.3.0/src/ntmemoryapi/structs.py

@@ -0,0 +1,219 @@
+# +-------------------------------------+
+# |         ~ Author : Xenely ~         |
+# +=====================================+
+# | GitHub: https://github.com/Xenely14 |
+# | Discord: xenely                     |
+# +-------------------------------------+
+
+
+import typing
+import ctypes
+
+
+# ==-------------------------------------------------------------------== #
+# C-structs                                                               #
+# ==-------------------------------------------------------------------== #
+class CLIENT_ID(ctypes.Structure):
+    """Client-ID structure that required to open process."""
+
+    _fields_ = [
+        ("unique_process", ctypes.c_void_p),
+        ("unique_thread", ctypes.c_void_p),
+    ]
+
+
+class LIST_ENTRY(ctypes.Structure):
+    """Linked list WinAPI node structure."""
+
+    _fields_ = [
+        ("flink", ctypes.c_void_p),
+        ("blink", ctypes.c_void_p),
+    ]
+
+
+class UNICODE_STRING(ctypes.Structure):
+    """Unicode string structure that holds data to represent UTF-16LE WinAPI strings."""
+
+    _fields_ = [
+        ("length", ctypes.c_short),
+        ("maximum_length", ctypes.c_short),
+        ("buffer", ctypes.c_void_p),
+    ]
+
+    def read(self, process: typing.Any) -> str:
+        """Read string from process using it's instance."""
+
+        return process.read_bytes(self.buffer, self.length).decode("utf-16le", errors="ignore")
+
+
+class LDR_DATA_TABLE_ENTRY(ctypes.Structure):
+    """Linked list entry structure that contains imformation about loaded into the process modules."""
+
+    _fields_ = [
+        ("flink", ctypes.c_void_p),
+        ("blink", ctypes.c_void_p),
+        ("reserved", ctypes.c_byte * 16),
+        ("dll_base", ctypes.c_void_p),
+        ("reserved2", ctypes.c_byte * 16),
+        ("base_dll_name", UNICODE_STRING),
+    ]
+
+    def read_name(self, process: typing.Any) -> str:
+        """Read module name."""
+
+        return self.base_dll_name.read(process)
+
+
+class OBJECT_ATTRIBUTES(ctypes.Structure):
+    """Object attributes structure that can be applied to objects or object handles."""
+
+    _fields_ = [
+        ("length", ctypes.c_ulong),
+        ("root_directory", ctypes.c_void_p),
+        ("object_name", ctypes.c_void_p),
+        ("attributes", ctypes.c_ulong),
+        ("security_descriptor", ctypes.c_void_p),
+        ("security_quality_of_service", ctypes.c_void_p),
+    ]
+
+
+class MODULEENTRY32(ctypes.Structure):
+    """Module entry structure, describes an entry from a list of the modules belonging to the specified process."""
+
+    _fields_ = [
+        ("dw_size", ctypes.c_ulong),
+        ("module_id", ctypes.c_ulong),
+        ("process_id", ctypes.c_ulong),
+        ("glbl_cnt_usage", ctypes.c_ulong),
+        ("proc_cnt_usage", ctypes.c_ulong),
+        ("mod_base_addr", ctypes.c_void_p),
+        ("mod_base_size", ctypes.c_ulong),
+        ("h_module", ctypes.c_void_p),
+        ("sz_module", ctypes.c_char * 256),
+        ("sz_exe_path", ctypes.c_char * 260),
+    ]
+
+    @property
+    def name(self) -> str:
+        """Process module name."""
+
+        return self.sz_module.decode()
+
+    @property
+    def path(self) -> str:
+        """process module on disk path."""
+
+        return self.sz_exe_path.decode()
+
+    @property
+    def base(self) -> int:
+        """Process module base address."""
+
+        return self.mod_base_addr
+
+    @property
+    def size(self) -> int:
+        """Process module base address."""
+
+        return self.mod_base_size
+
+
+class MEMORY_BASIC_INFORMATION(ctypes.Structure):
+    """Memory basic information structure that contains information about a range of pages in the virtual address space of a proces"""
+
+    _fields_ = [
+        ("m_base_address", ctypes.c_void_p),
+        ("m_allocation_base", ctypes.c_void_p),
+        ("m_allocation_protect", ctypes.c_ulong),
+        ("m_partition_id", ctypes.c_ushort),
+        ("m_region_size", ctypes.c_size_t),
+        ("m_state", ctypes.c_ulong),
+        ("m_protect", ctypes.c_ulong),
+        ("m_type", ctypes.c_ulong),
+    ]
+
+    @property
+    def base_address(self) -> int:
+        """Memory region base address."""
+
+        return self.m_base_address
+
+    @property
+    def allocation_base(self) -> int:
+        """Memory region allocation base."""
+
+        return self.m_allocation_base
+
+    @property
+    def allocation_protect(self) -> int:
+        """Memory region allocation protect."""
+
+        return self.m_allocation_protect
+
+    @property
+    def partition_id(self) -> int:
+        """Memory region partition ID."""
+
+        return self.m_partition_id
+
+    @property
+    def size(self) -> int:
+        """Memory region size."""
+
+        return self.m_region_size
+
+    @property
+    def state(self) -> int:
+        """Memory region state."""
+
+        return self.m_state
+
+    @property
+    def protect(self) -> int:
+        """Memory region protect."""
+
+        return self.m_protect
+
+    @property
+    def type(self) -> int:
+        """Memory region type."""
+
+        return self.m_type
+
+
+class PROCESS_BASIC_INFORMATION_X32(ctypes.Structure):
+    """Process basic information structure that contains information about the OS-process."""
+
+    _fields_ = [
+        ("ExitStatus", ctypes.c_uint32),
+        ("PebBaseAddress", ctypes.c_uint32),
+        ("AffinityMask", ctypes.c_uint32),
+        ("BasePriority", ctypes.c_int32),
+        ("UniqueProcessId", ctypes.c_uint32),
+        ("InheritedFromUniqueProcessId", ctypes.c_uint32),
+    ]
+
+    @property
+    def peb(self) -> int:
+        """Process peb base address."""
+
+        return self.peb_base_address
+
+
+class PROCESS_BASIC_INFORMATION_64(ctypes.Structure):
+    """Process basic information structure that contains information about the OS-process."""
+
+    _fields_ = [
+        ("exit_status", ctypes.c_void_p),
+        ("peb_base_address", ctypes.c_void_p),
+        ("affinity_mask", ctypes.c_void_p),
+        ("base_priority", ctypes.c_uint32),
+        ("unique_process_id", ctypes.c_void_p),
+        ("inherited_from_unique_process_id", ctypes.c_void_p),
+    ]
+
+    @property
+    def peb(self) -> int:
+        """Process peb base address."""
+
+        return self.peb_base_address

ntmemoryapi-2.2.4/PKG-INFO

@@ -1,9 +0,0 @@
-Metadata-Version: 2.3
-Name: ntmemoryapi
-Version: 2.2.4
-Summary: Simple library for Windows to manipulate process virtual memory with stelthy syscall wraps.
-Author: Xenely
-Requires-Dist: psutil>=7.1.3
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-

ntmemoryapi-2.2.4/pyproject.toml

@@ -1,19 +0,0 @@
-[project]
-name = "ntmemoryapi"
-version = "2.2.4"
-description = "Simple library for Windows to manipulate process virtual memory with stelthy syscall wraps."
-authors = [
-    {name = "Xenely"}
-]
-readme = "README.md"
-requires-python = ">=3.10"
-dependencies = [
-    "psutil>=7.1.3",
-]
-
-[project.scripts]
-ntmemoryapi = "ntmemoryapi:main"
-
-[build-system]
-requires = ["uv_build>=0.9.9,<0.10.0"]
-build-backend = "uv_build"