SKILL.md 10.8 KB

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 <group> <uid> -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

# 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:

# 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

# 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:

# 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:

# 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:

#!/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 <uid>, 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>/ 确认目标 pkg 是用户明确指定的 未明确指定 → 人工确认
SQLCipher 打开 DB 用 shlex.quote 处理密钥 密钥含特殊字符未转义 → 拒绝执行
修改 /data/adb/magisk/ 人工确认 任何写操作 → 人工

Dry Run 原则

  • 文件系统修改命令先 ls 确认目标存在
  • DB 操作先用 sqlcipher -cmd ".tables" 只读探测,再决定是否写入
  • 所有 su -c 命令必须先在本会话验证过 su -c "id" 返回 uid=0
  • 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 <uid> -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.