Introduction to Magisk Modules and Systemless Root

Magisk has revolutionized Android root access by offering a “systemless” approach, meaning it modifies the boot image without altering the system partition itself. This allows users to retain Widevine L1 certification, pass SafetyNet, and receive OTA updates while still enjoying the full benefits of root. For developers and security enthusiasts, Magisk’s true power lies in its module framework. Magisk modules are ZIP files that can inject or modify system components, binaries, libraries, and configuration files, all without touching the actual system partition. This makes them an ideal tool for experimenting with root exploits, system tweaks, and custom functionalities in a safe, reversible manner.

This guide will walk you through the essential steps to create your very first Magisk module. We’ll focus on understanding the core components and building a practical example to illustrate how you can leverage this powerful framework for system-level modifications.

Understanding the Magisk Module Architecture

A Magisk module is essentially a specialized ZIP archive containing a specific directory structure and script files that Magisk understands. When installed, Magisk unpacks these files into a systemless overlay, applying your desired changes at boot time.

Core Components of a Magisk Module:

• META-INF/com/google/android/updater-script: Standard Android update script.
• META-INF/com/magisk/module.prop: Module metadata (name, ID, version, author).
• customize.sh: The primary shell script executed during module installation. This is where most of your logic for file copying, permission setting, and system modifications resides.
• common/: Directory for common scripts.
• system/: This directory mimics the root filesystem structure. Any files placed here will be overlaid onto the actual system at boot. For example, a file at system/bin/my_tool will appear as /system/bin/my_tool to processes once the module is active.

Setting Up Your Development Environment

Before diving into module creation, ensure you have the following tools:

• Android Device with Magisk Installed: Essential for testing.
• ADB (Android Debug Bridge): For pushing/pulling files and shell access.
• Text Editor: Visual Studio Code, Notepad++, Sublime Text, or any other code editor.
• Basic Linux/Shell Scripting Knowledge: Crucial for writing customize.sh.
• Magisk Module Template: Start with an existing template for the correct structure. You can often find one in the official Magisk documentation or a reputable GitHub repository.

Download a clean Magisk Module Template (e.g., from Magisk’s GitHub or a trusted source like osm0sis’s template) and extract it. This will provide the necessary base structure.

Dissecting Core Module Files

1. module.prop

This file defines your module’s identity. It’s a simple text file with key-value pairs.

id=myfirstmodule
name=My First Magisk Module
version=v1.0
versionCode=1
author=YourName
description=A simple demo module for system property modification.

• id: A unique identifier for your module (no spaces).
• name: User-friendly name displayed in Magisk Manager.
• version: Human-readable version.
• versionCode: Integer version code (must increment for updates).
• author: Your name or handle.
• description: Brief explanation of what the module does.

2. customize.sh

This is the heart of your module, a shell script executed by Magisk during installation. It’s responsible for copying files, setting permissions, running commands, and making system modifications. Magisk provides several utility functions within this script, such as `ui_print` for displaying messages and helper functions for paths.

A typical customize.sh will perform these actions:

• Define paths for the module’s installation directory.
• Check device compatibility (optional).
• Copy files from the module’s `system/` directory to the target `MODPATH/system/` (which Magisk then overlays).
• Set appropriate permissions for copied files.
• Execute any other necessary commands.

Here’s a simplified structure:

SKIPUNZIP=1

ui_print "- Initializing My First Magisk Module..."

# Helper function for printing
print_status() {
  ui_print "- $1"
}

# Main installation logic
install_module() {
  print_status "Copying example script..."
  # Copy our custom script from module's 'system/bin' to Magisk's module path
  # Magisk will then overlay MODPATH/system/bin onto /system/bin
  cp -f $MODPATH/system/bin/my_custom_exploit.sh $MODPATH/system/bin/my_custom_exploit.sh.tmp
  
  # Set executable permissions
  chmod 755 $MODPATH/system/bin/my_custom_exploit.sh.tmp
  mv -f $MODPATH/system/bin/my_custom_exploit.sh.tmp $MODPATH/system/bin/my_custom_exploit.sh

  print_status "Setting a custom system property..."
  # Example of setting a system property via a boot script (service.sh)
  echo "setprop persist.sys.my_custom_prop "HelloMagisk"" >> $MODPATH/common/service.sh

  print_status "Module installed successfully!"
}

install_module

Note SKIPUNZIP=1. This tells Magisk that you will handle file copying yourself, which is generally preferred for custom modules to avoid unnecessary extraction of the entire `system/` directory by Magisk’s default unzipping, giving you more control.

3. common/post-fs-data.sh and common/service.sh

• post-fs-data.sh: Executed very early in the boot process, after `/data` is mounted but before Zygote starts. Ideal for modifying files that need to be present early or for setting up paths/permissions that other scripts will rely on.
• service.sh: Executed later, typically after Zygote has started and most system services are up. Useful for running background services, setting system properties, or executing commands that rely on a fully booted system.

For our simple example, we appended to `service.sh` in `customize.sh` to set a system property.

Crafting a Simple Exploit Module: Injecting a Custom System Binary

Let’s create a module that injects a custom shell script into `/system/bin` and sets a custom system property. This illustrates how you can introduce new binaries or modify system behavior.

Step-by-Step Implementation:

1. Prepare the Module Directory

Start with your extracted template. Your directory structure should look something like this:

myfirstmodule/
├── META-INF/
│   └── com/
│       └── google/
│           └── android/
│               └── updater-script
│       └── magisk/
│           └── module.prop
├── common/
│   └── post-fs-data.sh
│   └── service.sh
├── customize.sh
└── system/
    └── bin/

2. Edit module.prop

Open `myfirstmodule/META-INF/com/magisk/module.prop` and populate it:

id=myexploitscript
name=Custom Exploit Script Injector
version=v1.0
versionCode=1
author=YourName
description=Injects a custom script and sets a system property.

3. Create Your Custom Script

Inside `myfirstmodule/system/bin/`, create a file named `my_custom_exploit.sh`. This script will be injected into `/system/bin` on the device.

#!/system/bin/sh

echo "Hello from my custom Magisk injected script!"

# Example: Log device info to a file
log_file="/data/local/tmp/my_exploit_log.txt"

echo "--- Device Info ---" > $log_file
getprop ro.product.model >> $log_file
getprop ro.build.version.release >> $log_file

echo "--- System Properties ---" >> $log_file
getprop persist.sys.my_custom_prop >> $log_file

echo "Script execution complete at $(date)" >> $log_file

# For demonstration, you might want to execute something privileged here
# e.g., su -c "dmesg > /data/local/tmp/kernel_log.txt"
# For a true 'exploit', this might be a setuid binary, a privilege escalation
# payload, or a backdoor mechanism. For safety, we keep it simple here.

exit 0

4. Modify customize.sh

Open `myfirstmodule/customize.sh` and use the example content provided earlier. Ensure the `cp` and `chmod` commands correctly reference `my_custom_exploit.sh` and the appending to `service.sh` for the system property.

SKIPUNZIP=1

ui_print "- Initializing Custom Exploit Script Injector..."

print_status() {
  ui_print "- $1"
}

install_module() {
  print_status "Copying custom exploit script..."
  mkdir -p $MODPATH/system/bin
  cp -f $MODPATH_TEMP/system/bin/my_custom_exploit.sh $MODPATH/system/bin/my_custom_exploit.sh
  
  print_status "Setting executable permissions..."
  chmod 755 $MODPATH/system/bin/my_custom_exploit.sh

  print_status "Setting a custom system property via service.sh..."
  # This line will be added to common/service.sh, making it run at boot
  echo "setprop persist.sys.my_custom_prop "HelloMagiskFromExploit"" >> $MODPATH/common/service.sh
  # We also add a call to our script here to ensure it runs at boot
  echo "/system/bin/my_custom_exploit.sh &" >> $MODPATH/common/service.sh

  print_status "Module installation complete!"
}

install_module

5. Package the Module

Navigate to the parent directory of `myfirstmodule/` in your terminal. Select all contents of the `myfirstmodule` folder (META-INF, common, customize.sh, system) and compress them into a ZIP file. Name it `my_exploit_module.zip` (or similar). Crucially, the ZIP must contain these directories/files directly at its root, not an enclosing folder.

cd path/to/myfirstmodule/parent
zip -r my_exploit_module.zip myfirstmodule/*

6. Install and Verify

1. Push to Device: Use ADB to push the ZIP file to your Android device:

   adb push my_exploit_module.zip /sdcard/Download/

2. Install with Magisk Manager: Open Magisk Manager on your device. Go to the “Modules” section, tap “Install from storage,” and select `my_exploit_module.zip`.
3. Reboot: Reboot your device after installation.
4. Verification: Once rebooted, open an ADB shell or a terminal emulator on your device (with root access):

   adb shell
   su
   /system/bin/my_custom_exploit.sh
   getprop persist.sys.my_custom_prop
   cat /data/local/tmp/my_exploit_log.txt

   You should see the output “Hello from my custom Magisk injected script!”, the correct system property value, and the log file containing device info.

Advanced Considerations and Best Practices

• Logging and Debugging: Use `ui_print` extensively in `customize.sh` for installation feedback. For runtime debugging, use `logcat` or write to files in `/data/local/tmp`.
• Systemless Principle: Always ensure your module makes changes in the Magisk overlay (`$MODPATH`) and avoids directly modifying `/system` or `/vendor`.
• Conditional Execution: You can use shell scripting to detect Android versions, device models, or kernel versions within `customize.sh` or `service.sh` to apply device-specific changes.
• Module Updates: Ensure `versionCode` in `module.prop` is incremented for new versions. Magisk handles updates seamlessly.
• Uninstall Logic: Magisk handles basic uninstallation by removing the module’s overlay. If your module makes persistent changes (e.g., in `/data`), you might need to include a `uninstall.sh` script (though typically not needed for simple overlay modules) or provide instructions for manual cleanup.
• Security Implications: While this guide focuses on module creation, remember that Magisk modules run with root privileges. Carefully audit any code you include or execute, especially if obtained from third parties, as they can perform any action on your device.

Conclusion

Crafting your first Magisk module opens a door to powerful system-level customization and experimentation. By understanding the core components like `module.prop`, `customize.sh`, and the `system/` overlay, you can inject custom binaries, modify system properties, or even implement complex exploits in a systemless and reversible manner. This foundational knowledge empowers you to explore the vast possibilities of Android root exploitation, security research, and advanced device customization responsibly.