Merge branch 'indev'

merge v0.1.2 changes

Makefile

@@ -86,7 +86,6 @@ install:
 	mkdir -p ${MAN_PAGES_INSTALL}
 	cp -R ${MAN_PAGES}/* ${MAN_PAGES_INSTALL}
 	ldconfig
-	mandb
 
 install_docs:
 	mkdir -p ${DOC_INSTALL}

README.md

@@ -67,6 +67,6 @@ The <i>-l</i> option takes the name of the library minus the 'lib' prefix and th
 
 ### GETTING STARTED:
 
-To get started, take a look at <i>docs/markdown/intro.md</i> for quick introduction to commonly used components of Libpwu. Example implementations of payload injection, function hooking, symbol resolution and more can be found in <i>examples</i>.
+To get started, take a look at <i>docs/markdown/intro.md</i> for quick introduction to commonly used components of Libpwu. All libpwu structures can be found in <i>docs/markdown/structs.md</i>. All functions provided by libpwu can be found in <i>docs/markdown/functions.md</i>. Documentation is available in markdown and roff (manpage) formats. The default installation installs only the manpages. To install markdown docs, run <i>make install_docs</i>.
 
-For documentation, see <i>docs</i>. Documentation is available in markdown and roff (manpage) formats. I recommend starting with a read of <i>structs.md</i>. The default installation will install manpages only; to install markdown docs run <i>make install_docs</i>
+Example implementations of payload injection, function hooking, symbol resolution and more can be found in <i>examples</i>.

docs/man.3/libpwu_help.3 → docs/man.3/libpwu_functions.3

@@ -1,5 +1,5 @@
-.IX Title "HELP 3
-.TH HELP 3 "June 2023" "libpwu 1.0" "help"
+.IX Title "FUNCTIONS 3
+.TH FUNCTIONS 3 "June 2023" "libpwu 1.0" "functions"
 .\" Automatically generated by Pandoc 3.1.2
 .\"
 .\" Define V font for inline verbatim, using C font in formats
@@ -117,12 +117,14 @@ write_mem : write process memory
 .IP
 .nf
 \f[C]
-open_lib           : open shared object in own process
-close_lib          : close shared object in own process
+open_lib            : open shared object in own process
+close_lib           : close shared object in own process
 
-get_symbol_addr    : get address of symbol
+get_symbol_addr     : get address of symbol
 
-get_region_by_addr : find which memory region an address resides in
+get_region_by_addr  : find which memory region an address resides in
+get_obj_by_pathname : find memory object that matches a pathname
+get_obj_by_basename : find memory object that matches a basename
 \f[R]
 .fi
 .SS util

docs/man.3/libpwu_get_obj_by_basename.3

@@ -0,0 +1,45 @@
+.IX Title "GET_OBJ_BY_BASENAME 3
+.TH GET_OBJ_BY_BASENAME 3 "June 2023" "libpwu 1.0" "get_obj_by_basename"
+.\" Automatically generated by Pandoc 3.1.2
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.hy
+.SS get_obj_by_basename()
+.IP
+.nf
+\f[C]
+int get_obj_by_basename(char * basename, maps_data * m_data, 
+                        maps_obj ** matched_obj);
+\f[R]
+.fi
+.SS description
+.PP
+\f[V]get_obj_by_basename()\f[R] locates a backing object
+\f[V]matched_obj\f[R] in the provided \f[V]m_data\f[R] structure with a
+matching \f[V]basename\f[R] string.
+Use this function to locate backing objects by name.
+.SS parameters
+.IP \[bu] 2
+\f[V]*basename\f[R] : name of the backing file for the queried region.
+.IP \[bu] 2
+\f[V]*m_data\f[R] : \f[V]maps_data\f[R] structure to search.
+.IP \[bu] 2
+\f[V]**matched_obj\f[R] : pointer to a backing object inside
+\f[V]m_data\f[R].
+.SS return value
+.PP
+\f[V]0\f[R] on success, \f[V]-1\f[R] on no object found, \f[V]-2\f[R] on
+fail.

docs/man.3/libpwu_get_obj_by_pathname.3

@@ -0,0 +1,45 @@
+.IX Title "GET_OBJ_BY_PATHNAME 3
+.TH GET_OBJ_BY_PATHNAME 3 "June 2023" "libpwu 1.0" "get_obj_by_pathname"
+.\" Automatically generated by Pandoc 3.1.2
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.hy
+.SS get_obj_by_pathname()
+.IP
+.nf
+\f[C]
+int get_obj_by_pathname(char * pathname, maps_data * m_data, 
+                        maps_obj ** matched_obj);
+\f[R]
+.fi
+.SS description
+.PP
+\f[V]get_obj_by_pathname()\f[R] locates a backing object
+\f[V]matched_obj\f[R] in the provided \f[V]m_data\f[R] structure with a
+matching \f[V]pathname\f[R] string.
+Use this function to locate backing objects by name.
+.SS parameters
+.IP \[bu] 2
+\f[V]*pathname\f[R] : name of the backing file for the queried region.
+.IP \[bu] 2
+\f[V]*m_data\f[R] : \f[V]maps_data\f[R] structure to search.
+.IP \[bu] 2
+\f[V]**matched_obj\f[R] : pointer to a backing object inside
+\f[V]m_data\f[R].
+.SS return value
+.PP
+\f[V]0\f[R] on success, \f[V]-1\f[R] on no object found, \f[V]-2\f[R] on
+fail.

docs/man.3/libpwu_get_region_by_addr.3

@@ -22,18 +22,16 @@
 .nf
 \f[C]
 int get_region_by_addr(void * addr, maps_entry ** matched_region,
-                       unsigned * int offset, int * obj_index, maps_data * m_data);
+                       unsigned * int offset, maps_data * m_data);
 \f[R]
 .fi
 .SS description
 .PP
 \f[V]get_region_by_addr()\f[R] takes an address and returns the segment
-and offset into the segment at which this address resides in the callee.
-It also takes an optional pointer \f[V]obj_index\f[R], which if not NULL
-contains on return the `index' into the corresponding backing file.
-For example, libc may contain 4 segments.
-If the address is found in the second segment of libc,
-\f[V]obj_index\f[R] will be set to 1 on return.
+and offset into the segment at which this address occurs in
+\f[V]m_data\f[R].
+Acquiring the underlying backing object can be done using
+\f[V](*matched_region)->obj_vector_index\f[R].
 .SS parameters
 .IP \[bu] 2
 \f[V]*addr\f[R] : address to query.
@@ -44,8 +42,6 @@ If the address is found in the second segment of libc,
 \f[V]*offset\f[R] : offset into the \f[V]matched_region\f[R] segment
 where \f[V]addr\f[R] occurs.
 .IP \[bu] 2
-\f[V]*obj_index\f[R] : `index' into the backing file.
-.IP \[bu] 2
 \f[V]*m_data\f[R] : pointer to a \f[V]maps_data\f[R] structure for the
 target process.
 .SS return value

docs/man.3/libpwu_open_memory.3

@@ -28,6 +28,9 @@ int open_memory(pid_t pid, FILE ** fd_maps, int * fd_mem);
 .PP
 \f[V]open_memory()\f[R] opens \f[V]/proc/<pid>/{mem,maps}\f[R] for use
 by other functions.
+\f[V]fd_maps\f[R] or \f[V]fd_mem\f[R] may be NULL, in which case the
+function will not attempt to open the corresponding stream/file
+descriptor.
 .SS parameters
 .IP \[bu] 2
 \f[V]pid\f[R] : PID of the target process.

docs/man.3/libpwu_structs.3

@@ -55,10 +55,12 @@ typedef struct {
 
         //read_maps()
         char pathname[PATH_MAX];
+        char basename[NAME_MAX];
         byte perms;
         void * start_addr;
         void * end_addr;
-
+        unsigned long obj_vector_index;
+
         //get_caves()
         vector cave_vector; //cave
 
@@ -77,15 +79,21 @@ Created automatically.
 \f[V]pathname\f[R] : name of the backing file for this segment.
 refer to \f[V]proc(5)\f[R].
 .IP \[bu] 2
-\f[V]perms\f[R] : permissions for the region in the format taken by
-\f[V]mprotect(2)\f[R].
+\f[V]basename\f[R] : basename of backing file for this segment.
+refer to \f[V]proc(5)\f[R].
+.IP \[bu] 2
+\f[V]perms\f[R] : permissions for the region, see \f[V]mprotect(2)\f[R]
+for format.
 .IP \[bu] 2
 \f[V]start_addr\f[R] : address of the start of this segment in
 \f[V]/proc/<pid>/mem\f[R].
 .IP \[bu] 2
 \f[V]end_addr\f[R] : address of the end of this segment in
 \f[V]/proc\[rs]<pid\[rs]>/mem\f[R].
 .IP \[bu] 2
+\f[V]object_vector_index\f[R] : index into
+\f[V]maps_data.obj_vector\f[R] for this entry.
+.IP \[bu] 2
 \f[V]cave_vector\f[R] : vector of \f[V]cave\f[R] struct.
 .SS functions
 .IP \[bu] 2
@@ -97,7 +105,8 @@ refer to \f[V]proc(5)\f[R].
 \f[C]
 typedef struct {
 
-        char name[PATH_MAX];
+        char pathname[PATH_MAX];
+        char basename[NAME_MAX];
         vector entry_vector; //*maps_entry
 
 } maps_obj;
@@ -112,7 +121,9 @@ See \f[V]proc(5)\f[R].
 Created automatically.
 .SS elements
 .IP \[bu] 2
-\f[V]name\f[R] : name of the backing file.
+\f[V]name\f[R] : name of the backing file for this object.
+.IP \[bu] 2
+\f[V]basename\f[R] : basename of backing file for this object.
 .IP \[bu] 2
 \f[V]entry_vector\f[R] : vector of pointers to \f[V]maps_entry\f[R]
 structures belonging to this backing file.

docs/markdown/help.md → docs/markdown/functions.md

@@ -87,13 +87,14 @@ write_mem : write process memory
 
 ### symbol resolution
 ```
-open_lib           : open shared object in own process
-close_lib          : close shared object in own process
+open_lib            : open shared object in own process
+close_lib           : close shared object in own process
 
-get_symbol_addr    : get address of symbol
-
-get_region_by_addr : find which memory region an address resides in
+get_symbol_addr     : get address of symbol
 
+get_region_by_addr  : find which memory region an address resides in
+get_obj_by_pathname : find memory object that matches a pathname
+get_obj_by_basename : find memory object that matches a basename
 ```
 
 

docs/markdown/get_obj_by_basename.md

@@ -0,0 +1,17 @@
+## get\_obj\_by\_basename()
+
+```c
+int get_obj_by_basename(char * basename, maps_data * m_data, 
+                        maps_obj ** matched_obj);
+```
+
+### description
+`get_obj_by_basename()` locates a backing object `matched_obj` in the provided `m_data` structure with a matching `basename` string. Use this function to locate backing objects by name.
+
+### parameters
+- `*basename`        : name of the backing file for the queried region.
+- `*m_data`          : `maps_data` structure to search.
+- `**matched_obj`    : pointer to a backing object inside `m_data`.
+
+### return value
+`0` on success, `-1` on no object found, `-2` on fail.

docs/markdown/get_obj_by_pathname.md

@@ -0,0 +1,17 @@
+## get\_obj\_by\_pathname()
+
+```c
+int get_obj_by_pathname(char * pathname, maps_data * m_data, 
+                        maps_obj ** matched_obj);
+```
+
+### description
+`get_obj_by_pathname()` locates a backing object `matched_obj` in the provided `m_data` structure with a matching `pathname` string. Use this function to locate backing objects by name.
+
+### parameters
+- `*pathname`        : name of the backing file for the queried region.
+- `*m_data`          : `maps_data` structure to search.
+- `**matched_obj`    : pointer to a backing object inside `m_data`.
+
+### return value
+`0` on success, `-1` on no object found, `-2` on fail.

docs/markdown/get_region_by_addr.md

@@ -2,17 +2,17 @@
 
 ```c
 int get_region_by_addr(void * addr, maps_entry ** matched_region,
-                       unsigned * int offset, int * obj_index, maps_data * m_data);
+                       unsigned * int offset, maps_data * m_data);
 ```
 
 ### description
-`get_region_by_addr()` takes an address and returns the segment and offset into the segment at which this address resides in the callee. It also takes an optional pointer `obj_index`, which if not NULL contains on return the 'index' into the corresponding backing file. For example, libc may contain 4 segments. If the address is found in the second segment of libc, `obj_index` will be set to 1 on return.
+`get_region_by_addr()` takes an address and returns the segment and offset into the segment at which this address occurs in `m_data`. Acquiring the underlying backing object can be done using `(*matched_region)->obj_vector_index`.
+
 
 ### parameters
 - `*addr`            : address to query.
 - `**matched_region` : pointer to a segment pointer in `m_data`, filled by the call.
 - `*offset`          : offset into the `matched_region` segment where `addr` occurs.
-- `*obj_index`       : 'index' into the backing file.
 - `*m_data`          : pointer to a `maps_data` structure for the target process.
 
 ### return value

docs/markdown/open_memory.md

@@ -5,7 +5,9 @@ int open_memory(pid_t pid, FILE ** fd_maps, int * fd_mem);
 ```
 
 ### description
-`open_memory()` opens `/proc/<pid>/{mem,maps}` for use by other functions.
+`open_memory()` opens `/proc/<pid>/{mem,maps}` for use by other functions. `fd_maps`
+or `fd_mem` may be NULL, in which case the function will not attempt to open the 
+corresponding stream/file descriptor.
 
 ### parameters
 - `pid`       : PID of the target process.