O3 Root（中文版）

英文原版：README.md。若两者不一致，以英文版为准并同步本文件。

针对 HyperOS 4（Android 17，内核 6.18.21）上的小米 yingtian（Pad 9 Pro Max）与 lhasa（Xiaomi 18 Fold）系列，做本地提权 + KernelSU。整条链打包成一个 普通 Android 应用：它以 shell 模式驱动 Shizuku，利用 CVE-2026-98260， 按已安装的管理器（KernelSU / KernelSU-Next / SukiSU）加载对应 LKM —— 不需要电脑、 不需要解锁 bootloader、不改任何分区。

研究 / 教育 / 设备维修项目。仅当前 boot 有效（重启即失效）。只在自己拥有的 设备上运行。使用前请读 docs/SECURITY.md（中文版 docs/SECURITY.zh-CN.md）。

自动化贡献者 / Agent： 先读 AGENTS.md（入口：不变量、 构建/测试配方、坑、卫生要求），再读 docs/AGENT_HANDOFF.md（已验证状态、失败实验、待办）。 提交前运行 bash scripts/verify.sh；配置好工具链环境时它还会重建 payload/APK。

中文版： AGENTS.zh-CN.md / docs/AGENT_HANDOFF.zh-CN.md

状态

发布	v3.2（release/o3root2-v3.2.apk，14,239,248 B，sha256 64bbc654…）
O1 测试构建	v3.3.3-o1-test（release/test/o3root2-v3.3.3-o1-test.apk，14,247,440 B，sha256 62411f72…）：v3.2 功能 + 实验性 O1（XRING）profile（dijun / jinghu / violin）+ 隐藏 root 控制台。接受 OS4.0.0.x 的任意 6.18.21-android17…-4k 内核：已分析构建走验证路径，其他构建走宽松模式并警告；仅供测试，从未真机验证
旧测试构建	v3.2.1-console（release/beta/o3root2-v3.2.1-console.apk，14,243,344 B，sha256 9cba365a…）：正式版 + 隐藏 root 控制台（长按版本行，三道确认）
O1 设备	小米 O1 SoC 的 dijun / jinghu / violin（OS4.0.0.x）：三台共用同一颗 6.18.21 内核（sha256 0d9917ca…，g1d099fcb35e0）；静态分析认为链路可用，尚未实机验证
自定义 LKM	可选：任意 KernelSU 系列 .ko（基础兼容性检查；未通过可退回自适应内置模块；选择会保存并在下次启动恢复，长按该行可清除）
链路	Shizuku shell → CVE-2026-98260 → uid=0 + full caps → 对应 KernelSU LKM（KernelSU / KernelSU-Next / SukiSU）→ rootd
持久化	无（仅当前 boot）
已验证设备	小米 Pad 9 Pro Max yingtian，HyperOS OS4.0.16.0.XBMCNXM
第二设备	lhasa（Xiaomi 18 Fold，OS4.0.26.0.XPNCNXM）：其 boot 内核与 yingtian 逐位相同（sha256 cde87cd7…），因此同一载荷适用；未实机测试

工作原理（简版）

1. App 通过 Shizuku 的 newProcess 拉起 /system/bin/sh -c …，因此载荷运行在 u:r:shell:s0（uid=2000）。
2. 载荷触发 CLOCK_THREAD_CPUTIME_ID + execve/de_thread 竞态 （CVE-2026-98260），用一个包含伪造 RB 树节点的 kmalloc-8k 喷页缓冲回收已 释放的 posix_timers_cache order-1 slab 页，并借第二次 timerqueue_del → rb_erase 向任意内核地址写入一个 8 字节值。
3. stage 0 在 selinux_state-7 做 8 字节非对齐写清掉 enforcing（同时清掉 相邻 notif_lock 的 pending/tail 字节；initialized/policycap 保留）； stage 1 把 task_struct.cred 指向伪造的 cred 页（uid 0、full caps）。
4. 载荷加载内置 KernelSU LKM：未定义符号默认运行时经 /proc/kallsyms 解析 （回退：248 符号并集重链接 + 当前 KASLR slide），默认不打 init 补丁—— policycap 干净，所以 KSU 自己的 setenforce(1) 无害、设备停在 Enforcing。 然后 insmod 并留下一个 rootd 守护进程（抽象 socket @o3p_rootd， peer-uid 0/2000）。上游 KernelSU、KernelSU-Next、SukiSU 三种 LKM 都可加载 （旧行为：O3P_CODEPATCH=1 才会去改 setenforce 立即数）。v3.1 起也可以在 App 里自选 .ko（基础 ELF/.modinfo 兼容性检查；被拒绝或加载失败时自动退回内置 LKM）。v3.1.1 起选择会持久化到 files/custom-ko.ko + custom-ko.meta，启动时恢复；失效文件会被丢弃，长按 模块行可清除。v3.2 起 LogBox 可选中，并有 复制 链接复制全部日志；只有 已在底部附近时才自动滚动。识别到 O1 机型时，测试版会在启动载荷前弹出两步 风险确认（风险说明 + 勾选），确认后才开始提权。测试构建额外把 root 控制台藏在长按版本行之后： 三道不可跳过的确认，之后命令经 rootd socket 以 root 执行（需本次 boot 内 先跑过一次载荷）。正式版不包含控制台类。

偏移、写原语、KernelSU 补丁与移植指南见 docs/ARCHITECTURE.md（中文版 docs/ARCHITECTURE.zh-CN.md）。

快速开始

1. 设备上：开启开发者选项 → 无线调试（或 ADB）。安装 Shizuku / ShizukuX， 并以 shell 模式 启动：shizuku_plus_server 必须是 uid=2000、 u:r:shell:s0。
2. 安装 release/o3root2-v3.2.apk（MIUI 可能需要允许“USB 安装”）。
3. 打开 O3 Root，授予 Shizuku 权限，点 Continue to UID 0。日志会显示 ★ UIDNOW uid=0、★ KSU_MODULE LIVE，随后 KernelSU 管理器自动打开。

O1 设备（dijun / jinghu / violin）测试：请安装 release/test/o3root2-v3.3.3-o1-test.apk， 并按 docs/TESTING_O1.md 操作。门禁接受三个代号下任意 6.18.21-android17…-4k 内核（OS4.0.0.x）；已分析的 g1d099fcb35e0 构建走验证 路径，其他构建会打印 固件门禁通过（O1 宽松模式：…） 并带警告沿用 O1 地址。 载荷会打印 SELINUX_PROFILE kernel=… base=… src=env|uname，所以反馈只需附上 导出的日志。

没装管理器？按钮会变成 安装 KernelSU 管理器，点击后安装内置 APK（按系统 提示确认即可）。

仓库结构

AGENTS.md   自动化贡献者入口（不变量、陷阱、检查）
app/        Android App 源码（Java）、manifest、res、build.sh
payload/    o3p.c（利用载荷 + 运行时 KernelSU 加载器）、248 符号回退表 /
            重链接器、mk_payload.py、build-payload.sh、legacy/（早期版本）
tools/      OTA/内核提取 + 校验脚本
docs/       架构、安全、构建、OTA 分析、可行性报告、证据截图
scripts/    工具链下载、环境模板、一键构建
release/    预编译 APK + 校验和
third_party/ 内置第三方组件的许可说明

构建

bash scripts/fetch-toolchain.sh
cp scripts/env.example.sh env.sh && . ./env.sh   # 修改路径
bash payload/build-payload.sh                    # -> payload/build/libo3p.so
bash app/build.sh                                # -> app/build/o3root2.apk

完整前提与排错见 docs/BUILD.md（中文版 docs/BUILD.zh-CN.md）。

限制

• 仅当前 boot：重启会移除 root 与 KernelSU。持久化需要改 boot/init_boot（被锁定的 bootloader 挡住），不在范围内。
• 概率性：UAF 竞态需要 1–6 次尝试（偶尔更多）。App 会自动重试；重启通常 有帮助。
• SELinux 姿态：v3 终态是 Enforcing，selinux_state 干净（policycap 不变），MAC 保持开启。只有旧路径 O3P_SELDIRTY=1 会停在 Permissive（全系统 MAC 关闭）；见安全说明。
• 旧 policycap 副作用：仅 O3P_SELDIRTY=1 时存在。该路径仍写旧的脏值，任何 setenforce 1 都会让 Wi-Fi TX 卡住，直到 setenforce 0 或重启；v3 默认不碰 policycap、也不再带恢复 UI（v1.8–v2.1 有守护与一键恢复）。
• KernelSU LKM ABI：上游模块是为 6.18.32-4k 构建的；这里为 6.18.21 内核重链接，因此会污染内核（taint）。不要把它当生产级 root 方案。
• 绑定 profile：偏移/地址是按这个确切内核编译的。换内核构建需要新的 profile（见 docs/ARCHITECTURE.md 的移植章节）。O1 测试构建是唯一受控例外： 接受 OS4.0.0.x 中 6.18.21-android17…-4k 系列的任意构建，沿用已分析的 O1 selinux_state 地址，并警告其他静态地址未做比对。

证据

docs/evidence/ 里有设备截图：v3 App 成功日志（v3_app_log.png）、Enforcing 下的 KernelSU 管理器（v3_ksu.png）；旧的 v1.8 守护/恢复截图（v18risk.png、 v18rec.png）保留作为历史。详细日志与完整记录在 docs/APP_O3_ROOT.md。

文档