Introduction to Zygisk and Advanced Module Development
Magisk, the ubiquitous systemless rooting solution, introduced Zygisk in its v24 release as a powerful evolution of MagiskHide. Zygisk operates by injecting itself into the Zygote process, the parent of all Android application and system processes. This strategic placement allows Zygisk modules to execute code within nearly every process on the device, opening doors for unparalleled system-level modifications, including native function hooking and advanced ART (Android Runtime) method interception.
This article serves as an expert-level guide to developing Zygisk modules, focusing on two core advanced techniques: intercepting native C/C++ functions and hooking Java methods at the ART level. We’ll delve into the necessary tooling, module structure, and provide practical code examples to demonstrate these powerful capabilities.
Prerequisites and Development Environment Setup
Before diving into development, ensure you have the following:
- Basic understanding of C++ and Android’s native layer.
- Familiarity with the Android NDK (Native Development Kit).
- A Linux-based development environment (Ubuntu, WSL, etc.) or macOS.
- ADB (Android Debug Bridge) installed and configured.
- A rooted Android device with Magisk v24+ (Zygisk enabled).
Setting Up Your Project Structure
A typical Zygisk module project structure includes:
my_zygisk_module/├── module.prop├── customize.sh├── zygisk/│ └── zygisk_module.cpp│ └── CMakeLists.txt└── build.sh
module.prop: Contains module metadata (id, name, version, author).customize.sh: An optional shell script executed during module installation.zygisk/: Directory for native C++ source code.zygisk/zygisk_module.cpp: The main source file for your Zygisk module.zygisk/CMakeLists.txt: Build script for the native code using CMake.build.sh: A convenience script to build and package your module.
Example module.prop
id=myzygiskmodule_v1name=My Zygisk Moduleversion=v1versionCode=1author=Your NameDescription=A sample Zygisk module for demonstration.minApi=23# Set to true to enable Zygisk supportzygisk=true
Example customize.sh (Minimal)
#!/system/bin/shui_print "Installing My Zygisk Module..."
Example CMakeLists.txt (zygisk/)
cmake_minimum_required(VERSION 3.16 FATAL_ERROR)project(zygisk_module)add_library(zygisk_module SHARED zygisk_module.cpp)target_compile_features(zygisk_module PRIVATE cxx_std_17)find_package(Zygisk REQUIRED)zygisk_add_module(zygisk_module)
System-Level Hooks: Intercepting Native Functions
Native hooking involves redirecting the execution flow of a function within a dynamically linked library (e.g., `.so` files) to your custom code. This allows you to inspect arguments, modify return values, or completely alter the function’s behavior. For this, we often use hooking frameworks like Dobby or inline assembly.
Introducing Dobby for Native Hooking
Dobby is a powerful, cross-platform hooking library that simplifies inline hooking. You’ll typically integrate Dobby by compiling it into your module or including its source. For brevity, assume Dobby’s headers are available and linked.
Example: Hooking `execve`
Let’s demonstrate by hooking the `execve` system call, which is responsible for executing a program. We’ll log every command executed by processes where our module is active.
zygisk/zygisk_module.cpp (Native Hooking)
#include <jni.h>#include <string>#include <vector>#include <unistd.h>#include <sys/mman.h>#include <dlfcn.h>#include <android/log.h> // For __android_log_print#include "zygisk.hpp" // Zygisk API headers#include "Dobby.h" // Assume Dobby is integratedextern "C" int execve(const char *pathname, char *const argv[], char *const envp[]);typedef int (*execve_t)(const char *pathname, char *const argv[], char *const envp[]);execve_t original_execve = nullptr; // Pointer to the original execve functionint my_execve_hook(const char *pathname, char *const argv[], char *const envp[]) { __android_log_print(ANDROID_LOG_INFO, "ZygiskModule", "execve called: %s", pathname); if (argv) { for (int i = 0; argv[i] != nullptr; ++i) { __android_log_print(ANDROID_LOG_INFO, "ZygiskModule", " Arg %d: %s", i, argv[i]); } } // Call the original function return original_execve(pathname, argv, envp);}class MyZygiskModule : public zygisk::ModuleBase {public: void onLoadResources(zygisk::LoadResourcesParam *param) override { // Not used for this example } void onPreAppSpecialize(zygisk::AppSpecializeParam *param) override { // This method is called just before an app process is specialized // Dobby init should be here or in onPreSystemServerSpecialize for system processes. // Hook execve by searching for its symbol in libc void *execve_addr = DobbySymbolResolver(NULL, "execve"); if (execve_addr) { DobbyHook(execve_addr, (void*)my_execve_hook, (void**)&original_execve); __android_log_print(ANDROID_LOG_INFO, "ZygiskModule", "execve hooked successfully!"); } else { __android_log_print(ANDROID_LOG_ERROR, "ZygiskModule", "Failed to find execve address."); } } void onPostAppSpecialize(const zygisk::AppSpecializeParam *param) override { // Not used for this example }};REGISTER_ZYGISK_MODULE(MyZygiskModule);
In this code, onPreAppSpecialize is crucial. It’s invoked very early in the application process lifecycle, allowing us to establish hooks before much of the application’s native code has run. We use DobbySymbolResolver to find the address of execve in libc.so and then DobbyHook to replace it with our custom function, storing the original address.
ART Method Interception: Hooking Java Methods
ART method interception allows you to modify the behavior of Java methods at runtime. This is significantly more complex than native hooking due to the nature of the Android Runtime, JIT compilation, and class loading mechanisms. A common approach involves manipulating the internal structures of libart.so, specifically the ArtMethod objects that represent Java methods.
Understanding ART Method Structures
Each Java method in ART is represented by an ArtMethod object. This object contains crucial information like the method’s access flags, code entry point, and declaring class. By modifying the code entry point, we can redirect the method call to our own native or Java trampoline.
Developing a full-fledged ART hooking framework from scratch is a monumental task. Libraries like the underlying mechanisms of Xposed or ARTHook simplify this by providing helper functions to find ArtMethod objects and patch their entry points. For a Zygisk module, we’d typically use JNI to resolve a `jmethodID` and then map that to the internal `ArtMethod*` pointer.
Conceptual Example: Hooking `Activity.startActivity`
Let’s conceptually outline how one might hook android.app.Activity.startActivity. This requires deeper interaction with ART internals. A simplified approach involves finding the ArtMethod pointer and then replacing its entry point with a custom native trampoline.
zygisk/zygisk_module.cpp (ART Hooking – Conceptual)
#include <jni.h>#include <string>#include <vector>#include <dlfcn.h>#include <android/log.h> // For __android_log_print#include "zygisk.hpp"extern "C" jobject my_startActivity_hook(JNIEnv *env, jobject instance, jobject intent);class MyZygiskModule : public zygisk::ModuleBase {public: void onPreAppSpecialize(zygisk::AppSpecializeParam *param) override { // When hooking ART methods, it's often more convenient to do it in the app's context // rather than the system server, as app classes are loaded dynamically. // We will perform ART hooking in onPostAppSpecialize after the Java environment is ready. } void onPostAppSpecialize(const zygisk::AppSpecializeParam *param) override { // Get JNIEnv for the current process JNIEnv* env = param->env; if (env == nullptr) { __android_log_print(ANDROID_LOG_ERROR, "ZygiskModule", "JNIEnv is null in onPostAppSpecialize!"); return; } // Find the target class and method jclass activityClass = env->FindClass("android/app/Activity"); if (!activityClass) { __android_log_print(ANDROID_LOG_ERROR, "ZygiskModule", "Failed to find Activity class."); return; } jmethodID startActivityMethod = env->GetMethodID(activityClass, "startActivity", "(Landroid/content/Intent;)V"); if (!startActivityMethod) { __android_log_print(ANDROID_LOG_ERROR, "ZygiskModule", "Failed to find startActivity method."); return; } // --- Conceptual ART Hooking Logic --- // At this point, `startActivityMethod` is a `jmethodID`. // Internally, this `jmethodID` can often be cast to an `ArtMethod*` on various ART versions. // However, direct casting is fragile and not portable across Android versions. // A robust ART hooking library (like a simplified version of SandHook or LSPosed's core) // would handle the complexities: // 1. Resolve the `ArtMethod*` from `jmethodID`. // 2. Backup the original `ArtMethod` data. // 3. Create a trampoline function (often a native stub). // 4. Modify the `ArtMethod`'s entry point (`entry_point_from_quick_compiled_code_`) // to point to your native trampoline. // 5. In your trampoline, you can then call the original method or inject custom logic. // This typically involves managing JNIEnv, arguments, and return types. __android_log_print(ANDROID_LOG_INFO, "ZygiskModule", "startActivity method found. Conceptually hooking..."); // For demonstration purposes, we'll just log its presence. // A real hook would involve: // void* originalMethodPtr = (void*)startActivityMethod; // This is an oversimplification! // DobbyHook(originalMethodPtr, (void*)my_startActivity_native_trampoline, &original_startActivity_native_trampoline); // Where my_startActivity_native_trampoline would be a custom native function // that correctly marshals arguments and calls the original. env->DeleteLocalRef(activityClass); } void onPreSystemServerSpecialize(zygisk::PreSystemServerSpecializeParam *param) override { // This method is called before System Server starts. // Useful for hooking system services at a low level. // If you're hooking something that affects all apps, and is initialized very early, // this is a good place. // Example: If you wanted to hook Binder communication itself. } void onPostSystemServerSpecialize(const zygisk::PostSystemServerSpecializeParam *param) override { // After system server has started. }};REGISTER_ZYGISK_MODULE(MyZygiskModule);
In this example, onPostAppSpecialize is chosen because it runs after the application’s Java environment is fully initialized and classes are loaded. We use JNI’s FindClass and GetMethodID to locate the target Java method. The crucial part, converting jmethodID to an ArtMethod* and performing the actual memory patch, is highly version-dependent and complex. Production-grade modules rely on robust ART hooking libraries that abstract these details, often by analyzing libart.so symbols and structures at runtime.
Building and Deploying Your Module
build.sh (Example)
#!/bin/bashNDK_VERSION="25.2.9519653" # Adjust to your NDK versionANDROID_API=23 # Minimum API level for your moduleexport ANDROID_NDK_HOME=$HOME/Android/Sdk/ndk/$NDK_VERSION# Clean previous buildsrm -rf build lib# Build for arm64-v8a and armeabi-v7a (common ABIs)for ABI in arm64-v8a armeabi-v7a; do mkdir -p build/$ABI cd build/$ABI cmake -DANDROID_ABI=$ABI -DANDROID_PLATFORM=android-$ANDROID_API -DANDROID_NDK=$ANDROID_NDK_HOME $HOME/my_zygisk_module/zygisk cmake --build . cd ../.. mkdir -p "lib/$ABI" cp build/$ABI/libzygisk_module.so "lib/$ABI/zygisk_module.so"done# Create the Magisk module zipcp module.prop .cp customize.sh .zip -r my_zygisk_module.zip module.prop customize.sh lib/zygisk
After building, you’ll get a my_zygisk_module.zip file. Transfer this to your Android device, open Magisk Manager, go to Modules, and install it from storage. Reboot your device to activate the module.
Debugging and Verification
Use adb logcat -s ZygiskModule to monitor the logs generated by your module. For more in-depth debugging, consider using GDB or Frida for attaching to processes and inspecting memory/registers.
Best Practices and Considerations
- Stability: Hooks can introduce instability. Test thoroughly on various Android versions and devices.
- Performance: Keep your hook functions lean. Avoid heavy I/O or complex computations, as they can slow down the hooked process.
- Compatibility: ART internals change between Android versions. Native hooks are generally more stable, but ART hooks often require conditional logic or separate binaries for different Android API levels.
- Error Handling: Always check return values from JNI functions, Dobby calls, and system calls.
- Ethics: Zygisk modules are powerful. Use them responsibly and ethically, respecting user privacy and system integrity. Avoid malicious activities.
Conclusion
Zygisk provides an unparalleled platform for deep system modification on Android. By mastering native function hooking and ART method interception, developers can create powerful modules capable of extending or altering Android’s behavior in ways previously limited to custom ROMs or highly invasive system patches. While these techniques are complex and require a solid understanding of Android’s internal architecture, the potential for innovation and customization is immense. Embrace the challenge, test diligently, and contribute to the vibrant Magisk module ecosystem.