Skip to content

Commit f4b9ac2

Browse files
zeroSteinerzeroSteiner
committed
Update all of the docs
1 parent 929efe8 commit f4b9ac2

File tree

7 files changed

+156
-134
lines changed

7 files changed

+156
-134
lines changed

‎README.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,11 @@ components each of which are contained within their respective ``.c`` / ``.h``
1212
files and are capabile of operating independently.
1313

1414
**ReflectiveTransformer**
15-
Functionality to transform PE files between DLL and EXE formats.
15+
Functionality to transform PE files between DLL and EXE formats.
1616

1717
**ReflectiveUnloader**
18-
Functionality to copy a loaded PE image out of memory and reconstruct a byte
19-
for byte copy of the PE image as it would exist on disk.
18+
Functionality to copy a loaded PE image out of memory and reconstruct a byte
19+
for byte copy of the PE image as it would exist on disk.
2020

2121
License
2222
-------

‎ReflectivePolymorphism/ReflectivePolymorphism.c

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ BOOL RebaseImage(PDOS_HEADER pDosHeader, ULONG_PTR uiBaseFrom, ULONG_PTR uiBaseT
3535
// PDOS_HEADER pDosHeader: Pointer to the DOS header of the blob to patch.
3636
// ULONG_PTR uiBaseFrom: The address to rebase the image from.
3737
// ULONG_PTR uiBaseTo: The address to rebase the image to.
38-
// Returns: TRUE on success.
38+
// Returns: The function returns TRUE on success.
3939
PIMAGE_NT_HEADERS pImgNtHeaders = NULL;
4040
PIMAGE_DATA_DIRECTORY pImgDataDirectory = NULL;
4141
PIMAGE_BASE_RELOCATION pImgBaseReloc = NULL;
@@ -89,7 +89,8 @@ BOOL ShadowSectionCopy(PDOS_HEADER pDosHeader, BOOL bCopyTo) {
8989
// shadow section effectively updates backup content.
9090
//
9191
// PDOS_HEADER pDosHeader: Pointer to the DOS header of the blob to patch.
92-
// Returns: TRUE on success.
92+
// BOOL bCopyTo: Whether to copy to or from the shadow section.
93+
// Returns: The function returns TRUE on success.
9394
PIMAGE_SECTION_HEADER pImgSecHeaderCopy = NULL;
9495
PIMAGE_SECTION_HEADER pImgSecHeaderCursor = NULL;
9596
PIMAGE_SECTION_HEADER pImgSecHeader1 = NULL;
@@ -199,9 +200,9 @@ ULONG_PTR PAFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress) {
199200
// relation to the DOS header.
200201
//
201202
// PDOS_HEADER pDosHeader: A pointer to the associated DOS header.
202-
// ULONG_PTR pVirtualAddress: The RVA to convert to a VA.
203+
// ULONG_PTR pVirtualAddress: The RVA to convert to a PA.
203204
// Returns: The physical address of the specified relative virtual address or
204-
// NULL on failure.
205+
// 0 on failure.
205206
PIMAGE_SECTION_HEADER pImgSecHeader = NULL;
206207

207208
pImgSecHeader = SectionHeaderFromRVA(pDosHeader, pVirtualAddress);
@@ -220,7 +221,7 @@ ULONG_PTR VAFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress) {
220221
// PDOS_HEADER pDosHeader: A pointer to the associated DOS header.
221222
// ULONG_PTR pVirtualAddress: The RVA to convert to a VA.
222223
// Returns: The virtual address of the specified relative virtual address or
223-
// NULL on failure.
224+
// 0 on failure.
224225
PIMAGE_SECTION_HEADER pImgSecHeader = NULL;
225226
ULONG_PTR uiAddress = 0;
226227

@@ -231,4 +232,4 @@ ULONG_PTR VAFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress) {
231232
uiAddress += pImgSecHeader->PointerToRawData;
232233
}
233234
return uiAddress;
234-
}
235+
}

‎ReflectivePolymorphism/ReflectiveTransformer.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@ BOOL DOSHeaderIsDLL(PDOS_HEADER pDosHeader) {
1818
// image is marked as both executable (IMAGE_FILE_EXECUTABLE_IMAGE) and
1919
// a DLL (IMAGE_FILE_DLL).
2020
//
21-
// PDOS_HEADER pDosHeader: A pPointer to the DOS header to analyze
22-
// Returns: TRUE if pDosHeader is a DLL
21+
// PDOS_HEADER pDosHeader: A pointer to the DOS header to analyze.
22+
// Returns: TRUE if pDosHeader is a DLL.
2323
PIMAGE_NT_HEADERS pImgNtHeaders = NULL;
2424
WORD wCharacteristics = 0;
2525

‎docs/source/index.rst

Lines changed: 12 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,3 @@
1-
.. Reflective Polymorphism documentation master file, created by
2-
sphinx-quickstart on Sun Jun 24 00:56:14 2018.
3-
You can adapt this file completely to your liking, but it should at least
4-
contain the root `toctree` directive.
5-
61
Reflective Polymorphism Documentation
72
=====================================
83
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.
116
The source code is available on the `GitHub homepage`_.
127

138
.. toctree::
14-
:maxdepth: 2
15-
:caption: Contents:
9+
:maxdepth: 2
10+
:caption: Contents:
1611

17-
reflective_transformer.rst
18-
reflective_unloader.rst
12+
reflective_polymorphism.rst
13+
reflective_transformer.rst
14+
reflective_unloader.rst
1915

2016
Overview
2117
--------
@@ -24,11 +20,11 @@ components each of which are contained within their respective ``.c`` / ``.h``
2420
files and are capabile of operating independently.
2521

2622
**ReflectiveTransformer**
27-
Functionality to transform PE files between DLL and EXE formats.
23+
Functionality to transform PE files between DLL and EXE formats.
2824

2925
**ReflectiveUnloader**
30-
Functionality to copy a loaded PE image out of memory and reconstruct a byte
31-
for byte copy of the PE image as it would exist on disk.
26+
Functionality to copy a loaded PE image out of memory and reconstruct a byte
27+
for byte copy of the PE image as it would exist on disk.
3228

3329
Proof of Concept
3430
----------------
@@ -46,14 +42,14 @@ disk. After the message box is closed, the following two new files will be
4642
created on the user's desktop.
4743

4844
**ReflectivePolymorphism.dll**
49-
This is an identical copy of the injected DLL.
45+
This is an identical copy of the injected DLL.
5046

5147
**ReflectivePolymorphism.exe**
52-
This is an EXE version of the original, injected DLL.
48+
This is an EXE version of the original, injected DLL.
5349

5450
The user can then compare the hashes of the two DLL files to determine that they
55-
are identical. At that point the user can delete the DLLs an run the EXE version
56-
which will create the DLL version again at the same path.
51+
are identical. At that point the user can delete the DLLs and run the EXE
52+
version which will create the DLL version again at the same path.
5753

5854
Indices and tables
5955
==================

‎docs/source/reflective_polymorphism.rst

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
.. _Reflective Polymorphism:
2+
3+
Reflective Polymorphism
4+
=======================
5+
6+
The ``ReflectivePolymorphism.c`` and ``ReflectivePolymorphism.h`` contain common
7+
functionality for use by other components in the project. This reduces the
8+
amount of code duplication but also requires users of other components to
9+
include these sources files.
10+
11+
API Reference
12+
-------------
13+
14+
.. c:function:: DWORD ImageSizeFromHeaders(PDOS_HEADER pDosHeader)
15+
16+
Calculate the size of of a PE image from the specified DOS headers.
17+
18+
:param PDOS_HEADER pDosHeader: The headers to use for the calculation.
19+
:return: The size of the PE image.
20+
:rtype: DWORD
21+
22+
.. c:function:: BOOL RebaseImage(PDOS_HEADER pDosHeader, ULONG_PTR uiBaseFrom, ULONG_PTR uiBaseTo)
23+
24+
Rebase the specified PE image by processing the relocation data as
25+
necessary.
26+
27+
:param PDOS_HEADER pDosHeader: Pointer to the DOS header of the blob to patch.
28+
:param ULONG_PTR uiBaseFrom: The address to rebase the image from.
29+
:param ULONG_PTR uiBaseTo: The address to rebase the image to.
30+
:return: The function returns ``TRUE`` on success.
31+
:rtype: BOOL
32+
33+
.. c:function:: BOOL ShadowSectionCopy(PDOS_HEADER pDosHeader, BOOL bCopyTo)
34+
35+
Copy data to or from the shadow section. Copying data from the shadow
36+
section effectively restores content from the backup. Copying data to the
37+
shadow section effectively updates backup content.
38+
39+
:param PDOS_HEADER pDosHeader: Pointer to the DOS header of the blob to patch.
40+
:param BOOL bCopyTo: Whether to copy to or from the shadow section.
41+
:return: The function returns ``TRUE`` on success.
42+
:rtype: BOOL
43+
44+
.. c:function:: PIMAGE_SECTION_HEADER SectionHeaderFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress)
45+
46+
Retrieve the section header for the specified Relative Virtual Address
47+
(RVA).
48+
49+
:param PDOS_HEADER pDosHeader: A pointer to the associated DOS header.
50+
:param ULONG_PTR pVirtualAddress: The RVA of the section header to retrieve.
51+
:return: A pointer to the section header or ``NULL`` if it could not be found.
52+
:rtype: PIMAGE_SECTION_HEADER
53+
54+
.. c:function:: PIMAGE_SECTION_HEADER SectionHeaderFromName(PDOS_HEADER pDosHeader, PVOID pName)
55+
56+
Retrieve the section header for the specified name.
57+
58+
:param PDOS_HEADER pDosHeader: A pointer to the associated DOS header.
59+
:param PVOID pName: A pointer to the section header name to retrieve.
60+
:return: A pointer to the section header or ``NULL`` if it could not be found.
61+
:rtype: PIMAGE_SECTION_HEADER
62+
63+
.. c:funtion:: ULONG_PTR PAFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress)
64+
65+
Calculate the Physical Address (VA) from the specified Relative Virtual
66+
Address (RVA). The Physical Address is the offset within the PE image in
67+
relation to the DOS header.
68+
69+
:param PDOS_HEADER pDosHeader: A pointer to the associated DOS header.
70+
:param ULONG_PTR pVirtualAddress: The RVA to convert to a PA.
71+
:return: The physical address of the specified relative virtual address or 0 on failure.
72+
:rtype: ULONG_PTR
73+
74+
.. c:funtion:: ULONG_PTR VAFromRVA(PDOS_HEADER pDosHeader, ULONG_PTR pVirtualAddress)
75+
76+
Calculate the Virtual Address (VA) from the specified Relative Virtual
77+
Address (RVA).
78+
79+
:param PDOS_HEADER pDosHeader: A pointer to the associated DOS header.
80+
:param ULONG_PTR pVirtualAddress: The RVA to convert to a VA.
81+
:return: The virtual address of the specified relative virtual address or 0 on failure.
82+
:rtype: ULONG_PTR

‎docs/source/reflective_transformer.rst

Lines changed: 39 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -24,91 +24,56 @@ Usage
2424
API Reference
2525
-------------
2626

27-
DOSHeaderIsDLL
28-
^^^^^^^^^^^^^^
27+
.. c:function:: BOOL DOSHeaderIsDLL(PDOS_HEADER pDosHeader)
2928
30-
.. code-block:: c
29+
Check the FileHeader Characteristics field to determine whether the PE image
30+
is marked as both executable (IMAGE_FILE_EXECUTABLE_IMAGE) and a DLL
31+
(IMAGE_FILE_DLL).
3132
32-
BOOL DOSHeaderIsDLL(
33-
_In_ PDOS_HEADER pDosHeader
34-
);
33+
:param PDOS_HEADER pDosHeader: A pointer to the DOS header to analyze.
34+
:return: ``TRUE`` if *pDosHeader* is a DLL.
35+
:rtype: BOOL
3536
36-
*pDosHeader* [in]
37-
A pointer to the DOS header to check.
37+
.. c:function:: BOOL DOSHeaderIsEXE(PDOS_HEADER pDosHeader)
3838
39-
**Return value**
40-
The function returns ``TRUE`` if pDosHeader appears to be representative of a
41-
DLL file.
39+
Check the FileHeader Characteristics field to determine whether the PE image
40+
is marked as both executable (IMAGE_FILE_EXECUTABLE_IMAGE) and not a DLL
41+
(IMAGE_FILE_DLL).
4242
43-
DOSHeaderIsEXE
44-
^^^^^^^^^^^^^^
43+
:param PDOS_HEADER pDosHeader: A pointer to the DOS header to analyze.
44+
:return: ``TRUE`` if *pDosHeader* is an EXE.
45+
:rtype: BOOL
4546
46-
.. code-block:: c
47+
.. c:function:: BOOL ReflectiveTransformerToDLL(PDOS_HEADER pDosHeader, DWORD dwAddressOfEntryPoint)
4748
48-
BOOL DOSHeaderIsEXE(
49-
_In_ PDOS_HEADER pDosHeader
50-
);
49+
Transform the PE image pDosHeader into a DLL. This updates the FileHeader
50+
Characteristics field as necessary, updates the OptionalHeader ImageBase to
51+
the default value for DLL files and sets a new entry point.
5152
52-
*pDosHeader* [in]
53-
A pointer to the DOS header to check.
53+
:param PDOS_HEADER pDosHeader: A pointer to the DOS header transform.
54+
:param DWORD dwAddressOfEntryPoint: The RVA of the new entry point for the PE image.
55+
:return: ``TRUE`` on success.
56+
:rtype: BOOL
5457
55-
**Return value**
56-
The function returns ``TRUE`` if pDosHeader appears to be representative of
57-
an EXE file.
58+
.. c:function:: BOOL ReflectiveTransformerToEXE(PDOS_HEADER pDosHeader, DWORD dwAddressOfEntryPoint)
5859
59-
RVAFromExportName
60-
^^^^^^^^^^^^^^^^^
60+
Transform the PE image pDosHeader into an EXE. This updates the FileHeader
61+
Characteristics field as necessary, updates the OptionalHeader ImageBase to
62+
the default value for EXE files and sets a new entry point.
6163
62-
.. code-block:: c
64+
:param PDOS_HEADER pDosHeader: A pointer to the DOS header transform.
65+
:param DWORD dwAddressOfEntryPoint: The RVA of the new entry point for the PE image.
66+
:return: ``TRUE`` on success.
67+
:rtype: BOOL
6368
64-
DWORD RVAFromExportName(
65-
_In_ PDOS_HEADER pDosHeader,
66-
_In_ LPCSTR lpProcName
67-
);
69+
.. c:function:: DWORD RVAFromExportName(PDOS_HEADER pDosHeader, LPCSTR lpProcName)
6870
69-
*pDosHeader* [in]
70-
A pointer to the DOS header of the PE image to resolve the export from.
71+
Get the relative virtual address (RVA) of an exported function by it's name
72+
from an unloaded PE image. The return value can then be used as the
73+
*dwAddressOfEntryPoint* argument to the ``ReflectiveTransformerTo*`` set of
74+
functions.
7175
72-
*lpProcName* [in]
73-
A pointer to the name of the exported function to resolve the RVA for.
74-
75-
**Return value**
76-
The function returns a non-zero value on success.
77-
78-
ReflectiveTransformerToDLL
79-
^^^^^^^^^^^^^^^^^^^^^^^^^^
80-
81-
.. code-block:: c
82-
83-
BOOL ReflectiveTransformerToDLL(
84-
_In_ PDOS_HEADER pDosHeader,
85-
_In_ DWORD dwAddressOfEntryPoint
86-
);
87-
88-
*pDosHeader* [in]
89-
A pointer to the DOS header transform.
90-
91-
*dwAddressOfEntryPoint* [in]
92-
The RVA of the new entry point for the PE image.
93-
94-
**Return value**
95-
The function returns ``TRUE`` on success.
96-
97-
ReflectiveTransformerToEXE
98-
^^^^^^^^^^^^^^^^^^^^^^^^^^
99-
100-
.. code-block:: c
101-
102-
BOOL ReflectiveTransformerToEXE(
103-
_In_ PDOS_HEADER pDosHeader,
104-
_In_ DWORD dwAddressOfEntryPoint
105-
);
106-
107-
*pDosHeader* [in]
108-
A pointer to the DOS header transform.
109-
110-
*dwAddressOfEntryPoint* [in]
111-
The RVA of the new entry point for the PE image.
112-
113-
**Return value**
114-
The function returns ``TRUE`` on success.
76+
:param PDOS_HEADER pDosHeader: A pointer to the DOS header of the PE image to resolve the export from.
77+
:param LPCSTR lpProcName: A pointer to the name of the exported function to resolve the RVA for.
78+
:return: The function returns a non-zero value on success.
79+
:rtype: DWORD

0 commit comments

Comments
 (0)