From 16e29bd938fe475dfdd5c13aaf6d5109699789b4 Mon Sep 17 00:00:00 2001
From: Clement Rouault <project@hakril.net>
Date: Wed, 16 Aug 2017 18:07:00 +0200
Subject: [PATCH] Added a sample for Debugger.attach

---
 docs/source/sample.rst            | 28 ++++++++++++++++++++++++++++
 docs/source/windef.rst            | 13 -------------
 samples/debug/attach.py           | 30 ++++++++++++++++++++++++++++++
 samples/debug/debug_functionbp.py | 21 ++++++++++-----------
 windows/debug/debugger.py         |  6 +++++-
 5 files changed, 73 insertions(+), 25 deletions(-)
 delete mode 100644 docs/source/windef.rst
 create mode 100644 samples/debug/attach.py

diff --git a/docs/source/sample.rst b/docs/source/sample.rst
index af30441..831825a 100644
--- a/docs/source/sample.rst
+++ b/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
 ~~~~~~~~~~~~~~~~~~
diff --git a/docs/source/windef.rst b/docs/source/windef.rst
deleted file mode 100644
index c910698..0000000
--- a/docs/source/windef.rst
+++ /dev/null
@@ -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
\ No newline at end of file
diff --git a/samples/debug/attach.py b/samples/debug/attach.py
new file mode 100644
index 0000000..d46d206
--- /dev/null
+++ b/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)
diff --git a/samples/debug/debug_functionbp.py b/samples/debug/debug_functionbp.py
index 59b997f..6f53c53 100644
--- a/samples/debug/debug_functionbp.py
+++ b/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()
\ No newline at end of file
+if __name__ == "__main__":
+    calc = windows.test.pop_calc_32(dwCreationFlags=DEBUG_PROCESS)
+    d = windows.debug.Debugger(calc)
+    d.add_bp(FollowNtCreateFile())
+    d.loop()
\ No newline at end of file
diff --git a/windows/debug/debugger.py b/windows/debug/debugger.py
index d994513..aed3b1e 100644
--- a/windows/debug/debugger.py
+++ b/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)