Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/8dcc/libsigscan

Single-header C/C++ library for signature scanning on Linux.
https://github.com/8dcc/libsigscan

c c-library cpp game-hacking hacking library signature-scanning sigscan

Last synced: 4 days ago
JSON representation

Single-header C/C++ library for signature scanning on Linux.

Awesome Lists containing this project

README 

        
#+title: libsigscan

#+options: toc:nil

#+startup: showeverything

#+author: 8dcc



#+TOC: headlines 2



*Simple C/C++ library for signature scanning on Linux.*



This library is for matching byte patterns (signatures) in the memory of a

process. It's able to scan the memory of the current process, or an external

process using the =process_vm_readv= function.



It only supports linux, since it parses the =/proc/PID/maps= file to get the start

and end addresses of the loaded modules.



The library asumes all signatures are in [[https://hex-rays.com/ida-pro/][IDA]] (=DE AD ? EF=) or [[https://x64dbg.com/][x64Dbg]]

(=DE AD ?? EF=) format. See also the [[https://github.com/ajkhoury/SigMaker-x64][sigmaker]] plugin.



For more information on signature scanning and on how this library works, check

out my [[https://8dcc.github.io/programming/signature-scanning.html][Signature scanning in C]] blog entry.



* Building the example



To try the example, simply clone the repository, compile it, and run

=libsigscan-test.out=. Please see [[file:src/main.c][src/main.c]] and the /Usage/ section for an example

on how to use it.



#+begin_src console

$ git clone https://github.com/8dcc/libsigscan

$ cd libsigscan

$ make

$ ./libsigscan-test.out

#+end_src



If you want to try the external example, run the following two commands in

separate terminals after compiling.



#+begin_src console

$ ./libsigscan-test-external.out  # Simulates target process, keep it open

$ sudo ./libsigscan-test.out      # Scans the other process, needs root

#+end_src



* Usage

** Including in a project



If you want to use this library, simply copy the detour source and headers to

your project, =#include= the header in your source files and compile the

=libsigscan.c= source with the rest of your code.



For a full example, see [[file:src/main.c][src/main.c]]. For more information on how to compile it,

see the [[file:Makefile][Makefile]].



** Public functions



The library is pretty simple and consists of one main function for signature

scanning, and some wrappers for it. There are also some utilities that may be

used independently. All the functions are documented in [[file:src/libsigscan.h][the header]], but I will

explain them here as well.



*** =sigscan_pidof=



This utility function can be used to get the PID of a process by name.



#+begin_src C

#include "libsigscan.h"



int pid = sigscan_pidof("my-test.out");

#+end_src



*** =sigscan_pid_module=



This is the main function of the library. It scans all the modules loaded by the

process with the specified =pid=, whose name matches the specified =regex=.



It uses POSIX [[https://www.gnu.org/software/sed/manual/html_node/ERE-syntax.html][Extended Regular Expression]] (ERE) syntax, so keep that in mind

before escaping certain characters like =+=, =?=, etc. See also [[https://www.gnu.org/software/sed/manual/html_node/BRE-vs-ERE.html][BRE vs. ERE]].



Also note that it skips modules starting with =[= in =/proc/PID/maps=, like heap,

stack, etc.



#+begin_src C

#include "libsigscan.h"



#define MODULE_REGEX ".+/libc\\.so\\.6"

#define SIGNATURE    "DE AD BE EF ? ? CA FE"



/*

 ,* Search for a signature in the modules loaded by "my-test.out" whose name

 ,* matches the regex.

 ,*/

int pid     = sigscan_pidof("my-test.out");

void* match = sigscan_pid_module(pid, MODULE_REGEX, SIGNATURE);

#+end_src



*** =sigscan_pid=, =sigscan_module= and =sigscan=



These functions are just wrappers for =sigscan_pid_module=.



The =sigscan_pid= function can be used to search for a pattern in *all modules*

loaded by the process with the specified PID. Same as using =NULL= as the second

parameter of =sigscan_pid_module=.



The =sigscan_module= function can be used to search for a pattern in the modules

loaded by *the current process*, whose name matches a regex. Same as using

=SIGSCAN_PID_SELF= as the first parameter of =sigscan_pid_module=.



The =sigscan= function can be used to search for a pattern in *all modules* loaded

by *the current process*. Same as using =SIGSCAN_PID_SELF= and =NULL= as the first and

second parameters of =sigscan_pid_module=.



*** =sigscan_get_module_bounds= and =sigscan_free_module_bounds=



These functions are used internally by the library when calling

=sigscan_pid_module=. They are exposed, so the user can call them whenever

necessary.



The =sigscan_get_module_bounds= function parses the =/proc/PID/maps= file (see

[[https://man.cx/proc(5)][proc(5)]]) to get the start and end addresses of the modules loaded by the process

with the specified PID, whose name matches the specified regex. Similarly to

=sigscan_pid_module=, it accepts =SIGSCAN_PID_SELF= as its first parameter, and =NULL=

as its second parameter.



It returns a linked list of =SigscanModuleBounds= structures, and each element

contains the start and end addresses of a readable memory chunk. The caller is

responsible for freeing this linked list by calling =sigscan_free_module_bounds=.



* Troubleshooting



If you are having any unexpected problems with this library (e.g. it's not able

to find a signature that you know to be there), try compiling the =libsigscan.c=

source with =LIBSIGSCAN_DEBUG= defined. You can easily do this by adding the

following compilation option to your =CFLAGS=.



#+begin_src diff

-CFLAGS=-std=gnu99 -Wall -Wextra -Wpedantic

+CFLAGS=-std=gnu99 -Wall -Wextra -Wpedantic -DLIBSIGSCAN_DEBUG

#+end_src



Now the library will print some useful information to =stderr=. For example:



#+begin_example

my-user-program: Searching in all modules matching regex "^.*module\.o$"...

libsigscan: Couldn't get any module bounds matching regex "^.*module\.o$" in /proc/364195/maps

#+end_example



In that example, you might want to look at the output of =cat /proc/self/maps= and

see if, for example, the =module.o= line ends with =(deleted)=. In that case, you

should remove the =$= from the regex.



If any other unexpected errors occur, please [[https://github.com/8dcc/libsigscan/issues][report them]] with as much

information as possible.