Add some doc/sample on LocalDebugger

doc/source/debug.rst

@@ -20,6 +20,27 @@ The :class:`Debugger` have some functions called on given event that can be impl
 
 
 
+:class:`LocalDebugger`
+""""""""""""""""""""""
+
+.. note::
+
+    See sample :ref:`sample_local_debugger`
+
+The :class:`Debugger` is the base class to perform the debugging the current process.
+It is based on :func:`VectoredException` (see :ref:`sample_vectoredexception`)
+
+There is not much documentation for now as the code might change soon.
+
+
+
+.. autoclass:: LocalDebugger
+    :members:
+
+
+
+
+
 :class:`Breakpoint`
 """""""""""""""""""
 

doc/source/sample.rst

@@ -261,6 +261,9 @@ Output::
 Debugging
 """""""""
 
+:class:`Debugger`
+'''''''''''''''''
+
 .. literalinclude:: ..\..\samples\debugger.py
 
 Ouput::
@@ -281,4 +284,59 @@ Ouput::
     Loading <C:\Windows\system32\shell32.dll>
     Loading <C:\Windows\SYSTEM32\WINMM.dll>
     Loading <C:\Windows\system32\ole32.dll>
-    Ask to load <ole32.dll>: exiting process
+    Ask to load <ole32.dll>: exiting process
+
+
+.. _sample_local_debugger:
+
+:class:`LocalDebugger`
+''''''''''''''''''''''
+
+In current process
+^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ..\..\samples\local_debugger.py
+
+Ouput::
+
+    (cmd λ) python.exe .\samples\local_debugger.py
+    Your main thread is 3864
+    Code addr = 0x46000b
+    GOT AN HXBP <3 at 0x46000b
+    EXCEPTION !!!! Got a EXCEPTION_SINGLE_STEP(0x80000004L) at 0x46000c
+    EXCEPTION !!!! Got a EXCEPTION_SINGLE_STEP(0x80000004L) at 0x46000d
+    EXCEPTION !!!! Got a EXCEPTION_SINGLE_STEP(0x80000004L) at 0x46000e
+    EXCEPTION !!!! Got a EXCEPTION_SINGLE_STEP(0x80000004L) at 0x46000f
+    EXCEPTION !!!! Got a EXCEPTION_SINGLE_STEP(0x80000004L) at 0x460010
+    EXCEPTION !!!! Got a EXCEPTION_SINGLE_STEP(0x80000004L) at 0x460011
+
+
+In remote process
+^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ..\..\samples\local_debugger_remote_process.py
+
+Ouput::
+
+    (cmd λ) python.exe .\samples\local_debugger_remote_process.py
+    (In another console)
+    I AM LOADING <C:\Windows\system32\uxtheme.dll>
+    I AM LOADING <C:\Windows\system32\uxtheme.dll>
+    I AM LOADING <C:\Windows\system32\uxtheme.dll>
+    I AM LOADING <C:\Windows\system32\uxtheme.dll>
+    I AM LOADING <kernel32.dll>
+    I AM LOADING <C:\Windows\WinSxS\x86_microsoft.windows.gdiplus_6595b64144ccf1df_1.1.9600.17415_none_dad8722c5bcc2d8f\gdiplus.dll>
+    I AM LOADING <comctl32.dll>
+    I AM LOADING <comctl32.dll>
+    I AM LOADING <comctl32.dll>
+    I AM LOADING <comctl32.dll>
+    I AM LOADING <comctl32.dll>
+    I AM LOADING <comctl32>
+    I AM LOADING <C:\Windows\SysWOW64\oleacc.dll>
+    I AM LOADING <OLEAUT32.DLL>
+    I AM LOADING <C:\Windows\system32\ole32.dll>
+    I AM LOADING <C:\Windows\system32\MSCTF.dll>
+    I AM LOADING <C:\Windows\SysWOW64\msxml6.dll>
+    I AM LOADING <C:\Windows\system32\shell32.dll>
+    I AM LOADING <C:\Windows\SYSTEM32\WINMM.dll>
+    I AM LOADING <C:\Windows\system32\ole32.dll>

samples/local_debugger_remote_process.py

@@ -27,7 +27,6 @@ exp = windows.current_process.peb.modules[1].pe.exports
 #windows.utils.FixedInteractiveConsole(locals()).interact()
 ldr = exp["LdrLoadDll"]
 d.add_bp(YOLOHXBP(ldr))
-print("By from {0}".format(windows.current_thread.tid))
 
 """
 
@@ -37,4 +36,4 @@ c.threads[0].resume()
 
 import time
 time.sleep(2)
-c.exit()
+c.exit()

windows/debug.py

@@ -501,6 +501,7 @@ from windows.exception import VectoredException
 import ctypes
 
 class LocalDebugger(object):
+    """A debugger interface around :func:`AddVectoredExceptionHandler`"""
     def __init__(self):
         self.breakpoints = {}
         self._memory_save = {}
@@ -516,12 +517,15 @@ class LocalDebugger(object):
         self.code = windows.native_exec.create_function("\xcc\xc3", [PVOID])
 
     def get_exception_code(self):
+        """Return ExceptionCode of current exception"""
         return self.current_exception[0].ExceptionRecord[0].ExceptionCode
 
     def get_exception_context(self):
+        """Return context of current exception"""
         return self.current_exception[0].ContextRecord[0]
 
     def single_step(self):
+        """Make the current thread to single step"""
         self.get_exception_context().EEFlags.TF = 1
         return windef.EXCEPTION_CONTINUE_EXECUTION
 
@@ -559,11 +563,18 @@ class LocalDebugger(object):
         return EXCEPTION_CONTINUE_EXECUTION
 
     def on_exception(self, exc):
+        """Called on exception"""
         if not self.get_exception_code() in windows.exception.exception_name_by_value:
             return windef.EXCEPTION_CONTINUE_SEARCH
         return windef.EXCEPTION_CONTINUE_EXECUTION
 
     def add_bp(self, bp, targets=None):
+        """Add a breakpoint, bp is a "class:`Breakpoint`
+
+            If the ``bp`` type is ``STANDARD_BP``, target must be None.
+
+            If the ``bp`` type is ``HARDWARE_EXEC_BP``, target can be None (all threads), or some threads of the process
+        """
         if bp.type == HARDWARE_EXEC_BP:
             return self.add_bp_hxbp(bp, targets)
         if bp.type != STANDARD_BP: