Module Development Guide​

For most aspects, ShiroSU is largely consistent withMagiskandKernelSU. This document only describes the differences.

Systemless^[1]​

ShiroSU's Systemless is a mount mechanism similar to Magisk, with fully compatible interfaces, such as the.replaceusage. However, ShiroSU's mount mechanism has stronger compatibility. It is based on dynamic partition identification. This means modules can directly mount partitions likeodm, and other root implementations cannot mount, without extra effort.

Furthermore, to ensure stronger security, ShiroSU's Systemless ignores theSELinux contextof mountedfiles/directories,directory permissions, andfile/directory user/group ownership. If a file is mounted to a non-existent directory, itsSELinux context,permissions, anduser/groupwill inherit from the parent directory. Generally, these actions do not affect module operation and instead help improve stability.

Shell​

ShiroSU differs significantly from other root implementations here. ShiroSU's running shell scripts arenotrun in "standalone mode" withinBusyBox.

To improve the convenience of shell script development, ShiroSU usessush(Bash written in Rust) to run shell scripts and prioritizes the command set ofuutils(coreutils written in Rust) over Magisk's BusyBox. Commands arefirst retrieved from uutils, and only if not found are they retrieved from BusyBox.

Since it's not run in "standalone mode" within BusyBox, commands are injected through thePATHenvironment variable. Do not hardcode modifications toPATHwithin module shell scripts!

Environment Variables​

To aid in differentiation, ShiroSU injects the following variables during module execution:

• SSU(boolean): When running in the ShiroSU environment, this value will betrue. However, this does not mean you can execute code with$SSU && # code .... Always use[ "$SSU" = true ]or a similar method to detect ShiroSU.
• SSU_VER(string): ShiroSU's version number (excluding patch number).
• SSU_VER_CODE(integer): ShiroSU's pure numerical version number (including patch number).

Recovery​

ShiroSU does not support installing modules via Recovery, and code withinMETA-INF/com/google/android/update-binarywill not be executed during module installation.

SU Calls​

ShiroSU's SU implementation defaults to asudothat can only be used to directly execute shell commands, allowing direct execution of commands likesudo ls /.

sudoexists only as a simplesu -calternative, butnomodule should usesudoorsu -cto execute shell commands!

Similarly, modules shouldnothardcode commands, such as/data/adb/ssu/bin/busybox crond, because regardless of BusyBox "standalone mode" or directPATHinjection, commands can be called directly without any hardcoded manual retrieval.

ANSI Escape Codes^[2]​

ShiroSU allows the use ofANSI escape codesinmodule.propor shell scripts to enhance text display. For example, inmodule.prop:

id=ssu_cmd_ext
name=Command Set Extension
version=Auto-generated by SSU
versionAnsi=\e[1mAuto-generated\e[0m by SSU
versionCode=1
author=SSU Developers (OOM. WG.)
description=Add coreutils, busybox, and bash to /system/bin.
descriptionAnsi=Add \e[1mcoreutils, busybox, and bash\e[0m to \e[1m/system/bin\e[0m.

Using the abovemodule.prop, the module will displayAuto-generated,coreutils, busybox, and bash, and/system/binin bold within the ShiroSU manager.

Inmodule.prop, you can usenameAnsi,versionAnsi,authorAnsi, anddescriptionAnsito display text containing ANSI escape codes.

While omitting theAnsisuffix is possible, for compatibility, use theAnsisuffix.

ShiroSU parsesmodule.propsequentially, so ensure values with theAnsisuffix are placed later in the file.

Module WebUI​

ShiroSU, likeKernelSU, allows modules to use WebUI for functionality, seeModule WebUI.

module.prop​

The ShiroSU manager has a mechanism to detect ifmodule.propis corrupted or conforms to the standard. If corrupted or non-compliant, the manager will display a tag above the module.

The ShiroSU manager checks the following:

• Whethermodule.propcontains non-compliant syntax.
• Whetherid,name,version,author,description(and theirAnsicounterparts) are empty.
• Whetheridmatches the regular expression:^[a-zA-Z][a-zA-Z0-9._-]+$.
• WhetherversionCodeis greater than0.
• Whethermodule.propcontains case inconsistencies (the manager will parse correctly but still display a tag).

If onlymodule.propis corrupted, reinstalling the module usually resolves the issue. If it's non-compliant, developers must fix it.

Kernel Interface​

ShiroSU uses/data/adb/ssu/._settingsas the kernel settings directory, typically containing the following files:

• ._su_list: List of packages authorized to use superuser privileges.
• ._bypass_list: List of entries bypassing SELinux restrictions.
• ._hide_list: List of entries needing hidden root usage traces.

These files storebinary UID(32-bit integer) +\0+package nameformat, with multiple values separated by\n.

Other Differences​

ShiroSU will providemodule backup interface,module update interface (executing original module code during updates), andmodule storage interfacein future updates. These features are still under development and will be released in future updates.

Contributors

白彩恋 YumeYuka

Changelog