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

Class EventSift

source code


Event handler that allows you to use customized event handlers for each process you're attached to.

This makes coding the event handlers much easier, because each instance will only "know" about one process. So you can code your event handler as if only one process was being debugged, but your debugger can attach to multiple processes.

Example:

   from winappdbg import Debug, EventHandler, EventSift

   # This class was written assuming only one process is attached.
   # If you used it directly it would break when attaching to another
   # process, or when a child process is spawned.
   class MyEventHandler (EventHandler):

       def create_process(self, event):
           self.first = True
           self.name = event.get_process().get_filename()
           print "Attached to %s" % self.name

       def breakpoint(self, event):
           if self.first:
               self.first = False
               print "First breakpoint reached at %s" % self.name

       def exit_process(self, event):
           print "Detached from %s" % self.name

   # Now when debugging we use the EventSift to be able to work with
   # multiple processes while keeping our code simple. :)
   if __name__ == "__main__":
       handler = EventSift(MyEventHandler)
       #handler = MyEventHandler()  # try uncommenting this line...
       with Debug(handler) as debug:
           debug.execl("calc.exe")
           debug.execl("notepad.exe")
           debug.execl("charmap.exe")
           debug.loop()

Subclasses of EventSift can prevent specific event types from being forwarded by simply defining a method for it. That means your subclass can handle some event types globally while letting other types be handled on per-process basis. To forward events manually you can call self.event(event).

Example:

   class MySift (EventSift):

       # Don't forward this event.
       def debug_control_c(self, event):
           pass

       # Handle this event globally without forwarding it.
       def output_string(self, event):
           print "Debug string: %s" % event.get_debug_string()

       # Handle this event globally and then forward it.
       def create_process(self, event):
           print "New process created, PID: %d" % event.get_pid()
           return self.event(event)

       # All other events will be forwarded.

Note that overriding the event method would cause no events to be forwarded at all. To prevent this, call the superclass implementation.

Example:

   def we_want_to_forward_this_event(event):
       "Use whatever logic you want here..."
       # (...return True or False...)

   class MySift (EventSift):

       def event(self, event):

           # If the event matches some custom criteria...
           if we_want_to_forward_this_event(event):

               # Forward it.
               return super(MySift, self).event(event)

           # Otherwise, don't.
Instance Methods [hide private]
 
__init__(self, cls, *argv, **argd)
Maintains an instance of your event handler for each process being debugged, and forwards the events of each process to each corresponding instance.
source code
 
__call__(self, event)
Dispatch debug events.
source code
 
event(self, event)
Forwards events to the corresponding instance of your event handler for this process.
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 ). (Inherited from winappdbg.event.EventHandler)
Instance Variables [hide private]
list argd
Keyword arguments to pass to the constructor of cls.
list argv
Positional arguments to pass to the constructor of cls.
class cls
Event handler class.
dict forward
Dictionary that maps each debugged process ID to an instance of cls.
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, cls, *argv, **argd)
(Constructor)

source code 

Maintains an instance of your event handler for each process being debugged, and forwards the events of each process to each corresponding instance.

Parameters:
  • cls (class) - Event handler class. This must be the class itself, not an instance! All additional arguments passed to the constructor of the event forwarder will be passed on to the constructor of this class as well.
Overrides: object.__init__

Warning: If you subclass EventSift and reimplement this method, don't forget to call the superclass constructor!

See Also: event

__call__(self, event)
(Call operator)

source code 

Dispatch debug events.

Parameters:
  • event - Event object.
Overrides: EventHandler.__call__
(inherited documentation)

event(self, event)

source code 

Forwards events to the corresponding instance of your event handler for this process.

If you subclass EventSift and reimplement this method, no event will be forwarded at all unless you call the superclass implementation.

If your filtering is based on the event type, there's a much easier way to do it: just implement a handler for it.


Instance Variable Details [hide private]

cls

Event handler class. There will be one instance of this class per debugged process in the forward dictionary.
Type:
class