APatch FAQ 深度解读：基于 boot.img 的内核级 Root 方案、KPM 内核模块与 SuperKey 认证机制详解

系统编程移动开发【免费下载链接】APatchThe patching of Android kernel and Android system项目地址https://gitcode.com/gh_mirrors/ap/APatch点击查看免费下载APatch 是一个面向 Android 的、以“直接修补内核”为核心的全新 Root 方案它在安装体验上继承了 Magisk 通过boot.img快速部署的优势在能力上继承了 KernelSU 内核级修补的强大扩展性。本文以仓库docs/id/faq.md与docs/en/faq.md同源的官方 FAQ为骨架结合 apd 守护进程与 SuperCall UAPI 等源码实现逐一拆解 APatch 与 Magisk、KernelSU 的差异、Kernel Patch ModuleKPM、SuperKey 认证机制与 SELinux 处理策略帮助读者理解这套方案的底层工作原理并掌握相关命令与配置的落地方式。APatch 是什么Magisk 与 KernelSU 的融合官方 FAQ 对 APatch 的定义非常直接APatch 是一种类似于 Magisk 或 KernelSU 的 Root 解决方案它取两者之长——既拥有 Magisk 通过boot.img进行的便捷安装方式又具备 KernelSU 强大的内核修补kernel patching能力。仓库 README.md 将其概括为一句定位语The patching of Android kernel and Android system.APatch 的完整能力面包括三部分APMAPatch Module提供与 Magisk 类似的模块化支持systemless 机制模块目录位于/data/adb/modules详细开发指南见 模块(APM)开发指南KPMKernel Patch Module支持向内核注入任意代码提供内核级inline-hook与syscall-table-hook能力SuperKey / SuperCall由内核新增系统调用提供的 userspace 能力入口与访问凭证。在部署前提上官方 README.md 明确了两点约束仅支持ARM64 架构仅支持Android 内核版本 3.18 – 6.12。此外内核需要开启符号导出相关配置CONFIG_KALLSYMSy且CONFIG_KALLSYMS_ALLy可获得完整支持若CONFIG_KALLSYMS_ALLn则提供初步支持。这些约束决定了 APatch 与 Magisk几乎不依赖内核配置在底层实现上的根本差异。APatch 与 Magisk 的区别修补 ramdisk 还是直接修补内核FAQ 用一句话点出了 APatch 与 Magisk 的核心分水岭Magisk 通过在 boot image 的 ramdisk 中加入补丁来修改系统的 init 流程而 APatch 是直接修补内核kernel本身。Magisk 的工作方式是在启动早期对 init 进程进行注入patch 位于boot.img的 ramdisk 部分从而在 userspace 层接管系统而 APatch 的“直接修补内核”体现在它依赖 KernelPatch 在内核镜像上直接植入代码再通过内核中的 SuperCall 机制为 userspace 提供能力。仓库的构建资产也能印证这一点——app/src/main/assets 下提供了boot_extract.sh、boot_patch.sh、boot_unpatch.sh等脚本其操作对象是设备的boot.img先提取extract再修补patch并支持还原unpatch。而安装完成后真正承载运行时的是位于/data/adb/apd的 apd 守护进程见 apd/src/defs.rs 中DAEMON_PATH定义以及/data/adb/ap工作目录WORKING_DIR。APatch 与 KernelSU 的对比只需原厂 boot.img无需内核源码KernelSU 是另一款知名的内核级 Root 方案但它的部署强依赖设备的内核源码。FAQ 指出KernelSU 需要你设备内核的源代码而 OEM 并不总是提供它APatch 只需你手上的原厂boot.img即可工作。这一点对普通用户极为关键内核源码往往是厂商闭源或未公开的导致 KernelSU 在大量机型上无法部署。而 APatch 直接对官方boot.img进行修补绕开了源码依赖大大拓宽了适用机型范围。从源码看这一设计还延伸到“越狱模式jailbreak mode”apd/src/late_load.rs 中的late-load流程允许在未预置修补的原厂内核上运行时加载 KernelPatch 内核模块自动检测内核 KMIKernel Module Interface形如android14-5.15支持从内核 release 字符串解析parse_kmi查找/data/adb/ap/{kmi}_kernelpatch.ko若无显式--module参数则使用该默认路径通过 apd/src/insmod.rs 绕过内核严格的版本校验vermagic / modversions CRC 检查加载模块未定义符号从/proc/kallsyms解析在线注入 Magisk 策略apply_magisk_policy_live写入/data/adb/ap/jailbreak标记重启管理器应用并恢复 SELinux enforcing。其中 apd/src/insmod.rs 的实现细节——临时置kptr_restrict1以便读取/proc/kallsyms地址、解析 ELF 重定位、调用init_module(2)——正是“无需内核源码也能完成内核级修补”的技术支撑。APatch vs Magisk 与 KernelSU 的组合对比线程级 Root 与可选 SELinux 修改FAQ 进一步指出 APatch 相对 Magisk、KernelSU 的两个差异化能力APatch 允许你选择不修改 SELinux这意味着应用APP的线程本身就可以被 Rootlibsu 与 IPC 都不是必需的。提供Kernel Patch ModuleKPM。线程级 Root免 libsu、免 IPC在传统方案如 Magisk中Root 一个应用通常需要通过su启动一个全新的进程再由客户端通过 IPC 与服务端通信——即 libsu 体系。APatch 借助内核直接注入的 SuperCall可以在应用自己的线程上下文内完成 Root 化无需拉起新进程自然也就不需要 libsu 与 IPC。UAPI 头文件 app/src/main/cpp/uapi/scdefs.h 中对此有直接佐证#define SUPERCALL_SU 0x1010 #define SUPERCALL_SU_TASK 0x1011 // syscall(__NR_gettid)SUPERCALL_SU_TASK的注释表明它基于线程 IDgettid工作可以在指定线程上执行提权操作——这正是“APP 线程可被 Root”的内核侧实现通道。KPM内核空间的代码注入能力FAQ 对 KPM 的定义是一些代码运行在 Kernel Space内核空间类似于可加载内核模块Loadable Kernel ModulesLKM。此外KPM 还提供在内核空间进行inline-hook和syscall-table-hook的能力。UAPI 中同样能看到 KPM 的管理命令族#define SUPERCALL_KPM_LOAD 0x1020 #define SUPERCALL_KPM_UNLOAD 0x1021 #define SUPERCALL_KPM_CONTROL 0x1022 #define SUPERCALL_KPM_NUMS 0x1030 #define SUPERCALL_KPM_LIST 0x1031 #define SUPERCALL_KPM_INFO 0x1032这与 apd 守护进程的两个相关子命令对应apd insmod module.ko不带版本检查地加载内核模块见 apd/src/cli.rs以及apd late-load越狱模式见 apd/src/cli.rs。更完整的 KPM 编写指南由上游 KernelPatch 项目提供其仓库中的doc/module.md属于内核模块开发者的进阶主题。APatch 与 KernelPatch 的关系依赖、继承与扩展FAQ 明确了二者的关系APatch 依赖 KernelPatch继承了它的全部能力并在此之上进行了扩展。你也可以只安装 KernelPatch但这样你将无法使用 Magisk 模块APM。也就是说KernelPatch 是 APatch 的内核底座README 的 Credits 部分也把 KernelPatch 称为 “The core”负责内核修补、SuperCall 注入等底层能力APatch 在其上叠加了模块机制APM、SELinux 策略支持magiskpolicy、管理器 UI 等 userspace 生态。只装 KernelPatch 只能获得内核层能力无法享受 APatch 的模块化生态。从代码层面看apd 甚至把 KernelPatch 的版本号作为常量编译进 SuperCall 调用中apd/src/supercall.rs 通过build.rs生成kp_version.rs并在ver_and_cmd()中把KP_MAJOR/KP_MINOR/KP_PATCH编码进系统调用的高 32 位apd/src/supercall.rsfn ver_and_cmd(cmd: c_long) - c_long { let version_code: u32 ((KP_MAJOR 16) (KP_MINOR 8) KP_PATCH) .try_into() .unwrap(); ((version_code as c_long) 32) | (0x1158 16) | (cmd 0xFFFF) }这里的0x1158正是 UAPI 中定义的SUPERCALL_HELLO_MAGIC低 16 位app/src/main/cpp/uapi/scdefs.h用于内核侧校验调用协议的合法性。SuperKey 与 SuperCall内核级的能力入口与访问凭证这是 FAQ 中最具技术分量的部分KernelPatch 新增了一个系统调用syscall为 userspace 的应用与程序提供全部能力这个系统调用被称为SuperCall。当应用/程序尝试调用 SuperCall 时需要提供访问凭证即SuperKey。只有当 SuperKey 正确时 SuperCall 才能被成功调用否则调用方不会受到任何影响。调用约定与命令码SuperCall 复用了truncate的系统调用号ARM64 上为 45通过命令码分发不同功能。UAPI 头文件 app/src/main/cpp/uapi/scdefs.h 明确定义// #define __NR_supercall __NR3264_truncate // 45 #define __NR_supercall 45所有功能按命令码组织涵盖命令码宏定义功能0x1000SUPERCALL_HELLO握手探测hello0x1008 / 0x1009SUPERCALL_KERNELPATCH_VER/SUPERCALL_KERNEL_VER查询 KernelPatch 与内核版本0x100a–0x100cSUPERCALL_SKEY_GET/SET/ROOT_ENABLESuperKey 读取、设置与 Root 使能0x1010 / 0x1011SUPERCALL_SU/SUPERCALL_SU_TASK提权进程级 / 线程级0x1020–0x1032SUPERCALL_KPM_*KPM 模块的加载、卸载、控制与枚举0x1040–0x1046SUPERCALL_KSTORAGE_*内核存储kernel storage读写与分组管理0x1100–0x1112SUPERCALL_SU_*SU 授权管理授予/撤销 UID、列表、安全模式等其中与“Root 授权管理”直接相关的一组SUPERCALL_SU_GRANT_UID 0x1100、SUPERCALL_SU_REVOKE_UID 0x1101、SUPERCALL_SU_NUMS 0x1102、SUPERCALL_SU_LIST 0x1103在 apd 中被封装为完整的管理流程apd/src/supercall.rs 的refresh_ap_package_list()会先查询已授权 UID 数量、拉取列表、逐个撤销再依据包配置重新授予实现 Root 授权列表与系统包管理的同步。密钥校验SuperKey 如何工作SuperCall 的身份验证发生在内核侧调用者把 SuperKey 以 C 字符串指针传入系统调用内核用与 UAPI 中hash_key()相同的算法app/src/main/cpp/uapi/scdefs.h初值1000000007、逐字符hash * 31 c对密钥做哈希比对匹配才放行。密钥有长度上限SUPERCALL_KEY_MAX_LEN 0x4064 字节。提权时的目标描述结构su_profileapp/src/main/cpp/uapi/scdefs.h包含三个字段struct su_profile { uid_t uid; uid_t to_uid; char scontext[SUPERCALL_SCONTEXT_LEN]; // 0x60 };即“当前 UID → 目标 UID通常为 0/root”以及目标 SELinux 上下文。apd 在启动时若带有--superkey参数会先以该结构自我提权privilege_apd_profile见 apd/src/supercall.rs使用的上下文为u:r:magisk:s0。在 userspaceapd 的 CLI 把 SuperKey 作为全局参数暴露apd/src/cli.rs-s, --superkey KEY Super key for authentication root所有需要内核能力的子命令如post-fs-data、boot-completed、soft-reboot都会携带该参数。日常使用中内核也会以argv[0]为/system/bin/kp或/system/bin/su的方式直接 exec apd进入 su 兼容的 Root Shell见 apd/src/cli.rs 与 apd/src/apd.rs 的root_shell()。安全警告SuperKey 权限高于 Root由于 SuperKey 直接控制内核注入的 SuperCall 通道README 的 Security Alert 特别强调SuperKey 拥有比 Root 更高的权限。弱密钥或被泄露的密钥可能导致设备被未授权控制。使用强健的密钥并妥善保管至关重要。这与 FAQ 中“SuperCall 只有在 SuperKey 正确时才能成功调用”的描述互为印证——SuperKey 本质上是内核级能力总开关其安全级别高于普通的su授权。SELinux 处理hook 绕过不改变上下文magiskpolicy 补充策略FAQ 的最后一个技术点聚焦 SELinuxKernelPatch不修改 SELinux 上下文而是通过 hook 绕过 SELinux 检查。这使得你可以直接在应用上下文内 Root 一个 Android 线程而无需借助 libsu 启动新进程再做 IPC非常实用。此外APatch直接使用 magiskpolicy提供额外的 SELinux 支持。两套并行的 SELinux 策略理解这一点需要区分“绕过”与“补充”两条路径KernelPatch 的 hook 绕过不触碰 SELinux 的上下文属性context也不改动策略文件而是在内核中对 SELinux 检查点做 hook从而在保留原上下文的条件下放行目标操作——这正是线程级 Root 得以实现的前提。APatch 的 magiskpolicy 注入apd 移植了 Magisk 的 magiskpolicy 工具在启动阶段向内核加载策略补丁。相关实现位于 apd/src/sepolicy.rs其apply_magisk_policy_live()apd/src/sepolicy.rs等价于执行magiskpolicy --magisk --live——从/sys/fs/selinux/policy加载当前策略、注入内置的 Magisk 规则、再写回/sys/fs/selinux/load。magiskpolicy 的完整用法apd 还通过 multicall 方式直接提供magiskpolicy命令argv[0]以magiskpolicy结尾时进入该模式见 apd/src/cli.rs选项与 Magisk 原生工具一致见 apd/src/sepolicy.rs选项说明--load FILE从指定文件加载单一 sepolicy--load-split从预编译 sepolicy 或编译 split cil 策略加载--compile-split编译 split cil 策略--save FILE将策略导出到文件--live立即将策略载入内核写入/sys/fs/selinux/load--magisk应用内置的 Magisk sepolicy 规则--apply FILE按行读取并应用策略语句文件可多次指定--print-rules打印已加载策略中的全部规则位置参数直接追加的 policy statements在启动事件中的实际应用SELinux 策略注入不是孤立操作它被编排进完整的启动事件流。以post-fs-data阶段为例apd/src/event.rsapd 依次执行加载 live policy 并应用 Magisk 规则、写入/sys/fs/selinux/load、重新为自身提权刷新 SuperCall 上下文、执行模块脚本与 Lua 阶段钩子、加载system.prop、触发post-mount等。整个生命周期由 apd/src/cli.rs 中的子命令驱动apd post-fs-data # 触发 post-fs-data 事件 apd services # 触发 service 事件 apd boot-completed # 触发 boot-completed 事件 apd uid-listener # 监听包列表变化同步 Root 授权 apd soft-reboot # 模拟系统重启保留运行时加载的模块 apd resetprop ... # Magisk 兼容的属性读写工具 apd sepolicy ... # magiskpolicy 的封装入口从 FAQ 到实践常用路径、命令与注意事项为了让 FAQ 中的概念落地这里汇总仓库中可确认的运行时关键路径与常用入口工作目录/data/adb/ap二进制位于/data/adb/ap/bin含 Magisk 同源编译的 BusyBox见 apd/src/defs.rs 与 模块开发指南守护进程/data/adb/apd同时承担su/kp/resetprop/magiskpolicy的 multicall 入口模块目录/data/adb/modulesAPM/data/adb/metamodule元模块详见 apd/src/defs.rsSuperCall 事件通道内核通过truncate二进制SUPERCMDapp/src/main/cpp/uapi/scdefs.h向 apd 上报事件见 apd/src/event.rs 的report_kernel安全模式/dev/.safemode标记app/src/main/cpp/uapi/scdefs.h进入安全模式会跳过模块脚本并禁用全部模块避免 bootloop。需要留意的部署限制仅支持 ARM64且内核版本需在 3.18 – 6.12 区间内README.md内核需满足CONFIG_KALLSYMS相关配置要求详见本文第一节安装基于官方boot.img的修补流程脚本见 app/src/main/assetsboot_extract.sh、boot_patch.sh、boot_unpatch.sh、InstallAP.sh、UninstallAP.sh启用/卸载请务必遵循官方安装说明SuperKey 请使用高强度的密钥并妥善保管。结语APatch 的 FAQ 虽短但每个条目都指向一组清晰的工程决策用直接修补内核的方式取代 ramdisk 注入vs Magisk用原厂boot.img取代内核源码依赖vs KernelSU用 SuperCall SuperKey 实现线程级 Root 与内核级能力开放vs libsu/IPC 体系并用“hook 绕过 magiskpolicy 补充”双轨处理 SELinux。理解这些底层机制有助于开发者更安全、更高效地使用 APM/KPM 生态也能在排障时如安全模式、SuperKey 失效、SELinux 策略冲突快速定位问题所在的层次——是内核侧KernelPatch/SuperCall还是 userspace 侧apd/模块脚本/magiskpolicy。赞分享系统编程移动开发【免费下载链接】APatchThe patching of Android kernel and Android system项目地址https://gitcode.com/gh_mirrors/ap/APatch点击查看免费下载相关推荐APatch 官方 FAQ 深度解读内核级 Root 方案、KPM 内核模块与 SuperKey 安全模型APatch 官方 FAQ 深度解读内核级 Root 方案、KPM 内核模块与 SuperKey 安全模型 APatch 是一个基于内核补丁Kernel P系统编程移动开发APatch FAQ 深度解读boot.img 内核修补、SuperKey/SuperCall 授权机制与 KPM 内核补丁模块全解析APatch FAQ 深度解读boot.img 内核修补、SuperKey/SuperCall 授权机制与 KPM 内核补丁模块全解析 本篇以官方西班牙语文档系统编程移动开发APatch 内核 Root 方案全面解析KernelPatch、SuperKey、KPM 内核模块与 SELinux 机制详解APatch 内核 Root 方案全面解析KernelPatch、SuperKey、KPM 内核模块与 SELinux 机制详解 APatch 是一款基于内核系统编程移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考