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.