Android Substrate Hooking C Code


This article is to provide a tutorial about Android Substrate native hooking using the latest version v3.0.1 of Android Studio at the time of writing.
Typically, you already have a target Android app to be hooked and what you are trying to do is creating the native hooking module to tamper the code execution of the target app. Android Substrate can help with such kind of work not only on Java layer but also on native C layer. This article will focus on the latter.

Project setup

Host PC: MacOS Sierra 10.12.4

Android Studio: 3.0.1

Android OS: 4.4 and below (Note that Android Substate only works for Dalvik vm)

Android Substrate SDK r2: , extract the substrate.h file and the dynamic library directories.



Create target app

We will use Android Studio project setup panel to create a simple app that has a button to trigger one native method “testPassword” which will just compare the parameter with the real hardcoded password and then try to hook this native method making it always return “equal” result.

Also, we will add one more button trying to trigger the hooking of standard libc method “strncmp()”.

Your target app should be something looks like below screenshot.

Screen Shot 2017-11-30 at 1.12.25 PM

Include Substrate native libs and header file

The two Substrate dependencies and need to be put in correct directory, i.e. under app/src/main/jniLibs for different ABIs. Note that it only support x86 and armeabi. The rest of ABIs came onto stage from Android API 21. But, it looks that Android Substrate is no longer maintained and updated Since 2013.

Add shared libs
Screen Shot 2017-11-30 at 10.01.37 AM
Add header file

Add code to load these shared libs

Open the file and add below code snippet to load the necessary shared native libs.

static {
    // The target .so file to be hooked.
    // The hooking module, note that the .cy is necessary for CydiaSubstrate to recognize it correctly.
    // CydiaSubstrate dependencies.

Modify the onCreate() method to let your buttons link to your methods to be hooked.

protected void onCreate(Bundle savedInstanceState) {
    testPassword.setOnClickListener(new View.OnClickListener() {
        public void onClick(View v) {
            String resultString = testPassword("faked_password") == 0 ? "password success":"password failed";
            Toast.makeText(MainActivity.this, resultString, Toast.LENGTH_LONG).show();
    testStrncmp.setOnClickListener(new View.OnClickListener() {
        public void onClick(View v) {
            String resultString = testStrncmp("apple", "banana", 5) == 0 ? "strncmp success":"strncmp failed";
            Toast.makeText(MainActivity.this, resultString, Toast.LENGTH_LONG).show();

Declare your JNI methods which will invoke the native implementation.

public native int testPassword(String password);
public native int testStrncmp(String s1, String s2, int size);


Modify build.gradle

Configure the native build process as below

android {
    compileSdkVersion 26
    defaultConfig {
        externalNativeBuild {
            cmake {
                cppFlags "-frtti -fexceptions"
                abiFilters 'armeabi', 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
                targets "fooSo", ""
    buildTypes {
    externalNativeBuild {
        cmake {
            path "CMakeLists.txt"


Add the CMakeLists.txt

This file usually is under directory app/ for Android native build. What does this cmake file do are:

  1. Add a “SHARED” library named “fooSo”, whose execution will be hooked.
  2. Add a “SHARED” library named “”, which is the Substrate hooking module, the “.cy” string is necessary for Substrate to recognise it correctly.
cmake_minimum_required(VERSION 3.4.1)

set(MODULE_NAME fooSo)
add_library( ${MODULE_NAME}
             src/main/cpp/hook_example.c )
find_library( log-lib log )
target_link_libraries( ${MODULE_NAME}

add_library( ${HOOK_MODULE}
             src/main/cpp/hook.cpp )
target_link_libraries( ${HOOK_MODULE}

Add the JNI implementation

const int testPassword(const char *myString)
    const char *mySecret = "my_secret_pass";
    int cmpResult = strncmp(myString, mySecret, strlen(mySecret));
    return cmpResult;

Java_com_example_shizzhan_sampleapp_MainActivity_testPassword(JNIEnv *env, jobject instance, jstring myString) {
    const char *password = (*env)->GetStringUTFChars(env, myString, 0);
    int ret = testPassword(password);
    LOGI("In JNI method, password is: %s", password);
    return ret;

Java_com_example_shizzhan_sampleapp_MainActivity_testStrncmp(JNIEnv *env, jobject instance,
                                                             jstring s1_, jstring s2_, jint size) {
    const char *s1 = (*env)->GetStringUTFChars(env, s1_, 0);
    const char *s2 = (*env)->GetStringUTFChars(env, s2_, 0);
    int cmpResult = strncmp(s1, s2, (size_t)size);
    (*env)->ReleaseStringUTFChars(env, s1_, s1);
    (*env)->ReleaseStringUTFChars(env, s2_, s2);
    return cmpResult;

Add the hooking module

I will provide examples for hooking 3 different shared libs.

  1. Hooking user defined .so
  2. Hooking standard
  3. Hooking the Android dalvik vm lib.
#include <jni.h>
#include "substrate.h"
#include <android/log.h>
#include <unistd.h>
#include <stdio.h>
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>


#define LOGD(...) __android_log_print(ANDROID_LOG_DEBUG, TAG, __VA_ARGS__)
#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, TAG, __VA_ARGS__)

MSConfig(MSFilterLibrary, "");
MSConfig(MSFilterLibrary, "");
MSConfig(MSFilterLibrary, "");

void performHook(const char *targetSo, const char *symbol, void *replace, void **original);

bool (*_dvmLoadNativeCode)(char* pathName, void* classLoader, char** detail);
bool fake_dvmLoadNativeCode(char* soPath, void* classLoader, char** detail)
    LOGD("fake_dvmLoadNativeCode soPath:%s", soPath);
    return _dvmLoadNativeCode(soPath,classLoader,detail);

const int (*original_testPassword)(const char *myString);
const int faked_testPassword(const char *myString)
    LOGE("testPassword() is hooked!!!!!!, will always return ZERO !!!!!!");
    return 0;

static int (*original_strncmp)(const char*, const char*, size_t);
int faked_strncmp(const char* a, const char * b, size_t n)
    LOGE("strncmp() is hooked!!!!!!");
    if(strcmp("apple", a) == 0) {
        LOGE("strncmp() is hooked!!!!!!, will always return ZERO is the string is \"apple\" !!!!!!");
        return 0;
    return original_strncmp(a, b, n);

void* find_symbol(const char* libraryname, const char* symbolname)
    void *imagehandle = dlopen(libraryname, RTLD_GLOBAL | RTLD_NOW);
    if (imagehandle != NULL) {
        void * sym = dlsym(imagehandle, symbolname);
        if (sym != NULL) {
            LOGE("symbol (%s) is found at address %p (%p) in lib %s", symbolname, sym, &sym, libraryname);
            return sym;
        } else {
            LOGE("find_symbol() can't find symblo (%s).", symbolname);
            return NULL;
    } else {
        LOGE("dlopen error: %s, when opening lib %s",dlerror(), libraryname);
        return NULL;

// Substrate entry point
    // Example 1: hook user defined .so
    // Hook testPassword
    const char *fooSoPath = "/data/data/com.example.shizzhan.sampleapp/lib/";
    performHook(fooSoPath, "testPassword", (void*)&faked_testPassword, (void**)&original_testPassword);
    // Example 2: hook Hooking libc functions may cause the system hang. So, don't play around libc hookings.
    // Hook strncmp
    performHook("/system/lib/", "strncmp", (void*)&faked_strncmp, (void**)&original_strncmp);
    // Example 3: hook
    // Hook dvmLoadNativeCode
    performHook("/system/lib/", "_Z17dvmLoadNativeCodePKcP6ObjectPPc", (void*)&fake_dvmLoadNativeCode, (void**)&_dvmLoadNativeCode);

void performHook(const char *targetSoPath, const char *symbol, void *replace, void **original) {
    // MSGetImageByName only work when the .so has already been loaded.
    MSImageRef image = MSGetImageByName(targetSoPath);
    void *symAddress;
    if (image != NULL) {
        LOGE("===>>>>>> MSGetImageByName (%s) succeed, symbol address: %p", targetSoPath, image);
        symAddress = MSFindSymbol(image, symbol);
        LOGE("===>>>>>> MSFindSymbol (%s) succeed, symbol address: %p", symbol, symAddress);
        MSHookFunction(symAddress, replace, original);
    } else { // When the .so has not been loaded, need to use below code to find the symbol.
        LOGE("Image not found, trying with find_symbol");
        // The following will work, as it will forcefully load given library.
        symAddress = find_symbol(targetSoPath, symbol);
        if (symAddress != NULL) {
            LOGE("===>>>>>> find_symbol (%s) succeed, symbol address: %p", symbol, symAddress);
            MSHookFunction(symAddress, replace, original);
            LOGE("===>>>>>> find_symbol (%s) succeed, symbol address: %p", symbol, symAddress);
        } else {
            LOGE("===>>>>>> find_symbol failed");

Substrate Permission

Last but not least, add the Substrate permission in AndroidManifest.xml

<uses-permission android:name="cydia.permission.SUBSTRATE" />


To hook the system, you need to know the absolute path on your device. Sometimes, the path of system libs may be different from different kind of devices.

You can use cat command to check the absolute paths of all the loaded components of your app.

adb shell
cat /proc/<pid>/maps

Then you should be able to see something like below, for example, the pid is 4276. Then feed the proper .so path to your hooking module.

root@generic_x86:/ # cat /proc/4276/maps
b4d19000-b4edb000 r-xp 00000000 fd:00 696 /system/lib/
b622f000-b6230000 r — p 00050000 fd:00 651 /system/lib/
b6494000-b6496000 r — p 00056000 fd:00 778 /system/lib/
b6ba8000-b6bf1000 r-xp 00000000 fd:00 738 /system/lib/
b6c95000-b6c97000 r — p 0007a000 fd:00 711 /system/lib/
b6c98000-b6c99000 r — p 00000000 00:00 0
b6c99000-b70df000 r-xp 00000000 fd:00 770 /system/lib/
b742f000-b744b000 r-xp 00000000 fd:00 830 /system/lib/
b76a7000-b76a8000 rw-p 00002000 fd:00 806 /system/lib/
b76a8000-b7741000 r-xp 00000000 fd:00 673 /system/lib/
b7756000-b775c000 r-xp 00000000 fd:00 741 /system/lib/
b7771000-b7772000 rw-p 00012000 fd:00 690 /system/lib/
b7798000-b779a000 r-xp 00000000 fd:00 95 /system/bin/app_process
b779a000-b779b000 r — p 00001000 fd:00 95 /system/bin/app_process
root@generic_x86:/ #

If hooking success, then by clicking on the respective buttons, you should be able to see a Toast message saying “password success” or “strncmp success“.

Source code download

All the source code can be downloaded from my github page at AndroidCydiaHook.


4 thoughts on “Android Substrate Hooking C Code

  1. Hi my friend! I want to say that this post is awesome, great
    written and come with approximately all important infos. I’d like
    to look extra posts like this .


  2. You need to understand the exported symbols and functions of that particular .so from the target application using some reverse engineering tools, e.g. IDA pro. Then apply the hooking approach as demonstrated in this example project. But, for your information that cydia substrate has not updated since Android ART come on to stage meaning this example project is not applicable to later Android versions.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s