From 9db75b022685d6679a4d48e5f443578aa68376cb Mon Sep 17 00:00:00 2001 From: Clement Rouault Date: Fri, 12 Feb 2016 15:06:41 +0100 Subject: [PATCH] Add some doc/sample on LocalDebugger --- doc/source/debug.rst | 21 +++++++++ doc/source/sample.rst | 60 +++++++++++++++++++++++- samples/local_debugger_remote_process.py | 3 +- windows/debug.py | 11 +++++ 4 files changed, 92 insertions(+), 3 deletions(-) diff --git a/doc/source/debug.rst b/doc/source/debug.rst index e9f5910..01d9e07 100644 --- a/doc/source/debug.rst +++ b/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` """"""""""""""""""" diff --git a/doc/source/sample.rst b/doc/source/sample.rst index 8eba591..553a5ea 100644 --- a/doc/source/sample.rst +++ b/doc/source/sample.rst @@ -261,6 +261,9 @@ Output:: Debugging """"""""" +:class:`Debugger` +''''''''''''''''' + .. literalinclude:: ..\..\samples\debugger.py Ouput:: @@ -281,4 +284,59 @@ Ouput:: Loading Loading Loading - Ask to load : exiting process \ No newline at end of file + Ask to load : 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 + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING + I AM LOADING \ No newline at end of file diff --git a/samples/local_debugger_remote_process.py b/samples/local_debugger_remote_process.py index 43d897b..1b735b1 100644 --- a/samples/local_debugger_remote_process.py +++ b/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() \ No newline at end of file diff --git a/windows/debug.py b/windows/debug.py index 3afbc21..b713f3d 100644 --- a/windows/debug.py +++ b/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: