ntmemoryapi 2.0.2__tar.gz → 2.1.0__tar.gz

{ntmemoryapi-2.0.2 → ntmemoryapi-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ntmemoryapi
-Version: 2.0.2
+Version: 2.1.0
 Summary: Simple library for Windows to manipulate process virtual memory with stelthy syscall wraps
 Author: Xenely
 Requires-Dist: psutil>=7.1.3

{ntmemoryapi-2.0.2 → ntmemoryapi-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ntmemoryapi"
-version = "2.0.2"
+version = "2.1.0"
 description = "Simple library for Windows to manipulate process virtual memory with stelthy syscall wraps"
 authors = [
     {name = "Xenely"}

{ntmemoryapi-2.0.2 → ntmemoryapi-2.1.0}/src/ntmemoryapi/__init__.py

@@ -12,6 +12,7 @@ import psutil
 # Local imports
 from .misc import *
 from .embed import *
+from .errors import *
 
 # ==-------------------------------------------------------------------== #
 # Static and global variables, constans                                   #
@@ -76,7 +77,7 @@ class CLIENT_ID(ctypes.Structure):
 
     _fields_ = [
         ("unique_process", ctypes.c_void_p),
-        ("unique_thread", ctypes.c_void_p)
+        ("unique_thread", ctypes.c_void_p),
     ]
 
 
@@ -89,7 +90,7 @@ class OBJECT_ATTRIBUTES(ctypes.Structure):
         ("object_name", ctypes.c_void_p),
         ("attributes", ctypes.c_ulong),
         ("security_descriptor", ctypes.c_void_p),
-        ("security_quality_of_service", ctypes.c_void_p)
+        ("security_quality_of_service", ctypes.c_void_p),
     ]
 
 
@@ -106,7 +107,7 @@ class MODULEENTRY32(ctypes.Structure):
         ("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)
+        ("sz_exe_path", ctypes.c_char * 260),
     ]
 
     @property
@@ -241,8 +242,8 @@ def list_processes(include_process_information: int = PROCESS_ID | PROCESS_NAME)
     """List all of the currently active system processes."""
 
     # If `include_id` and `include_name` disabled both
-    if not include_process_information & PROCESS_ID and not include_process_information & PROCESS_NAME:
-        raise Exception("Unable to disable ID and name including at once")
+    if not (include_process_information & (PROCESS_ID | PROCESS_NAME)):
+        raise ValueError("Unable to disable ID and name including at once")
 
     # Result list of processes
     processes = []
@@ -251,18 +252,18 @@ def list_processes(include_process_information: int = PROCESS_ID | PROCESS_NAME)
     for process in psutil.process_iter():
 
         # Save process to list
-        process_dict = {}
+        process_info = {}
 
         # If process ID including required
         if include_process_information & PROCESS_ID:
-            process_dict |= {"id": process.pid}
+            process_info["id"] = process.pid
 
         # If process ID including required
         if include_process_information & PROCESS_NAME:
-            process_dict |= {"name": process.name()}
+            process_info["name"] = process.name()
 
         # Save process information to list
-        processes.append(process_dict)
+        processes.append(process_info)
 
     return processes
 
@@ -287,10 +288,9 @@ def _get_be_buffer(soure_c_type: typing.Any) -> ctypes.BigEndianStructure:
 class Process:
     """Basic class of process, have methods to manipulate it."""
 
-    # ==-------------------------------------------------------------------== #
-    # Methods                                                                 #
-    # ==-------------------------------------------------------------------== #
-
+    # ==--------------------------------== #
+    # Public methods                       #
+    # ==--------------------------------== #
     def __init__(self, name_or_pid: str | int, access: int = PROCESS_ALL_ACCESS) -> None:
         """Initialize instance to manipulate process."""
 
@@ -304,12 +304,12 @@ class Process:
                 self.handle, self.pid, self.name = self.__init_with_pid(name_or_pid, access)
 
             case _:
-                raise Exception("Invalid `name_or_pid` argument value, have to be `int` or `str` type")
+                raise 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:
 
-            # Write library bytes directry from python list
+            # Write library bytes directly from python list
             with open("%s\\simdkmp.dll" % (appdata := os.getenv("APPDATA")), "wb") as file:
                 file.write(bytes(embed.kmp))
 
@@ -330,7 +330,7 @@ class Process:
 
         # Create snapshot to iterate process modules
         if (snapshot := create_tool_help32_snapshot(TH32CS_SNAPMODULE, self.pid)) == -1:
-            raise Exception("Unable to create snapshot to iterate process modules")
+            raise ctypes.WinError(descr="Unable to create snapshot for `%s` PID" % self.pid)
 
         # Result list of process modules
         process_modules = []
@@ -344,7 +344,7 @@ class Process:
 
             # Retrieve first process module snapshot
             if not module32_first(snapshot, ctypes.byref(modules_entry)):
-                raise Exception("Unable to get first process module to save to snapshot")
+                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:
@@ -387,7 +387,7 @@ class Process:
                     break
 
                 else:
-                    raise Exception("NtVirtualQueryMemory failed with status: 0x%s" % hex(result)[2:].upper())
+                    raise 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:
@@ -424,7 +424,7 @@ class Process:
             if module.name.lower() == name.strip().lower():
                 return module
 
-        raise Exception("Module with `%s` name not found" % name)
+        raise ValueError("Module with `%s` name not found" % name)
 
     def get_memory_region(self, address: int) -> MEMORY_BASIC_INFORMATION:
         """Get memory region information located at given address."""
@@ -434,7 +434,7 @@ class Process:
 
         # 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 Exception("NtVirtualQueryMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise NtError("NtVirtualQueryMemory failed with status: 0x%s" % hex(result)[2:].upper())
 
         return memory_basic_information
 
@@ -446,7 +446,7 @@ class Process:
 
         # 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 Exception("NtQueryInformationProcess failed with status: 0x%s" % hex(result)[2:].upper())
+            raise NtError("NtQueryInformationProcess failed with status: 0x%s" % hex(result)[2:].upper())
 
         return wow64_info.value is None
 
@@ -459,7 +459,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 Exception("NtAllocateVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise NtError("NtAllocateVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
 
         return allocation_address.value or 0, allocation_size.value or 0
 
@@ -472,7 +472,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 Exception("NtFreeVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise NtError("NtFreeVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
 
         return allocation_size.value or 0
 
@@ -485,7 +485,7 @@ 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 Exception("NtProtectVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise NtError("NtProtectVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
 
         return memory_old_protect.value or 0
 
@@ -493,7 +493,7 @@ class Process:
         """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
-        for byte in pattern.strip().split():
+        for byte in pattern.lower().strip().split():
 
             # If pattern byte is not wildcard and valid
             if len(byte) == 2 and [item in "0123456789ABCDEFabcdef" for item in byte].count(True) == 2:
@@ -503,7 +503,7 @@ class Process:
             if byte == "??":
                 continue
 
-            raise Exception("Invalid pattern: `%s`" % pattern)
+            raise ValueError("Invalid pattern: `%s`" % pattern)
 
         # Result list of found addresses
         found_addresses = []
@@ -562,7 +562,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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return buffer.value
 
@@ -571,7 +571,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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return buffer.value
 
@@ -580,7 +580,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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return buffer.value
 
@@ -589,7 +589,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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return buffer.value
 
@@ -598,7 +598,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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return buffer.value
 
@@ -607,7 +607,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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return buffer.value
 
@@ -616,7 +616,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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return buffer.value
 
@@ -625,7 +625,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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return buffer.value
 
@@ -634,7 +634,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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return buffer.value
 
@@ -643,7 +643,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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return buffer.value
 
@@ -652,7 +652,7 @@ 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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return bytes(buffer)
 
@@ -661,7 +661,7 @@ class Process:
 
         # If result failed
         if (result := _nt_read_virtual_memory(self.handle, address, ctypes.byref(buffer), ctypes.sizeof(buffer), None)):
-            raise Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryReadError(result, address)
 
         return buffer
 
@@ -670,42 +670,42 @@ class Process:
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer := ctypes.c_int8(value)), ctypes.sizeof(buffer), None)):
-            raise Exception("NtWriteVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise 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 Exception("NtWriteVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise 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 Exception("NtWriteVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise 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 Exception("NtWriteVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise 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 Exception("NtWriteVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise 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 Exception("NtWriteVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise 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."""
@@ -719,35 +719,35 @@ class Process:
 
         # 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 Exception("NtWriteVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise 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 Exception("NtWriteVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise 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 Exception("NtWriteVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise 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 Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise 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`."""
 
         # If result failed
         if (result := _nt_write_virtual_memory(self.handle, address, ctypes.byref(buffer), ctypes.sizeof(buffer), None)):
-            raise Exception("NtReadVirtualMemory failed with status: 0x%s" % hex(result)[2:].upper())
+            raise MemoryWriteError(result, address)
 
     def close(self) -> None:
         """Close opened process using it's handle, have to be called once on stop interacting with process."""
@@ -755,9 +755,9 @@ class Process:
         # Close process
         _nt_close(self.handle)
 
-    # ==-------------------------------------------------------------------== #
-    # Private methods                                                         #
-    # ==-------------------------------------------------------------------== #
+    # ==--------------------------------== #
+    # Private methods                      #
+    # ==--------------------------------== #
     def __init_with_pid(self, pid: int, access: int, listed_processes: list[dict[str, int | str]] | None = None) -> tuple[int, int, str]:
         """Open process handle by it's ID with desired access."""
 
@@ -771,7 +771,7 @@ class Process:
                 break
 
         else:
-            raise Exception("Process with `%s` ID not found" % pid)
+            raise OpenProcessError("Process with `%s` ID not found" % pid)
 
         # Prepare arguments
         object_attributes = OBJECT_ATTRIBUTES()
@@ -782,13 +782,7 @@ class Process:
 
         # 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))):
-
-            # If result failed due process ID not found
-            if result == 0xC000000B:
-                raise Exception("Process with `%s` ID not found" % pid)
-
-            else:
-                raise Exception("NtOpenProcess failed with status: 0x%s" % hex(result)[2:].upper())
+            raise NtError("NtOpenProcess failed with status: 0x%s" % hex(result)[2:].upper())
 
         return handle.value, pid, process_name
 
@@ -802,4 +796,4 @@ class Process:
             if process["name"].lower() == name.strip().lower():
                 return self.__init_with_pid(process["id"], access, listed_processes)
 
-        raise Exception("Process with `%s` name not found" % name)
+        raise OpenProcessError("Process with `%s` name not found" % name)

ntmemoryapi-2.1.0/src/ntmemoryapi/errors.py

@@ -0,0 +1,103 @@
+# +-------------------------------------+
+# |         ~ Author : Xenely ~         |
+# +=====================================+
+# | GitHub: https://github.com/Xenely14 |
+# | Discord: xenely                     |
+# +-------------------------------------+
+
+# ==-------------------------------------------------------------------== #
+# Classes                                                                 #
+# ==-------------------------------------------------------------------== #
+class NtError(Exception):
+    """Exception that raises on `nt` functions calls fails."""
+
+    # ==--------------------------------== #
+    # Public methods                       #
+    # ==--------------------------------== #
+    def __init__(self, message: str, status: int | None) -> None:
+        """Initialize instance of `nt` error."""
+
+        # Save initializer arguments as an attributes
+        self.message = message
+        self.status = status
+
+        # Call initializer of parrent class
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        """Overload triggered on `str` cast calls"""
+
+        # If error status is defined
+        if self.status is not None:
+            return "Nt function failed with `%s` status: %s" % (self.get_hex_status(), self.message)
+
+        # If error status is not defined
+        return "Nt function failed: %s" % self.message
+
+    def get_hex_status(self, hex_prefix: str | None = "0x") -> str:
+        """Get error `nt`status in hex string view."""
+
+        return "%s%08x" % (hex_prefix if hex_prefix is not None else "", self.status)
+
+
+class OpenProcessError(NtError):
+    """Exception that raises on process open fail."""
+
+    # ==--------------------------------== #
+    # Public methods                       #
+    # ==--------------------------------== #
+    def __init__(self, message: str, status: int | None = None) -> None:
+        """Initialize instance of `nt` error."""
+
+        # Call initializer of parrent class
+        super().__init__(message, status)
+
+    def __str__(self) -> str:
+        """Overload triggered on `str` cast calls."""
+
+        # If error status is defined
+        if self.status is not None:
+            return "Unable to open process due `nt` function failed with `%s` status: %s" % (self.get_hex_status(), self.message)
+
+        # If error status is not defined
+        return "Unable to open process: %s" % self.message
+
+
+class MemoryReadError(NtError):
+    """Exception that raises on virtual memory read fail."""
+
+    # ==--------------------------------== #
+    # Public methods                       #
+    # ==--------------------------------== #
+    def __init__(self, status: int, address: int):
+
+        # Save initializer arguments as an attributes
+        self.address = address
+
+        # Call initializer of parrent class
+        super().__init__(None, status)
+
+    def __str__(self) -> str:
+        """Overload triggered on `str` cast calls"""
+
+        return "Unalble to read memory at `0x%08x` address, `nt` function failed with `%s` status" % (self.address, self.get_hex_status())
+
+
+class MemoryWriteError(NtError):
+    """Exception that raises on virtual memory read fail."""
+
+    # ==--------------------------------== #
+    # Public methods                       #
+    # ==--------------------------------== #
+    def __init__(self, status: int, address: int):
+
+        # Save initializer arguments as an attributes
+        self.address = address
+
+        # Call initializer of parrent class
+        super().__init__(None, status)
+
+    def __str__(self) -> str:
+        """Overload triggered on `str` cast calls"""
+
+        return "Unalble to write memory at `0x%08x` address, `nt` function failed with `%s` status" % (self.address, self.get_hex_status())

{ntmemoryapi-2.0.2 → ntmemoryapi-2.1.0}/src/ntmemoryapi/misc.py

@@ -46,6 +46,9 @@ class DirectSyscallWrapper:
     # Table containing all syscall wrappers allocations
     registred_syscalls_table = dict()
 
+    # ==--------------------------------== #
+    # Public methods                       #
+    # ==--------------------------------== #
     def __init__(self) -> None:
         """Creates wrapper instance to wrap syscalls."""
 
@@ -70,11 +73,11 @@ class DirectSyscallWrapper:
 
         # Module loading
         if not (module_handle := _LoadLibraryA(search_module)):
-            raise Exception("Unable to load module `%s`" % search_module.decode())
+            raise ctypes.WinError(descr="Unable to load module `%s`" % search_module.decode())
 
         # Retrieve function pointer
         if not (serach_function := _GetProcAddress(module_handle, function_name.encode())):
-            raise Exception("Function `%s` not found" % function_name)
+            raise ctypes.WinError(descr="Function `%s` not found" % function_name)
 
         # Syscall id
         syscall_id = None
@@ -90,7 +93,7 @@ class DirectSyscallWrapper:
 
         # If syscall ID not found
         if syscall_id is None:
-            raise Exception("Syscall ID for function `%s` not found" % function_name)
+            raise ValueError("Syscall ID for function `%s` not found" % function_name)
 
         # Convert syscall ID to hex-bytes list
         syscall_id_bytes = [hex(item)[2:] if len(hex(item)[2:]) == 2 else "0" + hex(item)[2:] for item in bytes(ctypes.c_ushort(syscall_id))]
@@ -111,7 +114,7 @@ class DirectSyscallWrapper:
 
         # Allocate buffer for function machine code
         if not (shellcode_buffer := _VirtualAlloc(0, len(shellcode), 0x1000 | 0x2000, 0x04)):
-            raise Exception("Unable to alloate memory for shellcode")
+            raise ctypes.WinError(descr="Unable to alloate memory for shellcode")
 
         # Save allocated buffer into wrapped syscalls table
         self.registred_syscalls_table[id(self)][function_name] = shellcode_buffer