Update all of the docs

zeroSteiner · zeroSteiner · commit f4b9ac21306b · 2018-06-28T15:13:15.000-04:00
diff --git a/README.rst b/README.rst
@@ -12,11 +12,11 @@ components each of which are contained within their respective ``.c`` / ``.h``
 files and are capabile of operating independently.
 
 **ReflectiveTransformer**
-   Functionality to transform PE files between DLL and EXE formats.
+    Functionality to transform PE files between DLL and EXE formats.
 
 **ReflectiveUnloader**
-   Functionality to copy a loaded PE image out of memory and reconstruct a byte
-   for byte copy of the PE image as it would exist on disk.
+    Functionality to copy a loaded PE image out of memory and reconstruct a byte
+    for byte copy of the PE image as it would exist on disk.
 
 License
 -------
diff --git a/ReflectivePolymorphism/ReflectivePolymorphism.c b/ReflectivePolymorphism/ReflectivePolymorphism.c
@@ -35,7 +35,7 @@ BOOL RebaseImage(PDOS_HEADER pDosHeader, ULONG_PTR uiBaseFrom, ULONG_PTR uiBaseT
 	// PDOS_HEADER pDosHeader: Pointer to the DOS header of the blob to patch.
 	// ULONG_PTR uiBaseFrom:   The address to rebase the image from.
 	// ULONG_PTR uiBaseTo:     The address to rebase the image to.
-	// Returns: TRUE on success.
+	// Returns: The function returns TRUE on success.
 	PIMAGE_NT_HEADERS pImgNtHeaders = NULL;
 	PIMAGE_DATA_DIRECTORY pImgDataDirectory = NULL;
 	PIMAGE_BASE_RELOCATION pImgBaseReloc = NULL;
@@ -89,7 +89,8 @@ BOOL ShadowSectionCopy(PDOS_HEADER pDosHeader, BOOL bCopyTo) {
 	// shadow section effectively updates backup content.
 	//
 	// PDOS_HEADER pDosHeader: Pointer to the DOS header of the blob to patch.
-	// Returns: TRUE on success.
+	// BOOL bCopyTo:           Whether to copy to or from the shadow section.
+	// Returns: The function returns TRUE on success.
 	PIMAGE_SECTION_HEADER pImgSecHeaderCopy = NULL;
 	PIMAGE_SECTION_HEADER pImgSecHeaderCursor = NULL;
 	PIMAGE_SECTION_HEADER pImgSecHeader1 = NULL;
@@ -199,9 +200,9 @@ ULONG_PTR PAFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress) {
 	// relation to the DOS header.
 	//
 	// PDOS_HEADER pDosHeader:    A pointer to the associated DOS header.
-	// ULONG_PTR pVirtualAddress: The RVA to convert to a VA.
+	// ULONG_PTR pVirtualAddress: The RVA to convert to a PA.
 	// Returns: The physical address of the specified relative virtual address or
-	//          NULL on failure.
+	//          0 on failure.
 	PIMAGE_SECTION_HEADER pImgSecHeader = NULL;
 
 	pImgSecHeader = SectionHeaderFromRVA(pDosHeader, pVirtualAddress);
@@ -220,7 +221,7 @@ ULONG_PTR VAFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress) {
 	// PDOS_HEADER pDosHeader:    A pointer to the associated DOS header.
 	// ULONG_PTR pVirtualAddress: The RVA to convert to a VA.
 	// Returns: The virtual address of the specified relative virtual address or
-	//          NULL on failure.
+	//          0 on failure.
 	PIMAGE_SECTION_HEADER pImgSecHeader = NULL;
 	ULONG_PTR uiAddress = 0;
 
@@ -231,4 +232,4 @@ ULONG_PTR VAFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress) {
 		uiAddress += pImgSecHeader->PointerToRawData;
 	}
 	return uiAddress;
-}
+}
diff --git a/ReflectivePolymorphism/ReflectiveTransformer.c b/ReflectivePolymorphism/ReflectiveTransformer.c
@@ -18,8 +18,8 @@ BOOL DOSHeaderIsDLL(PDOS_HEADER pDosHeader) {
 	// image is marked as both executable (IMAGE_FILE_EXECUTABLE_IMAGE) and
 	// a DLL (IMAGE_FILE_DLL).
 	//
-	// PDOS_HEADER pDosHeader: A pPointer to the DOS header to analyze
-	// Returns: TRUE if pDosHeader is a DLL
+	// PDOS_HEADER pDosHeader: A pointer to the DOS header to analyze.
+	// Returns: TRUE if pDosHeader is a DLL.
 	PIMAGE_NT_HEADERS pImgNtHeaders = NULL;
 	WORD wCharacteristics = 0;
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,8 +1,3 @@
-.. Reflective Polymorphism documentation master file, created by
-   sphinx-quickstart on Sun Jun 24 00:56:14 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Reflective Polymorphism Documentation
 =====================================
 This project provides various utilities for the self-modification of PE images
@@ -11,11 +6,12 @@ ith the intention that they can be incorporated into external projects.
 The source code is available on the `GitHub homepage`_.
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+    :maxdepth: 2
+    :caption: Contents:
 
-   reflective_transformer.rst
-   reflective_unloader.rst
+    reflective_polymorphism.rst
+    reflective_transformer.rst
+    reflective_unloader.rst
 
 Overview
 --------
@@ -24,11 +20,11 @@ components each of which are contained within their respective ``.c`` / ``.h``
 files and are capabile of operating independently.
 
 **ReflectiveTransformer**
-   Functionality to transform PE files between DLL and EXE formats.
+    Functionality to transform PE files between DLL and EXE formats.
 
 **ReflectiveUnloader**
-   Functionality to copy a loaded PE image out of memory and reconstruct a byte
-   for byte copy of the PE image as it would exist on disk.
+    Functionality to copy a loaded PE image out of memory and reconstruct a byte
+    for byte copy of the PE image as it would exist on disk.
 
 Proof of Concept
 ----------------
@@ -46,14 +42,14 @@ disk. After the message box is closed, the following two new files will be
 created on the user's desktop.
 
 **ReflectivePolymorphism.dll**
-   This is an identical copy of the injected DLL.
+    This is an identical copy of the injected DLL.
 
 **ReflectivePolymorphism.exe**
-   This is an EXE version of the original, injected DLL.
+    This is an EXE version of the original, injected DLL.
 
 The user can then compare the hashes of the two DLL files to determine that they
-are identical. At that point the user can delete the DLLs an run the EXE version
-which will create the DLL version again at the same path.
+are identical. At that point the user can delete the DLLs and run the EXE
+version which will create the DLL version again at the same path.
 
 Indices and tables
 ==================
diff --git a/docs/source/reflective_polymorphism.rst b/docs/source/reflective_polymorphism.rst
@@ -0,0 +1,82 @@
+.. _Reflective Polymorphism:
+
+Reflective Polymorphism
+=======================
+
+The ``ReflectivePolymorphism.c`` and ``ReflectivePolymorphism.h`` contain common
+functionality for use by other components in the project. This reduces the
+amount of code duplication but also requires users of other components to
+include these sources files.
+
+API Reference
+-------------
+
+.. c:function:: DWORD ImageSizeFromHeaders(PDOS_HEADER pDosHeader)
+
+    Calculate the size of of a PE image from the specified DOS headers.
+
+    :param PDOS_HEADER pDosHeader: The headers to use for the calculation.
+    :return: The size of the PE image.
+    :rtype: DWORD
+
+.. c:function:: BOOL RebaseImage(PDOS_HEADER pDosHeader, ULONG_PTR uiBaseFrom, ULONG_PTR uiBaseTo)
+
+    Rebase the specified PE image by processing the relocation data as
+    necessary.
+
+    :param PDOS_HEADER pDosHeader: Pointer to the DOS header of the blob to patch.
+    :param ULONG_PTR uiBaseFrom: The address to rebase the image from.
+    :param ULONG_PTR uiBaseTo: The address to rebase the image to.
+    :return: The function returns ``TRUE`` on success.
+    :rtype: BOOL
+
+.. c:function:: BOOL ShadowSectionCopy(PDOS_HEADER pDosHeader, BOOL bCopyTo)
+
+    Copy data to or from the shadow section. Copying data from the shadow
+    section effectively restores content from the backup. Copying data to the
+    shadow section effectively updates backup content.
+
+    :param PDOS_HEADER pDosHeader: Pointer to the DOS header of the blob to patch.
+    :param BOOL bCopyTo: Whether to copy to or from the shadow section.
+    :return: The function returns ``TRUE`` on success.
+    :rtype: BOOL
+
+.. c:function:: PIMAGE_SECTION_HEADER SectionHeaderFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress)
+
+    Retrieve the section header for the specified Relative Virtual Address
+    (RVA).
+
+    :param PDOS_HEADER pDosHeader: A pointer to the associated DOS header.
+    :param ULONG_PTR pVirtualAddress: The RVA of the section header to retrieve.
+    :return: A pointer to the section header or ``NULL`` if it could not be found.
+    :rtype: PIMAGE_SECTION_HEADER
+
+.. c:function:: PIMAGE_SECTION_HEADER SectionHeaderFromName(PDOS_HEADER pDosHeader, PVOID pName)
+
+    Retrieve the section header for the specified name.
+
+    :param PDOS_HEADER pDosHeader: A pointer to the associated DOS header.
+    :param PVOID pName: A pointer to the section header name to retrieve.
+    :return: A pointer to the section header or ``NULL`` if it could not be found.
+    :rtype: PIMAGE_SECTION_HEADER
+
+.. c:funtion:: ULONG_PTR PAFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress)
+
+    Calculate the Physical Address (VA) from the specified Relative Virtual
+    Address (RVA). The Physical Address is the offset within the PE image in
+    relation to the DOS header.
+
+    :param PDOS_HEADER pDosHeader: A pointer to the associated DOS header.
+    :param ULONG_PTR pVirtualAddress: The RVA to convert to a PA.
+    :return: The physical address of the specified relative virtual address or 0 on failure.
+    :rtype: ULONG_PTR
+
+.. c:funtion:: ULONG_PTR VAFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress)
+
+    Calculate the Virtual Address (VA) from the specified Relative Virtual
+    Address (RVA).
+
+    :param PDOS_HEADER pDosHeader: A pointer to the associated DOS header.
+    :param ULONG_PTR pVirtualAddress: The RVA to convert to a VA.
+    :return: The virtual address of the specified relative virtual address or 0 on failure.
+    :rtype: ULONG_PTR
diff --git a/docs/source/reflective_transformer.rst b/docs/source/reflective_transformer.rst
@@ -24,91 +24,56 @@ Usage
 API Reference
 -------------
 
-DOSHeaderIsDLL
-^^^^^^^^^^^^^^
+.. c:function:: BOOL DOSHeaderIsDLL(PDOS_HEADER pDosHeader)
 
-.. code-block:: c
+    Check the FileHeader Characteristics field to determine whether the PE image
+    is marked as both executable (IMAGE_FILE_EXECUTABLE_IMAGE) and a DLL
+    (IMAGE_FILE_DLL).
 
-    BOOL DOSHeaderIsDLL(
-      _In_  PDOS_HEADER pDosHeader
-    );
+    :param PDOS_HEADER pDosHeader: A pointer to the DOS header to analyze.
+    :return: ``TRUE`` if *pDosHeader* is a DLL.
+    :rtype: BOOL
 
-*pDosHeader* [in]
-   A pointer to the DOS header to check.
+.. c:function:: BOOL DOSHeaderIsEXE(PDOS_HEADER pDosHeader)
 
-**Return value**
-   The function returns ``TRUE`` if pDosHeader appears to be representative of a
-   DLL file.
+    Check the FileHeader Characteristics field to determine whether the PE image
+    is marked as both executable (IMAGE_FILE_EXECUTABLE_IMAGE) and not a DLL
+    (IMAGE_FILE_DLL).
 
-DOSHeaderIsEXE
-^^^^^^^^^^^^^^
+    :param PDOS_HEADER pDosHeader: A pointer to the DOS header to analyze.
+    :return: ``TRUE`` if *pDosHeader* is an EXE.
+    :rtype: BOOL
 
-.. code-block:: c
+.. c:function:: BOOL ReflectiveTransformerToDLL(PDOS_HEADER pDosHeader, DWORD dwAddressOfEntryPoint)
 
-    BOOL DOSHeaderIsEXE(
-      _In_  PDOS_HEADER pDosHeader
-    );
+    Transform the PE image pDosHeader into a DLL. This updates the FileHeader
+    Characteristics field as necessary, updates the OptionalHeader ImageBase to
+    the default value for DLL files and sets a new entry point.
 
-*pDosHeader* [in]
-   A pointer to the DOS header to check.
+    :param PDOS_HEADER pDosHeader: A pointer to the DOS header transform.
+    :param DWORD dwAddressOfEntryPoint: The RVA of the new entry point for the PE image.
+    :return: ``TRUE`` on success.
+    :rtype: BOOL
 
-**Return value**
-   The function returns ``TRUE`` if pDosHeader appears to be representative of
-   an EXE file.
+.. c:function:: BOOL ReflectiveTransformerToEXE(PDOS_HEADER pDosHeader, DWORD dwAddressOfEntryPoint)
 
-RVAFromExportName
-^^^^^^^^^^^^^^^^^
+    Transform the PE image pDosHeader into an EXE. This updates the FileHeader
+    Characteristics field as necessary, updates the OptionalHeader ImageBase to
+    the default value for EXE files and sets a new entry point.
 
-.. code-block:: c
+    :param PDOS_HEADER pDosHeader: A pointer to the DOS header transform.
+    :param DWORD dwAddressOfEntryPoint: The RVA of the new entry point for the PE image.
+    :return: ``TRUE`` on success.
+    :rtype: BOOL
 
-    DWORD RVAFromExportName(
-      _In_ PDOS_HEADER pDosHeader,
-      _In_ LPCSTR      lpProcName
-    );
+.. c:function:: DWORD RVAFromExportName(PDOS_HEADER pDosHeader, LPCSTR lpProcName)
 
-*pDosHeader* [in]
-   A pointer to the DOS header of the PE image to resolve the export from.
+    Get the relative virtual address (RVA) of an exported function by it's name
+    from an unloaded PE image. The return value can then be used as the
+    *dwAddressOfEntryPoint* argument to the ``ReflectiveTransformerTo*`` set of
+    functions.
 
-*lpProcName* [in]
-   A pointer to the name of the exported function to resolve the RVA for.
-
-**Return value**
-   The function returns a non-zero value on success.
-
-ReflectiveTransformerToDLL
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: c
-
-    BOOL ReflectiveTransformerToDLL(
-      _In_ PDOS_HEADER pDosHeader,
-      _In_ DWORD dwAddressOfEntryPoint
-    );
-
-*pDosHeader* [in]
-   A pointer to the DOS header transform.
-
-*dwAddressOfEntryPoint* [in]
-    The RVA of the new entry point for the PE image.
-
-**Return value**
-   The function returns ``TRUE`` on success.
-
-ReflectiveTransformerToEXE
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: c
-
-    BOOL ReflectiveTransformerToEXE(
-      _In_ PDOS_HEADER pDosHeader,
-      _In_ DWORD dwAddressOfEntryPoint
-    );
-
-*pDosHeader* [in]
-   A pointer to the DOS header transform.
-
-*dwAddressOfEntryPoint* [in]
-    The RVA of the new entry point for the PE image.
-
-**Return value**
-   The function returns ``TRUE`` on success.
+    :param PDOS_HEADER pDosHeader: A pointer to the DOS header of the PE image to resolve the export from.
+    :param LPCSTR lpProcName: A pointer to the name of the exported function to resolve the RVA for.
+    :return: The function returns a non-zero value on success.
+    :rtype: DWORD
diff --git a/docs/source/reflective_unloader.rst b/docs/source/reflective_unloader.rst
