SKILL.md 22.6 KB

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 — v1.10.2 through Vector v2.0
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

# 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 '<URL>'

Step 2: Install via Magisk

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

su -c 'cat /data/adb/modules/zygisk_lsposed/module.prop'

Step 4: Reboot

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/<target_pid>/maps | grep <module_name>, 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.

  3. 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.

  1. Zygisk must be enabled in Magisk: Without Zygisk, LSPosed won't inject. Check /data/adb/magisk/config or Magisk app settings.

  2. SELinux Enforcing is fine: Magisk injects custom sepolicy rules during module install. No need to set Permissive.

  3. 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.

  4. 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/<pkg>/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:

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:

-    JNINativeInterface native_interface_hook_{};
+    JNINativeInterface* native_interface_hook_ = nullptr;
+    size_t table_size_ = 0;

ipc_bridge.cpp:555-566 — use runtime size from reserved0:

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.

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:

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

# 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

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

# 1. Download and extract
cd /data/data/com.termux/files/home/tmp
curl -sL -o LSPosed-v1.11.0-zygisk-release.zip "<URL>"
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/<your_module> /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/<your_module>/scope"

# 11. Reboot
su -c 'reboot'

Post-reboot verification

# 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 <target_package>)/maps | grep <module_name>'

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

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 <pid>) 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):

    su -c 'reboot'
    
  2. Restart zygote (destructive — kills all app processes):

    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

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).

su -c 'strings /data/adb/lspd/config/modules_config.db | grep <module_package>'
# 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:

# Force-stop and relaunch target to trigger module init
su -c 'am force-stop <target_package>'
# (wait for app to restart, or user manually opens it)
su -c 'logcat -d -s "<ModuleTag>:*" | 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 <target> and cat /proc/<pid>/maps | grep <module> 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:

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

# Force-stop and reopen the target app to trigger a fresh GET_BINDER
su -c 'am force-stop <target.package>'
# Then open the app (manually — Android 16 blocks programmatic launch)
# After app starts, verify:
su -c 'cat /proc/$(pidof <target.package>)/maps | grep <module_name>'

⚠️ 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 <package>/<activity> → activity starts but app may exit immediately
  • monkey -p <package> 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 <pkg>), 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:

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:

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

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