From c2c3fe2dc2f1d396bcd80bb79bbbe92aef4ccbc6 Mon Sep 17 00:00:00 2001
From: hakril <project@hakril.net>
Date: Wed, 27 Apr 2016 00:33:02 +0200
Subject: [PATCH] more doc

---
 TODO                           | 11 +----------
 doc/source/sample.rst          | 17 +++++++++--------
 doc/source/service.rst         | 15 +++++++++++++++
 doc/source/volume.rst          |  4 ++++
 doc/source/windows.rst         |  4 ++++
 samples/system.py              |  1 +
 windows/debug.py               | 21 ++++++++++++---------
 windows/winobject/exception.py | 15 ++++++++++++---
 windows/winobject/process.py   | 14 ++++++++++----
 windows/winobject/service.py   |  2 +-
 windows/wintrust.py            |  2 +-
 11 files changed, 70 insertions(+), 36 deletions(-)
 create mode 100644 doc/source/service.rst

diff --git a/TODO b/TODO
index 64a4352..3afde44 100644
--- a/TODO
+++ b/TODO
@@ -2,9 +2,6 @@ TODO:
     - Documentation
         - Pass 0.2 when doc is done <3
         - type pass to dbg callback
-        - Context.regs
-        - explain what is a DeadThread (do I still need it ?)
-        - Eflags (raw stuff)
 
     - ProcessMemory object ? (metasm like)
 
@@ -20,7 +17,7 @@ TODO:
 
     - Injection
         - code generated by generate_python_exec_shellcode_64[32] may be reused
-            Just need to passe the address of the python string as argument
+            Just need to pass the address of the python string as argument
 
     - rewrite generate_stub_64[32] : it's a non-sens to not save stuff on the stack..
         I can re-copy the args on stack..
@@ -44,8 +41,6 @@ TODO:
     - NtQueryVirtualMemory_32_to_64 (stop using hardcoded value for request type: add it to enum)
 
 
-
-
 CHANGELOG:
     * NEW REGISTRY -> change examples and documentation
     * WinProcess is not a PROCESSENTRY32 anymore (change doc)
@@ -55,10 +50,7 @@ Documentation
     * Debugger
     * LocalDebugger
     * windows.com
-    * windows.wintrust
     * New stuff in exception  ?
-    * system.services
-    * New stuff in WMI ?(think not just change in internal)
     * windows.utils
 
     * verif samples
@@ -66,7 +58,6 @@ Documentation
 FIXME:
     - setup.py build seems to raise an error
     - winutils.create_process : use WinProcess._from_handle
-
     - Push("[ECX]") in simple_x64 as a "H" rex and i think it should not..
 
 RESSOURCE
diff --git a/doc/source/sample.rst b/doc/source/sample.rst
index 288b933..d0a2f4b 100644
--- a/doc/source/sample.rst
+++ b/doc/source/sample.rst
@@ -421,18 +421,19 @@ Make WMI requests
 Ouput::
 
     (cmd λ) python .\samples\wmi_request.py
-    WMI requester is <windows.winobject.wmi.WmiRequester object at 0x02CAA410>
+    WMI requester is <windows.winobject.wmi.WmiRequester object at 0x02B37EF0>
     Selecting * from 'Win32_Process'
-    They are <94> processes
+    They are <92> processes
     Looking for ourself via pid
     Some info about our process:
         * Name -> python.exe
-        * ProcessId -> 7896
+        * ProcessId -> 7968
         * OSName -> Microsoft Windows 8.1 Pro|C:\Windows|\Device\Harddisk0\Partition2
-        * UserModeTime -> 1406250
+        * UserModeTime -> 2812500
         * WindowsVersion -> 6.3.9600
-        * CommandLine -> "C:\Python27\python.exe"  .\wmi_request.py
+        * CommandLine -> python.exe  .\samples\wmi_request.py
     <Select Caption,FileSystem,FreeSpace from Win32_LogicalDisk>:
-        * {'Caption': u'C:', 'FreeSpace': u'14729031680', 'FileSystem': u'NTFS'}
-        * {'Caption': u'D:', 'FreeSpace': u'243872890880', 'FileSystem': u'NTFS'}
-        * {'Caption': u'E:', 'FreeSpace': u'1073852416', 'FileSystem': u'FAT32'}
\ No newline at end of file
+        * {'Caption': u'C:', 'FreeSpace': u'43991547904', 'FileSystem': u'NTFS'}
+        * {'Caption': u'E:', 'FreeSpace': u'82776027136', 'FileSystem': u'NTFS'}
+        * {'Caption': u'F:', 'FreeSpace': u'5711265792', 'FileSystem': u'FAT32'}
+        * {'Caption': u'G:', 'FreeSpace': None, 'FileSystem': None}
\ No newline at end of file
diff --git a/doc/source/service.rst b/doc/source/service.rst
new file mode 100644
index 0000000..6c1d041
--- /dev/null
+++ b/doc/source/service.rst
@@ -0,0 +1,15 @@
+Service
+=======
+
+.. note::
+
+    See sample :ref:`sample_system`
+
+.. module:: windows.winobject.service
+
+.. autoclass:: ServiceStatus
+    :exclude-members: count, index
+
+.. autoclass:: ServiceA
+   :show-inheritance:
+   :inherited-members:
\ No newline at end of file
diff --git a/doc/source/volume.rst b/doc/source/volume.rst
index cda4be7..60d440d 100644
--- a/doc/source/volume.rst
+++ b/doc/source/volume.rst
@@ -1,6 +1,10 @@
 Volume -- The logical drives
 ============================
 
+.. note::
+
+    See sample :ref:`sample_system`
+
 .. module:: windows.winobject.volume
 
 .. autoclass:: LogicalDrive
diff --git a/doc/source/windows.rst b/doc/source/windows.rst
index eee1eb6..d0b658b 100644
--- a/doc/source/windows.rst
+++ b/doc/source/windows.rst
@@ -23,6 +23,10 @@ The submodules that you might use by themself are:
 The ``system`` object
 """""""""""""""""""""
 
+.. note::
+
+    See sample :ref:`sample_system`
+
 .. currentmodule:: windows.winobject
 
 .. autoclass:: windows.winobject.system.System
diff --git a/samples/system.py b/samples/system.py
index 5b0f0eb..7bb7c95 100644
--- a/samples/system.py
+++ b/samples/system.py
@@ -15,6 +15,7 @@ print("")
 print("There is {0} processes".format(len(system.processes)))
 print("There is {0} threads".format(len(system.threads)))
 print("")
+
 print("Dumping first logical drive:")
 drive = system.logicaldrives[0]
 print("    " + str(drive))
diff --git a/windows/debug.py b/windows/debug.py
index 66b8fc4..b5bd1a7 100644
--- a/windows/debug.py
+++ b/windows/debug.py
@@ -426,7 +426,10 @@ class Debugger(object):
 
     # Public callback
     def on_exception(self, exception):
-        """Called on exception event other that known breakpoint
+        """Called on exception event other that known breakpoint. ``exception`` is one of the following type:
+
+                * :class:`windows.winobject.exception.EEXCEPTION_DEBUG_INFO32`
+                * :class:`windows.winobject.exception.EEXCEPTION_DEBUG_INFO64`
 
            The default behaviour is to return ``DBG_CONTINUE`` for the known exception code
            and ``DBG_EXCEPTION_NOT_HANDLED`` else
@@ -436,35 +439,35 @@ class Debugger(object):
         return DBG_CONTINUE
 
     def on_create_process(self, create_process):
-        """Called on create_process event"""
+        """Called on create_process event (see https://msdn.microsoft.com/en-us/library/windows/desktop/ms679286(v=vs.85).aspx)"""
         pass
 
     def on_exit_process(self, exit_process):
-        """Called on exit_process event"""
+        """Called on exit_process event (see https://msdn.microsoft.com/en-us/library/windows/desktop/ms679334(v=vs.85).aspx)"""
         pass
 
     def on_create_thread(self, create_thread):
-        """Called on create_thread event"""
+        """Called on create_thread event (see https://msdn.microsoft.com/en-us/library/windows/desktop/ms679287(v=vs.85).aspx)"""
         pass
 
     def on_exit_thread(self, exit_thread):
-        """Called on exit_thread event"""
+        """Called on exit_thread event (see https://msdn.microsoft.com/en-us/library/windows/desktop/ms679335(v=vs.85).aspx)"""
         pass
 
     def on_load_dll(self, load_dll):
-        """Called on load_dll event"""
+        """Called on load_dll event (see https://msdn.microsoft.com/en-us/library/windows/desktop/ms680351(v=vs.85).aspx)"""
         pass
 
     def on_unload_dll(self, unload_dll):
-        """Called on unload_dll event"""
+        """Called on unload_dll event (see https://msdn.microsoft.com/en-us/library/windows/desktop/ms681403(v=vs.85).aspx)"""
         pass
 
     def on_output_debug_string(self, debug_string):
-        """Called on debug_string event"""
+        """Called on debug_string event (see https://msdn.microsoft.com/en-us/library/windows/desktop/ms680545(v=vs.85).aspx)"""
         pass
 
     def on_rip(self, rip_info):
-        """Called on rip_info event"""
+        """Called on rip_info event (see https://msdn.microsoft.com/en-us/library/windows/desktop/ms680587(v=vs.85).aspx)"""
         pass
 
 def debug(path, args=None, dwCreationFlags=0, show_windows=False):
diff --git a/windows/winobject/exception.py b/windows/winobject/exception.py
index 6e202cd..18dbb94 100644
--- a/windows/winobject/exception.py
+++ b/windows/winobject/exception.py
@@ -145,6 +145,11 @@ class EEflags(ctypes.Structure):
         return "{0}({1}:{2})".format(type(self).__name__, hex(self.raw), self.dump())
 
     raw = property(get_raw, set_raw)
+    """Raw value of the eflags
+
+       :type: :class:`int`
+    """
+
 
 class EDr7(ctypes.Structure):
     "Flag view of the DR7 register"
@@ -180,7 +185,11 @@ class ECONTEXTBase(object):
     pc_reg = ''
     special_reg_type = {}
 
+
     def regs(self, to_dump=None):
+        """Return the name and values of the registers
+
+        :returns: [(reg_name, value)] -- A :class:`list` of :class:`tuple`"""
         res = []
         if to_dump is None:
             to_dump = self.default_dump
@@ -208,7 +217,7 @@ class ECONTEXTBase(object):
 
     @property
     def EEFlags(self):
-        """Enhanced view of the Eflags
+        """Enhanced view of the Eflags (you also have ``EFlags`` for the raw value)
 
             :type: :class:`EEflags`
         """
@@ -219,7 +228,7 @@ class ECONTEXTBase(object):
 
     @property
     def EDr7(self):
-        """Enhanced view of the DR7 register
+        """Enhanced view of the DR7 register (you also have ``Dr7`` for the raw value)
 
             :type: :class:`EDr7`
         """
@@ -286,7 +295,7 @@ class EEXCEPTION_POINTERS(ctypes.Structure):
     ]
 
     def dump(self):
-        """Dump the EEXCEPTION_POINTERS"""
+        """Dump (print) the EEXCEPTION_POINTERS"""
         record = self.ExceptionRecord[0]
         print("Dumping Exception: ")
         print("    ExceptionCode = {0} at {1}".format(record.ExceptionCode, hex(record.ExceptionAddress)))
diff --git a/windows/winobject/process.py b/windows/winobject/process.py
index ace87ad..7b9396a 100644
--- a/windows/winobject/process.py
+++ b/windows/winobject/process.py
@@ -24,6 +24,10 @@ from windows.generated_def import windef
 
 from windows.winobject import exception
 
+
+TimeInfo = namedtuple("TimeInfo", ["creation", "exit", "kernel", "user"])
+"""Time information about a process"""
+
 class AutoHandle(object):
     """An abstract class that allow easy handle creation/destruction/wait"""
      # Big bypass to prevent missing reference at programm close..
@@ -210,7 +214,7 @@ class WinThread(THREADENTRY32, AutoHandle):
             return DeadThread(handle, tid)
 
 class DeadThread(AutoHandle):
-    """An already dead thread"""
+    """An already dead thread (returned only by API returning a new thread if thread die before being returned)"""
     def __init__(self, handle, tid=None):
         if tid is None:
             tid = winproxy.GetThreadId(handle)
@@ -304,6 +308,7 @@ class Process(AutoHandle):
 
     @contextmanager
     def virtual_protected(self, addr, size, protect):
+        """A context manager for local virtual_protect (old Protection are restored at exit)"""
         old_protect = DWORD()
         self.low_virtual_protect(addr, size, protect, old_protect)
         try:
@@ -521,10 +526,11 @@ class Process(AutoHandle):
         """write a qword at ``addr``"""
         return self.write_memory(addr, struct.pack("<Q", qword))
 
-    TimeInfo = namedtuple("TimeInfo", ["creation", "exit", "kernel", "user"])
-
     @property
     def time_info(self):
+        """The time information of the process (creation, kernel/user time, exit time
+
+        :type: :class:`TimeInfo"""
         CreationTime = FILETIME()
         ExitTime = FILETIME()
         KernelTime = FILETIME()
@@ -536,7 +542,7 @@ class Process(AutoHandle):
         kernel = (KernelTime.dwHighDateTime << 32) + KernelTime.dwLowDateTime
         user = (UserTime.dwHighDateTime << 32) + UserTime.dwLowDateTime
 
-        return self.TimeInfo(creation, exit, kernel, user)
+        return TimeInfo(creation, exit, kernel, user)
 
     @utils.fixedpropety
     def token(self):
diff --git a/windows/winobject/service.py b/windows/winobject/service.py
index f54d1f5..def7ad7 100644
--- a/windows/winobject/service.py
+++ b/windows/winobject/service.py
@@ -23,7 +23,7 @@ ServiceStatus = namedtuple("ServiceStatus", ["type", "state", "control_accepted"
     * ``SERVICE_WIN32_SHARE_PROCESS(0x20L)``
     * ``SERVICE_INTERACTIVE_PROCESS(0x100L)``
 
-``state`` might be on of:
+``state`` might be one of:
 
     * ``SERVICE_STOPPED(0x1L)``
     * ``SERVICE_START_PENDING(0x2L)``
diff --git a/windows/wintrust.py b/windows/wintrust.py
index 8b6f483..52117cb 100644
--- a/windows/wintrust.py
+++ b/windows/wintrust.py
@@ -81,7 +81,7 @@ wintrust_return_value_mapper = {x:x for x in wintrust_know_return_value}
 def check_signature(filename):
     """Check if ``filename`` embeds a valid signature.
 
-        :return: ``0`` if ``filename`` have a valid signature else the error
+        :return: :class:`int`: ``0`` if ``filename`` have a valid signature else the error
     """
     file_data = WINTRUST_FILE_INFO()
     file_data.cbStruct = ctypes.sizeof(WINTRUST_FILE_INFO)