pymhf.core.hooking module#

Bases: MinHook

add_detour(detour: HookProtocol)#: Add the provided detour to this FuncHook.

bind() → bool#: Actually initialise the base class. Returns whether the hook is bound.

property caller_address#

close()#: Close the hook. Removing it.

disable()#: Disable the hook.

enable()#: Enable the hook.

property name#

property offset: int#: The relative offset of the target to the binary base.

remove_detour(detour: HookProtocol)#: Remove the provided detour from this FuncHook.

class pymhf.core.hooking.HookFactory#

Bases: object

classmethod after(detour: Callable[[...], Any]) → HookProtocol#: Run the detour after the original function. An optional _result_ argument can be added as the final argument. If this argument is provided it will be the result of calling the original function.

classmethod before(detour: Callable[[...], Any]) → HookProtocol#: Run the detour before the original function. If this detour returns any values they must be the same types and order as the original arguments to the function. If this happens these values will be passed into the original function instead of the original arguments.

classmethod overload(overload_args)#

class pymhf.core.hooking.HookManager#

Bases: object

call_custom_callbacks(callback_key: str, detour_time: DetourTime = DetourTime.NONE)#

Call the specified custom callback with the given detour_time.

Parameters:

callback_key – The key which is used to reference the custom callback.
detour_time – Whether to call the before or after detour.

Notes

If there is no callback registered for the key and detour_time combination nothing will happen.

disable(func_name: str)#: Disable the hook for the provided function name.

enable(func_name: str)#: Enable the hook for the provided function name.

initialize_hooks() → int#: Initialize any uninitialized hooks. This will also enable the hooks so that they become active.

register_hook(hook: HookProtocol)#: Register the provided hook.

pymhf.core.hooking.NOOP(detour: HookProtocol) → HookProtocol#: Specify the hook to not run the original function. This decorator must be used with extreme caution as it can cause the hooked program to not run correctly if not used right. The decorated function MUST return something of the same type as the original function if the hooked function normally returns something otherwise the hooked program will almost certainly crash.

pymhf.core.hooking.disable(obj)#: Disable the current function or class.

pymhf.core.hooking.exported(func_name: str, func_def: FUNCDEF, detour_time: str = 'after')#

Hook an exported function.

Parameters:

func_name –
The name of the function which is to be hooked.

Note

It is recommended that the function name is the “mangled” version. Ie. do not “demangle” the function name.
func_def – The function signature.
detour_time – Whether to run the detour before or after the original function.

pymhf.core.hooking.get_caller(func: HookProtocol) → CallerHookProtocol#

Capture the address this hooked function was called from. This address will be acessible by the caller_address() method which will belong to the function that is decorated by this.

Examples

@get_caller
@manual_hook("test_function", 0x12345678, FUNCDEF(restype=ctypes.void, argtypes=[ctypes.c_ulonglong]))
def something(self, *args):
    logger.info(f"'test_function' called with {args} from 0x{self.something.caller_address():X}")

pymhf.core.hooking.imported(dll_name: str, func_name: str, func_def: FUNCDEF, detour_time: str = 'after')#

Hook an imported function in dll_name dll.

Parameters:

dll_name – The name of the dll which contains the function.
func_name – The name of the function in the dll which is to be hooked.
func_def – The function signature.
detour_time – Whether to run the detour before or after the original function.

pymhf.core.hooking.manual_hook(name: str, offset: int | None = None, pattern: str | None = None, func_def: FUNCDEF | None = None, detour_time: str = 'before', binary: str | None = None)#

Manually hook a function.

Parameters:

name – The name of the function to hook. This doesn’t need to be known, but any two manual hooks sharing the same name will be combined together so one should remember to keep the name/offset combination unique.
offset – The offset in bytes relative to the start of the binary. To determine this, you normally subtract off the exe Imagebase value from the address in IDA (or similar program.)
pattern – A pattern which can be used to unqiuely find the function to be hooked within the binary. The pattern must have a format like “01 23 45 67 89 AB CD EF”. The format is what is provided by the IDA plugin SigMakerEx and the ?? values indicate a wildcard.
func_def – The function arguments and return value. This is provided as a pymhf.FUNCDEF object. This argument is only optional if another function with the same offset and name has already been hooked in the same mod.
detour_time – When the detour should run (“before” or “after”)
binary – If provided, this will be the name of the binary which the function being hooked is within. offset and pattern are found relative to/within the memory region of this binary.

pymhf.core.hooking.on_key_pressed(event: str)#

Parameters:: event – The string representing the key which is to trigger the event.

pymhf.core.hooking.on_key_release(event: str)#

Parameters:: event – The string representing the key which is to trigger the event.

pymhf.core.hooking.one_shot(func: HookProtocol) → HookProtocol#: Run this detour once only.