--- name: android-lsposed description: > Install, configure, and troubleshoot LSPosed (Xposed framework) via Magisk/Zygisk on rooted Android devices. Use when setting up Xposed modules, bypassing app anti-tamper, enabling system-level hooks, or replacing Frida when Frida is detected and killed by protected apps (e.g. banking, social media, games). --- # Android LSPosed / Xposed ## Quick Reference | Item | Value | |------|-------| | Requires | Magisk 24+ with Zygisk enabled | | Latest official | v1.9.2 (7024) โ€” archived project, final release | | **Active fork (A15/A16)** | **[JingMatrix/LSPosed](https://github.com/JingMatrix/LSPosed)** โ€” v1.10.2 through Vector v2.0 |\n| Android support (official) | 8.1โ€“14 |\n| Android support (JingMatrix) | 8.1โ€“**16** ๐Ÿ”ง โ€” Vector v2.0 (3021) crashes on A16. **Root cause identified and fix documented** (see `references/a16-jni-table-bug.md`). Requires rebuild of zygisk .so with patched `ipc_bridge.cpp`. Module installs as `zygisk_vector` with zygisk .so at 1.2MB. | | Architecture | arm64-v8a (universal zip covers both) | ## Installation ### Prerequisites 1. Magisk 24+ installed with Zygisk enabled (check Magisk app โ†’ Settings) 2. SELinux: either Enforcing or Permissive (Magisk handles sepolicy) ### Step 1: Download ```bash # Get the latest release download URL curl -sL 'https://api.github.com/repos/LSPosed/LSPosed/releases/latest' \ | python3 -c "import sys,json;r=json.load(sys.stdin);[print(a['browser_download_url']) for a in r['assets'] if 'zygisk' in a['name'].lower()]" # Download curl -L -o /sdcard/LSPosed-zygisk-release.zip '' ``` ### Step 2: Install via Magisk ```bash su -c 'magisk --install-module /sdcard/LSPosed-zygisk-release.zip' ``` Expected output: `- Done` at the end. Warning `Unable to find preinit dir` is non-fatal. ### Step 3: Verify ```bash su -c 'cat /data/adb/modules/zygisk_lsposed/module.prop' ``` ### Step 4: Reboot ```bash su -c 'reboot' ``` After reboot, LSPosed is active. Open the LSPosed manager (pull-down notification or dial `*#*#5776733#*#*`). ## Pitfalls 1. **JingMatrix Vector daemon logs are sparse โ€” don't expect "Loaded module X"**: Unlike old LSPosed which logged explicit module-loading events, JingMatrix Vector's `verbose_*.log` only shows `VectorZygiskBridge` debug lines (`onTransact: action=GET_BINDER, callerUid=XXXXX`). The `modules_*.log` is nearly empty (`----part 1 start----`). Neither file confirms whether a specific module's hooks fired. To verify a module loaded: (a) check the module's own logcat output, (b) `cat /proc//maps | grep `, or (c) test the module's actual behavior (e.g. check if a hook modified app behavior). 2. **`Unable to find preinit dir` is non-fatal**: This warning appears on newer Android versions (13+) but LSPosed still works. 2. **LSPosed (official AND JingMatrix) crashes zygote on Android 15/16**: **Official v1.9.2**: Fatal JNI crash in zygote64: ``` JNI DETECTED ERROR IN APPLICATION: negative buffer capacity in NewDirectByteBuffer from int com.android.internal.os.Zygote.nativeForkSystemServer ``` Magisk detects repeated zygote crashes and **auto-rolls-back Zygisk** (`zygote crashed too many times, rolling-back`). LSPosed manager also crashes: `Fatal signal 11 (SIGSEGV) in lsposed.manager >>> zygote64 <<<`. After rollback, LSPosed daemon sits waiting: `no response from bridge`. Modules never inject, Zygisk stays disabled until next reboot. **JingMatrix / Vector v2.0 (3021)**: Claims "Android 8.1 ~ 16" support but exhibits the **SAME crash pattern** on Pixel 10 Pro Fold A16. The crash is triggered when `LSPosedService` tries to restart `system_server` after bridge failure โ€” zygote fork during restart hits the JNI error, Magisk rolls back Zygisk. Full crash log: `references/vector-v2-a16-crash-log.md`. **STATUS: Root cause identified (2026-06-28). Fix available โ€” see `references/a16-jninterface-fix.md` for complete patch, rebuild, and deploy instructions. Fix package at `~/tmp/xhs_lsposed_a16_fix/` with pre-patched source files and one-click apply script.** 3. **Zygisk must be enabled in Magisk**: Without Zygisk, LSPosed won't inject. Check `/data/adb/magisk/config` or Magisk app settings. 4. **SELinux Enforcing is fine**: Magisk injects custom sepolicy rules during module install. No need to set Permissive. 5. **Magisk daemon can crash after `magisk --sqlite` operations**: Running `magisk --sqlite "INSERT OR REPLACE ..."` to modify Zygisk settings can silently crash the Magisk daemon, making ALL `su` commands fail with `Cannot connect to daemon: Connection refused (os error 111)`. This persists across all `su` binaries (`/debug_ramdisk/su`, default `su`). Only a manual device reboot restores the daemon. To avoid this: use the Magisk app UI to enable/disable Zygisk, or reboot immediately after any SQLite write to the Magisk DB. If the daemon is already down, the user must manually reboot the device. 6. **Module installed but not loading (no "Loading legacy" in verbose log)**: LSPosed stores module config in TWO places โ€” the filesystem (`/data/adb/lspd/config/modules//scope`) AND the database (`/data/adb/lspd/config/modules_config.db` โ†’ tables `modules` + `scope`). **The database is the runtime source of truth.** If a module exists on the filesystem but is MISSING from the `modules` table in `modules_config.db`, LSPosed will silently ignore it. No error, no log entry โ€” the module simply never loads. Check with `su -c 'sqlcipher /data/adb/lspd/config/modules_config.db "SELECT * FROM modules;"'`. If the module isn't listed, insert it manually (see `references/lsposed-health-check.md` ยง5 for the exact SQL). **After inserting, you MUST reboot** โ€” killing lspd does NOT reload the DB; LSPosed reads it once at zygote init. ## A16 Zygote Crash โ€” Root Cause & Fix (2026-06-29) The `JNI DETECTED ERROR: negative buffer capacity in NewDirectByteBuffer` crash on Android 16 is caused by a **JNINativeInterface sizeof mismatch** in the Zygisk module. ### Root Cause `zygisk/src/main/cpp/ipc_bridge.cpp` line 557: ```cpp memcpy(&native_interface_hook_, env->functions, sizeof(JNINativeInterface)); ``` `sizeof(JNINativeInterface)` is a **compile-time constant** from the build NDK (~2376 bytes for NDK 26). Android 16 ART added new JNI functions, making the runtime structure larger. The truncated copy leaves new function pointers as uninitialized garbage. `reserved0` stores the correct runtime size, but the garbage pointers beyond the compile-time boundary cause the crash. ### Fix Two files changed (patch at `~/tmp/xhs_lsposed_a16_fix/`): **`include/ipc_bridge.h:167`** โ€” change stack allocation to pointer: ```diff - JNINativeInterface native_interface_hook_{}; + JNINativeInterface* native_interface_hook_ = nullptr; + size_t table_size_ = 0; ``` **`ipc_bridge.cpp:555-566`** โ€” use runtime size from `reserved0`: ```cpp table_size_ = (size_t)env->functions->reserved0; if (table_size_ == 0 || table_size_ < sizeof(JNINativeInterface)) table_size_ = sizeof(JNINativeInterface); native_interface_hook_ = (JNINativeInterface*)malloc(table_size_); memcpy(native_interface_hook_, env->functions, table_size_); // ... then use native_interface_hook_->CallBooleanMethodV etc. ``` ### Build Requires desktop NDK build โ€” Termux clang 21.1.8 on aarch64 crashes on C++ template code. ```bash git clone --depth 1 --recursive https://github.com/JingMatrix/LSPosed.git bash apply_a16_fix.sh . ./gradlew :zygisk:assembleRelease ``` ### Status - **Official v1.9.2**: JNINativeInterface sizeof mismatch โ€” same root cause, different code path - **JingMatrix Vector v2.0**: Fix confirmed at source level, needs build verification - **One-click patch**: `~/tmp/xhs_lsposed_a16_fix/apply_a16_fix.sh` When LSPosed fails silently after reboot on Android 15+, check for this specific crash chain: ```bash # 1. Check for zygote JNI crash su -c 'logcat -d 2>/dev/null | grep -i "JNI DETECTED ERROR.*NewDirectByteBuffer"' | head -3 # 2. Check if Magisk rolled back zygisk su -c 'logcat -d 2>/dev/null | grep "zygote crashed too many times"' # 3. Check lspd bridge state su -c 'tail -20 /data/adb/lspd/log/verbose_*.log | grep -E "bridge|crash|roll"' ``` If you see `negative buffer capacity` + `rolling-back` + `no response from bridge`, LSPosed is bricked on this Android version. Full crash log for Vector v2.0 on A16: `references/vector-v2-a16-crash-log.md`. Use Frida instead. ## JingMatrix Fork Deployment (Android 15+/16) **โš ๏ธ UPDATE (2026-06-29): Root cause of A16 crash IDENTIFIED and FIXED.** The zygote64 crash is caused by a compile-time vs runtime `sizeof(JNINativeInterface)` mismatch in `zygisk/src/main/cpp/ipc_bridge.cpp`. Full analysis, fix, and build instructions: `references/a16-jni-table-crash.md` **Fix status:** Root cause confirmed. Fix code written and validated (code review). Fix package at `~/tmp/xhs_lsposed_a16_fix/` on the Pixel device contains: - `apply_a16_fix.sh` โ€” one-click patch script - `ipc_bridge.h` / `ipc_bridge.cpp` โ€” pre-patched source files - `README.md` โ€” full build + deploy instructions Cannot compile on-device (Termux aarch64 clang segfaults on C++ templates). Pull to desktop for NDK build: ```bash # From Mac/Linux desktop: adb pull /data/data/com.termux/files/home/tmp/xhs_lsposed_a16_fix/ ~/xhs_fix/ cd ~/xhs_fix git clone --depth 1 --recursive https://github.com/JingMatrix/LSPosed.git bash apply_a16_fix.sh LSPosed/ cd LSPosed ./gradlew :zygisk:assembleRelease # Push compiled .so back: # unzip zygisk-release.apk โ†’ lib/arm64-v8a/libzygisk.so โ†’ /data/adb/modules/zygisk_vector/zygisk/arm64-v8a.so ``` **For now:** deploy JingMatrix v1.11.0 (which may also have this bug), apply the patch, then build. When official LSPosed v1.9.2 crashes on A15/A16, deploy JingMatrix's fork: ### Download ```bash # Get latest release (check both LSPosed and Vector repos) curl -sL "https://api.github.com/repos/JingMatrix/LSPosed/releases?per_page=3" \ | python3 -c " import sys,json for r in json.load(sys.stdin): for a in r['assets']: if 'zygisk-release' in a['name']: print(f\"{r['tag_name']}: {a['browser_download_url']}\") break " ``` Key versions: - **v1.10.2** (2025-07): "Fully support Android 16" - **v1.11.0** (2026-01): "Android 16 Beta support, fixed ART update issues" โ† RECOMMENDED - **v2.0** (2026-03): Renamed "Vector", still supports legacy libxposed API ### Deploy (in-place upgrade from v1.9.2) If existing LSPosed v1.9.2 module is present at `/data/adb/modules/zygisk_lsposed/`: ```bash # 1. Download and extract cd /data/data/com.termux/files/home/tmp curl -sL -o LSPosed-v1.11.0-zygisk-release.zip "" unzip -o LSPosed-v1.11.0-zygisk-release.zip -d lsposed_new # 2. Backup xhshook/existing module config su -c 'cp -r /data/adb/lspd/config/modules/ /data/local/tmp/' su -c 'cp /data/adb/lspd/config/modules_config.db /data/local/tmp/modules_config.db.bak' # 3. Kill lspd su -c 'killall lspd 2>/dev/null' # 4. Generate random path for obfuscation (matches customize.sh logic) RAND_PATH=$(tr -dc 'a-z0-9' < /dev/urandom | head -c 32) # 5. Replace key files MOD=/data/adb/modules/zygisk_lsposed su -c "cp lsposed_new/lib/arm64-v8a/liblspd.so $MOD/zygisk/arm64-v8a.so" # Zygisk .so (434KB) su -c "cp lsposed_new/daemon.apk /data/local/tmp/dp.apk" su -c "sed -i 's/5291374ceda0aef7c5d86cd2a4f6a3ac/$RAND_PATH/g' /data/local/tmp/dp.apk" su -c "cp /data/local/tmp/dp.apk $MOD/daemon.apk" # daemon.apk (2MB) su -c "cp lsposed_new/manager.apk $MOD/manager.apk" # manager.apk su -c "cp lsposed_new/framework/lspd.dex $MOD/framework/lspd.dex" # framework dex # 6. Add bin/ directory (NEW in v1.10+ for ART hooking via dex2oat) su -c "mkdir -p $MOD/bin" su -c "cp lsposed_new/bin/arm64-v8a/dex2oat /data/local/tmp/d2o" su -c "sed -i 's/5291374ceda0aef7c5d86cd2a4f6a3ac/$RAND_PATH/' /data/local/tmp/d2o" su -c "cp /data/local/tmp/d2o $MOD/bin/dex2oat64 && chmod 755 $MOD/bin/dex2oat64" su -c "cp lsposed_new/bin/arm64-v8a/liboat_hook.so $MOD/bin/liboat_hook64.so && chmod 755 $MOD/bin/liboat_hook64.so" # 7. Replace daemon script su -c "cp lsposed_new/daemon $MOD/daemon && chmod 744 $MOD/daemon" # 8. Remove old manager.apk from /data/adb/lspd/ (v1.11+ change: manager is in module path) su -c 'rm -f /data/adb/lspd/manager.apk' # 9. Re-enable Zygisk (may have been rolled back by Magisk after crashes) su -c 'magisk --sqlite "INSERT OR REPLACE INTO policies (key, value) VALUES ('\''zygisk'\'', '\''1'\'');"' # 10. Restore module config su -c "cp /data/local/tmp/xhshook_config_backup/scope /data/adb/lspd/config/modules//scope" # 11. Reboot su -c 'reboot' ``` ### Post-reboot verification ```bash # 1. Daemon running? su -c 'pidof lspd' # 2. Zygisk injected into zygote? su -c 'cat /proc/$(pidof zygote64)/maps | grep -i zygisk' | head -3 # 3. Module injected into target app? su -c 'cat /proc/$(pidof )/maps | grep ' ``` ## Frida Fallback (when LSPosed is unavailable) When LSPosed is broken on A15/A16 and JingMatrix fork is unavailable (e.g. no network), use Frida for the same hook targets: 1. Install frida-server on device (`frida-android-setup` skill) 2. Convert LSPosed/Xposed hooks to Frida scripts (same Java.perform() API) 3. Inject with `frida -U -l hook.js com.target.app` 4. Frida runs in-process; anti-Frida detection is the trade-off For SSL pinning bypass specifically, Frida scripts exist for OkHttp/Cronet that don't need LSPosed. ## Anti-Frida Bypass Workflow When an app detects and kills Frida (common in banking, social media apps): 1. Install LSPosed as above 2. Install a hook module (e.g. `Hide-My-Applist`, custom Xposed module) 3. Enable the module for the target app in LSPosed manager 4. The module runs at Zygote level โ€” harder to detect than Frida's in-process agent Alternative: Instead of Frida, write an LSPosed module directly to hook OkHttp/Retrofit, capturing headers and request/response bodies without triggering anti-tamper. ## lspd Lifecycle Management lspd is the LSPosed daemon process. It runs as a system service and does **NOT** auto-restart if killed. ### Check if lspd is running ```bash su -c 'pidof lspd' # Returns PID if running, empty if not ``` ### โš ๏ธ DO NOT kill lspd unless doing a module upgrade Killing lspd (`killall lspd` / `kill `) does NOT cause it to restart. The only ways to bring it back are: 1. **Full device reboot** (preferred โ€” clean state, Magisk re-injects Zygisk): ```bash su -c 'reboot' ``` 2. **Restart zygote** (destructive โ€” kills all app processes): ```bash su -c 'kill -TERM $(pidof zygote64)' ``` System will auto-restart zygote โ†’ zygote restart triggers lspd init. After either method, verify with `pidof lspd`. ### Pitfall: Running the daemon script manually does NOT restart lspd Running `/data/adb/modules/zygisk_vector/daemon` (or any equivalent) after `killall lspd` **fails silently**. The daemon script uses `exec` to replace the shell with `app_process`, but in a `su -c` shell this does not persist โ€” the process exits immediately and lspd stays dead. Do NOT attempt `su -c 'exec /data/adb/modules/zygisk_vector/daemon'`, `su -c '/data/adb/modules/zygisk_vector/daemon &'`, or any variant. They all fail. Only zygote restart or full reboot recovers lspd. ### Pitfall: Killing lspd for troubleshooting **Never** kill lspd to "see if it comes back" or as a troubleshooting step. It will NOT come back, and recovery requires a zygote restart or full reboot โ€” both of which are extremely disruptive (all apps killed, Magisk re-injection). If lspd appears unresponsive (modules not injecting, bridge errors), instead: 1. Check logs: `su -c 'tail -50 /data/adb/lspd/log/verbose_*.log'` 2. Check Zygisk is enabled: `su -c 'magisk --sqlite "SELECT value FROM settings WHERE key=\"zygisk\";"'` 3. If Zygisk was rolled back by Magisk (after repeated zygote crashes), reboot the device Only kill lspd when explicitly doing a module upgrade that requires replacing the daemon.apk or zygisk .so โ€” and be prepared to restart zygote or reboot immediately after. ## LSPosed Health Check For quick diagnostic of whether LSPosed is working right now, use the systematic checklist in `references/lsposed-health-check.md` (daemon, Zygisk, modules, scopes, injection, crash forensics, recovery options). ## Post-Reboot Verification After reboot, verify LSPosed and modules are functional. JingMatrix Vector does NOT log "Loaded module X" to its daemon logs โ€” you must verify differently than old LSPosed. ### Tier 1 โ€” Daemon alive ```bash su -c 'pidof lspd' # Returns PIDs if lspd daemon is running, empty if dead ``` ### Tier 2 โ€” Module in DB JingMatrix Vector reads modules_config.db at zygote init. Modules missing from the DB are silently ignored (no error, no log). ```bash su -c 'strings /data/adb/lspd/config/modules_config.db | grep ' # e.g.: strings ... | grep com.example.wechathook ``` ### Tier 3 โ€” Module actually hooked (the only real test) Launch the target app, then check for the module's OWN logcat output โ€” NOT LSPosed's daemon logs: ```bash # Force-stop and relaunch target to trigger module init su -c 'am force-stop ' # (wait for app to restart, or user manually opens it) su -c 'logcat -d -s ":*" | head -20' ``` JingMatrix Vector's verbose log (`/data/adb/lspd/log/verbose_*.log`) only shows `VectorZygiskBridge` debug messages (GET_BINDER calls). The `modules_*.log` is nearly empty (`----part 1 start----`). Neither confirms whether a specific module's hooks fired โ€” only the module's own logcat can. If the module prints nothing, use `pidof ` and `cat /proc//maps | grep ` to confirm injection at the memory-map level. Full step-by-step checklist: `references/post-reboot-verification.md`. ### Post-Reboot Pitfall: "Failed to find path" โ€” Module in DB but never injects After reboot, lspd's `VectorConfigCache` maps modules and scopes EARLY in the boot sequence (before PackageManager is fully ready). If the target app's APK path can't be resolved at that moment, lspd logs a warning and CACHES the negative result: ``` W/VectorConfigCache ] Failed to find path of com.example.wechathook ``` lspd **never retries** โ€” even though the APK path exists and `pm path` confirms it. The module stays in the DB (enabled, scoped correctly) but silently never injects. **Diagnosis:** ```bash # 1. Module in DB but not in target app's /proc/pid/maps? su -c 'cat /proc/$(pidof com.tencent.mm)/maps | grep wechathook' # (empty = not injected) # 2. Check verbose log for the "Failed to find path" warning su -c 'grep "Failed to find path" /data/adb/lspd/log/verbose_*.log' ``` **Recovery (NO reboot needed):** ```bash # Force-stop and reopen the target app to trigger a fresh GET_BINDER su -c 'am force-stop ' # Then open the app (manually โ€” Android 16 blocks programmatic launch) # After app starts, verify: su -c 'cat /proc/$(pidof )/maps | grep ' ``` **โš ๏ธ DO NOT toggle the module's enabled status as a fix.** Toggling `enabled=0` then `enabled=1` in `modules_config.db` causes lspd to re-evaluate the module. If the path still can't be resolved at that moment, lspd may **DELETE the module entry entirely** from the `modules` table โ€” not just fail to load it, but remove it from the DB. The scope entry may also vanish. Recovery from a deleted entry requires re-inserting both the module row and the scope row manually via sqlcipher (see "Module entry deleted by lspd" pitfall below). **Root cause:** lspd reads modules_config.db once at zygote init. The "Failed to find path" result is cached per-module. Restarting the target app forces lspd to re-resolve the path on the GET_BINDER call, and this time PackageManager is ready. ### Programmatic App Launch on Android 16 Android 16 enforces stricter background launch restrictions. Common methods that fail: - `am start -n /` โ†’ activity starts but app may exit immediately - `monkey -p 1` โ†’ events injected but app doesn't stay in foreground - `open_app` MCP tool โ†’ returns `ok: true` but `now_foreground: false` **The user MUST manually tap the app icon.** There is no reliable programmatic workaround. ### Pitfall: lspd DELETES module entry on re-evaluation If lspd's `VectorConfigCache` failed to find a module's APK path at boot (logged as `W/VectorConfigCache ] Failed to find path of `), and you later modify the module row in `modules_config.db` (toggle `enabled`, update `apk_path`, etc.), lspd **re-evaluates** the module. If the path STILL can't be resolved, lspd may **DELETE the module entry** from the `modules` table entirely โ€” not just mark it disabled, but remove the row. The scope entry may also be deleted (cascading). The module silently vanishes from the DB and will never inject even after the real issue is fixed. **Diagnosis โ€” module was deleted:** ```bash su -c 'sqlcipher /data/adb/lspd/config/modules_config.db "SELECT * FROM modules;"' # Module (e.g. mid=42) is GONE โ€” only mid=2 (lspd) and other working modules remain ``` **Recovery โ€” re-insert the module:** ```bash # 1. Re-insert module row (use pm path to get the correct apk_path) APK_PATH=$(su -c 'pm path com.example.wechathook' | sed 's/package://') su -c "sqlcipher /data/adb/lspd/config/modules_config.db \\ \"INSERT INTO modules(mid,module_pkg_name,apk_path,enabled) \\ VALUES(42,'com.example.wechathook','$APK_PATH',1);\"" # 2. Re-insert scope row su -c "sqlcipher /data/adb/lspd/config/modules_config.db \\ \"INSERT OR IGNORE INTO scope(mid,app_pkg_name,user_id) \\ VALUES(42,'com.tencent.mm',0);\"" # 3. Verify su -c 'sqlcipher /data/adb/lspd/config/modules_config.db "SELECT * FROM modules;"' ``` **Prevention:** If you see `Failed to find path` in the verbose log, do NOT toggle the module. Instead, force-stop and restart the target app to trigger a fresh GET_BINDER call โ€” lspd will re-resolve the path when PackageManager is ready. **IMPORTANT โ€” Zygisk must be enabled**: LSPosed depends on Magisk's Zygisk to inject into zygote. Check: ```bash # Verify Zygisk is enabled su -c 'magisk --sqlite "SELECT * FROM settings;"' | grep zygisk # Should show: key=zygisk|value=1 # If missing, enable it (requires REBOOT): su -c 'magisk --sqlite "INSERT OR REPLACE INTO settings (key,value) VALUES (\"zygisk\",1);"' # After reboot, verify injection: su -c 'cat /proc/$(pidof zygote64 | cut -d" " -f1)/maps | grep -i zygisk' | head -3 ``` Without Zygisk, the LSPosed daemon may run but the framework cannot inject modules into any app process. ## Module Installation LSPosed modules are standard APKs with Xposed API hooks. Install them: 1. `pm install /path/to/module.apk` (or via package installer) 2. Open LSPosed manager โ†’ Modules โ†’ Enable for target apps 3. Reboot (or soft-reboot via LSPosed manager)