--- title: Android Root Detection & Troubleshooting description: Systematically diagnose root availability on Android devices, especially for Termux environments with Magisk. Covers wrapper scripts, path probing, and Magisk-specific issues. name: android-root-troubleshooting trigger: When root access fails, `su` command not found, Magisk installed but su unavailable, or WeChat data extraction requires root verification. --- # Android Root Detection & Troubleshooting ## Overview When working with Android devices (especially for WeChat data extraction, Frida injection, or system-level operations), root access is often required. However, root detection is non-trivial because: 1. **Termux ships a `su` wrapper script**, not a real su binary 2. **Magisk may hide su** via Zygisk or namespace isolation 3. **Multiple su paths exist** across different root solutions 4. **Discovery agents may falsely report "no root"** when the issue is just path resolution ## The Core Problem Termux's `/data/data/com.termux/files/usr/bin/su` is a **shell wrapper** that searches for the real su binary in a hardcoded list of paths. If Magisk's su isn't in one of those paths, the wrapper prints "No su program found" even though the device is rooted. **Important distinction**: In Termux, `su` serves two different purposes: 1. **Root access** — the wrapper searches for a real root su binary (Magisk, SuperSU, etc.) 2. **Permission elevation within Termux** — some setups use `su -G -c "..."` to run commands as the Termux app UID with specific group memberships (e.g., `AID_INET` for network access). This is NOT root — it's a workaround for Termux's safety mechanism that prevents root from running `apt`/`dpkg` directly. ## Systematic Detection Flow ### Phase 1: Check Termux's su Wrapper ```bash # Read the wrapper script to understand what paths it searches cat /data/data/com.termux/files/usr/bin/su ``` The wrapper typically searches: - `/debug_ramdisk/su` - `/sbin/su` - `/system/sbin/su` - `/system/bin/su` - `/system/xbin/su` - `/su/bin/su` - `/magisk/.core/bin/su` ### Phase 2: Probe for Real su Binary If the wrapper fails, manually check ALL possible locations: ```bash # Standard paths ls /debug_ramdisk/su 2>/dev/null ls /sbin/su 2>/dev/null ls /system/sbin/su 2>/dev/null ls /system/bin/su 2>/dev/null ls /system/xbin/su 2>/dev/null ls /su/bin/su 2>/dev/null ls /magisk/.core/bin/su 2>/dev/null # Magisk-specific paths (newer versions) ls /data/adb/magisk/magisk 2>/dev/null ls /data/adb/magisk/su 2>/dev/null ls /sbin/.magisk/mirror/bin/su 2>/dev/null # APEX paths (Android 10+) ls /apex/com.android.runtime/bin/su 2>/dev/null find /apex -name su -type f 2>/dev/null # Broad search (last resort) find /data -name "su" -type f 2>/dev/null | head -10 find /system -name "su" -type f 2>/dev/null | head -10 ``` ### Phase 3: Check Magisk Installation Status ```bash # Check if Magisk app is installed pm list packages | grep -i magisk # Check Magisk directories ls /data/adb/ 2>/dev/null ls /data/adb/magisk/ 2>/dev/null # Check for Magisk-specific files ls /sbin/.magisk/ 2>/dev/null ``` ### Phase 4: Verify Root Access Directly If you find a real su binary, test it directly: ```bash # Direct invocation (bypass wrapper) /sbin/su -c "id" 2>/dev/null /system/xbin/su -c "id" 2>/dev/null /debug_ramdisk/su -c "id" 2>/dev/null ``` ### Phase 5: Check Magisk App for Configuration If Magisk is installed but su is hidden: 1. **Open Magisk App** → Settings → Check "Zygisk" status 2. **Superuser tab** → Check if Termux is in the deny list 3. **Settings → Magisk Hide** → May need to disable for Termux ## Common Scenarios & Fixes ### Scenario 1: Magisk Installed, su Not in Standard Paths **Symptom**: `pm list packages | grep magisk` shows Magisk, but `su` fails **Cause**: Magisk 24+ with Zygisk enabled may relocate su or hide it from Termux **Fix**: - Disable Zygisk in Magisk settings, OR - Add Termux to Magisk's superuser allowlist, OR - Use Magisk's `su` directly via full path if found ### Scenario 2: Termux su Wrapper Outdated **Symptom**: Real su exists at `/data/adb/magisk/su` but wrapper doesn't check there **Fix**: Update the wrapper or create a symlink: ```bash # Option A: Update wrapper paths (requires root) su -c "ln -s /data/adb/magisk/su /system/xbin/su" # Option B: Direct invocation in scripts /data/adb/magisk/su -c "command" ``` ### Scenario 3: Device Not Actually Rooted **Symptom**: No su binary found anywhere, Magisk not installed **Fix**: Device needs root. Options: - Install Magisk (requires bootloader unlock + custom recovery) - Use a pre-rooted emulator (Android Studio emulator with `-writable-system`) - Use a root-enabled cloud device ## Quick Diagnostic Script Save as `check_root.sh`: ```bash #!/data/data/com.termux/files/usr/bin/sh echo "=== Android Root Diagnostic ===" echo "" echo "--- Termux su wrapper ---" if [ -f /data/data/com.termux/files/usr/bin/su ]; then echo "Wrapper exists" head -5 /data/data/com.termux/files/usr/bin/su else echo "Wrapper NOT found" fi echo "" echo "--- Standard su paths ---" for p in /debug_ramdisk/su /sbin/su /system/sbin/su /system/bin/su /system/xbin/su /su/bin/su /magisk/.core/bin/su; do if [ -x "$p" ]; then echo "FOUND: $p" $p -c "id" 2>/dev/null && echo " -> WORKING" || echo " -> NOT WORKING" fi done echo "" echo "--- Magisk paths ---" ls /data/adb/magisk/magisk 2>/dev/null && echo "Magisk binary exists" || echo "Magisk binary not found" ls /data/adb/magisk/su 2>/dev/null && echo "Magisk su exists" || echo "Magisk su not found" echo "" echo "--- Magisk app ---" pm list packages | grep magisk || echo "Magisk app not installed" echo "" echo "--- Direct root test ---" /data/data/com.termux/files/usr/bin/su -c "id" 2>/dev/null || echo "Termux wrapper failed" ``` ## Pitfalls 1. **Don't trust "No su program found" blindly** — it's from the wrapper, not the system 2. **Discovery agents may fail** — they often use `su -c "id"` which hits the wrapper 3. **Magisk Hide / Zygisk can hide root** from Termux even when root is active 4. **Termux PATH is limited** — `/system/bin` may not be accessible without root 5. **Android version matters** — APEX modules (Android 10+) change binary locations 6. **Don't assume root is lost** — it may just be hidden or relocated 7. **`su -G` is not standard su syntax** — it's Magisk-specific. If the user references `su -G 3003 `, they mean the Magisk su that supports group/UID switching, not the Termux wrapper. This pattern is used to run Termux commands with proper permissions (e.g., `AID_INET` group for network access), not to gain root. 8. **The Termux wrapper script itself is at `/data/data/com.termux/files/usr/bin/su`** — always check its content first to understand what paths it searches and whether it has been modified ## Verification Checklist After troubleshooting: - [ ] Checked Termux su wrapper content - [ ] Probed all standard su paths - [ ] Checked Magisk installation status - [ ] Tested direct su invocation if binary found - [ ] Verified Magisk app settings (Zygisk, denylist) - [ ] Can execute `su -c "id"` and get uid=0 ## 安全边界 (Safety Guardrails) > 对齐 Google Cloud Skills 的「操作手册 + 安全边界」标准。本节列出本 skill **禁止自主执行**的高风险动作,必须显式 HITL(人工)授权。 ### Prohibited Operations (Denylist) 以下动作**禁止** agent 自主执行: - **`adb shell rm -rf` 任何路径**:特别是 `/data`、`/sdcard`、`/system` 前缀 - **`adb reboot-bootloader` / `fastboot flashing unlock` / `fastboot oem unlock`**:变砖风险 - **`adb shell pm uninstall` 系统应用**:可能导致系统不稳定 - **`dd of=/dev/block/*`**:直接写裸分区 - **修改 boot / recovery / vbmeta 分区** - **`su -c "rm -rf /data"`**:root 权限下的批量删除 - **卸载/禁用 Magisk 模块**:可能影响 root 可用性 ### 执行前必做检查 | 动作 | 必做检查 | 拒绝条件 | |------|---------|---------| | `su -c` 任何命令 | 先 `su -c "id"` 确认 uid=0 | 非 root → 停止,不强行试 | | 写 `/data/data//` | 确认目标 pkg 是用户明确指定的 | 未明确指定 → 人工确认 | | SQLCipher 打开 DB | 用 `shlex.quote` 处理密钥 | 密钥含特殊字符未转义 → 拒绝执行 | | 修改 `/data/adb/magisk/` | 人工确认 | 任何写操作 → 人工 | ### Dry Run 原则 - 文件系统修改命令先 `ls` 确认目标存在 - DB 操作先用 `sqlcipher -cmd ".tables"` 只读探测,再决定是否写入 - 所有 `su -c` 命令必须先在本会话验证过 `su -c "id"` 返回 uid=0 ## Related - `wechat-group-digest` — WeChat data extraction (requires root) - `systematic-debugging` — General debugging methodology - `android-ui-automation` — Alternative to Frida hooking: UI automation via ADBKeyboard + OCR + tap ## SQLCipher Key Derivation Note When extracting WeChat data, root access alone is not sufficient — the SQLCipher encryption key must also be correct. A common pitfall is assuming the key is simply `MD5(UIN)[:7]`. In practice, newer WeChat versions may use `MD5(IMEI + UIN)[:7]` or the full 32-character MD5 hash. If `sqlcipher` returns "file is not a database (26)" despite root access working, the key derivation is wrong, not the root. See `wechat-group-digest/references/sqlcipher-wechat-db-access.md` for the full key derivation troubleshooting flow. ## Reference Files - `references/termux-su-wrapper-analysis.md` — Full analysis of Termux's su wrapper script, its search paths, and why it fails even on rooted devices. Includes the critical lesson: **re-verify root directly when user insists**, because stale memory/cached state can falsely report "no su". - `references/termux-su-g-group-pattern.md` — The `su -G 3003 -c "..."` pattern for running commands as Termux UID with network permissions (Magisk-specific, not root-related) - `references/sqlcipher-wechat-db-troubleshooting.md` — SQLCipher WeChat DB access: multi-account DB selection, sqlcipher `-cmd` flag usage, shell quoting with `shlex.quote`, and MCP process reload after code changes - `references/frida-devkit-termux-compilation.md` — Frida core devkit compilation on Termux: downloading devkit, installing build dependencies (meson, glib), the ninja blocker (PyPI wheels incompatible with bionic libc), and workaround options (compile ninja from source, use make backend, cross-compile, or use frida-server directly without Python client). **Key lesson**: devkit version MUST match frida Python package version exactly; check `frida-server --version` before downloading. Also covers Java VM unavailability after attach/spawn and version mismatch between frida-server and Python client. - `references/ninja-android-bionic-patch.md` — Step-by-step guide to compiling ninja from source on Android Bionic, including the `src/util.cc` patch for missing `sysinfo`/`SI_LOAD_SHIFT`.