Added a sample for Debugger.attach

docs/source/sample.rst

@@ -404,6 +404,34 @@ Ouput::
 
     Exiting process
 
+.. _sample_debugger_attach:
+
+:func:`Debugger.attach <windows.debug.Debugger.attach>`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ..\..\samples\debug\attach.py
+
+Ouput::
+
+    (cmd λ) python.exe debug\debug\attach.py
+    Finding process with pid <11392>
+    Target is <WinProcess "notepad.exe" pid 11392 at 0x471a750>
+    Debugger attached: <windows.debug.debugger.Debugger object at 0x04707EF0>
+
+    NtCreateFile of <\??\C:\Windows\Fonts\staticcache.dat>: handle = 0x288
+    Handle manually found! typename=<File>, name=<\Device\HarddiskVolume4\Windows\Fonts\StaticCache.dat>
+
+    NtCreateFile of <\??\C:\WINDOWS\Registration\R000000000015.clb>: handle = 0x320
+    Handle manually found! typename=<File>, name=<\Device\HarddiskVolume4\Windows\Registration\R000000000015.clb>
+
+    NtCreateFile of <\??\C:\WINDOWS\Globalization\Sorting\sortdefault.nls>: handle = 0x334
+    Handle manually found! typename=<File>, name=<\Device\HarddiskVolume4\Windows\Globalization\Sorting\SortDefault.nls>
+
+    Exiting process
+
+
+
+
 
 Native code tester
 ~~~~~~~~~~~~~~~~~~

docs/source/windef.rst

@@ -1,13 +0,0 @@
-Test generated !
-****************
-
-List of flags definition in :mod:`windows.generated_def`.
-
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-   :numbered:
-
-   windef_generated.rst
-   ntstatus_generated.rst

samples/debug/attach.py

@@ -0,0 +1,30 @@
+import sys
+import os.path
+import pprint
+sys.path.append(os.path.abspath(__file__ + "\..\.."))
+
+import windows
+import windows.test
+import windows.debug
+
+from windows.generated_def.winstructs import *
+
+# Just a debugger that follow NtCreateFile and print filename & handler
+from debug_functionbp import FollowNtCreateFile
+
+
+def follow_create_file(pid):
+    print("Finding process with pid <{0}>".format(pid))
+    target = [p for p in windows.system.processes if p.pid == pid][0]
+    print("Target is {0}".format(target))
+    dbg = windows.debug.Debugger.attach(target)
+    print("Debugger attached: {0}".format(dbg))
+    print("")
+    dbg.add_bp(FollowNtCreateFile())
+    dbg.loop()
+
+if __name__ == "__main__":
+    # Create a non-debugged process safe to debug
+    calc = windows.test.pop_calc_32(dwCreationFlags=0)
+    # Give ovnly the PID to follow_create_file
+    follow_create_file(calc.pid)

samples/debug/debug_functionbp.py

@@ -9,14 +9,12 @@ import windows.debug
 
 from windows.generated_def.winstructs import *
 
-class MyFunctionBP(windows.debug.FunctionBP):
-    def __init__(self, target, addr=None):
-        super(MyFunctionBP, self).__init__(target, addr)
-        self.target_name = target.target_func
-        self.counter = 3
+class FollowNtCreateFile(windows.debug.FunctionBP):
+    TARGET = windows.winproxy.NtCreateFile
+    COUNTER = 3
 
     def trigger(self, dbg, exc):
-        if not self.counter:
+        if not self.COUNTER:
             print("Exiting process")
             dbg.current_process.exit()
             return
@@ -41,9 +39,10 @@ class MyFunctionBP(windows.debug.FunctionBP):
         fhandle = fhandle[0]
         print("Handle manually found! typename=<{0}>, name=<{1}>".format(fhandle.type, fhandle.name))
         print("")
-        self.counter -= 1
+        self.COUNTER -= 1
 
-calc = windows.test.pop_calc_32(dwCreationFlags=DEBUG_PROCESS)
-d = windows.debug.Debugger(calc)
-d.add_bp(MyFunctionBP(windows.winproxy.NtCreateFile))
-d.loop()
+if __name__ == "__main__":
+    calc = windows.test.pop_calc_32(dwCreationFlags=DEBUG_PROCESS)
+    d = windows.debug.Debugger(calc)
+    d.add_bp(FollowNtCreateFile())
+    d.loop()

windows/debug/debugger.py

@@ -78,7 +78,11 @@ class Debugger(object):
     def attach(cls, target):
         """attach to ``target`` (must be a :class:`WinProcess`)
 
-        :rtype: :class:`Debugger`"""
+        :rtype: :class:`Debugger`
+
+        .. note::
+
+            see :ref:`Debugger.attach sample <sample_debugger_attach>`"""
         winproxy.DebugActiveProcess(target.pid)
         return cls(target)