From 0b2eabde5cc7690569e01637c6b737a97607d668 Mon Sep 17 00:00:00 2001 From: hakril Date: Mon, 4 Jan 2016 01:26:07 +0100 Subject: [PATCH] Documenting winproxy --- TODO | 5 +- doc/generate_winproxy_list.py | 28 +++ doc/source/index.rst | 1 + doc/source/winproxy.rst | 395 ++++++++++++++++++++++++++++++++++ 4 files changed, 428 insertions(+), 1 deletion(-) create mode 100644 doc/generate_winproxy_list.py create mode 100644 doc/source/winproxy.rst diff --git a/TODO b/TODO index abc7ebf..a256216 100644 --- a/TODO +++ b/TODO @@ -6,4 +6,7 @@ FIXME: - WMI - COM initialisation when injected in another process - The CoInitialize might be already called - - Fix that \ No newline at end of file + - Fix that + + - Add INVALID_HANDLE_VALUE to windef + - change error_check of CreateFile(A|W) \ No newline at end of file diff --git a/doc/generate_winproxy_list.py b/doc/generate_winproxy_list.py new file mode 100644 index 0000000..f985236 --- /dev/null +++ b/doc/generate_winproxy_list.py @@ -0,0 +1,28 @@ +import sys +import os.path +sys.path.append(os.path.dirname(os.path.abspath(__file__)) + "\\..") +print(sys.path[-1]) +import pydoc +import re +import windows + + +winprox = windows.winproxy +all_in_module = [getattr(winprox, x) for x in dir(winprox)] +transp = [f for f in all_in_module if isinstance(f, winprox.TransparentApiProxy)] +functions = [f for f in all_in_module if hasattr(f, "prototype") and f not in transp] + + +print ("Transparent proxies:") +print("") +for f in transp: + print("* {0}".format(f.func_name)) + +print ("Functions:") +print("") +for f in functions: + doc = pydoc.text.document(f) + doc = re.sub("\x08." , "", doc) + print("* {0}::\n\n {1}".format(f.func_name, doc)) + #print("* {0}::\n\n {1}".format(f.func_name, pydoc.plain(pydoc.render_doc(f)))) + diff --git a/doc/source/index.rst b/doc/source/index.rst index b615f39..ef9e425 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,6 +13,7 @@ Contents: :numbered: windows.rst + winproxy.rst utils.rst diff --git a/doc/source/winproxy.rst b/doc/source/winproxy.rst new file mode 100644 index 0000000..21a99d2 --- /dev/null +++ b/doc/source/winproxy.rst @@ -0,0 +1,395 @@ +``windows.winproxy`` -- Windows API +*********************************** + +.. module:: windows.winproxy + +The :mod:`windows.winproxy` module tries to be a pythontic wrapper around windows API of various DLL. +It also hevily relies on :mod:`ctypes`. + +Here are the thing to know about :mod:`windows.winproxy` + * All of this is based on :mod:`windows.generated_def.winfunc` + * DLL is loaded the first time an API of it is called + * All parameters can be passed by ordinal or keyword + * The call with fail if an argument with default value ``NeededParamater`` have be called without another value. + * The call will raise a subclasse of :class:`WindowsError` if it fail. + * Some functions are 'transparent proxy' it means that all parameters are mandatory + +Example: ``VirtualAlloc`` +""""""""""""""""""""""""" + +Exemple with the function `VirtualAlloc` in :mod:`windows.winproxy` + +Documentation: + +.. code-block:: python + + import windows + windows.winproxy.VirtualAlloc + # + + help(windows.winproxy.VirtualAlloc) + # Help on function VirtualAlloc in module windows.winproxy: + # VirtualAlloc(lpAddress=0, dwSize=NeededParameter, flAllocationType=MEM_COMMIT(0x1000L), flProtect=PAGE_EXECUTE_READWRITE(0x40L)) + # Errcheck: + # raise Kernel32Error if result is 0 + + +Calling it + +.. code-block:: python + + import windows + + # Ordinal arguments + windows.winproxy.VirtualAlloc(0, 0x1000) + 34537472 + + # Keyword arguments + windows.winproxy.VirtualAlloc(dwSize=0x1000) + 34603008 + + # NeededParameter must be provided + windows.winproxy.VirtualAlloc() + """ + Traceback (most recent call last): + File "", line 1, in + File "windows\winproxy.py", line 264, in VirtualAlloc + return VirtualAlloc.ctypes_function(lpAddress, dwSize, flAllocationType, flProtect) + File "windows\winproxy.py", line 130, in perform_call + raise TypeError("{0}: Missing Mandatory parameter <{1}>".format(self.func_name, param_name)) + TypeError: VirtualAlloc: Missing Mandatory parameter + """ + + # Error raise exception + windows.winproxy.VirtualAlloc(dwSize=0xffffffff) + """ + Traceback (most recent call last): + File "", line 1, in + File "windows\winproxy.py", line 264, in VirtualAlloc + return VirtualAlloc.ctypes_function(lpAddress, dwSize, flAllocationType, flProtect) + File "windows\winproxy.py", line 133, in perform_call + return self._cprototyped(*args) + File "windows\winproxy.py", line 59, in kernel32_error_check + raise Kernel32Error(func_name) + windows.winproxy.Kernel32Error: VirtualAlloc: [Error 8] Not enough storage is available to process this command. + """ + + +Functions in :mod:`windows.winproxy` +"""""""""""""""""""""""""""""""""""" + +Transparent proxies: + +* AllocConsole +* CloseHandle +* ExitProcess +* ExitThread +* FreeConsole +* GetCurrentProcess +* GetCurrentProcessorNumber +* GetCurrentThread +* GetCurrentThreadId +* GetExitCodeProcess +* GetExitCodeThread +* GetLastError +* GetProcAddress +* GetStdHandle +* GetThreadId +* LoadLibraryA +* LoadLibraryW +* ResumeThread +* SetStdHandle +* SetTcpEntry +* SuspendThread +* TerminateProcess +* TerminateThread +* VirtualQueryEx +* Wow64DisableWow64FsRedirection +* Wow64EnableWow64FsRedirection +* Wow64GetThreadContext +* Wow64RevertWow64FsRedirection + +Functions: + +* AddVectoredContinueHandler:: + + AddVectoredContinueHandler(FirstHandler=1, VectoredHandler=NeededParameter) + Errcheck: + raise Kernel32Error if result is 0 + +* AddVectoredExceptionHandler:: + + AddVectoredExceptionHandler(FirstHandler=1, VectoredHandler=NeededParameter) + Errcheck: + raise Kernel32Error if result is 0 + +* AdjustTokenPrivileges:: + + AdjustTokenPrivileges(TokenHandle, DisableAllPrivileges=False, NewState=NeededParameter, BufferLength=None, PreviousState=None, ReturnLength=None) + Errcheck: + raise Kernel32Error if result is 0 + +* CreateFileA:: + + CreateFileA(lpFileName, dwDesiredAccess=GENERIC_READ(0x80000000L), dwShareMode=0, lpSecurityAttributes=None, dwCreationDisposition=OPEN_EXISTING(0x3L), dwFlagsAndAttributes=FILE_ATTRIBUTE_NORMAL(0x80L), hTemplateFile=None) + Errcheck: + raise Kernel32Error if result is 0 + +* CreateFileW:: + + CreateFileW(lpFileName, dwDesiredAccess=GENERIC_READ(0x80000000L), dwShareMode=0, lpSecurityAttributes=None, dwCreationDisposition=OPEN_EXISTING(0x3L), dwFlagsAndAttributes=FILE_ATTRIBUTE_NORMAL(0x80L), hTemplateFile=None) + Errcheck: + raise Kernel32Error if result is 0 + +* CreateProcessA:: + + CreateProcessA(lpApplicationName, lpCommandLine=None, lpProcessAttributes=None, lpThreadAttributes=None, bInheritHandles=False, dwCreationFlags=0, lpEnvironment=None, lpCurrentDirectory=None, lpStartupInfo=None, lpProcessInformation=None) + Errcheck: + raise Kernel32Error if result is 0 + +* CreateProcessW:: + + CreateProcessW(lpApplicationName, lpCommandLine=None, lpProcessAttributes=None, lpThreadAttributes=None, bInheritHandles=False, dwCreationFlags=0, lpEnvironment=None, lpCurrentDirectory=None, lpStartupInfo=None, lpProcessInformation=None) + Errcheck: + raise Kernel32Error if result is 0 + +* CreateRemoteThread:: + + CreateRemoteThread(hProcess=NeededParameter, lpThreadAttributes=None, dwStackSize=0, lpStartAddress=NeededParameter, lpParameter=NeededParameter, dwCreationFlags=0, lpThreadId=None) + Errcheck: + raise Kernel32Error if result is 0 + +* CreateThread:: + + CreateThread(lpThreadAttributes=None, dwStackSize=0, lpStartAddress=NeededParameter, lpParameter=NeededParameter, dwCreationFlags=0, lpThreadId=None) + Errcheck: + raise Kernel32Error if result is 0 + +* CreateToolhelp32Snapshot:: + + CreateToolhelp32Snapshot(dwFlags, th32ProcessID=0) + Errcheck: + raise Kernel32Error if result is 0 + +* DeviceIoControl:: + + DeviceIoControl(hDevice, dwIoControlCode, lpInBuffer, nInBufferSize=None, lpOutBuffer=NeededParameter, nOutBufferSize=None, lpBytesReturned=None, lpOverlapped=None) + Errcheck: + raise Kernel32Error if result is 0 + +* GetExtendedTcpTable:: + + GetExtendedTcpTable(pTcpTable, pdwSize=None, bOrder=True, ulAf=NeededParameter, TableClass=5, Reserved=0) + Errcheck: + raise IphlpapiError if result is NOT 0 + +* GetThreadContext:: + + GetThreadContext(hThread, lpContext=None) + Errcheck: + raise Kernel32Error if result is 0 + +* GetTokenInformation:: + + GetTokenInformation(TokenHandle=NeededParameter, TokenInformationClass=NeededParameter, TokenInformation=None, TokenInformationLength=0, ReturnLength=None) + Errcheck: + raise Kernel32Error if result is 0 + +* LookupPrivilegeValueA:: + + LookupPrivilegeValueA(lpSystemName=None, lpName=NeededParameter, lpLuid=NeededParameter) + Errcheck: + raise Kernel32Error if result is 0 + +* LookupPrivilegeValueW:: + + LookupPrivilegeValueW(lpSystemName=None, lpName=NeededParameter, lpLuid=NeededParameter) + Errcheck: + raise Kernel32Error if result is 0 + +* NtCreateThreadEx:: + + NtCreateThreadEx(ThreadHandle=None, DesiredAccess=2097151, ObjectAttributes=0, ProcessHandle=NeededParameter, lpStartAddress=NeededParameter, lpParameter=NeededParameter, CreateSuspended=0, dwStackSize=0, Unknown1=0, Unknown2=0, Unknown=0) + +* NtGetContextThread:: + + NtGetContextThread(hThread, lpContext) + +* NtQueryInformationProcess:: + + NtQueryInformationProcess(ProcessHandle, ProcessInformationClass, ProcessInformation, ProcessInformationLength=0, ReturnLength=None) + +* NtQueryInformationThread:: + + NtQueryInformationThread(ThreadHandle, ThreadInformationClass, ThreadInformation, ThreadInformationLength=0, ReturnLength=None) + +* NtQuerySystemInformation:: + + NtQuerySystemInformation(SystemInformationClass, SystemInformation=None, SystemInformationLength=0, ReturnLength=NeededParameter) + +* NtQueryVirtualMemory:: + + NtQueryVirtualMemory(ProcessHandle, BaseAddress, MemoryInformationClass, MemoryInformation=NeededParameter, MemoryInformationLength=0, ReturnLength=None) + +* NtWow64ReadVirtualMemory64:: + + NtWow64ReadVirtualMemory64(hProcess, lpBaseAddress, lpBuffer, nSize, lpNumberOfBytesRead=None) + +* OpenProcess:: + + OpenProcess(dwDesiredAccess=PROCESS_ALL_ACCESS(0x1f0fffL), bInheritHandle=0, dwProcessId=NeededParameter) + Errcheck: + raise Kernel32Error if result is 0 + +* OpenProcessToken:: + + OpenProcessToken(ProcessHandle=None, DesiredAccess=NeededParameter, TokenHandle=NeededParameter) + If ProcessHandle is None: take the current process + Errcheck: + raise Kernel32Error if result is 0 + +* OpenThread:: + + OpenThread(dwDesiredAccess=THREAD_ALL_ACCESS(0x1f03ffL), bInheritHandle=0, dwThreadId=NeededParameter) + Errcheck: + raise Kernel32Error if result is 0 + +* Process32First:: + + Process32First(hSnapshot, lpte) + Set byref(lpte) if needed + Errcheck: + Nothing special + +* Process32Next:: + + Process32Next(hSnapshot, lpte) + Set byref(lpte) if needed + Errcheck: + Nothing special + +* ReadProcessMemory:: + + ReadProcessMemory(hProcess, lpBaseAddress, lpBuffer, nSize, lpNumberOfBytesRead=None) + Errcheck: + raise Kernel32Error if result is 0 + +* RegCloseKey:: + + RegCloseKey(hKey) + Errcheck: + raise Kernel32Error if result is NOT 0 + +* RegGetValueA:: + + RegGetValueA(hkey, lpSubKey, lpValue, dwFlags, pdwType, pvData, pcbData) + Errcheck: + raise Kernel32Error if result is NOT 0 + +* RegGetValueW:: + + RegGetValueW(hkey, lpSubKey, lpValue, dwFlags, pdwType, pvData, pcbData) + Errcheck: + raise Kernel32Error if result is NOT 0 + +* RegOpenKeyExA:: + + RegOpenKeyExA(hKey, lpSubKey, ulOptions, samDesired, phkResult) + Errcheck: + raise Kernel32Error if result is NOT 0 + +* RegOpenKeyExW:: + + RegOpenKeyExW(hKey, lpSubKey, ulOptions, samDesired, phkResult) + Errcheck: + raise Kernel32Error if result is NOT 0 + +* RemoveVectoredExceptionHandler:: + + RemoveVectoredExceptionHandler(Handler) + Errcheck: + raise Kernel32Error if result is 0 + +* SetThreadAffinityMask:: + + SetThreadAffinityMask(hThread=None, dwThreadAffinityMask=NeededParameter) + If hThread is not given, it will be the current thread + Errcheck: + raise Kernel32Error if result is 0 + +* SetThreadContext:: + + SetThreadContext(hThread, lpContext) + Allows to directly pass a CONTEXT and will call with byref(CONTEXT) by itself + Errcheck: + raise Kernel32Error if result is 0 + +* Thread32First:: + + Thread32First(hSnapshot, lpte) + Set byref(lpte) if needed + Errcheck: + Nothing special + +* Thread32Next:: + + Thread32Next(hSnapshot, lpte) + Set byref(lpte) if needed + Errcheck: + Nothing special + +* VirtualAlloc:: + + VirtualAlloc(lpAddress=0, dwSize=NeededParameter, flAllocationType=MEM_COMMIT(0x1000L), flProtect=PAGE_EXECUTE_READWRITE(0x40L)) + Errcheck: + raise Kernel32Error if result is 0 + +* VirtualAllocEx:: + + VirtualAllocEx(hProcess, lpAddress=0, dwSize=NeededParameter, flAllocationType=MEM_COMMIT(0x1000L), flProtect=PAGE_EXECUTE_READWRITE(0x40L)) + Errcheck: + raise Kernel32Error if result is 0 + +* VirtualFree:: + + VirtualFree(lpAddress, dwSize=0, dwFreeType=MEM_RELEASE(0x8000L)) + Errcheck: + raise Kernel32Error if result is 0 + +* VirtualFreeEx:: + + VirtualFreeEx(hProcess, lpAddress, dwSize=0, dwFreeType=MEM_RELEASE(0x8000L)) + Errcheck: + raise Kernel32Error if result is 0 + +* VirtualProtect:: + + VirtualProtect(lpAddress, dwSize, flNewProtect, lpflOldProtect=0) + Errcheck: + raise Kernel32Error if result is 0 + +* WaitForSingleObject:: + + WaitForSingleObject(hHandle, dwMilliseconds=INFINITE(0xffffffffL)) + Errcheck: + raise Kernel32Error if result is NOT 0 + +* WinVerifyTrust:: + + WinVerifyTrust(hwnd, pgActionID, pWVTData) + Errcheck: + Nothing special + +* WriteFile:: + + WriteFile(hFile, lpBuffer, nNumberOfBytesToWrite=None, lpNumberOfBytesWritten=None, lpOverlapped=None) + Errcheck: + raise Kernel32Error if result is 0 + +* WriteProcessMemory:: + + WriteProcessMemory(hProcess, lpBaseAddress, lpBuffer, nSize=None, lpNumberOfBytesWritten=None) + Computer nSize with len(lpBuffer) if not given + Errcheck: + raise Kernel32Error if result is 0 +