Package winappdbg :: Module breakpoint :: Class ApiHook
[hide private]
[frames] | no frames]

Class ApiHook

source code


Used by EventHandler.

This class acts as an action callback for code breakpoints set at the beginning of a function. It automatically retrieves the parameters from the stack, sets a breakpoint at the return address and retrieves the return value from the function call.


See Also: EventHandler.apiHooks

Instance Methods [hide private]
 
__init__(self, eventHandler, modName, procName, paramCount=None, signature=None)
x.__init__(...) initializes x; see help(type(x)) for signature
source code
 
__call__(self, event)
Handles the breakpoint event on entry of the function.
source code
 
hook(self, debug, pid)
Installs the API hook on a given process and module.
source code
 
unhook(self, debug, pid)
Removes the API hook from the given process and module.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Instance Variables [hide private]
str modName
Module name.
str procName
Procedure name.
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, eventHandler, modName, procName, paramCount=None, signature=None)
(Constructor)

source code 

x.__init__(...) initializes x; see help(type(x)) for signature

Parameters:
  • eventHandler (EventHandler) - Event handler instance. This is where the hook callbacks are to be defined (see below).
  • modName (str) - Module name.
  • procName (str) - Procedure name. The pre and post callbacks will be deduced from it.

    For example, if the procedure is "LoadLibraryEx" the callback routines will be "pre_LoadLibraryEx" and "post_LoadLibraryEx".

    The signature for the callbacks should be something like this:

       def pre_LoadLibraryEx(self, event, ra, lpFilename, hFile, dwFlags):
    
           # return address
           ra = params[0]
    
           # function arguments start from here...
           szFilename = event.get_process().peek_string(lpFilename)
    
           # (...)
    
       def post_LoadLibraryEx(self, event, return_value):
    
           # (...)
    

    Note that all pointer types are treated like void pointers, so your callback won't get the string or structure pointed to by it, but the remote memory address instead. This is so to prevent the ctypes library from being "too helpful" and trying to dereference the pointer. To get the actual data being pointed to, use one of the Process.read methods.

  • paramCount (int) - (Optional) Number of parameters for the preCB callback, not counting the return address. Parameters are read from the stack and assumed to be DWORDs in 32 bits and QWORDs in 64.

    This is a faster way to pull stack parameters in 32 bits, but in 64 bits (or with some odd APIs in 32 bits) it won't be useful, since not all arguments to the hooked function will be of the same size.

    For a more reliable and cross-platform way of hooking use the signature argument instead.

  • signature (tuple) - (Optional) Tuple of ctypes data types that constitute the hooked function signature. When the function is called, this will be used to parse the arguments from the stack. Overrides the paramCount argument.
Overrides: object.__init__

__call__(self, event)
(Call operator)

source code 

Handles the breakpoint event on entry of the function.

Parameters:
Raises:
  • WindowsError - An error occured.

hook(self, debug, pid)

source code 

Installs the API hook on a given process and module.

Parameters:
  • debug (Debug) - Debug object.
  • pid (int) - Process ID.

Warning: Do not call from an API hook callback.

unhook(self, debug, pid)

source code 

Removes the API hook from the given process and module.

Parameters:
  • debug (Debug) - Debug object.
  • pid (int) - Process ID.

Warning: Do not call from an API hook callback.


Instance Variable Details [hide private]

modName

Module name.
Get Method:
unreachable.modName(self)

procName

Procedure name.
Get Method:
unreachable.procName(self)