hookie 0.1.0__tar.gz

hookie-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,360 @@
+# Hookie Architecture
+
+This document describes how Hookie works internally. `README.md` intentionally
+stays small; this is the technical reference.
+
+## 1. Mental model
+
+Hookie has two layers:
+
+1. **Hook engine** — patches a native function in the process where Python is
+   already running.
+2. **Payload bootstrap** — gets Python + Hookie into another process, then runs
+   the user's payload entrypoint there.
+
+The hook engine does not know anything about DLL injection. The native bootstrap
+does not implement trampoline relocation. They meet only when the bootstrap
+executes the packaged Python payload and that code imports `hookie`.
+
+---
+
+## 2. Hook engine
+
+`HookEngine.create_hook()` receives:
+
+- a native target address,
+- a Python detour callable,
+- the target argument types,
+- the target return type,
+- optionally a ctypes prototype factory.
+
+Hookie wraps the Python detour with `ctypes`, disassembles whole instructions
+from the target prologue, builds a trampoline, and prepares a patch.
+
+The hook starts disabled. `enable()` writes the jump into the target prologue.
+`disable()` restores the original bytes.
+
+`hook.original(...)` calls the trampoline, not the patched target entrypoint.
+
+### x64 patch choices
+
+Hookie chooses among:
+
+- a 14-byte absolute indirect jump,
+- a 5-byte `rel32` jump when the destination is in range,
+- a 5-byte jump to a nearby relay which then performs the absolute jump.
+
+### Relocation
+
+Copied prologue instructions cannot always be copied byte-for-byte. Hookie
+relocates:
+
+- relative `call`, `jmp`, and conditional branches,
+- branches whose target lies inside the stolen prologue,
+- x64 RIP-relative memory operands,
+- loop/jcxz-family control flow.
+
+The trampoline ends with a jump back to the first original instruction after the
+stolen region.
+
+---
+
+## 3. Memory model
+
+Executable buffers are allocated writable, populated, then changed to executable
+permissions. Hookie also supports near/range-constrained allocation where x64
+RIP-relative relocation or a `rel32` relay requires it.
+
+Hook installation/removal is not thread-safe: another thread executing the
+prologue while its bytes are being replaced can observe a partial patch.
+
+---
+
+## 4. Build identity and directory layout
+
+Every `create-dll` / `create-so` operation generates one random **6-byte id**.
+It is rendered as **12 lowercase hex characters**:
+
+```text
+6 bytes -> a1b2c3d4e5f6
+```
+
+That exact id is the single identity for the build.
+
+Normal/path mode:
+
+```text
+deps/
+└── a1b2c3d4e5f6/
+    ├── Python runtime
+    ├── hookie/
+    ├── dependencies
+    └── hook.py
+
+builds/
+└── a1b2c3d4e5f6/
+    └── hookie_stub.dll   # or .so
+```
+
+Single-file mode extracts to the same relative name:
+
+```text
+%TEMP%\a1b2c3d4e5f6\          # Windows
+$TMPDIR/a1b2c3d4e5f6/        # Linux
+```
+
+The entrypoint filename remains simply:
+
+```text
+hook.py
+```
+
+There is no separate content id and no `hookie_` prefix on the dependency/temp
+directory. `deps/<id>`, `builds/<id>`, and temp extraction all expose the same
+build id. The file itself stays `hook.py`; only its in-memory Python module name
+uses the id (`hookie_<id>`).
+
+---
+
+## 5. Payload footer
+
+The final DLL/SO carries a 40-byte footer:
+
+```c
+struct HookieFooter {
+    char     magic[17];
+    uint8_t  mode;
+    uint8_t  ident_len;
+    uint8_t  reserved[5];
+    uint64_t raw_size;
+    uint64_t data_size;
+};
+```
+
+`magic` is:
+
+```text
+HOOKIE_PAYLOAD_V1
+```
+
+There are two modes.
+
+### Path mode
+
+The data before the footer is the absolute path to `deps/<id>`.
+
+```text
+[UTF-8 absolute deps path][footer]
+```
+
+`ident_len` is zero because the id can be obtained from the basename of the
+resolved payload directory.
+
+### Single-file mode
+
+The data is:
+
+```text
+[12-byte ASCII id][LZSS-compressed archive][footer]
+```
+
+The native bootstrap extracts the archive to the system temporary directory
+using exactly that id as the directory name.
+
+---
+
+## 6. Native bootstrap: high-level flow
+
+Windows:
+
+```text
+DllMain
+  -> create worker thread
+  -> resolve payload directory
+  -> locate versioned python3XY.dll
+  -> reuse matching initialized CPython if present
+     OR load bundled python3XY.dll
+  -> configure Python paths
+  -> execute hook.py as module hookie_<id>
+```
+
+Linux:
+
+```text
+constructor
+  -> create worker thread
+  -> resolve payload directory
+  -> read bundled libpython/runtime version
+  -> reuse matching process CPython when safe
+     OR load bundled libpython when no Python is present
+  -> configure Python paths
+  -> execute hook.py as module hookie_<id>
+```
+
+The heavy bootstrap work is deliberately not performed directly under Windows
+`DllMain` loader lock.
+
+---
+
+## 7. Single-file extraction
+
+Packaging serializes each payload file as:
+
+```text
+uint32 path_length
+uint64 file_size
+path bytes
+file bytes
+```
+
+A zero `path_length` terminates the archive.
+
+The archive is compressed with a small LZSS codec and appended to the native
+stub. At runtime the stub:
+
+1. reads its own final 40 bytes,
+2. validates the footer,
+3. reads the id + compressed blob,
+4. decompresses it,
+5. creates `<temp>/<id>/`,
+6. recreates the payload tree there.
+
+The archive extractor rejects absolute/traversal paths.
+
+---
+
+## 8. Python entrypoint execution
+
+The user writes:
+
+```text
+hook.py
+```
+
+Packaging keeps that filename unchanged. The bootstrap derives the id directly
+from the payload directory basename and uses it only for the module name:
+
+```python
+_hookie_id = os.path.basename(os.path.normpath(_hookie_dir))
+_hookie_name = "hookie_" + _hookie_id
+_hookie_file = os.path.join(_hookie_dir, "hook.py")
+```
+
+It loads `hook.py` using `importlib.util.spec_from_file_location`, but registers
+it in Python under the deterministic module name:
+
+```text
+hookie_a1b2c3d4e5f6
+```
+
+No path hash or second random identifier is involved.
+
+The module is put in `sys.modules` before execution. This has two useful
+properties:
+
+- a second load of the same payload does not blindly execute the same hook setup
+  again;
+- module globals keep `HookEngine`, `Hook`, and ctypes callback references alive.
+
+The payload top-level is the entrypoint. There is no `install()` callback.
+
+---
+
+## 9. `sys.path` vs `os.add_dll_directory` on Windows
+
+These solve different problems.
+
+### `sys.path`
+
+```python
+sys.path.insert(0, payload_dir)
+sys.path.insert(0, payload_dir / "Lib" / "site-packages")
+```
+
+This tells **Python's importer** where to find Python modules and packages such
+as `hookie` and `capstone`.
+
+### `os.add_dll_directory`
+
+```python
+handle = os.add_dll_directory(payload_dir)
+```
+
+This tells the **Windows native loader** to also search the payload directory
+when a `.pyd` or another native component needs dependent DLLs.
+
+Adding a directory to `sys.path` does not change Windows DLL dependency search.
+Conversely, `add_dll_directory` does not make Python modules importable.
+
+The returned handle owns that registration. If it is closed or garbage
+collected, Windows removes the directory from the DLL search list. Hookie keeps
+those handles alive in:
+
+```python
+sys._hookie_dll_dirs
+```
+
+for the lifetime of the embedded/reused interpreter.
+
+---
+
+## 10. Existing Python runtime policy
+
+Hookie currently avoids subinterpreters.
+
+### Windows
+
+If the payload was built for `python3XY.dll` and that same versioned DLL already
+exists and is initialized in the target, Hookie reuses the target main
+interpreter and acquires the GIL with `PyGILState_Ensure()`.
+
+If a different Python minor is present but the requested one is not, Hookie may
+load its own versioned bundled `python3XY.dll` because Windows symbol lookup is
+performed through that explicit module handle.
+
+### Linux
+
+If a matching CPython major/minor is already present, Hookie reuses it.
+
+If a different `libpython` is already mapped, Hookie refuses to load a second
+version. ELF symbol interposition makes two independent process-global CPython
+runtimes substantially less predictable than the Windows versioned-DLL case.
+
+---
+
+## 11. Bundled runtime lifetime
+
+When Hookie owns a newly initialized runtime, it does not finalize Python after
+executing the payload. Native target threads may later enter ctypes callbacks
+created by the hooks. Finalizing the interpreter would leave those native jump
+targets pointing into a dead Python runtime.
+
+The bootstrap releases the GIL and parks its worker for process lifetime.
+
+---
+
+## 12. Debug mode
+
+Windows `--debug` compiles `HK_DEBUG` traces using `OutputDebugStringW`, visible
+in a debugger or DebugView.
+
+Linux `--debug` compiles `HK_DEBUG` traces to stderr.
+
+Debug builds are compiled from source instead of silently reusing release cache
+artifacts.
+
+---
+
+## 13. Tests
+
+`examples/` contains user-facing hook payloads.
+
+`tests/` contains regression/native tests. In particular,
+`test_stub_runtime_policy` verifies the CPython bootstrap policy rather than
+instruction relocation:
+
+- same-version existing Python is reused;
+- Linux refuses a mismatched already-loaded Python runtime;
+- `hook.py` executes under module name `hookie_<id>`.
+
+x86 native tests require a real 32-bit Python/process and 32-bit toolchain.

hookie-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hookie-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include ARCHITECTURE.md
+include requirements.txt
+recursive-include hookie/stubs *.c
+recursive-include examples *.py *.md
+recursive-include tests *.py *.md
+global-exclude *.py[cod]
+prune build
+prune dist
+

hookie-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: hookie
+Version: 0.1.0
+Summary: Native x86/x64 inline hooking from pure Python on Windows and Linux
+Author: Sems
+License-Expression: MIT
+Project-URL: Source, https://github.com/SemsYapar/hookie
+Project-URL: Issues, https://github.com/SemsYapar/hookie/issues
+Keywords: hooking,detour,trampoline,minhook,reverse-engineering,ctypes,x86,x64
+Classifier: Development Status :: 3 - Alpha
+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
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Software Development :: Disassemblers
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: capstone<6,>=5.0.8
+Dynamic: license-file
+
+# Hookie
+
+Hookie has two useful parts that can be used together **or separately**:
+
+1. **Run Python code inside another process.** `create-dll` / `create-so` package a `hook.py` together with Python and the required dependencies so the native stub can execute that Python code inside the target process. You do not have to hook anything to use Hookie this way.
+2. **Hook native functions from Python.** `HookEngine` lets Python detours hook x86/x64 native functions while keeping the original function callable through a trampoline.
+
+Put the two together and you can inject Python into a target process and install native hooks there using Python.
+
+Windows and Linux are supported; x86 and x64 are supported.
+
+## Install
+
+```bash
+pip install hookie
+```
+
+## Hook a function in the current process
+
+```python
+from hookie import HookEngine
+
+engine = HookEngine()
+hook = engine.create_hook(target_addr, detour, argtypes, restype)
+hook.enable()
+
+# From the detour:
+# hook.original(...)
+```
+
+## Run Python inside another process
+
+Write normal top-level Python code in `hook.py`. It may install hooks, inspect the process, log information, or do any other authorized Python-side work.
+
+Windows:
+
+```bash
+hookie create-dll hook.py --arch x64
+hookie inject-dll target.exe builds/<id>/hookie_stub.dll
+```
+
+Linux:
+
+```bash
+hookie create-so hook.py --arch x64
+```
+
+Optional build modes:
+
+```bash
+--single-file
+--debug
+```
+
+See `examples/` for examples. See `ARCHITECTURE.md` for the trampoline, payload, stub, CPython bootstrap, and runtime-reuse internals.
+
+## Current limitations
+
+- Installing/removing inline hooks is not thread-safe; patch at a quiet point or stop the relevant threads yourself.
+- In an existing Python process, Windows reuses the same CPython minor version and can use Hookie's bundled runtime when a different minor is present.
+- On Linux, Hookie reuses the same CPython major/minor. If a different `libpython` is already mapped, Hookie refuses to load a second Python runtime.
+- x86 native testing/building requires a real 32-bit Python/process and a 32-bit toolchain.
+
+MIT licensed.

hookie-0.1.0/README.md

@@ -0,0 +1,64 @@
+# Hookie
+
+Hookie has two useful parts that can be used together **or separately**:
+
+1. **Run Python code inside another process.** `create-dll` / `create-so` package a `hook.py` together with Python and the required dependencies so the native stub can execute that Python code inside the target process. You do not have to hook anything to use Hookie this way.
+2. **Hook native functions from Python.** `HookEngine` lets Python detours hook x86/x64 native functions while keeping the original function callable through a trampoline.
+
+Put the two together and you can inject Python into a target process and install native hooks there using Python.
+
+Windows and Linux are supported; x86 and x64 are supported.
+
+## Install
+
+```bash
+pip install hookie
+```
+
+## Hook a function in the current process
+
+```python
+from hookie import HookEngine
+
+engine = HookEngine()
+hook = engine.create_hook(target_addr, detour, argtypes, restype)
+hook.enable()
+
+# From the detour:
+# hook.original(...)
+```
+
+## Run Python inside another process
+
+Write normal top-level Python code in `hook.py`. It may install hooks, inspect the process, log information, or do any other authorized Python-side work.
+
+Windows:
+
+```bash
+hookie create-dll hook.py --arch x64
+hookie inject-dll target.exe builds/<id>/hookie_stub.dll
+```
+
+Linux:
+
+```bash
+hookie create-so hook.py --arch x64
+```
+
+Optional build modes:
+
+```bash
+--single-file
+--debug
+```
+
+See `examples/` for examples. See `ARCHITECTURE.md` for the trampoline, payload, stub, CPython bootstrap, and runtime-reuse internals.
+
+## Current limitations
+
+- Installing/removing inline hooks is not thread-safe; patch at a quiet point or stop the relevant threads yourself.
+- In an existing Python process, Windows reuses the same CPython minor version and can use Hookie's bundled runtime when a different minor is present.
+- On Linux, Hookie reuses the same CPython major/minor. If a different `libpython` is already mapped, Hookie refuses to load a second Python runtime.
+- x86 native testing/building requires a real 32-bit Python/process and a 32-bit toolchain.
+
+MIT licensed.

hookie-0.1.0/examples/README.md

@@ -0,0 +1,36 @@
+# Examples
+
+`examples/` contains user-facing payloads. The entrypoint is always `hook.py`,
+and it stays named `hook.py` inside the built payload. The native stub loads it
+under the in-memory module name `hookie_<build-id>`. Its module top-level runs
+once and installs the hooks; there is no separate `install()` callback.
+
+Keep the `HookEngine`, `Hook`, and Python detour objects alive at module scope for
+as long as native code can enter the hook.
+
+## Windows
+
+- `windows/messagebox_payload/hook.py` — rewrites `MessageBoxW` text/caption.
+- `windows/beep_payload/hook.py` — rewrites `kernel32!Beep` arguments and shows
+  the x86 `WINFUNCTYPE` / x64 calling-convention pattern.
+
+Build one with:
+
+```powershell
+hookie create-dll examples\windows\messagebox_payload --arch x64
+```
+
+## Linux
+
+- `linux/puts_payload/hook.py` — prefixes strings sent to `libc!puts`.
+- `linux/getpid_payload/hook.py` — demonstrates return-value rewriting by
+  changing the observed result of `getpid()`.
+
+Build one with:
+
+```bash
+hookie create-so examples/linux/puts_payload --arch x64
+```
+
+These examples deliberately modify process behavior. Use disposable test
+programs while experimenting.

hookie-0.1.0/examples/linux/getpid_payload/hook.py

@@ -0,0 +1,27 @@
+"""Demonstrate return-value rewriting by intercepting libc getpid()."""
+import ctypes
+import hookie
+
+_engine = hookie.HookEngine()
+_hooks = []
+
+libc = ctypes.CDLL(None)
+libc.getpid.argtypes = []
+libc.getpid.restype = ctypes.c_int
+_target = ctypes.cast(libc.getpid, ctypes.c_void_p).value
+
+
+def _detour():
+    # Deliberately obvious demo value; do not use this payload in software that
+    # relies on its real PID for synchronization or file naming.
+    return _hook.original() + 100000
+
+
+_hook = _engine.create_hook(
+    _target,
+    _detour,
+    [],
+    ctypes.c_int,
+)
+_hook.enable()
+_hooks.append(_hook)

hookie-0.1.0/examples/linux/puts_payload/hook.py

@@ -0,0 +1,27 @@
+"""Prefix strings passed to libc puts()."""
+import ctypes
+import hookie
+
+_engine = hookie.HookEngine()
+_hooks = []
+
+libc = ctypes.CDLL(None)
+libc.puts.argtypes = [ctypes.c_char_p]
+libc.puts.restype = ctypes.c_int
+_target = ctypes.cast(libc.puts, ctypes.c_void_p).value
+
+
+def _detour(text):
+    original = text or b"(null)"
+    rewritten = b"[hookie] " + original
+    return _hook.original(rewritten)
+
+
+_hook = _engine.create_hook(
+    _target,
+    _detour,
+    libc.puts.argtypes,
+    libc.puts.restype,
+)
+_hook.enable()
+_hooks.append(_hook)

hookie-0.1.0/examples/windows/beep_payload/hook.py

@@ -0,0 +1,30 @@
+"""Intercept kernel32!Beep and rewrite its frequency/duration."""
+import ctypes
+from ctypes import wintypes
+import hookie
+
+_engine = hookie.HookEngine()
+_hooks = []
+
+kernel32 = ctypes.windll.kernel32
+kernel32.Beep.argtypes = [wintypes.DWORD, wintypes.DWORD]
+kernel32.Beep.restype = wintypes.BOOL
+_target = ctypes.cast(kernel32.Beep, ctypes.c_void_p).value
+
+
+def _detour(frequency, duration):
+    # Keep values in Beep's documented frequency range and shorten long beeps.
+    frequency = max(37, min(int(frequency) + 200, 32767))
+    duration = min(int(duration), 250)
+    return _hook.original(frequency, duration)
+
+
+_hook = _engine.create_hook(
+    _target,
+    _detour,
+    kernel32.Beep.argtypes,
+    kernel32.Beep.restype,
+    prototype_factory=(ctypes.WINFUNCTYPE if ctypes.sizeof(ctypes.c_void_p) == 4 else ctypes.CFUNCTYPE),
+)
+_hook.enable()
+_hooks.append(_hook)

hookie-0.1.0/examples/windows/messagebox_payload/hook.py

@@ -0,0 +1,32 @@
+"""Rewrite MessageBoxW text/caption inside the target process."""
+import ctypes
+from ctypes import wintypes
+import hookie
+
+_engine = hookie.HookEngine()
+_hooks = []
+
+user32 = ctypes.windll.user32
+user32.MessageBoxW.argtypes = [
+    wintypes.HWND,
+    wintypes.LPCWSTR,
+    wintypes.LPCWSTR,
+    wintypes.UINT,
+]
+user32.MessageBoxW.restype = ctypes.c_int
+_target = ctypes.cast(user32.MessageBoxW, ctypes.c_void_p).value
+
+
+def _detour(hwnd, text, caption, utype):
+    return _hook.original(hwnd, "hooked by hookie", "hookie", utype)
+
+
+_hook = _engine.create_hook(
+    _target,
+    _detour,
+    user32.MessageBoxW.argtypes,
+    user32.MessageBoxW.restype,
+    prototype_factory=(ctypes.WINFUNCTYPE if ctypes.sizeof(ctypes.c_void_p) == 4 else ctypes.CFUNCTYPE),
+)
+_hook.enable()
+_hooks.append(_hook)