ntnput 1.0.0__tar.gz

ntnput-1.0.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.3
+Name: ntnput
+Version: 1.0.0
+Summary: Minimalist Python library using wraps of undocumented `Nt` functions to interact with mouse and keyboard stealthy
+Author: Xenely
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Description-Content-Type: text/markdown
+
+# ntnput
+The Minimalist Python library for Windows using wraps of undocumented `Nt` functions to interact with mouse and keyboard stealthy.
+
+# Details
+This library uses syscall wraps of undocumented `NtUserInjectMouseInput` and `NtUserInjectKeyboardInput` functions from `win32u.dll` module.
+It's makes keyboard and mouse interaction safe and stealth due to the bypass of Windows triggers.</br>
+
+**NtNput** also works faster than analogues because of usage of builtin `ctypes` library allowing to interact directly with C and machine code.
+You can use this library if your process blocks usage of `mouse_event`, `SendInput` or etc. WinAPI functions.</br>
+
+## Installation
+1. You can install library using pip:
+```
+pip install ntnput
+```
+2. You can download this repo, put it's folder into your project and import it using the folder name
+
+## Usage
+Library provides several functions to interact with mouse:
+1. `mouse_move(x, y)` - moves mouse from current position
+2. `mouse_move_to(x, y)` - moves mouse to absolute x, y position
+3. `mouse_click(button <default "left">)` - clicks mouse
+4. `mouse_release(button <default "left">)` - releases mouse
+5. `mouse_click_and_release(button <default "left">, delay_ms <default 0.0>)` - clicks mouse, sleeps, releases
+
+And several functions to interact with keyboard:
+1. `keyboard_press(key_code)` - presses keyboard button
+2. `keyboard_release(key_code)` - releases keyboard button
+3. `keyboard_press_and_release(key_code, delay_ms <default 0.0>)` - presses keyboard button, sleeps, releases
+
+You can use official [Microsoft documentation](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) to find keyboard key codes definitions.
+

ntnput-1.0.0/README.md

@@ -0,0 +1,31 @@
+# ntnput
+The Minimalist Python library for Windows using wraps of undocumented `Nt` functions to interact with mouse and keyboard stealthy.
+
+# Details
+This library uses syscall wraps of undocumented `NtUserInjectMouseInput` and `NtUserInjectKeyboardInput` functions from `win32u.dll` module.
+It's makes keyboard and mouse interaction safe and stealth due to the bypass of Windows triggers.</br>
+
+**NtNput** also works faster than analogues because of usage of builtin `ctypes` library allowing to interact directly with C and machine code.
+You can use this library if your process blocks usage of `mouse_event`, `SendInput` or etc. WinAPI functions.</br>
+
+## Installation
+1. You can install library using pip:
+```
+pip install ntnput
+```
+2. You can download this repo, put it's folder into your project and import it using the folder name
+
+## Usage
+Library provides several functions to interact with mouse:
+1. `mouse_move(x, y)` - moves mouse from current position
+2. `mouse_move_to(x, y)` - moves mouse to absolute x, y position
+3. `mouse_click(button <default "left">)` - clicks mouse
+4. `mouse_release(button <default "left">)` - releases mouse
+5. `mouse_click_and_release(button <default "left">, delay_ms <default 0.0>)` - clicks mouse, sleeps, releases
+
+And several functions to interact with keyboard:
+1. `keyboard_press(key_code)` - presses keyboard button
+2. `keyboard_release(key_code)` - releases keyboard button
+3. `keyboard_press_and_release(key_code, delay_ms <default 0.0>)` - presses keyboard button, sleeps, releases
+
+You can use official [Microsoft documentation](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) to find keyboard key codes definitions.

ntnput-1.0.0/ntnput/__init__.py

@@ -0,0 +1,148 @@
+# +-------------------------------------+
+# |         ~ Author : Xenely ~         |
+# +=====================================+
+# | GitHub: https://github.com/Xenely14 |
+# | Discord: xenely                     |
+# +-------------------------------------+
+
+import typing
+import ctypes
+import ctypes.wintypes
+
+# Local imports
+from . import misc
+
+# ==-------------------------------------------------------------------== #
+# Global and static variables, constants                                  #
+# ==-------------------------------------------------------------------== #
+LEFT_DOWN = 0x02
+LEFT_UP = 0x04
+RIGHT_DOWN = 0x10
+RIGHT_UP = 0x08
+
+KEY_DOWN = 0x00
+KEY_UP = 0x02
+
+
+# ==-------------------------------------------------------------------== #
+# С-structures                                                            #
+# ==-------------------------------------------------------------------== #
+class InjectInputMouseInfo(ctypes.Structure):
+    """Structure containing information about mouse input injection."""
+
+    _fields_ = [
+        ("x_direction", ctypes.c_int),
+        ("y_direction", ctypes.c_int),
+        ("mouse_data", ctypes.c_uint),
+        ("mouse_options", ctypes.c_int),
+        ("time_offset_in_miliseconds", ctypes.c_uint),
+        ("extra_info", ctypes.c_void_p)
+    ]
+
+
+class KeybdInput(ctypes.Structure):
+    """Structure containing information about keyboard input injection."""
+
+    _fields_ = [
+        ("vk_code", ctypes.c_ushort),
+        ("scan_code", ctypes.c_ushort),
+        ("dw_flags", ctypes.c_ulong),
+        ("time", ctypes.c_ulong),
+        ("extra_info", ctypes.c_void_p)
+    ]
+
+
+# ==-------------------------------------------------------------------== #
+# Wrapped syscall functions                                               #
+# ==-------------------------------------------------------------------== #
+_NtDelayExecution = misc.syscall("NtDelayExecution", result_type=ctypes.c_ulong, arguments_types=[ctypes.c_int, ctypes.POINTER(ctypes.wintypes.LARGE_INTEGER)], module=b"ntdll.dll")
+_NtUserInjectMouseInput = misc.syscall("NtUserInjectMouseInput", result_type=ctypes.c_ulong, arguments_types=[ctypes.POINTER(InjectInputMouseInfo), ctypes.c_int], module=b"win32u.dll")
+_NtUserInjectKeyboardInput = misc.syscall("NtUserInjectKeyboardInput", result_type=ctypes.c_ulong, arguments_types=[ctypes.POINTER(KeybdInput), ctypes.c_int], module=b"win32u.dll")
+
+
+# ==-------------------------------------------------------------------== #
+# Functions                                                               #
+# ==-------------------------------------------------------------------== #
+def mouse_move(x: int, y: int) -> None:
+    """Moves mouse relative to it's current position using wrapped syscall `NtUserInjectMouseInput` function."""
+
+    # Moving mouse
+    _NtUserInjectMouseInput(ctypes.byref(InjectInputMouseInfo(x_direction=x, y_direction=-y)), 1)
+
+
+def mouse_move_to(x: int, y: int) -> None:
+    """Moves mouse by absolute coorinate position using wrapped syscall `NtUserInjectMouseInput` function."""
+
+    # Enable process DPI awareness to retrieve `indeed` screen resolution
+    ctypes.windll.user32.SetProcessDPIAware()
+
+    # Retrieving screen resolutions
+    screen_width = ctypes.windll.user32.GetSystemMetrics(0)
+    screen_height = ctypes.windll.user32.GetSystemMetrics(1)
+
+    # Normalizing coordinates
+    normalized_x = int((x / screen_width) * 65535)
+    normalized_y = int((y / screen_height) * 65535)
+
+    # Moving mouse
+    _NtUserInjectMouseInput(ctypes.byref(InjectInputMouseInfo(x_direction=normalized_x, y_direction=normalized_y, mouse_options=0x8000)), 1)
+
+
+def mouse_click(button: typing.Literal["left", "right"] = "left") -> None:
+    """Clicks mouse using wrapped syscall `NtUserInjectMouseInput` function."""
+
+    # If button literal is not allowed
+    if button not in (allowed_literals := typing.get_args(mouse_click.__annotations__["button"])):
+        raise Exception("Button literal is invalid, expected one of: `%s`" % ", ".join(allowed_literals))
+
+    # Clicking mouse
+    match button:
+
+        case "left": _NtUserInjectMouseInput(ctypes.byref(InjectInputMouseInfo(mouse_options=LEFT_DOWN)), 1)
+        case "right": _NtUserInjectMouseInput(ctypes.byref(InjectInputMouseInfo(mouse_options=RIGHT_DOWN)), 1)
+
+
+def mouse_release(button: typing.Literal["left", "right"] = "left") -> None:
+    """Releases mouse using wrapped syscall `NtUserInjectMouseInput` function."""
+
+    # If button literal is not allowed
+    if button not in (allowed_literals := typing.get_args(mouse_click.__annotations__["button"])):
+        raise Exception("Button literal is invalid, expected one of: `%s`" % ", ".join(allowed_literals))
+
+    # Releasing mouse
+    match button:
+
+        case "left": _NtUserInjectMouseInput(ctypes.byref(InjectInputMouseInfo(mouse_options=LEFT_UP)), 1)
+        case "right": _NtUserInjectMouseInput(ctypes.byref(InjectInputMouseInfo(mouse_options=RIGHT_UP)), 1)
+
+
+def mouse_click_and_release(button: typing.Literal["left", "right"] = "left", delay_ms: float = 0.0) -> None:
+    """Clicks mouse and releases after given delay time passed in milliseconds using wrapped syscall `NtUserInjectMouseInput` function."""
+
+    # If button literal is not allowed
+    if button not in (allowed_literals := typing.get_args(mouse_click.__annotations__["button"])):
+        raise Exception("Button literal is invalid, expected one of: `%s`" % ", ".join(allowed_literals))
+
+    # Clicking and releasing mouse
+    mouse_click(button), _NtDelayExecution(1, ctypes.byref(ctypes.wintypes.LARGE_INTEGER(int(-abs(delay_ms) * 10_000)))), mouse_release(button)
+
+
+def keyboard_press(key_code: int) -> None:
+    """Presses keyboard key using wrapped syscall `NtUserInjectKeyboardInput` function."""
+
+    # Pressing keyboard key
+    _NtUserInjectKeyboardInput(ctypes.byref(KeybdInput(vk_code=key_code, dw_flags=KEY_DOWN)), 1)
+
+
+def keyboard_release(key_code: int) -> None:
+    """Releases keyboard key using wrapped syscall `NtUserInjectKeyboardInput` function."""
+
+    # Pressing keyboard key
+    _NtUserInjectKeyboardInput(ctypes.byref(KeybdInput(vk_code=key_code, dw_flags=KEY_UP)), 1)
+
+
+def keyboard_press_and_release(key_code: int, delay_ms: float = 0.0) -> None:
+    """Presses keyboard key and releases after given delay time passed in milliseconds using wrapped syscall `NtUserInjectKeyboardInput` function."""
+
+    # Clicking and releasing keyboard key
+    keyboard_press(key_code), _NtDelayExecution(1, ctypes.byref(ctypes.wintypes.LARGE_INTEGER(int(-abs(delay_ms) * 10_000)))), keyboard_release(key_code)

ntnput-1.0.0/ntnput/misc.py

@@ -0,0 +1,102 @@
+# +-------------------------------------+
+# |         ~ Author : Xenely ~         |
+# +=====================================+
+# | GitHub: https://github.com/Xenely14 |
+# | Discord: xenely                     |
+# +-------------------------------------+
+
+import ctypes
+import struct
+import typing
+import ctypes.wintypes
+
+# ==-------------------------------------------------------------------== #
+# DLL functions                                                           #
+# ==-------------------------------------------------------------------== #
+
+# DLL libraries loading
+_kernel32 = ctypes.windll.kernel32
+
+# DLL libraries functions loading
+_LoadLibraryA = _kernel32.LoadLibraryA
+_GetProcAddress = _kernel32.GetProcAddress
+_VirtualProtect = _kernel32.VirtualProtect
+
+# Defining of DLL libraries functions return type
+_LoadLibraryA.restype = ctypes.wintypes.LPVOID
+_GetProcAddress.restype = ctypes.wintypes.LPVOID
+_VirtualProtect.restype = ctypes.wintypes.BOOL
+
+# Defining of DLL libraries functions argument types
+_LoadLibraryA .argtypes = [ctypes.wintypes.LPCSTR]
+_GetProcAddress.argtypes = [ctypes.wintypes.LPVOID, ctypes.wintypes.LPCSTR]
+_VirtualProtect.argtypes = [ctypes.wintypes.LPVOID, ctypes.c_size_t, ctypes.wintypes.DWORD, ctypes.POINTER(ctypes.wintypes.DWORD)]
+
+
+# ==-------------------------------------------------------------------== #
+# Functions                                                               #
+# ==-------------------------------------------------------------------== #
+def syscall(nt_function_name: str, *, result_type: typing.Any, arguments_types: list[typing.Any], module: bytes = b"ntdll.dll") -> ctypes.WINFUNCTYPE:
+    """Finds function in DLL module by it name, retrieves it's syscall ID, wraps it into raw function buffer and casts to `WINFUNCTYPE` to make call shadowed."""
+
+    # Module loading
+    if not (module_handle := _LoadLibraryA(module)):
+        raise Exception("Unable to load module `%s`" % module.decode())
+
+    # Retrieving nt-function pointer
+    if not (nt_function := _GetProcAddress(module_handle, nt_function_name.encode())):
+        raise Exception("Function `%s` not found" % nt_function_name)
+
+    offset = 0
+    syscall_id = None
+
+    # Retrieving syscall ID from nt-function pointer
+    while True:
+
+        # Syscall ID not found
+        if offset > 0x16:
+            break
+
+        # Retrieving syscall ID from memory
+        if ctypes.cast(nt_function + offset, ctypes.POINTER(ctypes.c_ubyte)).contents.value == 0xB8:
+            syscall_id = ctypes.cast(nt_function + offset + 1, ctypes.POINTER(ctypes.c_ushort)).contents.value
+            break
+
+        offset += 1
+
+    # Syscall ID not found
+    if syscall_id is None:
+        raise Exception("Syscall ID for function `%s` not found" % nt_function_name)
+
+    # Converting 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 struct.pack("<h", syscall_id)]
+
+    # NOTE: I actually don't know why does this code require access `gs` segment.
+    # I've just used this repo as reference: https://github.com/opcode86/SysCaller
+    #
+    # mov rax, gs:[0x60]
+    # mov r10, rcx
+    # mov eax, <syscall id>,
+    # syscall
+    # ret
+    shellcode = bytes.fromhex("""
+        65 48 8B 04 25 60 00
+        00 00
+        4C 8B D1
+        B8 %s %s 00 00
+        0F 05
+        C3
+    """ % tuple([*syscall_id_bytes]))
+
+    # Allocating buffer for function machine code
+    buffer = (ctypes.c_uint8 * len(shellcode))()
+    shellcode_buffer = ctypes.cast(buffer, ctypes.c_void_p)
+
+    # Copying shellcode into function machine code buffer
+    ctypes.memmove(shellcode_buffer, ctypes.create_string_buffer(shellcode, len(shellcode)), len(shellcode))
+
+    # Updating of function machine code buffer memory protection to make it executable
+    ctypes.windll.kernel32.VirtualProtect(shellcode_buffer, len(shellcode), 0x40, ctypes.wintypes.LPDWORD(ctypes.wintypes.DWORD()))
+
+    # Return wrapped syscall function
+    return ctypes.cast(shellcode_buffer, ctypes.WINFUNCTYPE(result_type, *arguments_types))

ntnput-1.0.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "ntnput"
+version = "1.0.0"
+description = "Minimalist Python library using wraps of undocumented `Nt` functions to interact with mouse and keyboard stealthy"
+authors = [
+    {name = "Xenely"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"