溺的文档
KernelSU · 第 1 篇 / 共 8 篇

KernelSU 架构概述

2026-06-30 · 阅读 4
#KernelSU#Android#Root

1. 项目简介

KernelSU 是一个基于 Linux 内核的 Android root 解决方案。与传统用户空间方案不同，它把核心能力实现在内核模块中，通过细粒度的 App Profile 与一套内核↔用户空间的私有接口提供 root 管理能力。

本套文档对应当前模块化重构后的代码。如果你看过早期资料，请注意：内核已从扁平的 ksu.c/core_hook.c/allowlist.c/supercalls.c 重构为模块化子目录；用户空间核心是 Rust 的 ksud（非 Manager 内置 C++）；通信走 [ksu_driver] 匿名 inode 的 IOCTL（非 prctl）；模块系统改为 metamodule + meta-overlayfs；默认 SELinux domain 是 u:r:ksu:s0。

1.1 设计理念

  1. 内核层实现：root 与权限管理在内核空间完成，更底层、更稳定、更难被绕过；
  2. 细粒度控制：App Profile（v4）可为每个应用定制 UID/GID、附加组、capabilities、SELinux domain、mount namespace 与提权标志；
  3. 可插拔模块系统：通过 metamodule + meta-overlayfs 解耦"如何挂载模块"，而非把挂载逻辑写死；
  4. 可开关特性：su 兼容、内核卸载、SELinux 隐藏、adb root、su 审计等以 feature 形式运行时开关；
  5. 安全优先：Manager 经纯 V2 签名校验，配合 no-new-privs、uid==0 域校验等防提权约束。

1.2 与其他 Root 方案对比

特性 KernelSU Magisk 传统 su
实现层次 内核模块 用户空间 + boot 修改 用户空间
通信机制 [ksu_driver] 匿名 inode IOCTL — setuid 二进制
权限控制 App Profile（细粒度） 白名单 无
模块系统 metamodule + meta-overlayfs Magic Mount / OverlayFS 无
安装形态 GKI（boot 内置）/ LKM（运行时） boot 修改 /system 修改
GKI 兼容 原生支持 需适配 不支持
隐藏性 较强（selinux_hide、模块卸载、自隐藏） 中等 较弱

2. 整体架构

KernelSU 由内核模块、Rust 用户空间（ksud/ksuinit）、Manager 应用三部分组成，通过共享的 uapi/ 接口契约协作。

┌──────────────────────────────────────────────────────────┐
│  Manager App (manager/, Kotlin + Jetpack Compose)         │
│  授权列表 / App Profile / 模块管理 / 刷写 boot / 设置       │
└───────┬───────────────────────────────────┬──────────────┘
        │ 通路 A：JNI 直连内核 IOCTL          │ 通路 B：libsu root shell
        │ Natives.kt→jni.cc→ksu.cc            │ 执行 libksud.so <子命令>
        ▼                                     ▼
┌─────────────────────────────┐   ┌──────────────────────────────┐
│  内核模块 kernelsu.ko (C)    │   │  ksud (userspace/ksud, Rust)  │
│  hook / supercall / policy   │◄──┤  守护进程 + 多功能 CLI         │
│  manager / selinux / feature │ioctl  打包为 libksud.so          │
│  [ksu_driver] 匿名 inode     │   └──────────────┬───────────────┘
└─────────────────────────────┘                  │ init.rc 各阶段
        ▲                            ┌────────────▼────────────┐
        │ uapi/*.h（三方共享接口）    │  ksuinit (Rust)          │
        └─────────────────────────────┤  LKM 模式 init shim      │
                                       └──────────────────────────┘
  • 通路 A：Manager 经 JNI 直接 IOCTL 内核，读写实时状态（版本、Profile、feature、授权计数）；
  • 通路 B：Manager 经 libsu 执行 ksud 子命令，做模块/boot/sepolicy 等重操作；
  • uapi/ 是 kernel(C)、ksud(Rust，bindgen)、Manager(C++，符号链接) 共享的单一接口真相源。

3. 核心组件

3.1 内核模块（kernel/，C）

模块名 kernelsu.ko，模块化为 13 个子目录：

子目录 职责
core/ 模块入口/退出（两条加载路径）
hook/ tracepoint 分发器 + 进程标记 + setuid/LSM hook + 内存改写
supercall/ [ksu_driver] IOCTL 接口、命令分发、权限检查
policy/ 白名单（RCU 哈希表）、App Profile、feature 框架
manager/ Manager 扫描追踪、APK 签名验证、包变化监听
selinux/ domain 切换、内置规则、动态 sepolicy
feature/ sucompat / kernel_umount / selinux_hide / adb_root / sulog
sulog/ su 审计日志事件队列与 fd
infra/ 符号解析、file_wrapper、seccomp_cache、mount ns、事件队列
runtime/ init.rc 注入、boot 事件回调

详见 内核层实现。

3.2 ksud（userspace/ksud/，Rust）

用户空间核心：既是 init 拉起的守护进程，又是多功能 CLI。负责与内核 IOCTL 通信、模块/metamodule 管理、init 事件处理、su 执行体、boot 修补、sepolicy/profile/feature 管理、resetprop。被打包为 libksud.so 进 Manager。详见 用户空间实现。

3.3 ksuinit（userspace/ksuinit/，Rust）

LKM 模式的极小 init shim：boot 早期加载 kernelsu.ko 后移交真正的 init。其 load_module（kallsyms 手动重定位加载 .ko）被 ksud 复用。详见 高级特性与安全 §4。

3.4 Manager（manager/，Kotlin）

Jetpack Compose UI（Material3 + Miuix 双主题），通过两条通路与系统交互。另含 WebUI（kernelsu js 库）、magica、adbroot 等子系统。详见 用户空间实现 与 libsu 与 su 兼容层。

4. 关键技术

4.1 syscall tracepoint 分发器 hook

不再用 Kprobe 逐个 hook syscall。而是把 syscall table 一个空闲 ni_syscall 槽改成分发器，用 sys_enter tracepoint 把被标记进程的目标 syscall（execve/setresuid/newfstatat/faccessat）绕路到分发器，再查路由表调 handler。普通进程不触发，零开销。详见 内核层实现 §2。

4.2 [ksu_driver] 匿名 inode + IOCTL

KernelSU 的"设备"是进程持有的匿名 inode [ksu_driver]，对它 ioctl 即调用内核功能（21 个命令，幻数 'K'）。fd 由内核在 Manager setresuid 时直接植入，或经 reboot magic 协议为 ksud/su 安装。无 /dev 节点，更隐蔽。详见 内核层实现 §4。

4.3 提权 escape_with_root_profile

修改进程 cred（uid/gid/caps）、刷新 user/ucounts、禁用 seccomp、切 u:r:ksu:s0 domain、按需禁止再提权、按 profile 切 mount namespace。详见 内核层实现 §3.3。

4.4 App Profile（v4）

每应用一份策略，结构定义在共享头 uapi/app_profile.h：allow_su 决定走 root（uid/gid/groups/caps/domain/namespace/flags + 模板）或 non-root（umount_modules）配置。白名单用 RCU 哈希表 + kref（非旧的 bitmap），持久化到 /data/adb/ksu/.allowlist 并带版本迁移。详见 内核层实现 §3。

4.5 metamodule + meta-overlayfs

ksud 不直接挂载模块，而委托唯一活动的 metamodule（提供 metamount.sh 等脚本）。模块状态用空文件标记，安装走 modules_update/ 暂存。详见 用户空间实现 §4、高级特性与安全 §3。

4.6 feature 系统

su_compat / kernel_umount / selinux_hide / adb_root / sulog 五个特性，经 IOCTL GET/SET_FEATURE 运行时开关。详见 高级特性与安全 §2。

5. 工作流程概览

开机 → 内核模块加载（GKI 内置 / LKM late-load）
     → (GKI) hook init.rc 注入触发器 → init 各阶段 exec ksud
     → ksud IOCTL REPORT_EVENT 回报 → 内核 on_* 回调（加载 allowlist、挂载模块、扫描 Manager）
运行 → zygote fork app 的 setresuid → 标记进程 / 给 Manager 装 fd / 按策略卸载模块
     → 授权应用 su 或 Manager GRANT_ROOT → escape_with_root_profile 提权

完整时序见 关键流程分析。

6. 安全设计

  • Manager 认证：只接受纯 V2 签名（V1 共存或 V3 存在即拒），证书 SHA-256 由构建注入；
  • 权限分级：supercall 命令按 always_allow / only_root / only_manager / manager_or_root / allowed_for_su 检查；
  • 防提权：uid==0 须在 ksu domain 才被认可；NO_NEW_PRIVS 可禁止再提权；系统 uid 保护；
  • 安全模式：音量下键开机（内核统计 input_event）禁用所有模块，从 bootloop 恢复；
  • 反检测：selinux_hide、模块卸载、ext4 sysfs 清理、匿名通信、模块自隐藏。

详见 Android 安全机制与绕过 与 高级特性与安全。

7. 技术优势

  1. GKI 友好：无需改内核源码，支持 GKI 2.0；兼 GKI 内置与 LKM 运行时两种形态；
  2. 稳定：内核层实现，构建期 check_symbol 校验符号依赖，fixmap 改写避开厂商 hypervisor；
  3. 低开销：tracepoint 选择性 hook，普通进程零开销；
  4. 隐蔽：无 /dev 节点、selinux_hide、模块自隐藏；
  5. 细粒度：App Profile 支持复杂的 per-app 配置。

8. 项目结构

KernelSU/
├── kernel/              # 内核模块 (C，模块化子目录)
│   ├── core/ hook/ supercall/ policy/ manager/
│   ├── selinux/ feature/ sulog/ infra/ runtime/
│   └── include/ tools/
├── userspace/
│   ├── ksud/            # 用户空间核心 (Rust，→ libksud.so)
│   └── ksuinit/         # LKM init shim (Rust)
├── manager/             # Manager 应用 (Kotlin/Compose)
│   └── app/src/main/{cpp/, java/}
├── uapi/                # 内核/ksud/Manager 共享接口头
├── js/                  # 模块 WebUI 的 JS 库 (npm: kernelsu)
├── website/             # 文档站 (VitePress)
└── scripts/ .github/    # 构建脚本 / CI

9. 总结

KernelSU 通过以下关键技术实现内核级 root：

  1. tracepoint 分发器 —— 选择性、低开销地 hook 关键 syscall；
  2. 匿名 inode IOCTL —— 隐蔽的内核↔用户空间通道；
  3. escape_with_root_profile —— 基于 App Profile 的细粒度提权；
  4. metamodule + meta-overlayfs —— 可插拔的模块挂载；
  5. feature 系统 + 纯 V2 认证 —— 运行时可控、安全可信。

相比传统方案，它在稳定性、细粒度控制与隐蔽性上更有优势，特别适合现代 GKI 设备。

下一章节：内核层实现 将深入内核模块的具体实现。完整阅读建议见 KernelSU 系列。

评论

  • 还没有评论，来说点什么吧。

无需注册或登录，填个昵称即可评论。