Package winappdbg :: Module event :: Class EventHandler
[hide private]
[frames] | no frames]

Class EventHandler

source code


Base class for debug event handlers.

Your program should subclass it to implement it's own event handling.

The constructor can be overriden as long as you call the superclass constructor. The special method __call__ MUST NOT be overriden.

The signature for event handlers is the following:

   def event_handler(self, event):

Where event is an Event object.

Each event handler is named after the event they handle. This is the list of all valid event handler names:

This is the list of all valid exception handler names (they all receive an ExceptionEvent object):

Instance Methods [hide private]
 
__init__(self)
Class constructor.
source code
 
__get_hooks_for_dll(self, event)
Get the requested API hooks for the current DLL.
source code
 
__hook_dll(self, event)
Hook the requested API calls (in self.apiHooks).
source code
 
__unhook_dll(self, event)
Unhook the requested API calls (in self.apiHooks).
source code
 
__call__(self, event)
Dispatch debug events.
source code

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

Class Variables [hide private]
dict( str → list( tuple( str, int ) ) ) apiHooks = {}
Dictionary that maps module names to lists of tuples of ( procedure name, parameter count ).
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self)
(Constructor)

source code 

Class constructor. Don't forget to call it when subclassing!

Forgetting to call the superclass constructor is a common mistake when you're new to Python. :)

Example:

   class MyEventHandler (EventHandler):

       # Override the constructor to use an extra argument.
       def __init__(self, myArgument):

           # Do something with the argument, like keeping it
           # as an instance variable.
           self.myVariable = myArgument

           # Call the superclass constructor.
           super(MyEventHandler, self).__init__()

       # The rest of your code below...
Overrides: object.__init__

__get_hooks_for_dll(self, event)

source code 

Get the requested API hooks for the current DLL.

Used by __hook_dll and __unhook_dll.

__hook_dll(self, event)

source code 

Hook the requested API calls (in self.apiHooks).

This method is called automatically whenever a DLL is loaded.

__unhook_dll(self, event)

source code 

Unhook the requested API calls (in self.apiHooks).

This method is called automatically whenever a DLL is unloaded.

__call__(self, event)
(Call operator)

source code 

Dispatch debug events.

Parameters:
  • event (Event) - Event object.

Warning: Don't override this method!


Class Variable Details [hide private]

apiHooks

Dictionary that maps module names to lists of tuples of ( procedure name, parameter count ).

All procedures listed here will be hooked for calls from the debugee. When this happens, the corresponding event handler can be notified both when the procedure is entered and when it's left by the debugee.

For example, let's hook the LoadLibraryEx() API call. This would be the declaration of apiHooks:

   from winappdbg import EventHandler
   from winappdbg.win32 import *

   # (...)

   class MyEventHandler (EventHandler):

       apiHook = {

           "kernel32.dll" : (

               #   Procedure name      Signature
               (   "LoadLibraryEx",    (PVOID, HANDLE, DWORD) ),

               # (more procedures can go here...)
           ),

           # (more libraries can go here...)
       }

       # (your method definitions go here...)

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.

Now, to intercept calls to LoadLibraryEx define a method like this in your event handler class:

   def pre_LoadLibraryEx(self, event, ra, lpFilename, hFile, dwFlags):
       szFilename = event.get_process().peek_string(lpFilename)

       # (...)

Note that the first parameter is always the Event object, and the second parameter is the return address. The third parameter and above are the values passed to the hooked function.

Finally, to intercept returns from calls to LoadLibraryEx define a method like this:

   def post_LoadLibraryEx(self, event, retval):
       # (...)

The first parameter is the Event object and the second is the return value from the hooked function.

Type:
dict( str → list( tuple( str, int ) ) )
Value:
{}