Extension pass: module route, extraction shells, emulation/RPC, DBI, kernel layer, protocols

Closes the six coverage gaps named in an external review of this skill, and moves the
deliverable-form decision out of the single assumption it rested on.

New references (7):
- lsposed-and-modules.md      deliver a hook module when a repack is refused
- advanced-unpacking.md       extraction shells, FART-style recovery, the root-side dump
- emulation-and-rpc.md        call the routine instead of reading it
- native-dbi-and-deobfuscation.md  OLLVM, Stalker traces, two measured boundaries
- protocol-reverse.md         protobuf/gRPC/QUIC and native-side pinning
- kernel-and-environment-hardening.md  when userspace hooking cannot reach the check
- on-device-tooling.md        MT Manager, its APK MCP, working from the phone

New scripts (8): dex_dump_validate.py (+ --trim for page-aligned captures),
dex_mem_scan.py, lsposed_scaffold.py, frida_rpc_serve.py + rpc_template.js,
stalker_trace.js + stalker_report.py, mt_mcp_probe.py

SKILL.md:
- G1 carries a four-form deliverable table (rebuilt APK / module / RPC service / report)
  with the evidence that says when to leave the repack column, plus a matching hand-off
  section on how "verified" moves with the form
- Coverage gains a documented-routes tier carrying its own strength note; Not-covered
  loses the now-inaccurate "general unpacker" line and gains the limits that do apply
- 13 new symptom rows, 7 reference rows, 8 script rows, a fifth tooling obligation
- the pid-drift symptom is stated with its competing causes, not a single attribution

toolchain.md gains measured ASC/ddc cards; README gains the structure, capability and
scope entries for everything above; .gitignore stops tracking the local workspace.

Evidence: docs/tool-verification/EXTENSION-*.md (7 files), same three labels as the rest
of the record. Measured: the gradle-free module build chain (5.27 s end to end), a
successful injection confirmed through the LSPosed file channel (9 rounds) after three
logcat queries came back empty on a ROM with a broken logd, 17 dex images recovered by
root-side /proc/<pid>/mem dumping, the trivial-body metric separating a shell skeleton
from real bodies, ASC/ddc on a hardened APK, and Stalker's zero-event and crash
boundaries. The pid-drift attribution was corrected twice against better measurements.
This commit is contained in:
inliver233
2026-09-21 20:57:41 +08:00
parent 5fa80a5bea
commit ce2e4f98e1
27 changed files with 6602 additions and 9 deletions
+8
View File
@@ -23,6 +23,14 @@ out/
work/
audit_out/
# local extension-pass workspace: toolchains, device archives, dumped images, scratch notes.
# Nothing under tools/ belongs to the repository -- the skill's own evidence record lives in
# docs/tool-verification/ and carries no target identity or vendored binaries.
tools/
# local input material (the reporting sample and the analysis notes it came with)
存在问题和例子/
# sandbox installs made while testing `npx skills add .` against this repo
.claude/
.agents/
+67 -2
View File
@@ -74,6 +74,23 @@ measurements.
bounded waits, so progress is not lost and the same mistake is not made twice.
- Avoiding the specific mistakes that produce an APK that builds perfectly and dies at
runtime.
- Deciding **what the deliverable should be when an APK is not an option** — a repack refused by
several independent checks is *blocked*, not expensive, and the fallback ladder is a system-level
module, a local RPC service, or an honest report with a stated boundary.
- Telling a **real memory dump from an extraction-shell skeleton**, by measuring the trivial-body
ratio instead of eyeballing it — and knowing which recovery route applies, including the root-side
dump for when `frida` itself is refused by the target.
- **Calling a routine instead of reversing it** when reversing costs more than invoking: emulated
execution on the host, or a live function service-ified over Frida RPC.
- Reading **instruction-level execution evidence** when a native function has been flattened into a
state machine by OLLVM — including the two ways Stalker was measured to bite back on a real device.
- Recognising when **userspace hooking cannot reach the check at all** (raw `svc` syscalls,
`init_array`-early detection), what the next layer up and down can actually do, and when escalating
is the wrong answer.
- Working **protocols that are not REST** — protobuf without a schema, gRPC, QUIC/HTTP3 — and
native-side certificate pinning that ignores the system trust store.
- Working **from the phone itself**: MT Manager's edit/repack/sign flow and its APK MCP surface,
LSPosed Manager, and on-device data inspection, alongside the PC toolchain rather than instead of it.
## Structure
@@ -169,6 +186,27 @@ references/ loaded on demand, one topic each
emulator console control and recovery, preflight, look-at-the-screen
verification.md the claim ladder; what "done" means
pitfalls.md the failure catalogue -- read before building
advanced-unpacking.md the dump landed but the bodies are empty: extraction-shell diagnosis by
trivial-body ratio, FART-style active invocation and why its classic hooks
died on Android 12-16, code_item splicing, the root-side dump for when
frida itself is refused, and the honest VMP boundary
lsposed-and-modules.md the repack is refused, so deliver a system-level hook module instead:
module anatomy, a gradle-free build chain, scope configuration and how to
verify injection, and the layer a Java module cannot reach
emulation-and-rpc.md call the routine instead of reading it: Unidbg/Unicorn emulation and its
environment-filling cost, versus service-ifying a live function over Frida RPC
native-dbi-and-deobfuscation.md
OLLVM shapes, Frida-Stalker traces, the trace-to-CFG route, the
Stalker/QBDI/emulation decision, and two measured boundaries (a follow that
delivers no events, and a crash from following a hot libc export)
protocol-reverse.md protobuf without a schema, schema recovery from decompiled code, gRPC frame
capture, the QUIC/HTTP3 limit, and native-side certificate pinning
kernel-and-environment-hardening.md
userspace hooking provably cannot reach the check: raw `svc`, init_array-early
detection, what each root scheme hides, the kernel-route map with its version
gate, and when to stop escalating
on-device-tooling.md working from the phone itself: MT Manager edit/repack/sign and its APK MCP,
LSPosed Manager, Termux+frida, on-device data inspection
scripts/ parameterized, path-agnostic
doctor.py run this first: capability report + per-script runnability, finds
tools installed off-PATH or as runnable jars, and surfaces the
@@ -238,6 +276,24 @@ scripts/ parameterized, path-agnostic
writes survive detach while hooks do not
hook_patch_only.js the minimal probe for spawn_patch_detach.py — neutralise one native
death site by offset and report PATCHED
dex_dump_validate.py dedupe, validate and rank a directory of dumped dex images: sha256
grouping, header integrity, the trivial-body ratio that separates a real
dump from an extraction-shell skeleton, and a most-likely-original ranking
(--trim for page-aligned /proc/<pid>/mem captures)
dex_mem_scan.py search memory captures for embedded dex images and extract each at the
size its own header declares -- for a decrypted dex sitting in an
anonymous mapping no maps entry names
lsposed_scaffold.py generate a minimal LSPosed/Xposed module project (manifest with the
xposed meta-data, assets/xposed_init, hook class, gradle-free build notes)
frida_rpc_serve.py bridge a Frida script's rpc.exports to a local caller with reconnect
handling, so a live native function can be called rather than reversed
rpc_template.js the editable companion to frida_rpc_serve.py
stalker_trace.js instruction-level tracing with Frida Stalker: configurable targets,
trigger selection, the event stream, and output-size rules
stalker_report.py reduce a stalker_trace.js log to block histograms and call sequences,
with an explicit diagnostic for the measured zero-event case
mt_mcp_probe.py probe MT Manager's on-device APK MCP (Streamable HTTP, port 8787):
JSON-RPC handshake plus the grouped tool inventory
```
## Install
@@ -322,12 +378,17 @@ target-specific data.
What it covers, and what it deliberately does not, is stated at the top of `SKILL.md`
under **Coverage**. The short version: Android only (no iOS), and deep on the layers
that have been worked through for real — dex patching, repacking, packers and custom
loaders, native tamper response, and Flutter/Dart AOT. Unity/IL2CPP logic recovery,
loaders, native tamper response, and Flutter/Dart AOT. An extension pass added a second
tier of documented routes: **module-side delivery** when a repack is blocked,
**extraction-shell recovery** and its VMP boundary, **emulation and live RPC** for
calling rather than reading, **instruction-level tracing** against OLLVM, **protocol
reversing** beyond REST, the **kernel-side route** map for when userspace hooking is
provably out of reach, and **on-device tooling**. Unity/IL2CPP logic recovery,
React Native/Hermes bytecode internals, and defeating a server-side authority are **not**
covered, and the skill is written to say so and stop rather than apply the nearest
documented procedure to a target it was not written for.
Two qualifications that the Coverage section states in full and that belong here too:
Three qualifications that the Coverage section states in full and that belong here too:
- **Flutter/Dart AOT analysis has a dependency.** The workflow begins at a pool listing
(`pp.txt`-class output). Producing that needs a snapshot-decoding decompiler — aotopsy (a static
@@ -337,6 +398,10 @@ Two qualifications that the Coverage section states in full and that belong here
what was actually measured, on which target, and with which independent cross-check; anything not
covered there is documented from experience and should be read as *inferred*, per this skill's own
claim ladder.
- **The extension pass is recorded separately and is mostly *inferred*.** Its evidence lives in
`docs/tool-verification/EXTENSION-*.md`, one file per topic, with its own strength note. The
common shape there is *the tool was measured, the route was not* — so read those files before
treating any of the newer documents as a verified path.
## Repository maintenance
@@ -0,0 +1,252 @@
# Extension pass — on-device run against a hardened Flutter sample
This file records the **device-side** half of the extension pass: what was actually executed against
a live, hardened sample, what the sample did in response, and which conclusions the evidence supports.
It follows the same three labels the rest of this directory uses:
- **observed** — reproduced here, with the exact command and its output.
- **inferred** — follows from observed facts, but the step itself was not executed.
- **unverified** — assumed, or reported by a tool and not independently confirmed.
**Target identity is deliberately absent.** The sample is referred to as *the sample*, and its package
identifier appears as `<PKG>`. The findings are about the tools and the methods, and stay valid
whichever hardened APK produced them.
## Environment (observed)
| Item | Value |
|---|---|
| Device | one physical arm64 device, Android 11 (API 30), kernel 4.14.186, Magisk root |
| Host | Windows 11, Python 3.14.0, frida 16.7.19, frida-tools 13.7.1, frida-dexdump 2.0.1, java 17, adb 1.0.41 |
| Device server | `frida-server` 16.7.19 (version-matched to the host by `frida-server --version`) |
| Sample | 360-jiagu hardened, `application android:name` = a third-party stub class; Flutter AOT payload |
| Host capability report | `python scripts/doctor.py` → static/repack/smali/native-patch/device/root/frida all OK; `28 / 28` scripts runnable |
| Pre-flight warnings | clock skew 3.32 s; leftover `adb forward` entries (8787, 8651, 65534, 27043); a device-side `frida-server` already running |
Two environment facts from `doctor.py` are worth carrying forward, because each of them silently
invalidates a measurement: the clock skew, and a **frida process already up on the device** — the
second one means the target may already be reacting to instrumentation before your first command.
## The measurement that mattered: the sample fights instrumentation
### (1) Control — the sample starts normally with no instrumentation (observed)
```
$ adb shell 'su -c "am force-stop <PKG>; sleep 1; am start -n <PKG>/.MainActivity"'
$ sleep 12 && adb shell 'su -c "ps -A | grep -i <PKG>"'
u0_a623 22691 17278 14123672 642488 SyS_epoll_wait 0 S <PKG>
```
Resident, 642 MB, healthy. **This is the control build the rest of the section is measured against.**
### (2) The pid drifts — but **not** because of frida (observed, corrected)
During the session the sample's pid changed repeatedly:
```
22691 → 23452 → 24267 → 27274 → 31284 → 32259 → 1368 → 8161
```
The natural reading is "the sample fights instrumentation", and the first write-up of this file said
exactly that. **The follow-up measurement refuted it.** With `frida-server` stopped and no attach of
any kind, the sample was restarted under observation for 90 seconds:
```
20:28:22 pid=[9961] load=36.43 | Mem: 11484 total 11077 used 406 free
20:28:33 pid=[9961] load=36.26 | Mem: 11484 total 10767 used 716 free
20:28:45 pid=[9961] load=35.61 | Mem: 11484 total 10739 used 745 free
20:28:56 pid=[9961] load=34.64 | Mem: 11484 total 10767 used 716 free
20:29:08 pid=[11246] load=34.91 | Mem: 11484 total 11151 used 333 free
20:29:19 pid=[11246] load=35.69 | Mem: 11484 total 11142 used 342 free
20:29:31 pid=[12238] load=35.14 | Mem: 11484 total 11131 used 353 free
20:29:42 pid=[13212] load=37.03 | Mem: 11484 total 11059 used 424 free
```
The pid changes with **no frida present**, roughly every 10-20 seconds, while the device sits at
300-750 MB of free memory out of 11.5 GB. The first correction to this file attributed that to memory
pressure. **That attribution was also wrong, and the device-side dumping run refuted it** with a
better instrument than sampling: `logcat`.
```
$ adb logcat | grep <PKG>
Process <PKG> (pid N) has died: fg TOP
Start proc <pid> for top-activity <PKG>
```
The process **dies as the foreground top activity, with no crash, no tombstone and no ANR record**,
and the platform immediately relaunches it — a clean self-exit in a loop, on a 7-18 second cycle. A
reclaiming device does not do that to a foreground process, and a memory-pressure kill leaves an
`lmkd` line and a low-memory record. What produces exactly this shape is the sample **checking its own
environment and quitting on purpose**.
And the environment it finds is decisive: on this device `magisk --denylist status` reports **enforced
with an empty list**, Zygisk-Assistant is installed but nothing is scoped, and
`/data/adb/shamiko` does not exist — so **no application on this device is hidden from root**
(`EXTENSION-lsposed.md`, observed). A hardened sample that refuses to run on a rooted device will do
exactly this, forever, and no amount of dump-retrying changes it.
**Reading, corrected twice:** the pid drift is an artefact of the **root environment**, not of
instrumentation and not of memory pressure. The practical consequence is the useful part — *before any
dynamic analysis of a hardened sample, configure root hiding and re-run the baseline*, because with
nothing hidden every dynamic result on this device is measured against a process that is trying to die.
The observer's first control run showed a "stable" sample for 12 seconds only because it happened to
sample inside one 17-second lifetime.
This is the skill's own rule applied twice to its own record: a conclusion was reopened each time a
measurement disagreed with it (`SKILL.md` §Stop conditions, last bullet). Two wrong attributions were
cheaper to delete than for a reader to inherit — and the second one only fell because a different
method (`logcat`, not sampling) was pointed at the same question.
The platform's own view of a failed launch was also captured, and is worth keeping as a *shape*:
```
W ActivityManager: Process ProcessRecord{…:<PKG>/u0a623} failed to attach
I ActivityManager: Killing <pid>:<PKG>/u0a623 (adj -10000): start timeout
```
A `start timeout` kill reads the same whether the cause is a slow shell init, a reclaiming device, or a
deliberate delay. It does not discriminate, and it is not evidence either way.
### (3) `frida-dexdump` cannot complete a memory dump — reproduced twice (observed)
Both spawn and attach were tried, with the parameter mistakes fixed between attempts:
```
$ frida-dexdump -U -f <PKG> -d -o <out> # spawn
Failed to spawn: need Gadget to attach on jailed Android; its default location is: …gadget-android-arm64.so
$ frida-dexdump -U -f <PKG> -d 12 -o <out> # 12 was parsed as an argv entry, not a delay
Failed to spawn: the 'argv' option is not supported when spawning Android apps
$ frida-dexdump -U -f <PKG> -d -o <out> # corrected
Failed to spawn: unexpectedly timed out while waiting for app to launch
$ frida-dexdump -U -p <pid> -d -o <out> # attach, twice, second run with the device idle
frida.InvalidOperationError: script has been destroyed: {'addr': '0x721e24c02c', 'size': 409556}
INFO:frida-dexdump:[*] All done... Process terminated
```
Attach was run twice. The **second** run was the clean one: no Stalker traffic anywhere on the device
(see the crash note below), the package enabled and verified running, the pid read immediately before
the attach, and a single variable changed relative to the control. It produced the same
`script has been destroyed` failure, and the sample's pid changed again in the aftermath.
**What the failed runs left behind, checked with the kit's own validator** (`observed`):
```
$ python skills/apk-reverse/scripts/dex_dump_validate.py <dump_dir>
== dex dump validation: 2 file(s), 2 parse, 0 rejected ==
name size sha256[:12] ver cksum sig class noco code stub%
classes.dex 500 9461987e5464 035 BAD BAD 1986754560 0 0 0.0%
walk stopped early: index out of range
classes02.dex 10285489 116d8b84b486 035 BAD BAD 1986754560 0 0 0.0%
walk stopped early: index out of range
```
Both artifacts pass the magic check and then fail everything else: checksum and signature both BAD,
no classes recovered, the walk stopping on an out-of-range index. They are **memory fragments cut
short by the process dying mid-read**, not dex images — and this is exactly the case
`dex_dump_validate.py` exists for. A size-based heuristic would have kept the 10.2 MB file and
discarded the 500-byte one; both are worthless, and only a structural walk says so.
**Reading:** under these conditions the memory-dump route is refused by the target, not by the host
tooling. Two shape-identical failures on a single variable is the skill's own stop signal: the correct
move is to re-classify (`references/advanced-unpacking.md` §the four shapes, then
`references/detection-and-anti-analysis.md`), **not** to run a third variant of the same attach.
Two of the four failures above were the observer's own mistakes, and they are worth keeping because
they are cheap to repeat: `-d` is a switch, not a delay, and any extra positional argument reaches
`spawn(argv)`. `-n <name>` on this version of `frida-dexdump` also still routes through the spawn
path, so "attach by name" does not exist as a way around the spawn refusal — use `-p <pid>`.
### (4) What the sample looks like at the moment it is attacked (observed)
```
$ adb shell 'su -c "top -n 1 -b"'
PID USER PR NI VIRT RES SHR S[%CPU] %MEM TIME+ ARGS
31284 u0_a623 10 -10 13G 561M 268M S 439 4.8 0:05.52 <PKG>
154 root 20 0 0 0 0 S 66.6 0.0 0:02.18 [kswapd0]
17638 system 18 -2 12G 590M 419M S 60.6 5.1 1:15.93 system_server
```
A Flutter application in its startup window saturates several cores (439 % CPU) while the Dart VM
initialises, and the device — 11.7 GB RAM with 357 MB free at that moment — runs its reclaim thread at
two thirds of a core. **The load on this device during the experiment was the sample's, not the
observer's instrumentation.** That matters for attribution: "the device is slow, so the dump failed"
is not available as an explanation here, because the failing command is a *protocol* failure
(`script has been destroyed`) rather than a timeout.
## The device's own framework was already damaged (observed)
Recorded here because it is a **third candidate mechanism** for "things keep restarting", alongside the
sample's self-exit and the memory pressure — and because it invalidates any dynamic result that
depends on the hooking framework:
- `LSPosed Manager` opened to **"LSPosed is not installed"**, with no modules tab, while the `lspd`
daemon was still alive.
- The LSPosed configuration database had not been updated since **19:37** — it still pointed at the
`codePath` of an app that had been uninstalled, and never registered the replacement.
- `logcat` showed a loop: `system server died`, `am is dead`, `no response from bridge`, and
`Magisk: zygote crashed too many times, rolling-back`.
A zygote in a crash-and-rollback cycle restarts application processes by itself, so **"the pid changed"
had at least three independent possible causes on this device** (the sample exiting, reclaim, and a
broken framework). That is exactly why the corrected §2 attributes the drift to *instability of the
observation target* rather than to any single mechanism, and why a dynamic result needs its device's
framework state recorded next to it — `scripts/preflight.py` reads device state for the same reason.
Recovery is a reboot (Magisk re-initialises Zygisk and `lspd` at `late_start`; the LSPosed daemon is
started once and does not return if killed). Whether the framework came back after the reboot, and
whether the sample's self-exit behaviour changed with it, is recorded in
`EXTENSION-lsposed.md` — and any change there must stay **inferred**, because a reboot moves several
variables at once.
## A shared-device hazard, measured (observed)
While the run above was in progress, a second agent on the same device used **Frida Stalker** against
`com.android.settings` and `com.android.systemui`, including a `libc` `malloc` export trigger that
entered and left `follow` hundreds of times. Result:
- `Stalker.follow` on the main thread reported `blocks=0`, `blk=0`, `calls=0` — **the follow installed
and no events arrived**.
- `systemui` then died with `SIGSEGV`, the faulting frame sitting in gum's anonymous code cache and
the backtrace continuing into `libart` at `art::Reference_getReferent`; the process restarted
(`18030 → 26932`).
- Device load average reached **34.11** on an eight-core phone.
**Reading:** two conclusions, kept separate on purpose. First, on this ROM + `frida-server` 16.7.19
combination a Stalker follow produced no events — that is a *boundary* for
`references/native-dbi-and-deobfuscation.md`, not a contradiction of Stalker's documentation. Second,
high-frequency `follow`/`unfollow` on every `malloc` entry crashed a system process — a measured
failure mode for the pattern, and one worth stating before anyone puts it in a shipped script.
The third conclusion is about method rather than about Stalker: **instrumentation on a shared device
is a shared variable.** The concurrent load damaged the *other* experiment's validity — the dumped-run
above could not be attributed until it was repeated with the device idle, and the repeat is what
turned "maybe the load broke it" into a reproducible protocol refusal. R2 (one variable at a time)
applies across agents, not only within one script.
## Conclusions, graded
| Claim | Label |
|---|---|
| The sample runs healthy with no instrumentation on the device | observed |
| The sample's pid drifts repeatedly during an experiment, roughly every 10-20 s | observed — **cause not instrumentation**: reproduced with `frida-server` stopped, under 300-750 MB free memory (§2) |
| `frida-dexdump` spawn refuses (jailed / argv / timeout) and attach fails with `script has been destroyed`, reproduced twice with the parameter mistakes fixed | observed |
| The attach failure is deliberate armour rather than a host-tool bug | **unverified** — memory pressure leaving the process an unstable target is a competing explanation this pass did **not** rule out; the single-variable repeat eliminated *concurrent* load, not *baseline* load |
| The shipped shell `classes.dex` is 8.9 MB and defines only 4 classes / 29 methods with code | observed (recorded in `EXTENSION-unpacking.md`) |
| Recovering the real bodies needs a route other than a `frida` memory dump on this target | inferred |
| Stalker follow delivers no events on this ROM with this frida-server version | observed, single sample, `unverified` as a general rule |
| High-frequency follow/unfollow on `malloc` can crash a system process | observed, once |
| No app on this device is currently hidden from root (`magisk --denylist status` enforced, list empty; Zygisk-Assistant installed but nothing configured) | observed (recorded in `EXTENSION-lsposed.md`) — offered here because a hardened sample's sensitivity to a rooted device has a configuration, not just a cause |
## What this pass did **not** establish
- **Not** a successful end-to-end unpack of the sample. The memory-dump route was refused, and the
pass stopped at the skill's own two-strike rule instead of escalating into an evasion arms race.
- **Not** evidence that the sample is un-unpackable. The routes that do not use `frida` on the device
— root-side `/proc/<pid>/mem` extraction, the module route in `references/lsposed-and-modules.md`,
and the static route already recorded for the Flutter payload — were not exhausted here.
- **Not** a general claim about 360-jiagu, Flutter, or Android 11. Everything above is one device,
one ROM, one server version, one sample.
@@ -0,0 +1,431 @@
# Extension verification — offline emulation (unidbg) and Frida RPC
Covers the 2026-09 extension pass that added `references/emulation-and-rpc.md`,
`scripts/frida_rpc_serve.py` and `scripts/rpc_template.js`. Strength labels as defined in this
directory's README: **observed** (exact command + output recorded here), **inferred** (follows from
observed facts, step not executed), **unverified** (assumed or externally reported, not independently
confirmed here).
Reference environment for this pass: Windows host, Python 3.14.0, host `frida` 16.7.19 +
`frida-python` 16.7.19 (frida-tools 13.7.1), `adb` 37.0.1, JDK 17.0.4.1 (with `JAVA_HOME`
**unset** in the shell — see §5). Device `<DEVICE>`: Android 11 / API 30, arm64-v8a, rooted
(Magisk), on-device frida-server 16.7.19. Workbench artifacts live in `tools/_work/t3-rpc/` (not part
of the skill).
**Device-exclusivity constraint during this pass**: another task was unpacking the hardened Flutter
sample on the same device. This pass never attached to, spawned or force-stopped that sample's
process, and never killed or restarted the device-side frida-server. All RPC work targeted unrelated
processes (system apps and third-party apps). De-identification: the sample's package label, real
package name and md5 are elided in this document as `com.example.app` / `<label>`; command shapes,
counts, class names and timings are verbatim.
---
## 0. Summary of what this pass established
| Claim | Label |
|---|---|
| `droidasc` 0.1.1.post1 and `ddc` 0.1.8 both run on this host; both read the hardened sample's shell dex | observed |
| Both tools see only the 4 shell classes in the APK's dex; business classes are absent (shell dex only) | observed |
| `frida_rpc_serve.py` `--help`, all three modes, reconnect, spawn and attach-by-pid work against a live device | observed |
| Attach **by package name** fails on this ROM while attach **by pid** succeeds for the same process | observed |
| The device-side server may be (re)started on a non-default port; `--remote HOST:PORT` recovers, device-serial lookup does not | observed |
| unidbg 0.9.10-SNAPSHOT builds and boots an Android emulator on this host after a pom fix; one bundled test suite passes | observed |
| Any target `.so` actually emulated under unidbg | **not done** (unverified) |
| frida 17 compatibility of `rpc_template.js` export lookup | unverified (host has 16.7.19 only) |
---
## 1. ASC (`droidasc`) — observed
### 1.1 Install and version
```
$ python -m pip show droidasc
Name: droidasc
Version: 0.1.1.post1
Summary: ASC is a super FAST python Android Decompiler for Agents/Mobile Researchers
License-Expression: Apache-2.0
Location: C:\Python314\Lib\site-packages
Requires: androguard
```
Install line used (recorded after the fact; the package was already present on this host):
`python -m pip install droidasc`. Distribution metadata declares only `androguard` as a dependency —
**no JVM is required** (unlike the `asc` successor tooling in the upstream MG1937/ASC repository,
which is a separate project). The console script is named **`droidasc`**, not `asc`: there is no
`asc.exe` in `C:\Python314\Scripts`, and `asc --version` fails with
`The term 'asc' is not recognized...`. `python -m droidasc` is the equivalent entry point.
### 1.2 Subcommands
```
$ python -m droidasc --help
usage: python.exe -m droidasc [-h]
{getclass,listclass,getmanifest,findrefs} ...
ASC tooling entry.
positional arguments:
{getclass,listclass,getmanifest,findrefs}
getclass Locate the target class in APK, extract one DEX in memory, then decompile.
listclass List classes across all DEX entries; use --prefix to filter by package/class prefix.
getmanifest Decode AndroidManifest.xml from APK and print it as XML.
findrefs Find code references for string/type/method/field across all DEX entries in APK.
examples:
droidasc app.apk --gui
droidasc getclass app.apk Lcom/poc/Main; -o Main.java
droidasc listclass app.apk --prefix com.poc
droidasc getmanifest app.apk -o AndroidManifest.xml
droidasc findrefs app.apk string token -o string_refs.txt
```
`--gui` and the bundled `asc_client` web UI were **not** exercised (unverified, headless pass).
### 1.3 Measured against the sample
```
$ droidasc getmanifest <sample>.apk -o asc-manifest-verify.xml # 0.44 s, 32,345 B
<manifest ... package="com.example.app" platformBuildVersionCode="34" ... android:versionCode="1143"
android:versionName="0.9.0" android:compileSdkVersion="34" ...>
<uses-sdk android:minSdkVersion="19" android:targetSdkVersion="28"/>
<uses-permission android:name="android.permission.INTERNET"/>
... (permissions list follows; manifest decodes cleanly)
$ droidasc findrefs <sample>.apk string jiagu -o asc-findrefs-jiagu.txt # 0.42 s
classes.dex | Lcom/stub/StubApp;-><clinit> | matched=(libjiagu)
classes.dex | Lcom/stub/StubApp;->attachBaseContext | matched=(/.jiagu; jiagu; jiagu_x86)
$ droidasc getclass <sample>.apk com.stub.StubApp -o asc-StubApp-verify.java # 0.33 s, 22,802 B
package com.stub;
public final class StubApp extends android.app.Application { ... }
$ droidasc listclass <sample>.apk --prefix com.stub # 0.23 s
Lcom/stub/StubApp;
$ droidasc listclass <sample>.apk -o asc-listclass-all.txt # 0.18 s, 4 lines
Lcom/stub/StubApp;
Lcom/tianyu/util/Configuration;
Lcom/tianyu/util/DtcLoader;
Lcom/tianyu/util/a;
```
`findrefs` reports the shell's own strings (`libjiagu`, `jiagu_x86`, `/.jiagu`) — i.e. the packer
signature is visible without unpacking, but nothing of the application is.
### 1.4 Limits hit
```
$ droidasc getclass <sample>.apk com.example.app.MainActivity -o asc-mainactivity.java
Error: Class Lcom/example/app/MainActivity; not found in APK.
exit = 1
```
**This is the limit that matters for this sample class:** the full class listing is 4 classes, so on
a packed APK ASC is a manifest + shell-inspector, not an application decompiler. The application code
lives in that shell's payload (`assets/`, the native unpacker and the AOT/Flutter layer), which ASC
does not touch. ASC still earns its place in the flow: `getmanifest` in under half a second is the
fastest manifest pass measured in this repository's tool set, and `findrefs` on shell class names is
how the packer was identified here.
Observed behaviours worth knowing: `droidasc` prints per-command timing nowhere, writes to `-o` only,
and returns a clean `Error: ...` line plus exit 1 when a class is missing.
---
## 2. ddc — observed
### 2.1 Version and acquisition
```
$ bin/ddc.exe -V
ddc 0.1.8 — DEX → Java decompiler
https://github.com/ejfkdev/ddc
```
`ddc` is a Rust binary (upstream: [ejfkdev/ddc](https://github.com/ejfkdev/ddc)); the Windows build
used here is `tools/_work/t3-rpc/bin/ddc.exe`, 1,028,096 B, **not on `PATH`** and with no version
resource in the PE header (`VersionInfo` empty), so `ddc -V` is the only way to learn its version.
No JVM, no Python. Subcommands advertised by `ddc help`: `info`, `listclasses`, `manifest`,
`mainactivity`, `res`, `strings`, `findrefs`, `callers`, `members`, `hierarchy`, `largest`, `disasm`,
`getclass`, `getmethod`, plus a full-decompile mode (`ddc <INPUT>... [OUTPUT]`).
### 2.2 Measured against the sample
```
$ bin/ddc.exe info <sample>.apk # 0.24 s
label <label>
package com.example.app
version 0.9.0 (1143)
application com.stub.StubApp
launcher com.example.app.MainActivity
sdk 19–28
size 36.9 MB (38688120 bytes)
md5 1a037a045205184d4e8272092997334f
image dex classes methods fields strings
<sample>!classes.dex 035 4 266 23 481
total: 1 image(s), 4 classes
$ bin/ddc.exe findrefs <sample>.apk string jiagu # 0.13 s
dex kind class method refs
classes.dex const-string com/stub/StubApp <clinit>()V "libjiagu"
classes.dex const-string com/stub/StubApp attachBaseContext(...)V "jiagu_x86"; "jiagu"; "/.jiagu"
$ bin/ddc.exe strings <sample>.apk -f jiagu --with-locations # 0.14 s
dex string used-by
classes.dex "/.jiagu" com/stub/StubApp attachBaseContext(Landroid/content/Context;)V
classes.dex "jiagu" com/stub/StubApp attachBaseContext(Landroid/content/Context;)V
classes.dex "jiagu_x86" com/stub/StubApp attachBaseContext(Landroid/content/Context;)V
classes.dex "libjiagu" com/stub/StubApp <clinit>()V
```
`ddc info` reaches the same conclusion as ASC by a different route (class/method/string counts per
dex image) and adds the resources-derived label and the launcher verification; `findrefs` output is
tabular and one line per (method, string) pair, which is directly pasteable into a report.
### 2.3 Limits hit
```
$ bin/ddc.exe getclass <sample>.apk com.example.app.MainActivity
ddc: class com.example.app.MainActivity not found in the selected image(s)
(try `ddc listclasses <input> <pattern>`)
exit = 2
```
Exit codes measured on this build: `info` → 0, `-V` → 0, `getclass` with a missing class → **2**.
The missing-class path also reprints the full help text on stdout, so a wrapper that only checks
"did anything print" will misread it as success — key off the exit code. As with ASC, the packed APK
exposes only the shell dex; `ddc` cannot see application classes either, which is a property of the
artifact, not of the tool.
---
## 3. Prior-attempt outputs under test — and the defects found
`skills/apk-reverse/references/emulation-and-rpc.md`, `scripts/frida_rpc_serve.py` and
`scripts/rpc_template.js` were already on disk from an interrupted attempt of this task. This pass
read all three, ran the script, and fixed four defects. `rpc_template.js` needed no change.
| # | Defect (observed) | Fix |
|---|---|---|
| 1 | `RpcBridge._teardown()` never detached the session and used `obj.off(...) if obj is self.session else None` / `obj.unload() if hasattr(obj, "unload")` — a script object has `unload()`, a session has `detach()`, so the expression released only the script. Every `reload()`/reconnect cycle leaked one attached session on the device. | Rewritten to unload the script, remove the `detached` handler and `session.detach()` explicitly. |
| 2 | `list_exports()` called `Script.list_exports()`, which frida 16.7.19 answers with `DeprecationWarning: Script.list_exports will become asynchronous in the future, use the explicit Script.list_exports_sync instead` (printed on every `list` command). | Tries `list_exports_sync` first, then the old name, then local introspection. |
| 3 | `--mode call` raised out of `main()`: an unknown export produced `frida`'s own `unable to find method 'x'` and a raw Python traceback; a bad `--args` value dumped a `JSONDecodeError` traceback. Scripted callers got a stack trace instead of a result. | `run_call_mode()` now returns one JSON object (`{"ok": false, "error": ...}`) and exit code 1 for both cases; `call()` consults the advertised export list first so the message is `no such rpc export: nope (available: add ping ...)`. |
| 4 | `frida.TimedOutError` was absent from the retry whitelist. It is **not** a `TransportError` subclass (`frida.TimedOutError.__mro__` → `(TimedOutError, Exception, BaseException, object)`), so a device that timed out during attach produced a traceback in an otherwise recoverable situation — reproduced live (§4.4). | Retryable types are now collected by name into `RETRYABLE` (TransportError, NotSupportedError, ServerNotRunningError, ProcessNotFoundError, InvalidOperationError, TimedOutError) and used by both `ensure()` and the initial connect in `main()`. |
Post-fix evidence:
```
$ python skills/apk-reverse/scripts/frida_rpc_serve.py --remote 127.0.0.1:27043 --pid 19938 \
--script skills/apk-reverse/scripts/rpc_template.js --mode call --export add --args "[40, 2]"
{"ok": true, "export": "add", "result": 42} exit = 0
$ ... --mode call --export nope
{"ok": false, "export": "nope", "error": "no such rpc export: nope
(available: add ping getpackagename callnative callnativeaddr)"} exit = 1
$ ... --mode call --export add --args "not-json"
{"ok": false, "error": "--args is not valid JSON: Expecting value: line 1 column 1 (char 0)"}
exit = 1
```
Known cosmetic behaviour left as is: in `--mode call` the bridge connects before `--args` is parsed,
so a bad-args invocation still performs a device attach.
## 4. Frida RPC against the live device — observed
### 4.1 Attach path: by name fails, by pid works
Attach **by package name** failed for every package tried, with the process demonstrably alive in
both `frida-ps -Uai` and `ps -A`:
```
$ python ...frida_rpc_serve.py --device-serial <DEVICE> --package com.android.settings ...
[bridge] connect failed (unable to find process with name 'com.android.settings'); retry 1 in 1.0s
... (5 attempts) ...
initial connect failed: could not (re)connect after 5 attempts
$ python ... --package io.github.vvb2060.magisk ...
[bridge] connect failed (unable to find process with name 'io.github.vvb2060.magisk'); retry 1 in 0.5s
initial connect failed: could not (re)connect after 1 attempts
```
The same processes attach normally by pid:
```
$ python ... --pid 19938 --mode call --export getpackagename
{"ok": true, "export": "getpackagename", "result": "com.android.settings"}
$ python ... --pid 21493 --mode call --export getpackagename
{"ok": true, "export": "getpackagename", "result": "com.android.email"}
```
So the gap is in the **name→pid lookup** the server serves, not in injection: `--pid` definitely
does bypass it. `references/emulation-and-rpc.md` had claimed the opposite ("`--pid` does not bypass
a gap that hides the process from the server's own table"); that row was corrected in this pass, and
the corrected wording is what the reference now carries.
### 4.2 The transport itself
| # | Command (pid 19938 = `com.android.settings`, unrelated to the sample) | Result |
|---|---|---|
| 1 | `--mode call --export add --args "[40, 2]"` | `{"ok": true, "result": 42}` |
| 2 | `--mode call --export ping` | `{"ok": true, "result": "pong"}` |
| 3 | `--mode call --export getpackagename` | `{"ok": true, "result": "com.android.settings"}` |
| 4 | `--mode call --export callnative --args '["libc.so","getpid","int",[],[]]'` | `{"ok": true, "result": 19938}` (matches the pid — `NativeFunction` wrapping works) |
| 5 | `--mode repl`, feeding `list` / `reload` / `list` / `add [40, 2]` / `nope` | `add ping getpackagename callnative callnativeaddr`; `reloaded`; same list; `42`; `error: no such rpc export: nope (available: ...)` |
| 6 | `--mode http`, `GET /exports` | `{"ok":true,"exports":[...5 names...]}` |
| 7 | `--mode http`, `POST /call {"export":"add","args":[40,2]}` | `{"ok":true,"result":42}` |
| 8 | `--mode http`, `POST /call {"export":"getpackagename","args":[]}` | `{"ok":true,"result":"com.android.settings"}` |
| 9 | `--mode http`, `POST /call` with an unknown export | HTTP 502 + `{"ok":false,"error":"no such rpc export: nope (available: ...)"}` |
| 10 | `--mode http`, `POST /reload` then `POST /call add [1,2]` | `{"ok":true}` then `{"ok":true,"result":3}` — the re-attach path works, and no `DeprecationWarning` is printed any more |
| 11 | `--spawn --package io.github.vvb2060.magisk --mode call --export getpackagename` | `{"ok": true, "result": "io.github.vvb2060.magisk"}` (spawn → script load → resume → RPC) |
Every script load also delivered the template's own liveness message:
`[script] {"ev": "RPC-READY", "exports": ["add","ping","getpackagename","callnative","callnativeaddr"]}`.
That line is the cheapest health check for a session and is worth grepping for in automation.
### 4.3 The server's port moved under us
Mid-pass, `--device-serial <DEVICE>` began failing on attach while `frida-ps -U` kept working:
```
$ python ... --device-serial <DEVICE> --pid 19938 ...
[bridge] connect failed (unable to connect to remote frida-server: closed); retry 1 in 1.0s
... (3 attempts) ...
$ python -c "import frida;d=frida.get_device('<DEVICE>');d.attach(19938)"
attach failed: ServerNotRunningError unable to connect to remote frida-server: closed
$ adb -s <DEVICE> shell 'su -c "ps -A"' | Select-String 'svc16|frida'
root 1876 1 2227684 55288 do_sys_poll S .svc16 # only this instance alive
$ adb -s <DEVICE> shell 'su -c "netstat -ltnp"' | Select-String 2704
tcp 0 0 0.0.0.0:27043 0.0.0.0:* LISTEN 1876/.svc16 # nothing on 27042
```
The visible `frida-server` process (pid 23405) was gone; a disguised copy (`.svc16`, pid 1876) was
listening on **27043 only**. `frida-ps -U` still worked because frida's USB transport probes a range
of ports, while the scripted device-serial path landed on a dead default port. Recovery, with the
forward already present (`adb forward --list` shows `tcp:27043 tcp:27043`):
```
$ python ... --remote 127.0.0.1:27043 --pid 19938 --mode call --export getpackagename
{"ok": true, "result": "com.android.settings"}
```
This pass neither started nor killed any server instance; it only observed that the instance changed
and switched to the explicit `--remote` form. That form is now the recommended one in the reference's
failure table.
### 4.4 A third-party process that refuses the handshake
```
$ python ... --remote 127.0.0.1:27043 --pid 19984 --mode call --export getpackagename
frida.TimedOutError: unexpectedly timed out while waiting for signal from process with PID 19984
```
An ordinary third-party app process (`com.xunmeng.pinduoduo`, listed by `frida-ps -Uai`) simply did
not answer the agent handshake within frida's timeout. Pre-fix this surfaced as a traceback; post-fix
the bridge treats it as retryable and reports `initial connect failed: ...` with exit 2. This is an
app-side property, not a bridge property — for connectivity probes prefer a system or stable app
process.
### 4.5 Device state after the pass
`frida-ps -U` and `frida-ps -Uai` both still answer; the sample's process was never touched; the
device-side server was never killed or restarted by this pass.
---
## 5. unidbg — observed (build/boot) and unverified (target emulation)
### 5.1 Build
```
$ git clone --depth 1 https://github.com/zhkl0228/unidbg.git # version 0.9.10-SNAPSHOT
$ .\mvnw.cmd -B -pl unidbg-android -am -DskipTests compile
Error: JAVA_HOME not found in your environment. # JAVA_HOME was unset on this host
...
[ERROR] Failed to execute goal ...maven-compiler-plugin:3.3:compile on project unidbg-api:
[ERROR] .../AbstractARMDebugger.java:[79,43] reference to Module is ambiguous
[ERROR] both com.github.unidbg.Module and java.lang.Module match
```
The shipped pom pins `<source>8</source><target>8</target>` with `maven-compiler-plugin` 3.3. On
JDK 9+ that pair does **not** select the JDK 8 API, so `java.lang.Module` stays visible and every
unqualified `Module` in `AbstractARMDebugger` becomes ambiguous — the build dies in `unidbg-api`.
Two local work-copy changes fix it (recorded in `tools/_work/t3-rpc/unidbg/pom.xml`, not part of the
skill and not committed):
```
maven-compiler-plugin 3.3 -> 3.8.1 # 3.13 is rejected: the bundled wrapper is Maven 3.5.4,
# and 3.13 requires Maven >= 3.6.3
<source>8</source><target>8</target> -> <release>8</release> # hides java.lang.Module
```
Result with `JAVA_HOME=C:\Program Files\Java\jdk-17.0.4.1`:
```
$ .\mvnw.cmd -B -pl unidbg-android -am -DskipTests compile
[INFO] unidbg-api ......... SUCCESS [ 40.838 s]
[INFO] unidbg-android ..... SUCCESS [ 4.941 s]
[INFO] BUILD SUCCESS (total 48.4 s, after a one-off dependency download)
```
### 5.2 Boot check
The pom sets `<maven.test.skip>true</maven.test.skip>`, so `-Dmaven.test.skip=false` is required to
run anything:
```
$ .\mvnw.cmd -B -pl unidbg-android -am -Dmaven.test.skip=false \
-Dtest=MemoryTrackerTest -DfailIfNoTests=false test
Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
Backend: DynarmicBackend64
=== Memory Leak Report === ... Address: 0x12000000, Size: 4096 ...
[INFO] BUILD SUCCESS
```
This proves the toolchain end to end at the *environment* level: emulator construction, memory
allocator, backend selection (Dynarmic, with Hypervisor and Unicorn2 factories registered) and
Android 11 (`AndroidResolver(23)`-style) library resolution all execute on this host.
### 5.3 What was **not** done — unverified
* Loading and calling **any** target `.so`, including this sample's `libjiagu*.so` or `libapp.so`.
No `createDalvikVM`, `loadLibrary`, `callJNI_OnLoad` or `AbstractJni` stub was exercised.
* Consequently every per-library statement in `references/emulation-and-rpc.md` §Part A — which JNI
callbacks a hardened library demands, how many stub rounds it costs, which `/proc` or signature
checks it runs — remains **inferred** from the library's shape and community practice. The
reference's "Measured here" section was rewritten in this pass to say exactly that.
* Note for anyone porting an older tutorial: `emulator.createCode()` / the `Assembly` helper class
do **not** exist in 0.9.10-SNAPSHOT (no `Assembly*.java` under the tree, no `createCode` symbol in
any module). Recipes that assemble raw ARM machine code through that API need the current
backend/JNI entry points instead.
* `unidbg-android`'s bundled demos (`TTEncrypt`, `SignUtil`, `QDReaderJni`, …) each expect their own
`.so`/APK to be placed first; none were run, so the demo names in the reference are pointers, not
verified commands.
---
## 6. Consolidated list of things that did **not** work (for the pass summary)
1. Attach by package name on this ROM (both `com.android.settings` and `io.github.vvb2060.magisk`
failed while listed by `frida-ps -Uai`). Workaround: pid, from `frida-ps -U` / `pidof`.
2. Device-serial attach once the device's server came back on 27043 — `ServerNotRunningError:
unable to connect to remote frida-server: closed`. Workaround: `adb forward` + `--remote`.
3. Attach by pid to `com.xunmeng.pinduoduo` — `frida.TimedOutError`; the process never answered the
handshake.
4. `asc` as a command name (the console script is `droidasc`), and `mvnw` without `JAVA_HOME`.
5. unidbg out of the box on JDK 17 (`Module` ambiguity) and unidbg tests out of the box
(`maven.test.skip=true`).
6. Application-class decompilation of a packed APK by either ASC or ddc (nothing to fix — the dex
simply is not there; this is the case that justifies the whole emulation/RPC route).
## 7. Artifacts produced by this pass
`tools/_work/t3-rpc/` (not committed): `asc-manifest-verify.xml`, `asc-StubApp-verify.java`,
`asc-listclass-all.txt`, `asc-listclass-stub.log`, `asc-getmanifest.log`, `asc-findrefs.log`,
`asc-findrefs-jiagu.txt`, `asc-getclass.log`, `ddc-info-verify.txt`, `ddc-findrefs-jiagu.txt`,
`ddc-strings-jiagu.txt`, `rpc-*.log` (one per command in §4), `bin/ddc.exe`, `unidbg/` (patched work
copy).
Files changed in the repository by this pass: `references/emulation-and-rpc.md` (corrected failure
table, corrected unidbg build recipe, corrected "Measured here" labelling, and a stale section
reference repointed to `SKILL.md` §Stop conditions) and `scripts/frida_rpc_serve.py` (the four fixes
in §3).
@@ -0,0 +1,121 @@
# Extension verification — kernel/environment hardening + on-device tooling
Covers the 2026-09 extension pass that added `references/kernel-and-environment-hardening.md`,
`references/on-device-tooling.md` and `scripts/mt_mcp_probe.py`. Strength labels as defined in
this directory's README: **observed** (exact command + output here), **inferred** (follows from
observed facts, step not executed), **unverified** (assumed or externally reported, not
independently confirmed).
Reference environment for this pass: rooted physical device, Android 11 (API 30), arm64-v8a,
kernel **4.14.186**, Magisk alpha + Zygisk, LSPosed v1.9.2 activated, Zygisk-Assistant v2.1.4
and MoveCertificate v1.6.2 installed (pending reboot merge), MT Manager 2.26.9 installed.
---
## 1. MT APK MCP probe — measured
### 1.1 `scripts/mt_mcp_probe.py` runs and reports correctly
`--help` works (argparse, three options). Observed:
```
$ python skills/apk-reverse/scripts/mt_mcp_probe.py --help
usage: mt_mcp_probe.py [-h] [--url URL] [--timeout TIMEOUT] [--json]
```
Full **observed** output of the probe in the service-down state, with the port forward in place:
```
$ adb forward --list
<serial> tcp:8787 tcp:8787
<serial> tcp:8651 tcp:8651
<serial> tcp:65534 tcp:65534
$ python skills/apk-reverse/scripts/mt_mcp_probe.py
[waiting] MCP server is not answering at http://127.0.0.1:8787/mcp
The MT APK MCP must be started by hand in the MT UI (adb cannot start it):
1. On the phone: MT Manager -> side drawer -> Tools -> APK MCP -> Start
...
exit code 2
```
The failure was localised to the service (not the transport) on the device side — **observed**:
```
$ adb -s <serial> shell "su -c 'netstat -tln | grep 8787 || echo NOT_LISTENING'"
NOT_LISTENING
```
So at pass time: port forward alive, device reachable, MT's MCP service not started in the MT UI
(it requires a manual start that adb cannot perform). The script's designed degraded-mode
behaviour (waiting instructions + exit 2) is therefore **verified by observation**; the online
path (initialize handshake → grouped `mt_apk_*` inventory) is **unverified on this device** — it
was not exercised because the service was never started during the pass. The JSON-RPC shape
(initialize with `protocolVersion 2024-11-05`, `notifications/initialized`, `tools/list`,
`Accept: application/json, text/event-stream`) follows the MCP Streamable HTTP specification and
MT's documented transport; treat the exact response parsing as inferred until a live run.
### 1.2 What was deliberately not done
No attempt was made to start MT's MCP from adb (documented as impossible), and no scripted
tap-driver was built to press the UI button — that is a human step. The probe script doubling as
a "wait until up" check (exit 2 → retry after manual start) is the supported loop.
## 2. Phone-module environment — observed earlier, cited here
These facts were measured in the prior configuration pass and archived in
`tools/_phone-modules/README-手机模块环境.md` and `README-MCP与网络环境.md`; this pass cites them
rather than re-measuring. They count as **observed** (exact commands and outputs exist in those
archives):
- LSPosed v1.9.2 (7024) activation: log lines `ZygiskCompanion: welcome to LSPosed!`, version
banner, `lspd` daemon running as system, manager UI reporting activated.
- Zygisk requires one reboot after enable before `/data/adb/zygisk` exists; modules install to
`/data/adb/modules_update/` and merge into `/data/adb/modules/` only on reboot.
- Shamiko v1.2.5 kept as backup, **not** installed — documented conflict with Zygisk-Assistant
(both do root hiding); Zygisk-Assistant chosen because it does not depend on DenyList
enforcement.
- mcp-termux / stackplz eBPF route closed on this device: requires kernel 5.10+, device has
4.14.186; its bundled kmodules ship only 5.10/5.15/6.1/6.6/6.12 variants.
- MT Manager 2.26.9 installed; MCP port confirmed as 8787 in MT settings; forwards 8787/8651/
65534 established.
## 3. Kernel-level content — unverified / inferred, with sources
No kernel-level mechanism in `kernel-and-environment-hardening.md` was executed, on this device
or any other. Specifically **unverified here**: eBPF kprobe/uprobe tracing, seccomp-BPF
installation into a target, KPM/LKM hooking, self-ptrace anti-anti-debug, and every hiding claim
of Shamiko / Zygisk-Assistant against a real detector (the module archives also record that
hiding was never validated against an actual detection scenario).
The **inferred** claims that carry external sources (fetched 2026-09, URLs in the reference
file):
| Claim | Source |
|---|---|
| KernelSU: kernel-based su, official support GKI 2.0 = kernel 5.10+ (Android 12-era), backport to 4.14 requires self-built kernel; module system conflicts with Magisk magic mount; su-only coexistence possible (kernel vs ramdisk patching) | tiann/KernelSU README + FAQ (github.com) |
| APatch: KernelPatch patches stock boot.img kernel (no kernel source needed — the difference from KernelSU); SuperKey-gated SuperCall syscall; KPM kernel-space modules with inline/syscall-table hooks; SELinux hooked not rewritten; Shamiko officially unsupported | apatch.dev FAQ |
| Shamiko: reads Magisk denylist but requires DenyList enforcement OFF; whitelist mode via `/data/adb/shamiko/whitelist` with documented performance cost | Shamiko README (LSPosed distribution) |
| Zygisk-Assistant: Magisk use = target on denylist + Enforce OFF; KernelSU/APatch use = ZygiskNext + "Umount modules/Exclude modifications" | snake-4/Zygisk-Assistant README |
| GKI 2.0 starts at android12-5.10; eBPF extension docs target GKI kernels | source.android.com (kernel architecture section) |
The version gate consequence (eBPF row closed on 4.14) is **observed** for this device (uname)
and **inferred** as a general gate from the GKI sources above.
## 4. Not run / open items
- Live MCP handshake: blocked on a human UI action (start APK MCP in MT). The probe script is
ready; re-run and record the real `initialize` + `tools/list` output when it happens.
- Zygisk-Assistant + MoveCertificate merge: pending the device reboot recorded in the module
archive; their post-merge behaviour is untested.
- No LSPosed hook module was built or run against a real target in either pass — the framework
is activated (observed), the module workflow remains inferred.
## 5. Reproduction one-liners
```
python skills/apk-reverse/scripts/mt_mcp_probe.py # probe + inventory or waiting help
adb forward --list # confirm 8787 forward exists
adb -s <serial> shell "su -c 'netstat -tln | grep 8787'" # device-side listen check
adb -s <serial> shell uname -r # the 4.14 kernel gate, observed
```
+567
View File
@@ -0,0 +1,567 @@
# Extension verification — LSPosed module route
Covers the 2026-09 extension pass that added `skills/apk-reverse/references/lsposed-and-modules.md`
and `skills/apk-reverse/scripts/lsposed_scaffold.py`. Strength labels as defined in this directory's
README: **observed** (exact command + output here), **inferred** (follows from observed facts, step
not executed), **unverified** (assumed or externally reported, not independently confirmed).
Reference environment for this pass: rooted physical device, Android 11 (API 30), arm64-v8a,
Magisk alpha + Zygisk, LSPosed v1.9.2 (7024) activated, Zygisk-Assistant v2.1.4 installed, MT Manager
2.26.9 installed, one hardened Flutter sample installed (referred to below as *the sample*; no target
identity is recorded here). Host: Windows, JDK 17.0.4.1, Android build-tools 34.0.0, API 28
`android.jar`, Xposed `api-82` stub jar.
**Identifier convention:** every occurrence of the sample's package identifier in the transcripts
below is normalized to `<PKG>` (`<PKG>.MainActivity`, `<PKG>.BaseApplication`), and its sub-package
prefixes are shortened the same way. The transcripts are otherwise verbatim, including the class
names a hook reported — those are what make the evidence checkable.
This pass closes an item left open by the previous extension record, which noted that "no LSPosed hook
module was built or run against a real target" (`EXTENSION-kernel-ondevice.md` §4). The build half is
now **observed**; the injection half is **partially observed** and the gap is stated in §6.
---
## 1. Scaffold script — observed
### 1.1 `--help` and generation
```
$ python skills/apk-reverse/scripts/lsposed_scaffold.py --help
usage: lsposed_scaffold.py [-h] --package PACKAGE --name NAME
[--hook-target TARGETS] --out OUT
[--class-name CLASS_NAME] [--tag TAG]
[--description DESCRIPTION] [--min-sdk MIN_SDK]
[--target-sdk TARGET_SDK] [--hook-class HOOK_CLASS]
[--hook-method HOOK_METHOD]
[--hook-params HOOK_PARAMS] [--force]
```
Generation of a throwaway module, **observed**:
```
$ python skills/apk-reverse/scripts/lsposed_scaffold.py \
--package com.example.probe --name "Example probe" \
--hook-target com.example.target \
--hook-class com.example.target.Helper --hook-method check \
--hook-params "java.lang.String" --out <work>/scaffold-gen
[+] <work>/scaffold-gen/AndroidManifest.xml
[+] <work>/scaffold-gen/assets/xposed_init
[+] <work>/scaffold-gen/src/com/example/probe/MainHook.java
[+] <work>/scaffold-gen/README.md
```
`assets/xposed_init` contains exactly one line, `com.example.probe.MainHook` (**observed**). Re-running
without `--force` leaves existing files alone and says so, so the script is safe to re-run.
### 1.2 The generated source compiles as written
The point of the scaffold is that its output builds, so this was checked rather than assumed —
**observed**, exit code 0, four class files (entry class plus three anonymous hook classes):
```
$ javac -encoding UTF-8 -source 8 -target 8 -nowarn -cp "<android.jar>;<api-82.jar>" \
-d <work>/build/classes <work>/scaffold-gen/src/com/example/probe/MainHook.java
$ echo $?
0
MainHook.class MainHook$1.class MainHook$2.class MainHook$3.class
```
## 2. Gradle-free build chain — observed end to end
Built with a parameterised driver that reproduces the chain documented in the reference. Times are
wall-clock on the host above; the module is one class.
| Step | Command shape | Time |
|---|---|---|
| compile | `javac -encoding UTF-8 -source 8 -target 8 -nowarn -cp <android.jar>;<api-82.jar> -d build/classes src/**/*.java` | 850 ms |
| jar | `jar cf build/classes.jar -C build/classes .` | 259 ms |
| dex | `d8.bat --min-api 24 --lib <android.jar> --output build build/classes.jar` | 1143 ms |
| link | `aapt2.exe link -o build/base.apk -I <android.jar> --manifest AndroidManifest.xml --min-sdk-version 24 --target-sdk-version 28 -A assets` | 126 ms |
| add dex | `(cd build && aapt.exe add unsigned.apk classes.dex)` | 97 ms |
| align | `zipalign.exe -f -p 4 build/unsigned.apk build/aligned.apk` | 76 ms |
| sign | `apksigner.bat sign --ks build/test.keystore --ks-pass pass:android --key-pass pass:android --v2-signing-enabled true --out build/module.apk build/aligned.apk` | 1794 ms |
| verify | `apksigner.bat verify --min-sdk-version 24 --print-certs build/module.apk` | 725 ms |
| | **total** | **5.27 s** |
Resulting artifact, **observed**: `module.apk` 12,745 bytes, `classes.dex` 5,024 bytes,
`apksigner verify` reporting v2 signature valid with signer `CN=module, O=local`. APK entry list
(**observed**, read back with zipfile):
```
AndroidManifest.xml 1680
resources.arsc 40
assets/xposed_init 27
classes.dex 5024
META-INF/MANIFEST.MF 375
```
A second, independent build of a hand-written one-class module (different package, different source)
produced the same shape and also verified, so the chain is not specific to the scaffold's output.
### 2.1 Three build-chain traps, all measured rather than assumed
These are the failures that cost time, quoted from the actual runs:
1. **`d8` rejects a directory as program input.** Pointing it at the compiled `classes/` directory
fails with:
```
Error in program input '<work>/build/classes':
com.android.tools.r8.internal.Sb: Unsupported source file type
Compilation failed
```
Jarring the classes first (`jar cf classes.jar -C classes .`) and passing the jar succeeds. This is
the opposite of what several command-line guides imply.
2. **`aapt add` fails with `Unable to add 'classes.dex' to 'unsigned.apk': file not found`** when the
dex is not in the current working directory. It resolves its argument relative to the cwd and stores
the same name, so the dex must be copied out of `dex/` to sit beside the apk.
3. **`jar` and `keytool` are not on `PATH` even where `javac` is.** On this host `javac` resolved to
Oracle's `javapath` shim while `keytool` was absent entirely; both tools had to be called from the
JDK's `bin` directory explicitly. A build script that assumes they are on `PATH` breaks on a
working machine.
Additionally the reference notes that `-bootclasspath` no longer exists on JDK 9+, so the Android API
comes from `-cp` alongside the Xposed stub jar — **observed** (that is the form used above, and it
compiled and dexed cleanly).
## 3. Module state on the device — observed
A previously built probe module was already installed on the device from an earlier pass. Its state
was read, not modified, except where noted:
```
$ adb -s <serial> shell "pm path com.t1.lsphook"
package:/data/app/~~<hash>==/com.t1.lsphook--<hash>==/base.apk
$ adb -s <serial> shell "dumpsys package com.t1.lsphook | grep -E 'User 0|enabled'"
User 0: ceDataInode=35322 installed=true ... stopped=true notLaunched=true enabled=0 ofs=0 ...
```
`enabled=0` here is the **package manager's** component state, not the LSPosed module switch. Enabling
the package was the one state change this pass made on the device:
```
$ adb -s <serial> shell "pm enable com.t1.lsphook"
Package com.t1.lsphook new state: enabled
$ adb -s <serial> shell "dumpsys package com.t1.lsphook | grep 'User 0'"
User 0: ... enabled=1 ...
```
LSPosed itself, **observed**:
```
$ adb -s <serial> shell "su -c 'cat /data/adb/modules/zygisk_lsposed/module.prop'"
id=zygisk_lsposed
name=Zygisk - LSPosed
version=v1.9.2 (7024)
$ adb -s <serial> shell "su -c 'ps -A -o PID,NAME | grep lspd'"
744 lspd
$ adb -s <serial> shell "dumpsys package org.lsposed.manager | grep versionName"
versionName=1.9.2
```
### 3.1 The installed module could never have run — observed
Before reusing that module for an injection attempt, its internals were checked. `assets/xposed_init`
declared one entry class while the dex in the same APK contained a different one:
```
$ python -c "... zipfile.ZipFile('installed-module.apk').read('assets/xposed_init') ..."
com.t1.lsphook.MainHook
$ dexdump -f installed.dex | grep 'Class descriptor'
Class descriptor : 'Lcom/example/t1probe/ProbeHook$1;'
Class descriptor : 'Lcom/example/t1probe/ProbeHook$2;'
Class descriptor : 'Lcom/example/t1probe/ProbeHook$3;'
Class descriptor : 'Lcom/example/t1probe/ProbeHook;'
```
The entry class named in `xposed_init` does not exist in that dex (`MainHook` appears nowhere in the
string table; `ProbeHook` does). LSPosed resolves the class named by `xposed_init`, so this module
could only fail at load — and it would fail **silently** from the outside, which is precisely the
failure mode the reference lists. Recorded because "the package is installed, the `xposedmodule`
meta-data is present and `pm path` returns a path" is still not evidence that the module can run:
the entry class has to exist.
Two consequences measured in the same check:
- A second APK produced by that earlier pass **did** contain the matching class, but was signed with a
different key — signer DN `O=local` against the installed build's `O=tools`, SHA-256
`892c18be…` against `9c86f386…`. Replacing the installed module therefore requires an uninstall
first; `adb install -r` would have failed on a signature mismatch.
- A module rebuilt from the same source with this pass's chain (`build_module.ps1`, the chain in §2)
was verified to contain the entry class, the `T1HOOK` log tag, the `injected: ` literal and the
target package string in its dex, and is the artifact intended for the injection attempt in §6.
Building it took 5.07 s and produced 12,745 bytes.
The **linked** manifest was checked as well, because LSPosed reads the compiled manifest rather than
the source file. `aapt2 dump xmltree <apk> --file AndroidManifest.xml` on the rebuilt APK shows all
three keys intact (`xposedmodule=true`, `xposeddescription="Minimal lifecycle hook probe for route
verification"`, `xposedminversion=82`). The broken APK's manifest was **equally intact** — which is the
point of recording this pair: a correct manifest, an installed package and a valid signature still do
not mean the module can run. Entry-class existence is a separate check, and it is the one that failed
here.
### 3.2 Replacing it, and an install failure that belongs to the ROM — observed
The broken module was removed and the rebuilt one installed. The install path is worth recording
because it failed for a reason that has nothing to do with LSPosed:
```
$ adb -s <serial> uninstall com.t1.lsphook
Success
$ adb -s <serial> install module.apk
[timed out after 240000 ms] # never landed; pm path returned nothing afterwards
$ adb -s <serial> push module.apk /data/local/tmp/<work>/module.apk
$ adb -s <serial> shell "pm install -r /data/local/tmp/<work>/module.apk"
Failure [-99]
$ adb -s <serial> shell "su -c 'pm install -r /data/local/tmp/<work>/module.apk'"
Success
```
Three findings from that sequence:
- `Failure [-99]` from a shell-identity `pm install`, with logcat showing the ROM's own security
centre (`com.coloros.safecenter`) taking the foreground from `com.android.packageinstaller` at the
same moment. The vendor layer is intercepting the install; the framework is not rejecting the APK.
- The same APK installs without complaint as **root**. That is the working path on this ROM, and the
one used here.
- The streaming `adb install` did not merely fail — it **hung for four minutes** and left no package
behind. Retrying as root is cheaper than waiting that out.
Installed state afterwards, **observed**:
```
$ adb -s <serial> shell "pm path com.t1.lsphook"
package:/data/app/~~c7aQQNK-GiP3BKd1g1iEvw==/com.t1.lsphook-<hash>/base.apk
$ adb -s <serial> shell "pm enable com.t1.lsphook"
Package com.t1.lsphook new state: enabled
$ adb -s <serial> shell "dumpsys package com.t1.lsphook | grep 'User 0'"
User 0: ... installed=true ... enabled=1 ...
```
So the **package-side** half of the deployment was completed in this pass: correct entry class,
correct meta-data, installed, PM-enabled. The scope half did not happen, for the reason in §6.
## 4. Where LSPosed keeps module and scope state — observed
The configuration database was copied off the device (three WAL files) and parsed read-only:
```
$ adb -s <serial> shell "su -c 'cp -f /data/adb/lspd/config/modules_config.db* /data/local/tmp/<work>/'"
$ adb -s <serial> pull /data/local/tmp/<work> ...
```
Schema and contents, **observed** (SQLite):
```
CREATE TABLE modules (mid integer PRIMARY KEY AUTOINCREMENT, module_pkg_name text NOT NULL UNIQUE,
apk_path text NOT NULL, enabled BOOLEAN DEFAULT 0 CHECK (enabled IN (0,1)))
CREATE TABLE scope (mid integer, app_pkg_name text NOT NULL, user_id integer NOT NULL,
PRIMARY KEY (mid, app_pkg_name, user_id), ...)
CREATE TABLE configs (module_pkg_name text NOT NULL, user_id integer NOT NULL, `group` text NOT NULL,
`key` text NOT NULL, data blob NOT NULL, ...)
== table modules ==
(1, 'lspd', '/data/adb/modules/zygisk_lsposed/manager.apk', 0)
(2, 'com.t1.lsphook', '/data/app/~~<hash>==/com.t1.lsphook--<hash>==/base.apk', 0)
== table scope ==
(no rows)
== table configs ==
('lspd', 0, 'config', 'misc_path', <blob>)
```
Three facts worth keeping from this, because each maps to a documented failure mode:
- `enabled` in the LSPosed database is a **separate** bit from the package manager's `enabled` state.
Both were 0 for the probe module when read, and only the package-manager one was changed here.
- The `scope` table was **empty**: an installed module that is not scoped is injected nowhere, which is
why "installed" is not evidence of injection.
- `sqlite_sequence.modules` was 3 while only ids 1 and 2 exist — a module had been registered and
removed in an earlier pass. The ids are not a count of what is loaded.
## 5. lspd lifecycle — observed from its own startup scripts
Read from the installed module directory, **observed**:
```
$ adb -s <serial> shell "su -c 'cat /data/adb/modules/zygisk_lsposed/service.sh'"
...
unshare -m sh -c "$MODDIR/daemon --from-service $@&"
$ adb -s <serial> shell "su -c 'cat /data/adb/modules/zygisk_lsposed/daemon'"
...
exec /system/bin/app_process $java_options /system/bin --nice-name=lspd org.lsposed.lspd.Main "$@"
```
`service.sh` is Magisk's late-start service script, which runs once per boot. **Inferred** (not
executed, deliberately): an `lspd` killed from a root shell is not restarted by anything reachable from
that shell, and the cheap-looking "just restart the daemon to pick up my database edit" move would take
the framework's scope decisions away from every subsequently forked process. This pass therefore did
**not** kill `lspd`, and the reference says so explicitly.
Related **inferred** consequence, stated in the reference: hand-editing `modules_config.db` is not a
supported way to change scope, because the daemon serves decisions from its live copy and the file is
its persisted state. The manager path updates both.
## 6. Injection: the framework had to be repaired first, then it worked — observed
With the module installed and PM-enabled, the next step was LSPosed Manager: enable the module there
and add the sample to its scope. That is where the pass stopped — and the reason is a property of the
device's LSPosed state at the time, not of the module.
Manager opened normally but reported the framework as **not installed**. Observed both on screen and in
the dumped node tree:
```
node: "未安装" / "LSPosed 未安装" (overview status card)
node: "API 版本" -> "未安装"
node: "Xposed API 调用保护" -> "未安装"
node: "Dex 优化器包装" -> "未安装"
bottom navigation: 仓库 / 概览 / 设置 # there is no module-list tab in this state
```
The daemon was still alive (`ps -A` → `744 lspd`), so this is not "LSPosed is absent". Two further
observations pin down what it actually is:
- **`lspd` stopped updating its own configuration.** The database still listed the **uninstalled**
module under its old, no-longer-existing path, and never gained an entry for the freshly installed
one. Its size and WAL set were unchanged across the whole pass (156,376 bytes in three files, the
same as before the uninstall):
```
== table modules ==
(1, 'lspd', '/data/adb/modules/zygisk_lsposed/manager.apk', 0)
(2, 'com.t1.lsphook', '/data/app/~~wiGaHYIZn5j3Am2JrJvA5g==/com.t1.lsphook-<hash>/base.apk', 0)
^ that codePath no longer exists: the package was uninstalled this pass
== table scope ==
(still empty)
```
A daemon that had re-scanned packages would have dropped id 2 and registered the new install path.
- **Its log records the framework bridge dying and never recovering.** The verbose capture contains
`system server died`, `am is dead`, then `no response from bridge, retry in 1s` on a loop, and
`Magisk: zygote crashed too many times, rolling-back`.
`[inferred]` The consistent explanation is that the half of the framework that lives in
`system_server`/`zygote` was lost (the same capture shows Magisk rolling a zygote restart back),
leaving `lspd` as a live process with nothing to talk to. Manager asks the framework for its state,
gets nothing, and falls back to its "not installed" onboarding UI — which has no module list, so
**scope cannot be configured through the UI at all** in that state.
Recorded consequences, deliberately not worked around:
- Scope was **not** configured, so no module was injected into any process, so no `T1HOOK` line could
appear. The injection claim therefore remains **unverified on this device**, stated plainly rather
than replaced by a weaker proxy (such as "the module is installed" or "`lspd` is running", both of
which were true the whole time and neither of which means anything about injection).
- The pass did not try to "fix" it by killing `lspd`, hand-editing the database, or restarting
`zygote`: the first two are explained in the reference's §Deploy and the third would have destroyed
concurrent instrumentation work another agent was running on the same device.
- The recovery action is a **device reboot**, which re-initialises Zygisk and `lspd`. It was not taken
because the device was shared and under heavy load. It is the concrete next step, and it is cheap:
after a reboot, open Manager, expect the module list to be present, enable the module, tick the
sample in its scope, then watch `logcat -T <ts> -s T1HOOK` while the sample restarts itself. Per the
reference, the scope change applies to the target's **next** process start, so a self-restarting
target is the ideal case — no spawn, no force-stop, no attach needed.
- Manager was returned to the background afterwards (`mCurrentFocus` back to the launcher). The sample
was never spawned, force-stopped or attached to during this pass.
### 6.1 The repair — observed
A reboot was approved and taken. It is the whole fix, and it is cheap:
```
$ adb -s <serial> reboot
[ 0 s] boot_completed='' ... polled with getprop, no fixed sleep
[ 31 s] boot_completed=1
--- post-boot ---
load average 17.40 4.37 1.46 (was 29.58 31.87 33.61 before)
746 lspd (new pid; was 744)
MoveCertificate zygisk-assistant zygisk_lsposed (all three modules present)
```
Manager then reported the framework normally, and the **module tab appeared** — the recovery
criterion. Observed on the overview page: `已激活 / 1.9.2 (7024) - Zygisk`, `API 版本 100`,
`Xposed API 调用保护 已启用`, `Dex 优化器包装 支持`; bottom navigation went from three tabs to five
(仓库 / 模块 / 概览 / 日志 / 设置). The module package itself survived the reboot
(`pm path` intact, `enabled=1`), so no reinstall was needed — the ROM install workaround in §3.2 only
matters on a fresh install.
### 6.2 Configuring scope through the UI — observed
Done strictly by reading coordinates out of a `uiautomator dump`, never by tapping a guess:
| Step | What was read from the dump | Coordinate tapped | Result |
|---|---|---|---|
| module tab | `[216,2160][432,2293]` | (324, 2260) | module list opened |
| module row | `T1 LSPosed probe`, row `[48,611][1008,793]` | (528, 702) | detail page |
| enable switch | switch node `[804,651][972,795]` | (888, 723) | `checked=true` |
| scope row | `<PKG>`, row `[252,1855][591,1912]` | (528, 1878) | `checked=true` |
The scope list had to be scrolled five screens to reach the target (the list is alphabetical by
display name, not by package). The database then confirmed the change, and — for the first time in
this whole exercise — **`lspd` wrote to it**:
```
== table modules ==
(2, 'com.t1.lsphook', '/data/app/~~c7aQQNK-GiP3BKd1g1iEvw==/com.t1.lsphook-<hash>/base.apk', 1)
enabled ^ = 1
== table scope ==
(2, '<PKG>', 0)
```
The database file grew from 156,376 to 201,696 bytes across the pass. Both facts together are the
proof that the framework, not just its daemon process, came back.
### 6.3 The injection line, and where it actually appears — observed
The target was launched once with `am start`, and the module fired on **every** subsequent process
start. Nine consecutive target starts produced nine full injection blocks:
```
Loading legacy module com.t1.lsphook from /data/app/~~c7aQQNK-GiP3BKd1g1iEvw==/.../base.apk
Loading class com.t1.lsphook.MainHook
T1HOOK injected: <PKG> / <PKG> cl=dalvik.system.PathClassLoader@c226f2f
T1HOOK loaders at-handleLoadPackage:
0: dalvik.system.PathClassLoader c226f2f
1: java.lang.BootClassLoader 8454a72
T1HOOK hook installed: Application.attach
T1HOOK hook installed: Activity.onCreate
T1HOOK hook installed: Application.onCreate
T1HOOK Application.attach #1 this=<PKG>.BaseApplication cl=dalvik.system.PathClassLoader@c226f2f
T1HOOK Application.attach #2 this=com.stub.StubApp cl=dalvik.system.PathClassLoader@c226f2f
T1HOOK Application.onCreate this=com.stub.StubApp
T1HOOK Application.onCreate this=<PKG>.BaseApplication
T1HOOK Activity.onCreate -> <PKG>.MainActivity
T1HOOK injected: com.google.android.webview / <PKG> cl=dalvik.system.PathClassLoader@141f448
T1HOOK Activity.onCreate -> com.qq.e.ads.PortraitADActivity
```
**The verification criterion had to be corrected, and this is the most transferable finding of the
pass.** The reference (and this record's earlier draft, and the scaffold's generated README) said to
watch `logcat -s <TAG>`. On this device that is **empty** — as is `logcat -s LSPosed-Bridge`, and as
is a full-buffer `grep -i T1HOOK`. The module's output exists only in
```
/data/adb/lspd/log/modules_<timestamp>.log
```
which is the same file that earlier appeared to contain nothing but `Logd maybe crashed (err=Socket
operation on non-socket), retrying in 1s...`. The two facts are related: the ROM's `logd` route is
broken, so LSPosed's logcat channel delivers nothing while its file channel works normally. Anyone
debugging a module on such a device with `logcat` alone would conclude "the module never ran" while
looking at nine successful injections. Read **both**: `logcat -s <TAG>` where the platform is healthy,
`/data/adb/lspd/log/modules_*.log` always. The evidence file for this pass is 201 lines, of which 126
are `T1HOOK`.
Three further observations from the same log, none of which needed any extra instrumentation:
- **The packer's double Application is visible in the hook order.** `Application.attach` fires twice —
first for the app's real `BaseApplication`, then for `com.stub.StubApp` — and `onCreate` then runs
for the stub *before* the real Application. Hooks installed at `handleLoadPackage` time survive
this swap, and by `Activity.onCreate` the classes reported are the **unpacked** ones
(`<PKG>.MainActivity`), not the stub's. That is the concrete value of this route on a
packed target: the Java layer is reachable without touching the APK.
- **Scope is per app, not per process.** The module also injected into the app's WebView process
(`com.google.android.webview / <PKG>`) and reported the ad SDK's activity
(`com.qq.e.ads.PortraitADActivity`) — worth knowing before scoping a module widely.
- **The target's self-restart cycle is unaffected by injection.** Nine pids in ~3 minutes, one every
22–23 s (8111 → 9392 → 10557 → 11453 → 12345 → 13236 → 14155 → 15061 → 15934), each run reaching
`MainActivity.onCreate`, the WebView process and an ad activity before ending. The module only
observes, so this says nothing about cause; and because a reboot changes many variables at once, any
comparison with the pre-reboot cycle (a different observer measured 10–20 s) is **inferred at best
and not a controlled result**.
## 7. Log surfaces — observed, and one trap
```
$ adb -s <serial> shell "su -c 'ls -la /data/adb/lspd/log/'"
kmsg.log 993690
modules_2026-09-21T18:44:31.523.log 401
props.txt 46937
verbose_2026-09-21T18:44:31.518.log 178482
```
The `modules_*.log` file is **not** module output. Its entire content, **observed**:
```
----part 1 start----
Logd maybe crashed (err=Socket operation on non-socket), retrying in 1s...
(repeated)
```
`verbose_*.log` is a full logcat snapshot that includes unrelated system events (it contained, for
example, Magisk zygote-restart lines and OEM process deaths from an earlier incident). Useful for
correlating a run with system state; useless as a module log. The injection proof must come from
`logcat -s <TAG>`, which is what the reference and the scaffold's README recommend.
## 8. Root-hiding layer — observed
```
$ adb -s <serial> shell "su -c 'cat /data/adb/modules/zygisk-assistant/module.prop'"
id=zygisk-assistant
name=Zygisk Assistant
version=v2.1.4 (1013f8a-release)
description=A Zygisk module to hide root.
$ adb -s <serial> shell "su -c 'magisk --denylist status'"
Denylist is enforced
$ adb -s <serial> shell "su -c 'magisk --denylist ls'"
(no output)
$ adb -s <serial> shell "su -c 'ls /data/adb/shamiko'"
ls: /data/adb/shamiko: No such file or directory
```
So at pass time the DenyList was **enforced but empty**: no process was being hidden from anything,
while LSPosed and `lspd` were running normally, and Shamiko was not installed. Worth recording because
"the target knows it is on a rooted device" is frequently an environment fact of exactly this shape,
and it is cheaper to check than to escalate (`references/detection-and-anti-analysis.md`).
The Shamiko/Zygisk-Assistant comparison in the reference is **inferred** from their own documentation
plus the on-device module metadata above; the hiding behaviour itself was not exercised against any
detector in this pass.
## 9. Not run / open items
- **Injection is not verified, and the blocker is now identified rather than unknown.** §6 records the
state that stopped it: Manager reporting the framework as not installed, `lspd` alive but no longer
updating its own configuration, and its log showing the framework bridge die and never recover. The
action known to clear that state is a **device reboot**; after it the remaining sequence is short
(enable the module in Manager, tick the sample in its scope, read `logcat -T <ts> -s T1HOOK` on the
target's next self-restart). Until someone does that, every statement in the reference about a module
*actually being injected* rests on framework documentation rather than on this bench.
- Editing `modules_config.db` directly was **not** attempted, on purpose: §5 explains why it would have
been an unreliable experiment, and the unsupported-ness of that path is recorded as inferred rather
than tested by breaking a working setup.
- Killing/restarting `lspd` was **not** attempted, for the same reason.
- The module's effect on a hardened, detection-aware target was not measured, because injection was not
reached. Consequently nothing here validates or contradicts the ClassLoader-count detection reported
externally (see the reference's *What detects you anyway*); that source is cited, not reproduced.
- The vendor install interception (§3.2) was worked around by installing as root; whether it can be
disabled from the ROM's own settings was **not** investigated, and whether `Failure [-99]`
reproduces on an idle device or on other vendor builds is **unverified**.
- `scaffold.py` was exercised on Windows only; the POSIX path in the generated README's command block
is **unverified** (the commands are standard, but not run here).
## 10. Reproduction one-liners
```
python skills/apk-reverse/scripts/lsposed_scaffold.py --help # argparse surface
python skills/apk-reverse/scripts/lsposed_scaffold.py --package <pkg> --name "<name>" \
--hook-target <target.pkg> --out <dir> # writes 4 files
# build (any ABI-neutral host with JDK + build-tools + android.jar + api-82.jar)
javac -source 8 -target 8 -cp "<android.jar>:<api-82.jar>" -d build/classes src/**/*.java
jar cf build/classes.jar -C build/classes . # d8 needs a jar, not a dir
d8 --min-api 24 --lib <android.jar> --output build build/classes.jar
aapt2 link -o build/base.apk -I <android.jar> --manifest AndroidManifest.xml \
--min-sdk-version 24 --target-sdk-version 28 -A assets
(cd build && aapt add unsigned.apk classes.dex) # dex must be in the cwd
zipalign -f -p 4 build/unsigned.apk build/aligned.apk
apksigner sign --ks build/test.keystore --ks-pass pass:android --key-pass pass:android \
--v2-signing-enabled true --out build/module.apk build/aligned.apk
apksigner verify --print-certs build/module.apk
adb -s <serial> shell "pm path <module.pkg>" # installed?
adb -s <serial> shell "dumpsys package <module.pkg> | grep 'User 0'" # pm enabled state
adb -s <serial> shell "su -c 'ps -A -o PID,NAME | grep lspd'" # daemon alive
adb -s <serial> shell "su -c 'magisk --denylist status'" # hiding layer state
```
@@ -0,0 +1,270 @@
# Extension verification — native DBI/deobfuscation and protocol reverse engineering
Covers the 2026-09 extension pass that added `references/native-dbi-and-deobfuscation.md` and
`references/protocol-reverse.md`. Strength labels as defined in this directory's README:
**observed** (exact command + output here), **inferred** (follows from observed facts, step not
executed), **unverified** (assumed or externally reported, not independently confirmed).
Reference environment for this pass: Windows 11 host, Python 3.14.0, host frida 16.7.19
(frida-tools 13.7.1); rooted physical device, Android 11 (API 30), arm64-v8a, 8-core mid-range SoC,
with an on-device frida-server 16.7.19 that was already running when the pass started and was never
killed or restarted (pid 23405 at pass time). All Stalker work ran against system processes; the
hardened Flutter sample under analysis by a different task on the same device was never attached to,
spawned, or stopped by this pass.
**The headline result is a negative one, and it is the reason this record matters: on this
combination, Stalker follow installs successfully and produces no events.** The record separates
that finding from a crash observed later in the same session; they are different observations with
different causes and must not be merged.
---
## 1. Scripts under test — observed
`skills/apk-reverse/scripts/stalker_trace.js` (456 lines) and
`skills/apk-reverse/scripts/stalker_report.py` (236 lines) were already on disk from an earlier
attempt of this task; this pass read them, changed neither, and exercised both.
```
$ node --check skills/apk-reverse/scripts/stalker_trace.js
syntax check exit = 0
$ python skills/apk-reverse/scripts/stalker_report.py --help
usage: stalker_report.py [-h] [--top TOP] [--skeleton SKELETON]
[--edges EDGES] [--seq SEQ] [--json PATH] [--quiet]
log
Summarize a stalker_trace.js log into a block histogram, a first-visit CFG
skeleton, and call-edge tables.
```
Two workbench drivers were written for this pass and live in `tools/_work/t4-dbi/` (not part of the
skill): `drive_usb.py`, which attaches over USB and calls
`rpc.exports.config(...)` / `start(tid)` explicitly, and `pb_selftest.py` (§7).
Why a second driver was needed at all: `scripts/run_probe.py` injects the probe faithfully (its
`--via usb` path attached and logged `READY`/`TRIG`/`DONE` correctly), but it never calls the
script's rpc exports, so `stalker_trace.js` runs with its built-in `autoStart` and follows whichever
thread `Process.getMainThreadId()` reports. That thread is not the Android main thread on this
device (§3), and there is no way to override it from that driver.
## 2. Report parser validated against a hand-written fixture — observed
`tools/_work/t4-dbi/synthetic.log` is a **hand-written** fixture (16 lines, 1,008 B) in the script's
documented output grammar, including lines wrapped the way `run_probe.py` wraps them. It is not a
device run and proves nothing about Stalker; it proves the parser reads the grammar.
```
$ python skills/apk-reverse/scripts/stalker_report.py tools/_work/t4-dbi/synthetic.log \
--top 4 --skeleton 6 --edges 4 --seq 8
module libdemo.so base=0x7abc000000 size=1048576 (target)
unique blocks first-seen (BB) : 3
block executions (BLK) : 7
call edges (CALL) : 2
DONE reason=timeout truncated=0 (device-side counts: bb=3 blk=7 call=2)
== execution histogram: top 4 (dispatcher candidates) ==
rank count pct block firstSeen
1 4 57.1% libdemo.so+0x9f6c0 #1
2 2 28.6% libdemo.so+0x9f710 #2
3 1 14.3% libdemo.so+0x9f800 #5
== call edges (top 4 of 2) ==
1 0x7ab3001020 -> libdemo.so+0x9f6c0
1 libdemo.so+0x9f800 -> libdemo.so+0x9f710
== collapsed execution sequence (first 6 runs of 6) ==
libdemo.so+0x9f6c0 -> libdemo.so+0x9f710 -> libdemo.so+0x9f6c0 -> libdemo.so+0x9f800 ->
libdemo.so+0x9f6c0*2 -> libdemo.so+0x9f710
```
The four reductions the reference promises — histogram, first-visit skeleton, call edges, collapsed
sequence — all behave as documented, including the `*N` repeat collapse that makes a
dispatcher/real-block rhythm legible. `--quiet` and `--json` paths were exercised too (§3, §4).
## 3. Device attempt A — follow a chosen thread, zero events (observed)
Two system processes, each attached for 8 s with `followMs=4000`, target module `libc.so`,
`autoStart` disabled by the driver, and the followed tid passed explicitly.
```
$ python tools/_work/t4-dbi/drive_usb.py --js skills/apk-reverse/scripts/stalker_trace.js \
--pid <settings pid> --seconds 8 --log tools/_work/t4-dbi/run2_settings_main.log
READY stalker_trace loaded; target=libc.so trigger={"kind":"main"} followMs=4000 maxBlocks=100000 moduleLoaded=true
TRIG following tid=26261 (main-thread follow (pid=19938)) module=libc.so base=0x721be88000
TRACE MOD libc.so base=0x721be88000 size=999424 path=/apex/com.android.runtime/lib64/bionic/libc.so
DONE reason=reconfig blocks=0 blk=0 calls=0 truncated=0
TRIG main trigger armed (autoStart=false); call start()
[rpc] start(19938) -> {"following": true, "followingTid": 19938}
DONE reason=timeout blocks=0 blk=0 calls=0 truncated=0
```
Facts worth keeping separate from the interpretation:
- `Process.getMainThreadId()` returned **26261** for a process whose pid is **19938**. On Android the
main thread's tid equals the pid, so the script's default thread selection followed a different
thread. This is observed on this device/version and is the reason the reference tells the reader to
pass `start(tid)` explicitly.
- Re-running with `start(19938)` — the real main thread — produced **the same zero**:
`DONE reason=timeout blocks=0 blk=0 calls=0`.
- A third run against a system UI process (`run3_systemui_libc.log`, same `followMs=4000`)
reproduced it identically. `stalker_report.py --quiet` on all three logs prints the same summary line
(`unique blocks first-seen (BB): 0`, `block executions (BLK): 0`, `call edges (CALL): 0`) and the
script's own "no target-module blocks at all" diagnosis.
**Interpretation: unverified as to cause.** The pipeline was healthy up to `TRIG following`, the
module was loaded and in `maps`, and the Interceptor trigger demonstrably fired (§4) — so the
narrowest supportable statement is "follow installs, events do not arrive in `onReceive`". Whether
that is a frida-server build property, a ROM restriction, or something about the followed threads was
not established and is not claimed. No trace was successfully recorded on this device during this
pass.
## 4. Device attempt B — hot-function export trigger, zero events (observed)
The `export` trigger kind was exercised with `malloc` in `libc.so` as the trigger target, so that
each call would start a follow and each return would end it. The trigger fired repeatedly for the
whole window.
```
$ python tools/_work/t4-dbi/drive_usb.py --js skills/apk-reverse/scripts/stalker_trace.js \
--pid <systemui pid> --seconds 6 --log tools/_work/t4-dbi/run4_systemui_malloc.log \
--cfg '{"targetModule":"libc.so","trigger":{"kind":"export","module":"libc.so","export":"malloc"},"followMs":1000,"maxBlocks":20000}'
$ lines = 609 follows = 201 done_lines = 201 nonzero_blk = 0
# per-firing shape:
TRIG following tid=18915 (trigger 0x721becbbf0) module=libc.so base=0x721be88000
DONE reason=trigger-leave blocks=0 blk=0 calls=0 truncated=0
```
This is the strongest evidence for the §3 statement: **201 fully-formed follow cycles, each with a
clean `DONE`, and not one reported block in any of them.** A trigger that never fires would show
`TRIG-FAIL` or a single cycle; a filter that dropped everything would still be consistent with this,
which is why §3's claim is deliberately limited to "events do not arrive".
## 5. Device attempt C — a system UI process died during the hot-trigger run (observed)
Same run as §4, minutes later, on the same pid. The process died and was restarted by the system.
```
$ adb shell pidof com.android.systemui
18030 # before
26932 # after
$ adb shell "su -c 'logcat -b crash -d -t 80'"
09-21 20:22:25.327 ... F DEBUG : pc 00000070cf8ae464 pst 0000000040001000
09-21 20:22:25.719 ... F DEBUG : backtrace:
09-21 20:22:25.719 ... F DEBUG : #00 pc 000000000001f464 <anonymous:70cf88f000>
09-21 20:22:25.719 ... F DEBUG : #01 pc 00000000004d0b64 /apex/com.android.art/lib64/libart.so
(art::Reference_getReferent(_JNIEnv*, _jobject*)+44)
09-21 20:22:25.719 ... F DEBUG : #03 pc 000000000008220c boot.oat (art_jni_trampoline+124)
09-21 20:22:25.719 ... F DEBUG : #08 pc 0000000000714240 boot-framework.oat (android.os.Looper.loop+2176)
```
Reading of the record, stated as an attribution hypothesis rather than a proven mechanism: frame
`#00` sits in an **anonymous executable region** (`<anonymous:70cf88f000>`), which is the shape of a
DBI's translated-code cache rather than of a file-backed library, and the return path leads into
`libart`. The condition that distinguishes this run from §3/§4 is **hundreds of follow/unfollow
cycles on a hot function**, so the attributed cause is that cycle — a follow/unfollow race against
ART's own execution state — not "Stalker is unusable". The engine-level question (would a single
long follow of the same thread also crash it?) was not tested and remains **unverified**.
The consequence written into the reference is therefore operational, not diagnostic: *do not use a
hot function as a follow trigger, and do not build a per-call follow/unfollow cycle.* Note also that
this crash is **not** the explanation for the zero-event results in §3/§4: those runs produced their
zeros before any death, on two other processes, and one of them never touched an export trigger.
## 6. Cross-task contamination on a shared device — observed (reported by the Lead)
While §3–§5 were running, the device's `load average` was **34.11** (`adb shell uptime`, 1:38 after
boot) on an 8-core mid-range phone, and a dynamic job belonging to **another task on the same
device** — a dex-dumping attach against the hardened Flutter sample — was destroyed mid-flight with
`script has been destroyed` and a terminating process. Both facts are the Lead's observation of its
own job, quoted here because they are part of this pass's outcome; no claim is made that the sample
was affected for any reason other than device load, and the sample's own pid changes observed
independently during that window are **not** attributed to this pass.
The rule this produced, added to the reference's failure modes: on a shared device, a heavy DBI run
is not an isolated experiment. One job pushing the device to load 30+ makes every *other* dynamic
result on that device unattributable, which is `references/long-task-discipline.md` §single-variable
discipline applied to hardware rather than to a patch. Practically: announce the window, keep
`followMs` in the low seconds, cap `maxBlocks`, attach rather than spawn, and treat a
`script has been destroyed` in a *different* job as a signal that your own load is the variable.
## 7. Protobuf wire format self-test — observed
`tools/_work/t4-dbi/pb_selftest.py` (workbench) encodes a message by hand and decodes it by walking
the wire format, with no `protoc`, no schema, and no third-party protobuf runtime. It exists to give
`references/protocol-reverse.md` §1 an output behind its claims.
```
$ python tools/_work/t4-dbi/pb_selftest.py
== canonical varint check ==
varint(0 ) = 00 ok
varint(150 ) = 9601 ok
varint(300 ) = ac02 ok
varint(86942 ) = 9ea705 ok
== fixture bytes ==
nested payload (5 B): 0801120178
packed payload (6 B): 038e029ea705
message (29 B): 089601120774657374696e671a0508011201782206038e029ea7052800
== schema-free decode (the shape protoc --decode_raw produces) ==
field 1 varint 150
field 2 len-delimited(7) str 'testing'
field 3 len-delimited(5) nested message:
field 1 varint 1
field 2 len-delimited(1) str 'x'
field 4 len-delimited(6) hex '038e029ea705'
field 5 varint 0
== what the decode cannot tell you ==
explicit 0 at field 5 : 2800
field 5 never written : b''
-> proto3 cannot distinguish these two on the wire; a decoded "0" is not evidence the sender set the field.
-> field numbers in the walk are local to their message; only a schema says which message field 3 belongs to.
== re-encode round trip ==
rebuild from the walked rows equals original: True
```
Two of the reference's claims are now measured rather than repeated: the packed repeated field
(`3, 270, 86942`) is reported by a schema-free decode as opaque hex because element boundaries need a
schema, and an explicitly written proto3 zero is byte-identical to an absent field. The round-trip
check is also load-bearing as a testing habit: the first version of this script printed
`equals original: False`, and the defect was the decoder's own string/bytes ambiguity — the same
false-confidence trap the reference warns about for third-party decoders.
## 8. Not run, and therefore unverified
Everything below is stated in the references as inferred or unverified, and was **not** exercised in
this pass:
- Any successful Stalker trace. No histogram, no dispatcher identification, and no CFG skeleton was
produced from real device execution; §2's fixture is hand-written.
- Whether Stalker works on this device under a different frida-server build, a different ROM, or with
a single long follow instead of per-call cycles.
- `events.exec` and `events.ret` (the per-instruction and return-edge paths) — never enabled.
- QBDI / frida-qbdi, angr, Triton, unidbg, Unicorn: not installed, not run. §4/§5 of
`native-dbi-and-deobfuscation.md` are method descriptions.
- Trace-driven deflattening end to end, including the state-variable identification and the LIEF
rewrite. The community write-up cited there was read, not reproduced; its performance numbers are
the author's.
- `protoc`, `protobuf-inspector`, `blackboxprotobuf`, `pbtk`/`protodump`, `grpcurl`: not installed,
not run. The schema-recovery routes in `protocol-reverse.md` §2 are inferred from generated-code
markers, not demonstrated on a real APK.
- gRPC and QUIC/HTTP3 capture: no HTTP/2 or HTTP/3 client was exercised; §3/§4 of
`protocol-reverse.md` are unverified.
- `universal-flutter-ssl-pinning` / PyGhidra discovery, and the Frida/Renef output it generates: not
reproduced. The README's own testing table (Google Flutter arm64-v8a, Shorebird builds, Ghidra
12.x, Frida 16.x/17.x) is the only evidence behind that section.
- The `MoveCertificate` module's interaction with a Flutter client: not tested. The reference states
the boundary conditionally (store-reading clients only), not as a measured result.
## 9. What this pass licenses
It licenses the following statements and nothing wider: the trace/report toolchain is syntactically
sound and its parser is verified against its documented grammar; an Android 11 arm64 device with
frida-server 16.7.19 accepted Stalker follows and delivered no events, so *a zero-block trace is not
by itself evidence about the target*; a per-call follow on a hot export killed a system process; and
the protobuf wire-format rules the new reference teaches are measured on a fixture, including the two
traps (packed fields, explicit zeros) that a decode cannot resolve without a schema.
@@ -0,0 +1,256 @@
# Extension verification — root-side memory dump (the route that does not use frida)
Covers the 2026-09 extension pass that added the §Dumping when frida is refused section
to `references/advanced-unpacking.md`. It is the follow-up to
`docs/tool-verification/EXTENSION-device-run.md`, which established that
`frida-dexdump` is refused by this target (attach: `script has been destroyed`, twice,
single-variable repeat) — that file is the background, not repeated here. This pass
asks the next question: **can root read the process's memory directly, with no
instrumentation present at all?**
Strength labels, as defined in this directory's README:
- **observed** — reproduced here, with the exact command and its output.
- **inferred** — follows from observed facts, but the step itself was not executed.
- **unverified** — assumed, or reported by a tool and not independently confirmed.
**Target identity is deliberately absent**; the package appears as `<PKG>`. The
findings are about the route, the device shell and the tooling, and stay valid
whichever hardened APK produced them.
## Environment (observed)
| Item | Value |
|---|---|
| Device | the same physical arm64 device as `EXTENSION-device-run.md`: Android 11 (API 30), kernel 4.14.186, Magisk root |
| Instrumentation | **none** — the device-side `frida-server` was left stopped for the whole pass; `ps -A \| grep -i frida` returned nothing before and after |
| Sample | 360-jiagu hardened, Flutter AOT payload, installed and untouched (no reinstall, no repack) |
| Root access | `adb shell 'su -c "…"` — full root, no `avc: denied` in any read attempt below |
| Device shell | toybox (`grep`, `dd`, `ps`, `stat`, `awk`, `sed`); no `findstr`, no `ls --time-style`, no `map_files` entries |
Two shell facts were measured before anything else, because both silently corrupt a
naive dump and neither announces itself:
```
$ adb shell 'su -c "grep --help"' # → -a -b -o -z -E -F available
$ adb shell 'su -c "dd --help"' # → iflag=skip_bytes,count_bytes available
```
## 1. The sample does not stay up, with or without frida (observed)
The control assumption going in was that the sample is stable when nothing is
attached. It is not: over a 60-second sample at 1 Hz the pid moved four times, and
logcat explains every move.
pid sequence, `ps -A -o PID,NAME | grep -w <PKG>` once per second:
```
20:31:02 16729 … 20:31:07 16729
20:31:08 17951 … 20:31:23 17951
20:31:26 20021 … 20:31:42 20021
20:31:43 21632 … 20:32:00 21632
20:32:01 (none) 20:32:02 22770 …
```
The platform's own record of two of those transitions:
```
09-21 20:31:43.327 I/ActivityManager: Process <PKG> (pid 20021) has died: fg TOP
09-21 20:31:43.394 I/ActivityManager: Start proc 21632:<PKG>/u0a623 for top-activity {<PKG>/.MainActivity}
09-21 20:32:01.463 I/ActivityManager: Process <PKG> (pid 21632) has died: fg TOP
09-21 20:32:01.555 I/ActivityManager: Start proc 22770:<PKG>/u0a623 for top-activity {<PKG>/.MainActivity}
```
- **observed:** each process lives **7-18 s**, then dies as a *foreground, top*
process, and is started again by `ActivityManager` because the activity stack is
still on top. Lifetime is not constant.
- **observed:** there is **no** crash, `SIGSEGV`, `SIGABRT`, ANR or tombstone entry
for these transitions — filtered logcat for `died|kill|Force|ANR|crash|Timeout|
SIGSEGV|SIGABRT` returned only the two `has died: fg TOP` lines and the restarts.
A clean self-exit, not a platform kill.
- **observed:** the restarts stop when the app is no longer the top activity; after
the last death in the 22-sample trace the pid stayed empty for 14 s until
`monkey` relaunched it.
- **inferred:** this is the packer's own environment check reacting to the device
(root), not a reaction to instrumentation — no instrumenter was present. It also
explains the earlier "stable" control reading: a 12-second window fits inside a
17-second lifetime.
- **inferred:** the practical consequence is the design rule of the whole route —
every step must complete inside one lifetime, and any batch routine must re-read
`/proc/<pid>/maps` after a restart instead of trusting its first pid.
## 2. The map is the cheapest source of dex images (observed)
`/proc/<pid>/maps` for the live sample: 522,795 bytes, 5,617 regions. ART names the
dex images it holds, so no search is needed for those:
```
7129d8c000-712a60f000 r--p [anon:dalvik-classes.dex extracted in memory from /data/app/~~…/base.apk]
6f9ba03000-6f9be2b000 r--p [anon:dalvik-classes.dex extracted in memory from /data/user/0/<PKG>/app_e_qq_com_onlp_…/1ced034d9b425c3061036c1cc9b634]
6f75899000-6f75cae000 r--p [anon:dalvik-classes.dex extracted in memory from /data/user/0/<PKG>/app_sodler/com.kwad.components.tachikoma/5.6.10.1/base-1_apk]
… 17 such regions in total
```
Export command actually used (decimal offsets; see §4 for why not hex):
```
dd if=/proc/<pid>/mem iflag=skip_bytes,count_bytes skip=<DEC_START> count=<SIZE> \
of=/data/local/tmp/t2dump/dexNN.bin bs=64k
```
All 17 regions exported; 16 of 17 completed inside one lifetime, two of the trailing
regions were cut short by the restart described in §1 and came back as 0-byte files —
which is the failure mode to expect, and the reason the batch must be re-entrant.
## 3. Validation: what the exported images actually are (observed)
The dumps are page-aligned and therefore 0..4095 bytes longer than the image they
carry, so all 17 were **rejected on first validation**:
```
== dex dump validation: 7 file(s), 0 parse, 7 rejected ==
dalvik-classes.dex_…base.apk.dex 8925184 REJECTED: file_size=8923752 actual=8925184
```
Trimming each file to the `file_size` field at dex-header offset 32 (dropped 68 …
3,724 bytes per file) then gave a clean run:
```
== dex dump validation: 17 file(s), 17 parse, 0 rejected ==
name size sha256[:12] ver cksum sig class noco code stub%
dex16.bin 122460 3fc5581d6eb3 035 ok BAD 103 207 8974 1.1% (ksad dynamic apk)
dex08.bin 1069516 613cfef811ab 035 ok BAD 1285 432 8929 0.9% (kwad ksdp)
dex14.bin 8923752 1497590d0a24 035 ok BAD 4 160 29 3.4% (from /data/app/…/base.apk)
dex01.bin 3212480 fb61a3f085f5 035 ok ok 3169 785 15924 1.0% (pangle live-lite classes6)
… 17 images, stub% 0.9 – 3.4, 17/17 unique by sha256
ranking (most likely original first):
1. dex08.dex stub%=0.9 cksum=ok sig=BAD classes=1285
…
17. dex14.dex stub%=3.4 cksum=ok sig=BAD classes=4
```
**What this means, and what it does not:**
- **observed:** the route produces *real, parseable dex* from a hardened app's process
memory without any instrumentation — 17 images, one class count 103 up to 10,148,
`stub%` in the low single digits. This is the strongest evidence that the
`/proc/<pid>/mem` route is viable where the frida route was refused.
- **observed:** the image that came from the app's own `base.apk` defines **4
classes** on an 8.9 MB file (`sig=BAD` on the untouched image). File size and class
count move independently under a packer — this is the landing-shell skeleton shape,
matching the shipped `classes.dex` recorded in `EXTENSION-unpacking.md`.
- **observed:** across 22 s of 1 Hz sampling of a live process, the count of
`extracted in memory from /data/app` mappings was **always 1** (`appBase=1`,
`appPrivate=7`, `dexmaps=17`, `VmRSS` 674-746 MB). No second application dex mapping
ever appeared.
- **inferred:** while the observer watched, the packer never placed its real payload
in memory as a *loaded ART dex*. Combined with the clean self-exit in §1, the
reading is that the shell's environment check fires before (or independently of)
payload loading on this device.
- **unverified:** whether a longer-lived or differently-triggered instance would load
a second dex. No attempt was made to defeat the check, by task instruction.
## 4. Searching memory for a decrypted dex: what the device shell does to you
Two blind searches were run for the pattern the payload would leave if it were sitting
in a native or heap buffer rather than a loaded dex.
**Anonymous `rw-p` regions** (everything except ART internals, per-thread stacks, cfi
shadow and dart regions), 143 regions exported, 40,670,268 bytes → **0 dex magic
hits** (`scan_magic.py`, `dex\n03x` with `file_size` cross-check).
**ART main space (`dalvik-main space (region space)`, 1 GB reservation)** sampled in
64 MB windows from the start of the space → **0 dex magic hits** in the 192 MB
covered, at **~10 MB/s**:
```
maps_line=12c00000-52c00000 rw-p … [anon:dalvik-main space (region space)]
region_space_base=314572800
off=0 abs=314572800 secs=6 hits=[]
off=134217728 abs=448790528 secs=7 hits=[]
PID_DEAD before off=268435456
```
**inferred:** at 10 MB/s a full 1 GB heap sweep is ~100 s — several process
lifetimes — so heap search is not a plan for a sample with this restart cadence.
Named ART dex mappings are free; a heap sweep is not.
Four device-shell traps cost real time, each one producing a plausible-looking wrong
answer rather than an error. All four are **observed**:
| Trap | Observed behaviour | What worked |
|---|---|---|
| mksh arithmetic is 32-bit | `$((16#7129d9a000))` → `702128128` (the low 32 bits); `dd skip=702128128` then read an unrelated address and the "dump" was zeros | convert with `awk` (`48-bit` values exact in double): `awk 'BEGIN{…n=n*16+v…; printf "%d", n}'` |
| VMA page alignment | 17/17 dumps rejected with `file_size=… actual=…`, excess 68…3724 B | trim to header `file_size` before validating |
| `grep` is line oriented | `grep -F` with a real newline in the pattern matched only `035` at the wrong offset; `-E` with a literal newline matched nothing | `grep -z -a -o -b -E 'dex.035'` → offset `4` on a synthetic probe containing the magic at offset 4 |
| toybox `awk` regex filter | `awk '/ rw-p / && $0 !~ /dalvik-\|…/'` selected all **808** map lines, including `r--p` system libraries, so the candidate list was meaningless | filter with `grep -aE '^[0-9a-f]+-[0-9a-f]+ rw-p '` plus `grep -av`, keep `awk` for arithmetic only |
**`/proc/<pid>/map_files/` is not a shortcut on this ROM** (observed): the directory
exists, is `dr-x------ root root`, and lists **no entries**, so
`dd if=/proc/<pid>/map_files/<start>-<end>` yields 75 bytes of `can't open … No such
file or directory`. The `mem` + decimal-offset form is the one that works.
**A quoting trap in a different layer** (observed): driving the same commands through
`subprocess` with a list argv stripped the inner quotes, so only the first statement
reached `su -c` and the rest ran as the `shell` user — the visible symptom was
`can't create /data/local/tmp/…: Permission denied` on a file owned by root. Root
commands with embedded quoting should go through one shell layer, not two.
## 5. Leftover dumps in the work directory — what they are (observed + inferred)
`/data/local/tmp` carried `.so` files from earlier sessions. They were verified rather
than trusted:
| File | Size | sha256[:16] | ELF | Sections |
|---|---|---|---|---|
| `L_libapp.so` = `d_libapp.so` = `libapp.bak` | 13,501,344 | `2275dd4398f0b34e` | ELF64 AARCH64, `ET_DYN`, phnum 7 | 11 |
| `rt_libapp.so` | 13,501,344 | `8b490512258ba1c8` | ELF64 AARCH64, `ET_DYN`, phnum 7 | 11 |
| `libapp.so` | 12,256,160 | `4cfec2762c25539b` | ELF64 AARCH64, `ET_DYN`, phnum 7 | 11 |
| `ll.so` | 6,230,040 | `20f2d12b5049f238` | ELF64 AARCH64, `ET_DYN`, phnum 9 | 26 |
- **observed:** all four are structurally valid ELF64/AARCH64 shared objects with a
**complete section header table**, and the three `libapp` variants contain the Dart
AOT `snapshot` marker (3 occurrences each).
- **observed:** the `libapp.so` shipped inside the reference APK is **16,352,152 B**
uncompressed (`lib/arm64-v8a/libapp.so`), i.e. ~2.9 MB larger than any leftover
copy, and no leftover file matches it byte for byte.
- **inferred:** the leftovers are copies of a *Dart AOT library from some build*, not
a range lifted from this process's memory. The signature of a memory-lifted image
is the opposite of what these show: `PT_LOAD` contents with **no** section header
table. They are therefore recorded as **reference material of uncertain
provenance**, not as "the dump this pass succeeded in taking" — and they were not
used for any conclusion above.
## 6. Conclusions, graded
| Claim | Label |
|---|---|
| Root can read `/proc/<pid>/maps` and `/proc/<pid>/mem` on this device with no `avc` denial and no instrumenter present | observed |
| 17 ART dex mappings were exported from a live hardened process and, after trimming to header `file_size`, all 17 parsed as valid dex | observed |
| The dex mapping sourced from the app's `base.apk` defines 4 classes on 8.9 MB (landing-shell skeleton); the other 16 are real SDK dexes, `stub%` 0.9-3.4 | observed |
| The sample self-exits every 7-18 s with no frida present (`has died: fg TOP`, no crash/tombstone) and is restarted by the platform while it is the top activity | observed |
| The earlier "stable with no instrumentation" control reading was an artefact of a 12 s window inside a 17 s lifetime | inferred |
| The packer's real payload never appeared as a loaded ART dex during 22 s of sampling (`appBase` constant at 1) | observed (single sample) |
| Anonymous `rw-p` memory (143 regions / 40.7 MB) and the first 192 MB of the ART heap contain no dex magic | observed |
| A full 1 GB heap sweep is impractical at the measured ~10 MB/s against a 7-18 s lifetime | observed (throughput), inferred (planning consequence) |
| `map_files` is unusable on this ROM; hex parsing in mksh is 32-bit; toybox `grep -F` cannot match the dex magic and toybox `awk` regex filtering is unreliable | observed |
| The leftover `libapp*.so` files are unrelated to this process's memory; provenance unverified | observed (structure/size), inferred (provenance) |
## 7. What this pass did not establish
- **Not** a recovered payload. The route recovered every dex the process had loaded
— SDK plugins and the shell skeleton — but no business dex, because none was loaded
while the process was observed. The Flutter payload itself (`libapp.so`, Dart AOT)
is a separate target and is not reached by a dex-oriented dump.
- **Not** an evasion. The sample's self-exit cadence was *not* fought: no attempt was
made to defeat the environment check, per the task's two-strike discipline. A
longer-lived instance might load more; that is stated as **unverified** rather than
attempted.
- **Not** a general claim about 360-jiagu, Flutter or Android 11 — one device, one
ROM, one sample, one session, with a shared device in use by other experiments at
the same time.
- **Not** a memory-completeness claim: the 102 MB unnamed anonymous block that appears
once the Flutter engine is up was never captured (it was absent during the short
lifetimes observed and the process died before the chunked export finished). It is
recorded here as an uncovered region, not as a scanned-clean one.
@@ -0,0 +1,142 @@
# Extension verification — advanced unpacking (extraction shells, active invocation, VMP boundary)
Covers the 2026-09 extension pass that added `references/advanced-unpacking.md` and
`scripts/dex_dump_validate.py`. Strength labels as defined in this directory's README:
**observed** (exact command + output here), **inferred** (follows from observed facts,
step not executed), **unverified** (assumed or externally reported, not independently
confirmed).
Reference environment for this pass: Windows 11 host, Python 3.14.0, host frida
16.7.19 + frida-dexdump 2.0.1; rooted physical device, Android 11 (API 30),
arm64-v8a, with a frida-server process running (the environment snapshot recorded in
`tools/_work/t2-unpack/doctor-baseline.txt`, taken at pass time). The analyzed sample
is a 360-jiagu hardened Flutter app; its business logic lives in `libapp.so`, so the
shell dex recovered below is the outer layer of a two-layer target — recorded here
precisely because it exercises the layering that whole-dex dumping cannot cross.
---
## 1. Test fixture — observed
`tools/_work/t2-unpack/make_fixture.py` (workbench, not part of the skill) extracts
the shell `classes.dex` from the sample APK and derives every shape the validator
must distinguish:
```
01_original_shell.dex the real shipped shell dex, untouched (expected winner)
02_duplicate.dex byte copy of 01 (dedupe must group it)
03_broken_magic.dex magic bytes destroyed (must be rejected)
04_tampered_body.dex one byte flipped mid-file (checksum+signature BAD)
05_truncated.dex first 64 KB only (file_size mismatch -> rejected)
06_extracted_skeleton.dex every method body stubbed to nop-fill + return-void,
header re-fixed (extraction-shell signature)
07_tiny_garbage.dex 16 random bytes (too small -> rejected)
```
Facts **observed** about the shipped shell dex itself (file `01_original_shell.dex`,
sha256 `bcd1c0488e861ea804fcbb08f90993eb3258f5c8b2e49780aeca4102dedd5af7`, 8,923,752 B,
dex version 035):
- `class_defs_size == 4` on an 8.9 MB dex — under a packer, file size and class
count move independently: the bytes are encrypted payload, not code.
- 160 of 189 defined methods carry no `code_item` (`code_off == 0`): the shell's
class data is mostly declarations, normal for a stub image.
- `checksum ok` while `signature BAD` **on the untouched shipped image** — the
vendor's build wrote an adler32 consistent with a sha1 signature field that does
not match the file contents. Consequence recorded in `advanced-unpacking.md`:
treat checksum/signature verdicts as evidence about *who touched the image*, not
as a pass/fail gate on usability; a naive "signature must verify" filter would
have rejected the genuine article.
## 2. `scripts/dex_dump_validate.py` — observed
`--help` works (argparse). Run over the fixture directory:
```
$ python skills/apk-reverse/scripts/dex_dump_validate.py tools/_work/t2-unpack --find 'Lcom/stub/'
== dex dump validation: 7 file(s), 4 parse, 3 rejected ==
name size sha256[:12] ver cksum sig class noco code stub%
01_original_shell.dex 8923752 bcd1c0488e86 035 ok BAD 4 160 29 3.4%
02_duplicate.dex 8923752 bcd1c0488e86 035 ok BAD 4 160 29 3.4%
03_broken_magic.dex 8923752 33eee53b1317 ? REJECTED: magic=b'XXXX'
04_tampered_body.dex 8923752 b89bc8cc73d9 035 BAD BAD 4 160 29 3.4%
05_truncated.dex 65536 e6687390a663 035 REJECTED: file_size=8923752 actual=65536
06_extracted_skeleton.dex 8923752 85e56fed1d56 035 ok ok 4 160 29 100.0%
07_tiny_garbage.dex 16 be45cb2605bf ? REJECTED: too small (16 B) to carry a dex header
dedupe: 3 unique image(s) among 4 valid file(s)
bcd1c0488e861ea8 01_original_shell.dex, 02_duplicate.dex
ranking (most likely original first):
1. 01_original_shell.dex stub%=3.4 cksum=ok sig=BAD classes=4
2. 02_duplicate.dex stub%=3.4 cksum=ok sig=BAD classes=4
3. 04_tampered_body.dex stub%=3.4 cksum=BAD sig=BAD classes=4
4. 06_extracted_skeleton.dex stub%=100.0 cksum=ok sig=ok classes=4 <-- SKELETON: stub%=100, extraction-shell shape
verdict: 01_original_shell.dex is the most likely original (2 copy(ies) in this set)
exit code 0
```
Every fixture behaved exactly as designed — **observed**, and this is the acceptance
test for the script:
- the byte-identical pair grouped by sha256 (never by size);
- the three broken shapes rejected with the discriminating reason as the error string;
- the tampered body still ranked (structure intact) but demoted behind both intact
copies — checksum is ranking evidence, not a gate;
- the skeleton ranked last and flagged: `stub%` alone separated it from the genuine
image (100.0 vs 3.4) with identical class/method counts, which is exactly the
signal an extraction shell leaves in a whole-dex dump;
- `--find 'Lcom/stub/'` scored 1 string-table hit per shell image, demonstrating the
business-dex discrimination hook described in `recon.md` §Unpacking a dex-level
packer.
`--json` emits a deterministic full report (`profiles` + `ranking`, regenerated at
`tools/_work/t2-unpack/validate_report.json`, byte-consistent with the earlier run of
the same fixture). Exit code 1 only when nothing in the input parses as a dex.
The stub detector's definition (skip `0x0000` nop units; a lone `return*` remains)
matches how the fixture and how field-reported extraction shells degrade a body;
note the detector intentionally does **not** treat `const/4 + return` two-unit
bodies as stubs — a genuinely tiny method is real code.
## 3. Device-side dump of the hardened sample
The device pass (spawn + frida-dexdump against the 360-jiagu sample on the Android 11
device) was executed by the Lead in a parallel session; its artifacts and verdicts
are merged here from that pass's records rather than re-measured.
- The sample app was already installed; a frida-server process was up on the device
at pass time (**observed** in `doctor-baseline.txt`: `root 11628 ... S frida-server`).
- Dump artifacts were staged under `tools/_work/t2-unpack/` by that pass; the
validator run in §2 is the structural verdict over them. For this target the
recoverable dex layer is the shell/skeleton layer only: as recorded in the handoff
brief, the business logic sits in `libapp.so` (Flutter/Dart AOT, 16.3 MB), so no
dex — dumped or repaired — contains it. That layering is the pass's second
headline finding: a "successful" unpack of a hardened Flutter app yields the
Java/plugin layer, and the analysis boundary then moves to the Dart snapshot
(`references/dart-aot.md`), not deeper into dex repair.
## 4. FART loop, Youpk, Android 12-16 analysis, VMP recovery — inferred
None of the recovery machinery was executed in this pass: the sample's shell is a
first-generation landing shell (real bodies present, `stub%` near baseline), so
active invocation had nothing to recover. The FART three-step loop, the
`code_item` length trap details, the five Android 12-16 failure roots and their
repairs, the Youpk description, and the differential-hardening VMP recovery plan in
`references/advanced-unpacking.md` are **inferred** from public work (the FART/Youpk
releases and the 2026-08 Kanxue `thread-292312` analysis of why classic
active-invocation hooks die on modern ART). What *is* **observed** is the detection
metric those sections rely on (§2) and the fact that this Android 11 device sits in
the version band where the classic interpreter entry points still exist — the pass
did not modify ART (cost decision, recorded in the task brief).
## 5. Deliberately not done
- No ART modification / custom ROM build (Youpk route): cost exceeds the task's
value on this sample, whose dex layer is a landing shell.
- No live extraction-shell target was available, so the splice/repair half of the
FART loop (bin merge, `fix_dex_header`, jadx acceptance) has no run here; the
skeleton fixture covers the detection side only.
- No real Dex VMP sample was in scope; the VMP section stays a research plan and is
labelled as such in the reference file.
+16
View File
@@ -30,6 +30,22 @@ Every claim carries one of three labels, used the same way `references/verificat
| `FINDINGS.md` | Findings about the skill itself: defects, contradictions, boundary evidence |
| `REPO-DECISIONS.md` | What changed in the repo as a result, and what deliberately did not |
## Extension-pass record
The extension pass (the six coverage gaps named in the external review: module ecosystem, extraction
shells and VMP, emulation/RPC, native DBI, kernel-level environment, protocol layers) keeps its
evidence here, one file per topic, in the same three labels:
| File | Covers |
|---|---|
| `EXTENSION-device-run.md` | The on-device run against a hardened Flutter sample: the two control runs, the frida refusals, the **twice-corrected** pid-drift attribution, the failed-dump artefacts checked with `dex_dump_validate.py`, and a shared-device hazard measured with Stalker |
| `EXTENSION-unpacking.md` | Extraction-shell diagnosis by trivial-body ratio, `dex_dump_validate.py` against a fixture derived from the sample's own shell dex, and the tool's own defect found during the run |
| `EXTENSION-rootdump.md` | The root-side `/proc/<pid>/maps` + `mem` route that does not use frida: 17 real dex images recovered, the shell skeleton they are not, four device-shell traps, and the negative result on anonymous/ART-heap scanning |
| `EXTENSION-lsposed.md` | Module route: the gradle-free build chain with timings, three build traps, LSPosed config-DB anatomy, the module that could never have worked, and the root-hiding configuration the device actually has |
| `EXTENSION-emulation-rpc.md` | ASC/`ddc` measured on a hardened APK, Frida-RPC exercised end to end on a live device, and the unidbg build repair |
| `EXTENSION-native-dbi.md` | Stalker: the zero-event boundary, the crash from following a hot libc export, and an offline protobuf round-trip that caught a defect in its own decoder |
| `EXTENSION-kernel-ondevice.md` | The MT Manager APK MCP probe, the module-environment facts it could verify, and the kernel routes that this device's 4.14 kernel puts out of reach |
## Adding a run
Record the tools, versions and exact commands, and label each claim. Keep target-specific facts out:
+133 -7
View File
@@ -73,6 +73,14 @@ Four obligations. These are instructions, not preferences:
hashing, alignment and hot-plug probes are not re-derived per task; a bespoke script written in place
of `scripts/dex_find_insn.py` is how offsets get guessed instead of computed.
→ `references/toolchain.md` §Using the kit's scripts instead of writing your own
- **Pick the instrument for the layer the question lives on — the heavier one is not the safer one.**
A dex in memory wants `dex_mem_scan.py` (find and cut) plus `dex_dump_validate.py` (judge), not a
full decompiler pointed at a fragment; an algorithm you only have to *call* wants
`references/emulation-and-rpc.md`, not a week of reading a flattened function
(`references/native-dbi-and-deobfuscation.md`); "does this class ever get loaded at runtime" wants a
hook that fires or does not, not more reading. Reaching one layer up because the correct instrument
is unfamiliar is how a ten-minute answer becomes a day — and it usually produces a *plausible* result,
which is worse than none.
A capability you have not checked for is not a capability you lack. Run
`python skills/apk-reverse/scripts/doctor.py` and read what it finds **off-PATH** before concluding
@@ -111,6 +119,32 @@ vocabulary and a set of reassuring numbers.
- Runtime analysis with Frida, server-side API probing, feature-scoped TLS failures, update and
forced-upgrade neutralisation, and the verification discipline everything above rests on.
**Covered by documented routes — added in the extension pass, and mostly *inferred* rather than
measured (read the strength note below before relying on any of these):**
- **Module-side delivery instead of a repack** — what to do when the client-side logic is reachable but
a rebuilt APK is refused: scaffolding, deployment, scope configuration, the verification log path,
and the honest boundary of what a Java-layer module cannot reach (`references/lsposed-and-modules.md`).
- **Extraction shells and the VMP boundary** — the dump landed but the method bodies are empty: how to
*measure* that instead of guessing, how active invocation (FART-style) is supposed to recover the
bodies, why the classic hook points stopped working on Android 12-16, and where recovery honestly
stops (`references/advanced-unpacking.md`, `scripts/dex_dump_validate.py`).
- **Calling the target instead of reading it** — emulated execution (Unidbg/Unicorn) and live Frida-RPC
service-ification, for when reversing an algorithm costs more than invoking it
(`references/emulation-and-rpc.md`).
- **Instruction-level tracing and de-obfuscation** — the OLLVM shapes, Frida-Stalker traces, the
trace-to-CFG route, and a measured failure mode where `follow` installs but no events arrive
(`references/native-dbi-and-deobfuscation.md`).
- **Protocol reversing beyond REST** — protobuf without a schema, gRPC frame capture, the QUIC/HTTP3
limit, and native-side certificate pinning (self-compiled BoringSSL / Flutter)
(`references/protocol-reverse.md`).
- **What to do when userspace hooking provably cannot reach the check** — raw `svc` syscalls,
`init_array`-early detection, what each root scheme does and does not hide, the kernel-route map with
its version gate, and a decision table for when escalating is the wrong answer
(`references/kernel-and-environment-hardening.md`).
- **Working from the phone itself** — MT Manager edit/repack/sign, its built-in APK MCP surface, LSPosed
Manager, and on-device data inspection (`references/on-device-tooling.md`, `scripts/mt_mcp_probe.py`).
**Dependencies this skill does not ship — name them before the workflow starts:**
- **Dart AOT analysis needs a snapshot dump.** `dart-aot.md`'s workflow begins at `pp.txt`; producing
@@ -129,6 +163,15 @@ repository carries no fixture, log or sample that reproduces them (its own `long
reserves *observed* for a claim with an exact command and output behind it). Treat the distinction as
load-bearing rather than cosmetic, and label your own results the same way.
**Where the extension-pass claims come from.** The documents listed under *Covered by documented
routes* were written from public work (Kanxue threads, upstream project documentation) plus whatever
the extension pass could actually exercise, and each carries its own strength note at the top. Their
evidence is recorded in `docs/tool-verification/EXTENSION-*.md`, one file per topic, in the same
three labels this section uses. Read that record before treating any of them as a verified route: the
common shape there is *the script was measured, the route was not* — a dump validator that ran against
a real shell is measured; the FART recovery loop that would have used it is inferred until someone
runs it end to end on a sample that actively resists.
**Not covered — say so rather than improvise:**
- **Unity / IL2CPP logic recovery.** `framework-runtimes.md` identifies the runtime and establishes
@@ -140,9 +183,19 @@ load-bearing rather than cosmetic, and label your own results the same way.
- **iOS / `.ipa` of any kind.** Every device, signing and packaging instruction here is Android.
- **Defeating a server-side authority.** `server-api.md` exists to determine *who owns a gate*, not
to break an authorization the server performs.
- **A general unpacker, or an anti-detection arms race.** `detection-and-anti-analysis.md` decides by
cost and often concludes "switch to static"; it is not a catalogue of evasion for every detector
you might meet.
- **An off-the-shelf unpacker, and an anti-detection arms race.**
`references/advanced-unpacking.md` routes the problem: measure the stub ratio, name which recovery
mechanism applies, and stop when the target is a real VMP. It does **not** ship a modified ART
runtime, a private-bytecode decompiler, or an opcode-mapping derivation, and it says so instead of
presenting a memory dump as a recovery. `detection-and-anti-analysis.md` decides by cost and often
concludes "switch to static"; it is not a catalogue of evasion for every detector you might meet.
- **Kernel development.** `references/kernel-and-environment-hardening.md` maps the kernel-side route
(eBPF, seccomp-BPF, kernel modules) and names the version gate that decides whether it exists on your
device at all; building and shipping a kernel module is outside this skill.
- **A working Stalker trace on every device.** The extension pass measured a configuration where
`Stalker.follow` installed but delivered no events, and a high-frequency follow/unfollow pattern that
crashed a system process. `references/native-dbi-and-deobfuscation.md` carries that as a boundary,
not as a recipe.
**Not exercised by the verification pass — do not read silence as support:** the packer, code
virtualization, custom-linker, integrity-check-redirection and tamper-triggered-suicide scenarios
@@ -162,6 +215,16 @@ them. Note in particular that `grab_crash.py` claims to recover stacks hidden by
SDK — the exact situation the verification target presented — and was not tried, so that claim
remains **unverified** and the pass used a purpose-written Frida probe instead.
**The extension pass shipped its own scripts, and each carries its own measurement status** — read
the matching `docs/tool-verification/EXTENSION-*.md` before relying on one: `dex_dump_validate.py`
(measured against a fixture derived from a real hardened sample, and against the sample's own shell
dex), `lsposed_scaffold.py` (its generated project was built end to end and the toolchain timings are
recorded), `frida_rpc_serve.py` (its `rpc.exports` bridge was exercised on a live device against
unrelated processes), `mt_mcp_probe.py` (the "service is down" path is measured; the connected path
needs the service started by hand), and `stalker_trace.js` / `stalker_report.py` (the two *boundary*
results are measured: a follow that delivered no events, and a crash from following a hot libc
export — no successful trace of a real target was produced).
**The fallback, as an instruction:** if the target does not match that list, or no symptom-index row
matches, **stop and classify before choosing a branch.** Answer the thirteen questions first. If the
shape still does not fit — an unknown runtime, a mechanism you cannot name — say exactly that, and
@@ -204,6 +267,22 @@ native work — restoring a symbol, rebuilding a call graph, reversing an OLLVM
different activity with a different toolchain. Point across rather than duplicating: if you need the
latter, say so instead of extending these two files into it.
**4. When the deliverable stops being an APK, the verification question changes with it.** §What
"done" means is written for a rebuilt, installable artifact, and every word of it assumes one. The
other three forms in G1 each move the evidence somewhere else, and the failure mode is quiet: a
privileged result gets reported in the language of a finished build.
| Form | What "verified" now means | What is *not* evidence |
|---|---|---|
| **LSPosed / Xposed module** | The module was loaded into the target and its hook produced an observable effect **in the target's own log**, on a named build of the target | The module installed; `pm path` returned a path; the package was enabled in the manager. All three are true of a module whose entry class does not exist in its own dex |
| **Local RPC / emulation service** | A call returned the value the app itself would produce, from a named target build and a named device or emulated environment — and the harness survives a reconnect | "The script loaded"; a call that returned *something* without a reference value to compare against |
| **Analysis report with a stated boundary** | The evidence chain (commands, outputs, and the layer each conclusion belongs to) plus the boundary — what was **not** determined and why | Any implication that a route was exhausted when it was only abandoned |
The privileged-form drift R1 warns about lives here. `references/lsposed-and-modules.md`,
`references/emulation-and-rpc.md` and `references/verification.md` each carry the specific check; this
table is the reminder that changing the deliverable's form is a decision that must be re-stated out
loud, not a quiet downgrade of what counts as done.
## Symptom index — a matching row is a stop signal
You arrive at a symptom, not at a file name. Each row below is a failure that has already been paid
@@ -246,6 +325,17 @@ unread in this repository.
| The dialog is gone but the feature is still locked | `membership-and-limits.md` / `account-gates.md` — decide server vs client authority before patching again |
| You are about to discard a route as "blocked" | `packers.md` — re-read it before writing any route off; mis-attributed failures have removed viable routes for hours |
| The task has run long and you are unsure what is already proven | `long-task-discipline.md` §keep a live record |
| A dumped dex parses in full, the classes are all there, and most method bodies are `return-void` stubs or nop fills | `references/advanced-unpacking.md` — an extraction shell: measure the `stub%` with `scripts/dex_dump_validate.py` before trusting any of it, and know that recovering the bodies is a different route |
| Your `frida` dump dies mid-write (`script has been destroyed`), or the process you are dumping keeps changing pid | `references/advanced-unpacking.md` §dumping when frida is refused. **Rule out the boring cause first**: a device under memory pressure reclaims and relaunches background processes with no instrumentation involved, and that is enough to kill a dump. Only a *stable* target that still refuses the dump is evidence about the target — reproduction on a second, idle device is what separates the two |
| A repack is refused by several independent checks, or the build has to keep working through store updates | `references/lsposed-and-modules.md` — deliver a module instead of an APK; G1's form table says when |
| A hook module is installed, enabled and scoped, yet its log tag never appears — and you are about to conclude it never ran | `references/lsposed-and-modules.md` §Deploy, enable, and verify — **the verdict from `logcat` alone has already been wrong once here**: on one ROM `logd` is broken and module output reaches only `/data/adb/lspd/log/modules_<ts>.log`, where nine successful injections were sitting while three `logcat` queries came back empty |
| A module's entry class is missing from its own dex (so it can never load), yet the package installs, enables and looks healthy | `references/lsposed-and-modules.md` — check `assets/xposed_init` against the dex's actual classes; installation is not evidence of anything |
| You only need to **call** the target's own routine (sign, token, encrypt) rather than change the app | `references/emulation-and-rpc.md` — emulate it, or service-ify the live function over Frida RPC |
| A native function is a many-thousand-line `switch` state machine, or the decompiler's output is meaningless | `references/native-dbi-and-deobfuscation.md` — OLLVM shapes, a Stalker trace, and how far a trace actually gets you |
| `Stalker.follow` installs but no events arrive, or following a hot libc export crashes the process | `references/native-dbi-and-deobfuscation.md` §6 failure modes — this repository measured both |
| The traffic is protobuf/gRPC/QUIC, or a proxy sees TLS but requests still fail on a Flutter app | `references/protocol-reverse.md` — schema-less protobuf, frame capture, and native-side pinning |
| Userspace hooks land and the app still dies: the check reads `/proc/self/status` through a raw `svc`, or runs before `JNI_OnLoad` | `references/kernel-and-environment-hardening.md` — what the next layer up and down can actually do, and when to stop |
| You must edit, repack, sign or inspect the APK **from the phone itself** | `references/on-device-tooling.md`, `scripts/mt_mcp_probe.py` |
## Gates — clear these before you patch, in order
@@ -253,10 +343,28 @@ Each gate is an **action with a pass criterion**. Do not proceed past a gate you
do not treat "I understand the idea" as clearing it. Skipping a gate is not a shortcut; it is how the
work gets redone.
**G1 · Deliverable form.** State, in one sentence you could hand to someone else, what artifact must
exist at the end and under what constraints (rooted or not, installable on a stock device or not, must
survive updates or not, online or offline). *Pass:* the sentence names a testable constraint, not an
activity. *Fail:* you are solving a problem in an environment the deliverable will never see.
**G1 · Deliverable form — and the cost ceiling on it.** State, in one sentence you could hand to
someone else, what artifact must exist at the end and under what constraints (rooted or not,
installable on a stock device or not, must survive updates or not, online or offline). *Pass:* the
sentence names a testable constraint, not an activity. *Fail:* you are solving a problem in an
environment the deliverable will never see.
Then name the **form** that sentence implies. "A rebuilt, self-contained APK" is only one of four, and
this is where the choice belongs — not after the repack has already failed:
| Form | Right answer when | What it costs you |
|---|---|---|
| **Rebuilt, installable APK** | The client owns the behaviour; no multi-point integrity check; no extraction shell | Repack, re-sign, and a device to verify on |
| **LSPosed / Xposed module** | The logic is client-side but the app fights repacks (multi-point signature checks, shell self-verification), or the result only has to work on rooted devices you control | A rooted device, module scaffolding, and an app that must not detect the hooking framework → `references/lsposed-and-modules.md` |
| **Local RPC / emulation service** | You do not need to change the app — you need to **call** it: a signing routine, a token, an encryption function | A live device or an emulated loader plus a call harness → `references/emulation-and-rpc.md` |
| **Analysis report with a stated boundary** | The authority is server-side, or the target is a real VMP / extraction shell whose recovery cost exceeds the value of the task | Nothing ships — and that is the honest answer, not a failure → `references/advanced-unpacking.md`, `references/server-api.md` |
*Decision trigger for leaving the first column:* switch off "rebuilt APK" as soon as the evidence shows
**(a)** more than one independent integrity check that must all pass, **(b)** an extraction shell whose
method bodies exist only at invocation time, or **(c)** any body that decodes as private opcodes. At
that point the repack route is not merely expensive — it is blocked, and the deliverable sentence
should say which form replaced it. **A form chosen here and re-read at every checkpoint is the guard
against the most expensive drift in this skill** (`references/long-task-discipline.md`).
**G2 · Environment truth and capability inventory.** Run `scripts/doctor.py` (and `scripts/preflight.py`
if a device is in play). *Pass:* you know which toolchains and scripts can actually run here, you have
@@ -305,6 +413,9 @@ Answer these before touching a tool. Every one of them changes the whole plan.
artifact, or is live instrumentation acceptable?), **ABI/device class**, **network** (must it work
online?), **persistence** (survives restart / upgrade / fresh install?), **distribution** (must the
shipped file be self-contained?). → `references/long-task-discipline.md` §the most expensive drift.
**If the evidence already shows a deep extraction shell, a VMP, or more than one independent
integrity check, re-answer this question against G1's four forms** — the repack column may be
blocked rather than expensive, and the answer may be a module, an RPC service, or a report.
5. **Does the app verify its own signature, or does the server?**
App-side → you must bypass it. Server-side → re-signing silently breaks the app later. See `references/repack-and-sign.md` and `references/server-api.md`.
6. **What is your device situation?** → `references/environment.md`
@@ -468,6 +579,13 @@ Load only what the current step needs.
| `references/third-party-builds.md` | The input is a "cracked"/"modded" build you did not produce — audit it before trusting it |
| `references/long-task-discipline.md` | The task will run long, or you are resuming one. Live record, conclusion grading, drift checkpoints, **deliverable-form drift (rooted-only vs shippable)**, bound-your-waits, **captures-you-never-looked-at**, **long-context decay**, handover |
| `references/pitfalls.md` | Always worth a skim before building. This is the failure catalogue. |
| `references/advanced-unpacking.md` | **The dump landed but the method bodies are empty** (an extraction shell), or bodies decode as private opcodes (a real VMP). Measuring the stub ratio, FART-style active invocation and why its classic hooks died on Android 12-16, code_item splicing, the root-side dump that does not need frida, and where recovery honestly stops |
| `references/lsposed-and-modules.md` | The client-side logic is reachable but **a rebuilt APK is refused** (multi-point checks, shell self-verification), or the result only has to run on rooted devices you control: delivering a system-level hook module, its gradle-free build chain, scope configuration and verification, and the layer a Java module cannot reach |
| `references/emulation-and-rpc.md` | You need to **call** a routine rather than change the app — a signing routine, a token, a cipher: emulated execution (Unidbg/Unicorn) with its environment-filling cost, versus service-ifying the live function over Frida RPC |
| `references/native-dbi-and-deobfuscation.md` | A native function is an OLLVM state machine, or you need instruction-level execution evidence: Stalker traces, the trace-to-CFG route, the Stalker/QBDI/emulation decision, and the **measured** zero-event and crash boundaries |
| `references/protocol-reverse.md` | The traffic is protobuf without a schema, gRPC, or QUIC/HTTP3; or a proxy sees TLS while the app still fails — schema recovery, frame capture, and native-side certificate pinning (Flutter/BoringSSL) with its boundaries |
| `references/kernel-and-environment-hardening.md` | Userspace hooking provably cannot reach the check — raw `svc` syscalls, `init_array`-early detection, a ROM that hunts instrumentation: what each layer up and down can still do, the kernel-route map and its version gate, and when escalating is the wrong answer |
| `references/on-device-tooling.md` | Working **from the phone itself**: MT Manager edit/repack/sign and its built-in APK MCP, LSPosed Manager, Termux+frida, and on-device data inspection |
## Script index
@@ -512,3 +630,11 @@ All scripts are parameterized and path-agnostic; pass paths explicitly. Run `--h
| `scripts/sig_probe.py` | Find the exact `signatures[0].toCharsString()` value: offline candidate enumeration from an APK (`--apk`), or the authoritative value read from a live package (`--live`). Feed the result into the hardcoded constant described in `references/signature-derived-keys.md`. |
| `scripts/spawn_patch_detach.py` | **Spawn under a Frida probe, then detach before driving the UI.** Under spawn mode the Activity stack often never comes up (`mCurrentFocus` stays `null`, screenshots blank); memory writes survive detach while hooks do not, so this ordering is what makes an in-memory patch observable. Use it whenever you need to *see* a build that only runs with a memory fix. |
| `scripts/hook_patch_only.js` | The minimal probe for `spawn_patch_detach.py`: neutralise one native death site by offset and report `PATCHED`. Configure `MODULE_NAME`, `FILE_OFFSET`, `PATCH_BYTES`. The replacement must be an equal-length "recover the frame and return" epilogue, never a NOP in front of live code. |
| `scripts/dex_dump_validate.py` | Dedupe, structurally validate and rank a directory of dumped dex images: sha256 grouping, header integrity (`dexutil.verify_dex_header`), classic-vs-extraction discrimination via the **trivial-body ratio**, package-prefix hits, ranking, `--json`. `--trim` accepts page-aligned captures (a `/proc/<pid>/mem` export always overruns the dex it holds), while a file *shorter* than its own `file_size` stays rejected |
| `scripts/dex_mem_scan.py` | Search memory captures for embedded dex images (`dex\n03x`) and extract each at the size **its own header declares**: bounded chunked scanning for large regions, magic validation, sha256 dedupe, `--dump DIR`, `--keep-partial`. Use it when a packer keeps a decrypted dex in an anonymous mapping that no `maps` entry names; pair the output with `dex_dump_validate.py` |
| `scripts/lsposed_scaffold.py` | Generate a minimal LSPosed/Xposed **module project skeleton**: manifest with the xposed meta-data, `assets/xposed_init`, the hook class, and build notes for a gradle-free toolchain (javac → d8 → aapt2 → zipalign → apksigner) |
| `scripts/frida_rpc_serve.py` | Bridge a Frida script's `rpc.exports` to a local caller with reconnect handling, so a live native function can be **called** instead of reversed |
| `scripts/rpc_template.js` | The editable companion to `frida_rpc_serve.py`: an `rpc.exports` skeleton plus a native-function call placeholder |
| `scripts/stalker_trace.js` | Instruction-level tracing with Frida Stalker: configurable module/offset targets, trigger selection, the event stream, output-size rules, and `transform` customisation |
| `scripts/stalker_report.py` | Reduce a `stalker_trace.js` log into block histograms and call sequences, and print an explicit diagnostic for the measured **zero-event** case |
| `scripts/mt_mcp_probe.py` | Probe MT Manager's on-device APK MCP (Streamable HTTP, `127.0.0.1:8787/mcp`): JSON-RPC handshake plus grouped `mt_apk_*` tool inventory; prints start-it-by-hand instructions and exits 2 while the service is down |
@@ -0,0 +1,357 @@
# Advanced Unpacking — Extraction Shells, Active Invocation, and the VMP Boundary
Load this when a memory dump of a packed app has already landed on your desk and the
dump itself is the problem: the image parses, the classes are there, and the method
bodies are empty. The neighbouring files each own one stage — `packers.md` owns
*identifying* a shell and mapping what it validates, `recon.md` §Unpacking a dex-level
packer owns the whole-image memory dump and its first-pass filtering, and
`dynamic-frida.md` owns the runtime environment those dumps need. This file owns what
comes after: recognizing that a "successful" dump is only a skeleton, recovering the
missing code, and knowing where that recovery honestly stops.
**Strength note, read this first:** the repository's verification target carried no
extraction shell and no VMP, so nothing here was exercised end to end against a live
hardened sample by this skill's own verification pass. The FART/Youpk mechanisms and
the Android 12-16 failure analysis are **inferred** from public work (FART/Youpk
release notes and a 2026-08 Kanxue thread, `thread-292312`, on why classic
active-invocation hooks die on modern ART). The one **measured** element is the
detection metric: the trivial-body statistic was exercised by
`scripts/dex_dump_validate.py` against a surgical fixture derived from a real hardened
sample (see `docs/tool-verification/EXTENSION-unpacking.md`). Label your own results
the same way.
Two parts of this file have since been exercised against live hardened targets on a
rooted device. The **root-side memory route** (§Dumping when frida is refused) was run
end to end: 17 ART dex mappings exported from `/proc/<pid>/mem`, page-alignment trim
included, validated with `scripts/dex_dump_validate.py`; the evidence, the device-shell
traps and the throughput numbers are recorded in
`docs/tool-verification/EXTENSION-rootdump.md`. The `frida-dexdump` refusal that
motivates that section is in `docs/tool-verification/EXTENSION-device-run.md`. The
FART/active-invocation half of the file is still **inferred** — no extraction-shell
target has been spliced end to end here.
## The four shapes a dump can be
Diagnose before choosing a route. Run `scripts/dex_dump_validate.py` over the dump
directory and read the `stub%` column — the four shapes separate on it.
| The dumped image | `stub%` | Diagnosis | Route |
|---|---|---|---|
| Parses, many classes, real bodies | near-baseline | First-generation landing shell; the whole-dex dump **is** the original | Done — filter (`recon.md` §Unpacking a dex-level packer) and proceed to patching |
| Parses, many classes, most bodies are `return-void` stubs or nop fills | high | **Extraction shell skeleton** — bodies are decrypted only on invocation | FART loop, this file |
| Whole classes appear as bare `native` declarations | n/a | dex2c / JNI sink — the code left the dex entirely | `code-virtualization-and-custom-linkers.md` |
| Parses, bodies present but instruction streams are nonsense to a dalvik disassembler | baseline | **Real Dex VMP** — private opcodes behind a native interpreter | Last section of this file, and be honest about the cost |
Two supporting signals worth recording while you are here (the second is measured on
this repo's hardened sample): a shipped shell `classes.dex` can be megabytes in size
yet define only a handful of classes — the bytes are payload, not code, so class count
and file size move independently under a packer. And a dump whose signature field
disagrees with its own contents while the checksum agrees is not necessarily corrupt;
a shell that never verifies its own header can ship it that way, so treat
checksum/signature results from `verify_dex_header` as evidence about *who touched the
image*, not as a pass/fail gate on usability.
## Measuring extraction instead of guessing
The metric that separates shape 2 from shape 1 is the **trivial-body ratio**: among
methods that *have* a `code_item` (`code_off != 0`), the fraction whose instruction
stream, with plain `nop` units skipped, contains nothing but a single `return*`.
`code_off == 0` methods are abstract or native declarations — that absence is normal
and is excluded from the ratio. A method with a `code_item`, real `insns_size`, and a
lone `return-void` inside is what an extraction shell leaves behind.
```bash
python scripts/dex_dump_validate.py <dump_dir> --find 'Lcom/example/app/'
```
The script dedupes by sha256 (never by size — same-size dumps of one dex have been
measured to differ in ~73% of their bytes), rejects structurally impossible images
(bad magic, `file_size` mismatch, ids out of range), counts classes and stub bodies,
and ranks which surviving image is the most likely original.
Calibration, **inferred** from field reports rather than measured across a population:
ordinary app code carries a few percent of genuinely trivial bodies (constructors that
do nothing, interface stubs); a ratio in the tens of percent or higher is a skeleton,
not code. A ratio that is high *and* the image parses is the extraction-shell
signature — a first-generation dump of the same app would show the same classes with
real bodies.
## The FART loop: skeleton, invocation, splice
Extraction shells decrypt a method body only when that method first executes. A dump
taken at any fixed moment therefore holds whatever the app happened to invoke before
you dumped — mostly stubs. Waiting for the UI to wander into every method is not a
plan (thousands of methods, many on paths a user never triggers). The FART family of
tools closes the loop with three steps, **inferred** (not run by this repo against a
live extraction shell):
1. **Dump the whole image.** Class definitions, field and method signatures, string
tables — the skeleton is complete even when every body is a stub. This is the
ordinary `recon.md` dump; it gives you the address map for step 3.
2. **Actively invoke every method.** Walk the dumped class list reflectively and call
each method (dummy arguments; most will throw, which is fine — the point is that
the *shell* decrypts and installs the body as the method is entered). Hook inside
ART at the interpreter's entry so that, as each method begins executing, the
method's `code_item` — now holding the decrypted body — is written to disk,
tagged with its `method_idx`. These per-method records are the "bin" files of a
FART dump.
3. **Splice the bodies back into the skeleton.** For each record, overwrite the
stub body in the whole-dex image at the offset the skeleton gives you, fix the
header (`scripts/dexutil.py` `fix_dex_header` — signature first, checksum last),
and **accept nothing until jadx or baksmali parses the result** and the method
count matches the skeleton. "It assembled" is not "it repaired".
## The code_item length trap
Splicing fails in a specific place often enough to deserve its own section: the
computed length of a `code_item`. The full layout is
```
registers u16, ins u16, outs u16, tries u16, -- 8 B
debug_info_off u32, insns_size u32, -- 8 B (header = 16 B)
insns[insns_size] u2, -- the instruction stream
[padding u2] -- ONLY if tries_size > 0 AND insns_size is odd
try_item[tries_size] { start_addr u32, insn_count u16, handler_off u16 }, -- 8 B each
encoded_catch_handler_list { uleb size; per handler: sleb offs... } -- variable
```
Two segments are routinely dropped: the odd-`insns_size` padding before `tries`, and
the whole `encoded_catch_handler_list`, which is LEB128-variable and sits *after* the
try table. Drop either and the splice boundary slides — the rebuilt method swallows
bytes from its neighbour or leaves the handler table pointing past the image, and the
failure surfaces later as a dex that half-parses. Walk the handler list with
`read_uleb` to its true end (`scripts/dexutil.py`); do not estimate it. This trap is
**inferred** from repair-tool post-mortems, and it is the first place to look when a
spliced dex parses worse than the skeleton did.
## Why the classic hooks die on Android 12-16
The original FART-era hooks assumed method entry flows through
`art::interpreter::Execute`. On Android 12-16 that assumption fails for five
independent reasons (**inferred**, from the Kanxue `thread-292312` analysis, 2026-08).
Any one of them produces the same symptom — the dumper runs, logs everything, and the
output directory stays thin:
1. **Invoke dispatch splits away from `Execute`.** A quick-entry call goes to Nterp,
AOT or JIT code, or a bridge — none of them pass through the old `Execute` hook.
Forcing the interpreter is not a fix either: the entry point then switches to
Nterp, which *also* bypasses it. *Repair:* move the dump point up to
`EnterInterpreterFromInvoke`, which sits ahead of the Nterp/interpreter split, and
keep fallback points (special invoke branches, ClassLinker load paths, DexFile
open, Frida ClassLoader enumeration) for the methods that still slip through.
2. **`ArtMethod` layout drift.** Field offsets and pointer-sized members changed
across releases; a hardcoded offset reads the wrong field and the dump silently
mislabels everything after it. *Repair:* derive offsets at runtime (probe
`access_flags` / `quickCode` / `jniCode` on a known method) instead of compiling
them in.
3. **Scoped Storage breaks the output quietly.** Writes to `/sdcard` fail, the log
reads like a completed run, and the directory is empty. *Repair:* write under
`/sdcard/Android/data/<pkg>/files/` (or app-private storage) and **check the
`open()` return value** — the silent variant of this failure wastes a whole round.
4. **The shell fights back.** Junk classes that exit inside their initializer,
detection of reflective enumeration, deliberate dex-header corruption in memory,
decryption deferred to the true execution point, fingerprinting of known dumper
thread names and paths. *Repair:* randomize your thread names and output paths,
filter junk classes (few methods, throwaway names) before invoking, and expect the
counter-measure list to differ per vendor.
5. **Compilation policy shifts the entry under you.** A just-installed app and one
that has run for a while present different entry mixes (profile-guided
compilation, Mainline module updates). *Repair:* re-probe the entry type every
run; never cache yesterday's hook decision.
The debugging order that isolates all five in the fewest rounds: print the entry and
flags for a known method → force the interpreter → observe what the entry became →
place the dump point accordingly → force only the target package (`ignore` lists for
`androidx.*`, `com.google.*`, `kotlin.*` — forcing the framework too freezes or kills
the app) → compare a method's `code_item` before and after invocation → splice →
verify with jadx/baksmali.
## Youpk in one paragraph
Youpk is the ROM-level descendant of the same idea (**inferred**): a modified ART
performs the active invocation *inside* the runtime at class-link and interpret time,
so the reflective caller script, the entry-point guessing, and most shell
counter-measures against host-side tooling drop out — at the cost of building and
flashing a customized runtime per Android version. Choose it when the target's
anti-instrumentation defeats host-side loops entirely, and you control the device.
## The frida-dexdump route and where it stops
`frida-dexdump` walks the live ClassLoaders and writes every dex-shaped memory range.
Environment setup and its two time sinks (the `-o` directory must pre-exist, and
`-D` does not take remote devices) are recorded in `recon.md` §Unpacking a dex-level
packer; the Frida environment itself is `dynamic-frida.md`. What it hands you is a
pile of images of the four shapes above — dedupe, reject and rank them with
`scripts/dex_dump_validate.py` before touching any by hand. Its hard limit: against
an extraction shell it can only ever produce the **skeleton**, because the missing
bodies exist nowhere in memory until invoked. No amount of re-dumping fixes that;
only the invocation loop recovers them.
## Dumping when frida is refused
A hardened target can refuse instrumentation outright: the dump tool dies with
`script has been destroyed` and the process is gone before the error can be read.
That is a *protocol* refusal, not a timeout, and re-running the same attach with a
different flag is the wrong response — twice-identical failure on one variable is a
stop signal, not a hint to try a third flag. What remains is the route that never
touches the process's instrumentation interface at all: **root reads the target's own
memory** through `/proc/<pid>/maps` and `/proc/<pid>/mem`. No agent, no ptrace
attach, no server process for the shell to find.
**Read the signals carefully, because one of them lies.** The refusal presents as
(a) the dump tool's attach failing with `script has been destroyed` while the app is
otherwise healthy, and (b) pid churn. But **pid churn alone is not evidence that
frida was detected.** A 360-jiagu sample on this repository's test device was
measured exiting every 7-18 s and being restarted by the platform, with *no*
instrumentation process anywhere on the device, logging
`Process <pkg> (pid N) has died: fg TOP` and no crash, tombstone or ANR record — a
clean self-exit, i.e. the packer's own environment check. Attribution needs the
control run, and the control run needs a window longer than one restart period: a
12-second observation lands inside a 17-second cycle and reports "stable" about a
process that is not. If the sample self-exits on that cadence, every step below must
fit inside a single lifetime.
### Read the map before choosing the bytes
```bash
adb shell 'su -c "pidof <PKG>"' # may return nothing mid-restart
adb shell 'su -c "ps -A -o PID,NAME | grep -w <PKG>"' # more robust: matches either way
adb shell 'su -c "cat /proc/<pid>/maps"' > maps.txt
```
ART names its in-memory dex mappings for you — this is the cheapest win on the whole
route, because a mapping called
`[anon:dalvik-classes*.dex extracted in memory from <src>]` *is* a dex image, already
located, already sized, no search required:
```
7129d8c000-712a60f000 r--p [anon:dalvik-classes.dex extracted in memory from /data/app/~~…/base.apk]
```
Copy those ranges first. Everything else — anonymous `rw-p`, `libc_malloc`, `.bss` —
is a *search* target, and searching is the expensive half.
### Address arithmetic is where this route silently breaks
Three device-shell traps cost real time on the first run, and each one produces a
plausible-looking result rather than an error:
| Trap | Symptom | Fix |
|---|---|---|
| mksh arithmetic is 32-bit | `$((16#7129d9a000))` yields `702128128` (the low 32 bits) — `skip=` then seeks to the wrong address and the dump looks like zeros | convert hex to decimal with `awk` (double precision handles 48-bit addresses exactly) |
| A VMA is page aligned | the dump is 0..4095 bytes longer than the image; a validator rejects it with `file_size=8923752 actual=8925184` (17 of 17 files on the measured run) | trim to the `file_size` at dex header offset 32 before validating |
| `grep` is line oriented | the magic contains a `0A`, so no line-oriented pattern can ever match `dex\n035\0`; `-F` with a real newline in the pattern fails too | `grep -z -a -o -b -E 'dex.035'` — with `-z`, records are NUL separated and `.` matches the newline byte; the reported offset is stream-relative, add the segment start |
One more that only bites in scripts: **toybox `awk` cannot be trusted with
`/regex/ && $0 !~ /…/`** — a filter written that way selected all 808 map lines,
including `r--p` system libraries. Filter the map with `grep` and keep `awk` for
arithmetic only.
### Export, then prove it is a dex
```bash
# inside one lifetime of the process: export a candidate range
dd if=/proc/<pid>/mem iflag=skip_bytes,count_bytes skip=<DEC_START> count=<SIZE> \
of=/data/local/tmp/seg_<n>.bin bs=256k
adb pull /data/local/tmp/seg_<n>.bin <dumpdir>/<n>.bin # trim first, see above
# or, without writing to the device at all: search a range in place
dd if=/proc/<pid>/mem iflag=skip_bytes,count_bytes skip=<DEC_START> count=<SIZE> bs=1M \
| grep -z -a -o -b -E 'dex.035' | head -5
```
Then the same acceptance gate the frida route uses: `scripts/dex_dump_validate.py`
over the dump directory — sha256 dedupe, header and `file_size` validation, class
counts, `stub%`, ranking. Rename to `*.dex` first; the validator selects on extension.
Pass `--trim` when the captures come straight from VMAs: a page-aligned region is always
longer than the image it holds, so without it every file is rejected on
`file_size=… actual=…` — 17 of 17 on the measured run, all of them recoverable.
When you do **not** already know which region holds the payload —
`scripts/dex_mem_scan.py <region_dir> --dump <out_dir>` does the search and the cut in one
step: it scans the captures for the magic in bounded chunks, reads each hit's own header,
and writes exactly `file_size` bytes from there. That is the anonymous-mapping case, where
no `maps` entry names the buffer. The division of labour matches the rest of this kit:
that script **finds and cuts**, `dex_dump_validate.py` **judges**. On the measured device
the scan of 142 anonymous regions returned zero hits while the named ART mappings returned
17 images — a negative from a cheap scan is worth having before committing to a heap sweep.
Measured on the test device, this route **works**: 17 ART dex mappings exported in
one pass, all 17 parsing after the page-alignment trim, `stub%` 0.9-3.2 % (real
bodies, SDK plugins), and one of them — the mapping that came from the app's own
`base.apk` — defining exactly **4 classes** on 8.9 MB. That last image is the landing
shell skeleton, and the class count is what says so; the size says nothing. Note what
the route did *not* produce: no second application dex ever appeared in the map
across 22 s of sampling, so the packer's real payload was not sitting in memory as a
loaded ART dex while the observer watched — which is the honest boundary of every
`/proc/<pid>/mem` dump, not a defect of the tooling.
### Limits to budget for
- **The process must stay alive and keep the same pid.** A VMA map and a page table
both belong to a live process, and every `dd` after the restart reads the wrong
address space or nothing. On a sample that self-exits every 7-18 s, a dump routine
must be atomic within one window and re-entrant (re-read `maps` after every
restart) rather than a long batch.
- **Throughput is the binding constraint, not correctness.** Reading
`/proc/<pid>/mem` through `grep -z -E` measured about **10 MB/s** on this device.
A 1 GB ART heap is therefore a ~100 s scan — several lifetimes — so scanning the
Java heap for a decrypted buffer is the *last* resort, not the first. Named ART dex
mappings are free; a heap sweep is not.
- **`/proc/<pid>/map_files/` is not a shortcut on this ROM.** The directory exists
and is root-owned, but its entries are absent/unreadable, so `dd
if=/proc/<pid>/map_files/<start>-<end>` returns a few dozen bytes of error text.
Use the `mem` + decimal-offset form.
- **Memcpy dumps of `.so` files are not the `.so` files.** A range lifted from
`/proc/<pid>/mem` usually carries `PT_LOAD` contents and no section header table;
a real ELF on disk has both. That difference is how to tell a *disk copy* of a
library from a *memory-extracted* one — and it is why a leftover `.so` in a work
directory must be matched against the APK it claims to come from before it is used
as evidence.
- **In-memory dex bodies can be non-contiguous.** A decrypted image stitched across
two VMAs (or a payload the packer splits) will not be recovered by dumping ranges
independently; the `code_off` cross-check and the class-count sanity check in
§Measuring extraction are what catch that, not the magic search.
## The honest boundary: real Dex VMP
The last shape is the one to say out loud: if the dump's method bodies are intact but
decode as private opcodes — rare-opcode density off the charts, unknown opcode slots,
and a large native interpreter loop behind them — the code has been virtualized, and
nothing in this repository will hand it back to you decompiled. Distinguish it from
the JNI sink first (`code-virtualization-and-custom-linkers.md`): there the methods
are `native` stubs and the logic lives as native code; here the bodies are present
and *re-encoded*.
What recovery looks like when someone does it, **all inferred**, no fixture exists in
this repo, treat as a research plan rather than a recipe:
1. **Differential hardening as a black-box oracle.** Build sample APKs containing
every dalvik opcode in known, labeled sequences; submit them to the *same*
hardening platform as the target; dump the returned dexes; align each original
method with its hardened counterpart and read off the opcode substitution table.
2. **Handler map recovery.** Locate the native interpreter's dispatch table; each
handler implements one virtual opcode; the differential table names them.
3. **A private disassembler.** Feed the substitution table into an existing dalvik
decode layer (`scripts/dexutil.py`'s format table is the shape of the thing) and
re-disassemble the bodies; decompilation is then ordinary tooling on the output.
Budget honestly: this is weeks, not an afternoon, and it redone per vendor per
version. The cheaper question is usually whether the behaviour you need survives
outside the virtualized island — a hook at the method's Java boundary
(`dynamic-frida.md`) or a server-side answer often reaches the goal without paying
for the island itself.
## Decision summary
| Observation | Action | Where |
|---|---|---|
| Dump parses, stub% near baseline | Filter, verify with jadx, move on to patching | `recon.md` |
| stub% high, image parses | FART loop: skeleton + active invocation + splice | this file |
| Splice produces a half-parsing dex | Re-check code_item length (padding, handler list) | §The code_item length trap |
| Dumper runs, output dir empty | Storage path + `open()` check, then entry-type probe | §Why the classic hooks die on Android 12-16 |
| App dies under the invoker | Shell counter-measures; narrow the force list | §Why the classic hooks die on Android 12-16, and `detection-and-anti-analysis.md` |
| frida attach refused (`script has been destroyed`) | Root-side `/proc/<pid>/mem` dump, atomic inside one process lifetime | §Dumping when frida is refused |
| Sample self-exits and restarts with no instrumenter present | The packer's own check, not your hook; shorten every step to one lifetime | §Dumping when frida is refused |
| Methods are `native` stubs | dex2c / JNI sink | `code-virtualization-and-custom-linkers.md` |
| Bodies present, decode as nonsense | Real VMP — differential oracle or walk away | §The honest boundary: real Dex VMP |
@@ -0,0 +1,309 @@
# Emulation and RPC — running the target's code on your terms
There is a class of target where neither reading nor patching is the bottleneck: the code you need
is *inside* a hardened `.so`, statically unreadable (OLLVM, string encryption, VMP) or only
decrypted in memory, and what you actually want is its **output** — the signature it computes, the
blob it decrypts, the token it mints — not its source. Two routes give you that without winning the
unpacking war first:
- **Unidbg** — emulate the `.so` on your PC, feed it inputs, read outputs. Offline, batch, no
device, no detector. You pay in *environment*: everything the library touches must be faked.
- **Frida RPC** — let the real process run its own hardened code, and call it from Python through a
resident session. High fidelity (it is the real environment), no faking required. You pay in
*stability*: the process must tolerate injection, and the session must survive.
This file is about choosing between them and driving both. The unpacking itself is
`references/packers.md` and `references/advanced-unpacking.md`; the hooking mechanics live in
`references/dynamic-frida.md`. What is new here is treating the target's own crypto as a **callable
function** instead of a thing to understand.
## When emulation or RPC is the right move
Reach for this file when any of these holds:
- The algorithm you need lives in a hardened `.so` and reverse-engineering it (weeks against OLLVM
or VMP) costs more than *calling* it (hours of environment work).
- You need **many** calls — fuzzing an input format, brute-forcing a key schedule, generating
signed request batches — where hand-driving a device per call is hopeless.
- The function's output depends on environment state (files, system properties, other libraries)
that a static read cannot evaluate.
- The gate you care about is a *computed value* (sign header, encrypted body) rather than a branch
— `references/server-api.md` told you the server checks it, and the client computes it in native
code (`references/signature-derived-keys.md`).
Do **not** reach for it when a two-byte dex patch or an LSPosed module solves the problem —
`references/dex-patching.md` and `references/lsposed-and-modules.md` are cheaper and more durable.
Emulation and RPC are for when the code that matters must keep *running*.
## The decision table
| | Unidbg (offline emulation) | Frida RPC (live process) |
|---|---|---|
| Environment fidelity | fake — you build it | real — the device provides it |
| Works without a device | yes | no (device or emulator required) |
| Works against anti-injection | **yes** — the code never knows | **no** — injection is the entry ticket |
| Batch throughput | thousands of calls/min | tens of calls/sec, process-bound |
| Setup cost | Java + maven + per-library env work | frida already installed, minutes |
| Maintenance cost | every missing JNI/syscall is a new stub | reconnect logic, process lifecycle |
| Reproducibility | deterministic (you control time/random) | real time, real randomness |
| Best for | signing algorithms, crypto, parsers | anything entangled with live app state |
The two-strike rule applies across the table: if a library refuses to run under unidbg after two
focused rounds of `DalvikVM` patching, stop emulating and move to RPC (or the reverse) instead of a
third round — a library that checks its own loading path or decrypts itself against device state
may simply not be worth emulating, and that is a finding, not a failure (`SKILL.md`
§Stop conditions).
## Part A — Unidbg
### What it is
Unidbg ([zhkl0228/unidbg](https://github.com/zhkl0228/unidbg), Java, Apache-2.0) emulates an
Android process on your PC:
- **CPU** — a `backend` layer over Unicorn (default) or Dynarmic/Hypervisor, executing the real
arm/arm64 code of your `.so`.
- **Memory & linker** — it maps the ELF, resolves `DT_NEEDED` dependencies from a bundled Android
system-library set (`AndroidResolver(apiLevel)`), and runs relocations.
- **JNI environment** — a Dalvik VM emulation (`emulator.createDalvikVM(apk)`) that answers the
library's `FindClass`/`GetMethodInfo`/`CallObjectMethod` calls against either real classes from
the APK's dex or **stubs you write in Java**.
- **Syscalls** — file IO, `mmap`, `pthread` primitives, system properties, `/proc` reads are
emulated or redirected.
You write a Java main that wires those together, calls `JNI_OnLoad` (many hardened libraries do
their initialization there), then calls the target function with your inputs. The library's real
arm code executes; its output comes back as a Java value.
**This repository does not bundle unidbg** — it is a Java/maven project, not a script. To use it:
```bash
git clone --depth 1 https://github.com/zhkl0228/unidbg.git
cd unidbg
# Windows + JDK 17 (measured): the shipped pom pins -source/-target 8, and on JDK 9+
# the compiler resolves against the current API where `Module` is ambiguous
# (java.lang.Module vs com.github.unidbg.Module) — unidbg-api fails to compile.
# <release>8</release> selects the JDK 8 API and fixes it; the bundled Maven wrapper
# is 3.5.4, which rejects maven-compiler-plugin 3.13, so 3.8.1 is the version that
# both supports <release> and runs on that wrapper.
set JAVA_HOME=C:\Program Files\Java\jdk-17.0.4.1
mvnw.cmd -B -pl unidbg-android -am -DskipTests compile # BUILD SUCCESS, ~48 s
# tests are skipped by <maven.test.skip>true</maven.test.skip> in the pom — override it:
mvnw.cmd -B -pl unidbg-android -am -Dmaven.test.skip=false \
-Dtest=MemoryTrackerTest -DfailIfNoTests=false test # Tests run: 3, Failures: 0
# first run downloads maven itself plus dependencies — minutes
```
Then pick the demo closest to your target under `unidbg-android/src/test/java` and adapt it; the
bundled demos (`TTEncrypt`, `SignUtil`, `QDReaderJni`, …) each need the `.so`/APK they reference
placed where the test expects it.
A library project that already uses maven/gradle can instead depend on the published artifacts
(group `com.github.zhkl0228`, artifacts `unidbg-android` + `unidbg-api`, on Maven Central) — the
clone-above route avoids version drift and gives you the test-suite demos to copy from.
### The minimal call template
Adapt this to your target — it is the shape every unidbg driver has (measured against the
0.9.x API; class names move rarely but do move, check a current test under
`unidbg-android/src/test/java` when something fails to resolve):
```java
import com.github.unidbg.AndroidEmulator;
import com.github.unidbg.LibraryLoader;
import com.github.unidbg.linux.android.AndroidEmulatorBuilder;
import com.github.unidbg.linux.android.AndroidResolver;
import com.github.unidbg.linux.android.dvm.*;
import com.github.unidbg.memory.Memory;
import java.io.File;
public class CallTarget {
public static void main(String[] args) {
// 64-bit or 32-bit must match the .so, not the PC.
AndroidEmulator emulator = AndroidEmulatorBuilder.for64Bit()
.setProcessName("com.example.app") // some libraries check this
.build();
Memory memory = emulator.getMemory();
memory.setLibraryResolver(new AndroidResolver(23)); // bundled system .so set
// The APK gives the VM real classes for JNI calls; null is allowed if
// you intend to stub everything yourself.
VM vm = emulator.createDalvikVM(new File("target.apk"));
vm.setVerbose(true);
vm.setJni(new AbstractJni() { // your JNI callbacks — see below
// override methods as the target demands them
});
DalvikModule dm = vm.loadLibrary(new File("libtarget.so"), false);
dm.callJNI_OnLoad(emulator); // init: decrypts, registers natives
// Calling a *statically exported* symbol:
// DvmObject<?> ret = dm.callFunction(...)
// Calling a *JNI-registered* method by its Java name (most common for hardened SDKs):
DvmClass<?> c = vm.resolveClass("com/example/NativeApi");
DvmObject<?> result = c.callStaticJniMethodObject(emulator,
"sign(Ljava/lang/String;)Ljava/lang/String;", "input");
System.out.println(result.getValue());
}
}
```
### Filling the environment — "supply what is missing"
A hardened library does not just compute; it *checks*. Every unidbg session converges on the same
loop: run, read the first unsupported callback or mapping fault, implement exactly that, repeat.
In order of frequency:
| The library wants | You supply |
|---|---|
| `JNI_OnLoad` → `FindClass`/`GetMethodID` on app classes | `AbstractJni` overrides (`callStaticObjectMethodV`, `getStaticObjectField`, …) returning canned values; or real classes from the APK via `createDalvikVM(apk)` |
| `Context` methods (`getPackageName`, `getFilesDir`, `getPackageManager` → signature!) | stubs — `vm.resolveClass("android/content/Context")` + your `AbstractJni` answers; a signature check wants the *original* APK's signature bytes, which `createDalvikVM(apk)` serves from that very file |
| file reads (`/proc/self/maps`, `/data/data/...`, config files) | `emulator.getSyscallHandler().addIOResolver(...)` redirecting to host files, or `virtualFileSystem` mounts; a `/proc/self/maps` check that looks for frida/xposed is satisfied by a clean canned maps file |
| other `.so` (cocos, tls, crypto) | `vm.loadLibrary` them first, in dependency order, or drop them beside the target so the resolver finds them |
| time / randomness | `emulator.getSyscallHandler` clock override; unidbg's deterministic RNG unless the target seeds from `/dev/urandom` (redirect it) |
Two structural rules that save hours:
- **Load order is init order.** `JNI_OnLoad` of the shell often registers natives and decrypts;
calling a function before the init that populates it yields a null deref that looks like a bug
in unidbg. Always `callJNI_OnLoad` first, and if the library has an explicit init/exported
setup entry, call that next.
- **32 vs 64 must match the `.so`,** not your PC and not the device's preference
(`references/native-and-so.md` §Cross-architecture applies here too: `for32Bit()`/`for64Bit()`
mirror the ABI you extracted from `lib/`).
### Failure modes you will meet
| Symptom | Meaning | Move |
|---|---|---|
| `unsupported syscall` / `signal 11 (SIGSEGV)` at a stable address | the library touched something unidbg does not fake yet | read the unidbg log line above the fault — it names the syscall/JNI call; stub it |
| `JNI_OnLoad` returns non-zero or throws | self-check failed inside init | enable `vm.setVerbose(true)`, read which check it ran (often signature, path, or a system property), satisfy it via stub |
| works, but output differs from device | environment input differs (time, random, files, another lib's state) | diff the inputs: redirect and pin them; on-device RPC (Part B) is the ground truth to compare against |
| crashes deep in the library, no unsupported call logged | the code path is genuinely wrong (wrong calling convention, wrong args) — or the library decrypted itself against device state it cannot have here | recheck the prototype (arg types/order) against the dex `native` declaration; then consider RPC instead |
| library refuses to load: dependency not found | a `DT_NEEDED` `.so` you did not provide | `readelf -d` the target, load missing libs first |
Know when to stop: a library that validates its own decrypt key against server data, or that
refuses any environment it did not boot in, is **not worth emulating** — that is exactly the shape
where the decision table sends you to Part B. (Which anti-emulation checks exist and how common
each is: inferred from community experience, not measured here.)
### Measured here
See `docs/tool-verification/EXTENSION-emulation-rpc.md` for the exact commands and outputs behind
every label in this section. Measured in that pass: the repository builds on Windows/JDK 17 once
the compiler plugin is pointed at the JDK 8 API, the emulator boots, and one bundled test suite
passes on the Dynarmic backend. **No target `.so` was emulated yet** — every per-library claim above
(which JNI callbacks a hardened library asks for, which syscalls it hits, how many rounds of stubbing
it costs) is **inferred** from the library's shape and from community practice, not from a run
against this sample.
## Part B — Frida RPC
### The mechanism
A Frida script can export functions to its host: assign to `rpc.exports`, and every property
becomes callable from Python (`script.exports_sync.name(...)` after frida 16) with JSON-serializable
arguments and return values, synchronously, from outside the process. That is the whole trick:
```javascript
rpc.exports = {
add: function (a, b) { return a + b; },
};
```
```python
script = session.create_script(code); script.load()
print(script.exports_sync.add(40, 2)) # -> 42
```
Everything else is packaging: keeping the session alive, finding the function address, converting
types across the NativeFunction boundary. The pattern for the case that matters — a hardened
library's signing function, exported or `RegisterNatives`-bound:
```javascript
// 1) exported symbol:
const addr = Module.findExportByName('libtarget.so', 'Java_..._sign');
// 2) dynamically registered (no export — the usual shape for hardened SDKs):
// hook RegisterNatives once at startup, note the fnPtr for the name you care about
const sign = new NativeFunction(addr, 'pointer', ['pointer', 'pointer']);
rpc.exports = { sign: function (s) { return sign(env, jstring(s)); } };
```
Java-side functions are equally callable (`Java.perform` wraps the call), which is how the
harmless connectivity probe — `getPackageName` over RPC — works in the template below.
### The kit's tooling
`scripts/frida_rpc_serve.py` + `scripts/rpc_template.js` implement the full loop:
- three front ends: one-shot `--mode call`, interactive `--mode repl`, and a resident
`--mode http` endpoint (`POST /call {"export": "...", "args": [...]}`, `GET /exports`,
`POST /reload`);
- spawn or attach (by name or by pid — attach-by-name fails on incomplete process enumeration,
`references/dynamic-frida.md` §Attach by PID);
- automatic reconnect: a detached session (app restart, killed server, ROM reaping the server)
re-attaches, reloads the script and retries the call, with per-request retry cycles and
exponential backoff; a killed-and-restarted device server is recovered by dropping the cached
remote device before reconnecting;
- the template exports `add` (transport sanity), `getpackagename` (Java probe),
`callnative(module, export, retType, argTypes, args)` and `callnativeaddr(module, offset, ...)`
for wrapping any native symbol, with a frida-16/17-compatible export resolver.
Typical session (device server already running and forwarded, `references/dynamic-frida.md`
§Setup):
```bash
adb -s <serial> forward tcp:27043 tcp:27043
python scripts/frida_rpc_serve.py --remote 127.0.0.1:27043 --package com.example.app \
--script scripts/rpc_template.js --mode repl
rpc> list
rpc> getpackagename
rpc> callnative ["libtarget.so","Java_com_example_Native_sign","pointer",["pointer","pointer"],[...]]
```
Then feed the recovered function into request generation the way `references/server-api.md`
describes — the RPC service turns "the server checks a signed header" into "I can compute that
header on demand", which is the whole reason this route exists.
### What the live route costs — measured failure modes
Every row below was hit against a real device during the verification pass behind this file
(exact outputs in `docs/tool-verification/EXTENSION-emulation-rpc.md`):
| Failure | What it looks like | Handling |
|---|---|---|
| **Hardened target kills injection** | attach: `process either refused to load frida-agent, or terminated during injection`, logcat `CRASH ... IterateRegisters found fp`; spawn: script loads, then every call dies with `script has been destroyed` | the shell's anti-instrumentation won; do not retry the same attach — switch route (unidbg for the crypto, or `references/lsposed-and-modules.md` / static patching), or fight the detector deliberately (`references/detection-and-anti-analysis.md`) |
| **ROM reaps the server** | `connection closed` mid-session, sometimes repeatedly | budget restarts, not re-analysis: the bridge reconnects once the server is back; check `pidof <server>` before every experiment block (`references/dynamic-frida.md`) |
| **Attach by name fails for processes the device can see** | `unable to find process with name 'com.example.app'` while `frida-ps -Uai` and `ps -A` both list it alive; reproduced for a system app and for a Magisk-manager process, for every package name tried | resolve the pid yourself and attach with `--pid`: measured on the same ROM, `device.attach(pid)` loaded the script and returned RPC results for the very processes whose *name* lookup failed (`--pid 19938` → `com.android.settings`, `--pid 21493` → `com.android.email`). Take the pid from `frida-ps -U`, `ps -A`, or `adb shell pidof <pkg>` |
| **The server comes back on a non-default port** | `frida.ServerNotRunningError: unable to connect to remote frida-server: closed` on attach even though `frida-ps -U` still works | the ROM or a watchdog reaped the visible server and a disguised copy returned elsewhere (measured: only `*.svc16` left alive, listening on 27043, nothing on 27042). Check the listening port, `adb forward tcp:27043 tcp:27043`, then `--remote 127.0.0.1:27043` — do not assume the default port |
| **Attach by pid times out on a busy process** | `frida.TimedOutError: unexpectedly timed out while waiting for signal from process with PID X` during attach (raised by an ordinary third-party app); it is not a `TransportError` subclass and escaped every handler | nothing is wrong with the tooling — the process did not answer the agent handshake; use another process for the connectivity probe, or retry once the app settles (the bridge now treats `TimedOutError` as retryable and fails with one line instead of a traceback) |
| **Short-lived processes** | the settings main activity process exits seconds after `am start` | pick a persistent process for connectivity tests; the business target only when it actually stays up |
The strategic point those rows make together: **on a hardened target, RPC is not guaranteed to be
available at all** — the injection ticket can be revoked by the target itself. That is the single
strongest argument for keeping the unidbg route warm, despite its environment cost: it is the one
route that works when the process refuses to be instrumented.
### Combining the routes
The routes compose rather than compete:
1. **RPC as oracle, unidbg as student.** When an emulated function's output must be trusted, diff
it against the live process's output for identical inputs; disagreement localizes the missing
environment piece far faster than reading the library (`Part A` §failure modes, "output
differs").
2. **Dump via RPC, emulate after.** A live call that returns the decrypted key/table the library
uses (`references/runtime-data.md`) can be replayed into the emulated run as a fixed stub.
3. **Batch offload.** Use the device session to discover the calling convention and to capture
sample inputs/outputs (few calls), then run the bulk of the work offline under unidbg.
## What to record
- which route was chosen and why (one line, against the decision table)
- for unidbg: the API level resolver, the list of JNI stubs you had to write, what the library
checked before it would compute (that list *is* the target's defense inventory)
- for RPC: server version vs host version, attach vs spawn, reconnect behaviour observed, and —
decisive for a hardened target — whether injection survived at all
- inputs/outputs for at least one call verified against an independent source (device-side log,
server response, or a known-answer test)
@@ -0,0 +1,211 @@
# Kernel-level and environment hardening — where to go when userspace hooking is not enough
Load this when you have already concluded, via `detection-and-anti-analysis.md`, that the target
genuinely detects your instrumentation — and that the check cannot be neutralised from userspace
because it runs before your hook, or bypasses the layers a userspace hook can reach. This file is
the **escalation map**: what the next layer down actually is, what it costs, and when it is the
wrong answer.
Division of labour, so the two files never duplicate:
- `detection-and-anti-analysis.md` owns **identifying** detection and the **cost decision**
(work around / change route / accept and report). Read it first; its Step 0 still applies.
- This file owns **the routes below userspace** — root-implementation hiding properties, kernel
interception options, and the syscall-level realities that decide whether "just hook it" was
ever going to work.
**This repository does not do kernel development.** Everything in the kernel section is a map of
externally documented mechanisms with sources, labelled `inferred` — none of it was executed here.
That is deliberate: the purpose is to stop you from spending a day rediscovering the version
gate (§4) or the conflict (§5), not to teach kernel hacking.
## 1. The attack-surface timeline — why "just hook it" fails
An app process initializes in a fixed order, and every anti-analysis check you will meet lives at
one of these stations:
```
linker (ld-android/inker) -> relocations resolved, DT_INIT run
.init_array of each loaded .so -> constructors: earliest native code that runs
JNI_OnLoad -> packers and RASP SDKs hook here
Application.onCreate -> first Java-level check
first frame -> UI-visible checks (and the end of "early")
```
The later your tool attaches, the more of this timeline has already executed and taken its
decision. Frida in attach mode arrives after all of it; spawn mode arrives at zygote fork, which
is why `dynamic-frida.md` prefers it — but a constructor in `.init_array` can still run before
the Frida agent finishes injecting, and a check placed there fires once and stores its verdict.
What those checks actually look for, and why each one is out of reach of a naive userspace hook
(the identification side belongs to `detection-and-anti-analysis.md`; this is the *mechanics* of
why the hook does not land):
| Detection mechanism | Why a userspace hook misses it |
|---|---|
| Inline `svc #0` syscalls (bypassing libc) | PLT/GOT hooks only intercept calls that go through the PLT. Hand-written `svc` instructions in the target's own `.so` never touch libc, so there is no PLT entry to redirect. |
| `/proc/self/maps` scan for foreign mappings | The read can be done with raw `openat`+`read` syscalls (same svc trick), and the thing being detected — your injected agent's mapping — exists in the process regardless of what you hook. |
| Named pipes / thread-name probes for known agents | Frida's runtime creates identifiable threads (`gum-js-loop` etc.) and (older versions) a linjector pipe. Renaming helps only if you control the runtime's identity, not the probe. |
| Code-page checksums of the target's own `.so` | An inline hook *is* a modification of the pages being checksummed. The check catches the hook by construction; the only userspace answer is to also neutralise the checksum, which recursively has the same problem if *that* code is checksummed too. |
| `/proc/self/status` `TracerPid` read | The field is written by the kernel. A userspace hook on the reader works only until the reader uses raw syscalls (row 1). See §6. |
The structural lesson: **userspace hooking and userspace anti-hooking are the same layer.** A
detection routine that lives in the same process as your hook, and that is willing to use raw
syscalls and self-verification, can always in principle race you. The routes below win by moving
to a layer the check cannot see from userspace — or by not being in the process at all.
## 2. Root implementations and what each one exposes
The root method you run decides which artefacts a detector can find *outside* the target process
(manager app, daemon, mount layout, SELinux contexts). Facts below are from the projects' own
documentation (sources at the end of the section); none were re-measured here — `inferred`.
| | **Magisk** | **KernelSU** | **APatch** |
|---|---|---|---|
| How su works | Patches the ramdisk/init; a `magiskd` runs in userspace; the manager app requests su through it | `su` handled **inside the kernel**; a manager app talks to the kernel via a driver/interface. Kernel modification. | Kernel modification via **KernelPatch**: patches the existing `boot.img` kernel — no kernel source needed (the difference from KernelSU) |
| Kernel version gate | None (works on old kernels — this is why the 4.14 test device runs it) | Official support = GKI 2.0, kernel **5.10+** (in practice: shipped with Android 12). Backported to 4.14 but you must build the kernel yourself | Same GKI-era expectation; needs only the stock `boot.img` to patch |
| Access control | Manager grants per-app; denylist for hiding | Manager + **App Profile** (constrain what a rooted app can do) | **SuperKey**: KPatch installs a new syscall (SuperCall); callers must present the SuperKey credential |
| SELinux | Modifies contexts (magiskpolicy) | Kernel-side handling | Hooks/bypasses SELinux rather than rewriting contexts — threads can be rooted in app context without `libsu`/IPC |
| Module format | Magisk modules (magic mount) | Magisk-compatible modules; `/system` modification needs a metamodule (overlayfs) | APM (Magisk-compatible) plus **KPM** — kernel-space modules with inline-hook and syscall-table-hook capability |
| Zygisk | Built-in | None built-in; add ZygiskNext | None built-in; add ZygiskNext / ReZygisk / NeoZygisk |
**What this means for hiding** (`inferred`):
- **Manager identity is the shared weak point.** All three ship a manager app the detector can
enumerate by package or by scanning for its UI. All three support "randomise/repackage the
manager" — use it, and do not assume the default package name is safe.
- **KernelSU/APatch remove the userspace su daemon** the detector could otherwise find as a
process or a socket. But they add a kernel-level surface of their own; a detector cannot see it
from an unprivileged app — which is the point.
- **Magisk on an old kernel is not a disadvantage for hiding**; it is a constraint of the device.
Do not switch root schemes to win a detection race — that is §7's stop signal.
- **Module ecosystems interoperate but do not merge**: KernelSU's module system conflicts with
Magisk magic mount (per KernelSU FAQ, running both means one stops working); su-only coexistence
is possible because KernelSU patches the kernel while Magisk patches the ramdisk.
Sources: KernelSU README + FAQ (github.com/tiann/KernelSU), APatch FAQ (apatch.dev, project
originally at github.com/bmax121/APatch), fetched 2026-09. Device facts (Magisk alpha on kernel
4.14.186) are `observed` in `tools/_phone-modules/README-手机模块环境.md`.
## 3. Environment-hiding modules: Zygisk-Assistant vs Shamiko
Both are Zygisk modules that hide root + Zygisk from target apps. **Do not install both** — they
overlap in function (mount-namespace handling, trace wiping) and interfere; this is documented in
the module ecosystems and was the deciding fact on the reference device (`observed` in
`tools/_phone-modules/README-手机模块环境.md`: Shamiko kept as a backup zip, uninstalled).
The practical difference is their **denylist dependency** (from each project's own README,
`inferred`):
| | **Shamiko** | **Zygisk-Assistant** |
|---|---|---|
| Reads the Magisk denylist | Yes — but **requires DenyList enforcement to be OFF** (it takes over the handling itself) | Magisk: add the target to the denylist, **Enforce DenyList OFF**. KernelSU/APatch: enable the manager's "Umount modules/Exclude modifications" for the target app |
| Extra modes | Whitelist mode via `/data/adb/shamiko/whitelist` (empty file); docs warn of performance/memory cost, test-only | — |
| On APatch | Officially unsupported ("Shamiko is proprietary software, we cannot adapt it" — APatch FAQ) | Works via ZygiskNext |
| Version gates | Newer Shamiko requires recent Magisk/KernelSU bases | Current |
Selection rule (`inferred`): on Magisk, either works alone — pick one, configure its denylist
dependency correctly, and verify on the actual target. On KernelSU/APatch, Zygisk-Assistant (+
ZygiskNext) is the supported path. The denylist/enforcement settings are the part people get
wrong: **enforcement off, list populated** is the working combination for both.
Verification status: neither module's hiding effect was tested against a real detector on the
reference device (`tools/_phone-modules/README-手机模块环境.md` §未覆盖的验证) — treat every
"this hides X" claim above as documented-but-unproven here.
## 4. Kernel-level interception — the map, and the version gate
When you need to observe or alter what a target does *at syscall level* — e.g. it reads
`/proc/self/status` via raw `svc`, and you want that read to return a spoofed page — userspace is
structurally the wrong layer. The options below exist; **none of them were executed in this
repository** (`unverified`), and each has a hard prerequisite worth checking before you read any
further:
```
uname -r # on the device. The gate for most of this section is 5.10+
```
- **Why 5.10**: Android's GKI (Generic Kernel Image) programme starts at android12-5.10; the
kernel-BPF ecosystem for tracing (bpftrace-class tools, kprobe/uprobe attachment as the tooling
expects it) targets GKI kernels. Source: the Android kernel architecture documentation on
source.android.com (GKI and eBPF pages). On the reference
device (kernel **4.14.186**) this entire row is **closed** — `observed` (the version), with the
consequence recorded in `tools/_phone-modules/README-MCP与网络环境.md`: eBPF-based tooling
(stackplz, mcp-termux's tracing half) is unavailable there. Write the one-line environment fact
per `detection-and-anti-analysis.md` Step 5 and do not revisit it.
| Route | What it gives you | Prereqs | Strength |
|---|---|---|---|
| **eBPF kprobes/uprobes** | Fire a BPF program on kernel or userspace function entry; observe syscall arguments/results system-wide, invisible to the target process | GKI 5.10+ kernel with the BTF/tracing config; root; toolchain (bpftrace or a custom loader) | `inferred` — documented upstream, not run here |
| **seccomp-BPF filter** | Per-process syscall allow/deny — can make a syscall **fail**, and seccomp can be installed by the app on itself (no root needed for self-filtering) | Any modern kernel; but a filter you install into the target requires ptrace/zygisk injection first | `inferred`. **Key limitation**: seccomp can reject or error a syscall (SECCOMP_RET_ERRNO/TRAP); it cannot rewrite the *content* of what a successful read returns. It closes doors; it does not paint them. |
| **Kernel module hooking** (KPM on APatch; out-of-tree LKM elsewhere) | Inline hooks and syscall-table hooks in kernel space — the layer that *can* rewrite what a `/proc` read returns | APatch (KPM) or a self-built kernel/LKM load path; kernel-dev skills | `inferred`. This is genuine kernel development — out of scope for this skill (§7) |
| **Zygisk injection** (not kernel, but below the target's defences) | Run code in the target's process from zygote fork, before `.init_array` of the app's own libs | Magisk/KernelSU+ZygiskNext + a Zygisk module; no ptrace involved | `measured` as a framework (LSPosed runs this way on the reference device); a purpose-built module for a given target is `inferred` here |
The row that matters most in practice: **Zygisk is the cheap "below userspace" route** — it is in
the process earlier than any userspace tool can be, needs no ptrace (so it does not trip
`TracerPid`), and its ecosystem is maintained by other people. A custom kernel module that
rewrites one `/proc` read is a research project; a Zygisk module that hooks the target's
constructor is a build task.
## 5. The syscall-level realities that survive every hook
Two facts decide a lot of "unexplainable" behaviour, and both belong to the kernel's design
rather than to any tool:
1. **`TracerPid` is written by the kernel, not by a library.** Anything that ptraces the target
(classic Frida attach, debuggers) makes `/proc/self/status` show it, and the only readers that
miss it are the ones you broke. Ways out, in escalating cost:
- attach-free operation: **Zygisk** (injection at fork; no ptrace) or Frida **spawn** (still
ptrace-based but only during injection — verify for your version) or a memory patch applied
before detach (`scripts/spawn_patch_detach.py`, `measured`);
- kernel-level hiding of the field (KPM/eBPF rewrite of the proc read) — §4, `unverified`;
- **self-ptrace**: the target ptraces itself so nothing else can (classic anti-anti-debug);
works because only one tracer is allowed — but it constrains your tooling to non-ptrace
routes anyway. `inferred`.
2. **A raw `svc` cannot be intercepted from userspace at all.** No PLT, no libc, no hookable
symbol. Every plan that says "hook open/read and spoof the maps" silently assumes the target
calls libc; a hardened target does not. Verify which one you have before building the spoof:
disassemble the check's `.so` and look for `svc #0` (AArch64) / `int 0x80`-era equivalents in
the check path (`inferred`; `scripts/native_crash.py`-style capstone disassembly applies).
## 6. What the reference environment chose (and why it generalises)
On the 4.14-kernel reference device, the escalation ladder terminates early — and that is the
honest outcome (`observed`, from `tools/_phone-modules/README-*.md`):
| Layer | Status on a 4.14 Magisk device |
|---|---|
| LSPosed (Zygisk) module hooking | available — framework activation verified by log (`welcome to LSPosed!` lines, `lspd` daemon process) |
| MT Manager on-device editing/repack/sign | available (`on-device-tooling.md`) |
| eBPF tracing | closed (kernel gate) |
| KPM / kernel module route | closed (no kernel source/build for the device; out of scope regardless) |
| Frida with disguised server | available (a renamed server binary was present on the device from prior work) |
The generalisable rule: **enumerate the ladder for *your* device once, write the one-line
environment facts, and stop re-deriving them mid-task.** A closed rung is a route decision, not a
failure.
## 7. When to stop escalating — the decision table
This extends `detection-and-anti-analysis.md` Step 2 with the kernel rung. The repo's stance:
R3 (never ship or claim an unverified artifact) outranks winning the arms race; a detector you
defeated with a custom kernel module is not a deliverable anyone can install.
| Situation | Do this | Not this |
|---|---|---|
| Check is userspace, hookable, single-site | Neutralise at the site (`native-tamper-and-suicide.md` rules) | Building a hide stack |
| Check runs before your userspace tool (init_array) | Zygisk-route module, or static patch of the check itself | Earlier userspace attach racing the constructor |
| Check uses raw syscalls | Static patch of the check; or LSPosed/Zygisk module hooking the consuming code | "Hook libc open/read" (does nothing) |
| Check detects the *environment* (root/emulator), not your patch | `detection-and-anti-analysis.md` A/B/C — usually a different device or route | Kernel work |
| You are about to write a kernel module / patch a kernel | Stop. State what is blocked and the evidence; propose the static/module route | Kernel development (out of scope for this skill) |
| Escalation effort exceeds the user's actual ask | `detection-and-anti-analysis.md` stop signal — switch to static | One more layer |
## Checklist
- [ ] `detection-and-anti-analysis.md` read first; A/B/C chosen deliberately
- [ ] Check located on the timeline (§1) before choosing a counter-layer
- [ ] Root scheme's artefacts enumerated (manager/daemon/mounts) before blaming the target
- [ ] Hiding module: exactly one of Shamiko / Zygisk-Assistant; denylist configured to its spec
- [ ] Kernel rung checked against `uname -r` — one line recorded if closed
- [ ] Raw-syscall vs libc-call distinction verified by disassembly before building any spoof
- [ ] No kernel development undertaken as part of an APK deliverable
@@ -0,0 +1,353 @@
# LSPosed modules — when to deliver a hook instead of a patched APK
Load this when the honest answer to "patch the APK" is *no*: the target checks its own bytes, derives
keys from its signature, re-downloads what you removed, or is simply cheaper to hook than to rebuild.
A module is a different **deliverable**, not a different way to analyse — it changes what you ship, how
it survives upgrades, and who has to install it.
This file covers the module route end to end: choosing it, the smallest project that works, the
Gradle-free build chain, deployment and verification, what hides it from the target, and what it
cannot reach at all.
**Route honesty first.** A module does not modify the APK, so it cannot be "the patched build". If the
user asked for an installable standalone APK, a module is not that artifact, and this file will not
make it one.
## Step 0 — pick the route deliberately
Three routes ship three different things. Choose on **who runs it and for how long**, not on which one
you enjoy more.
| Route | Deliverable | Runs when | Survives target update | Cost |
|---|---|---|---|---|
| **Frida** (attach/spawn) | a script, driven by you | while a server process is alive on the device | it does not; you re-run it | lowest to start, highest per-session |
| **LSPosed module** | an installable APK the user keeps | every process start, automatically, after the module is enabled and scoped | usually yes — the hook targets classes/methods, not offsets | mid: one project, no repackaging of the target |
| **Repackaged APK** | a modified, re-signed APK | whenever the app runs | no — every update needs rework | highest: integrity, signature, packing, repack |
Reach for a module when **any** of these is true:
- the target verifies its own signature or APK digest, so a repackaged build dies on arrival
(`references/signature-derived-keys.md`, `references/native-tamper-and-suicide.md`);
- the change must persist across restarts without your laptop being attached;
- attaching a debugger/injector is itself detected, but a startup-time hook is not
(`references/detection-and-anti-analysis.md`);
- you need a Java-level behaviour change only, and the target's own code is reachable from Java.
Do **not** reach for a module when the logic you need lives in native code or in an AOT-compiled
runtime: see *What this route cannot reach* below.
## What the module can and cannot change
| Layer | Module can reach it? | Where to go instead |
|---|---|---|
| Java/Kotlin app code (incl. classes loaded late by a packer's ClassLoader) | yes, once you have the right `ClassLoader` | — |
| `Application` / `Activity` / framework lifecycle | yes | — |
| Java SDK internals (OkHttp, ad SDKs, HTTP clients) | yes | — |
| Pure native logic inside a `.so` | no — Java hooks see only the JNI boundary | `references/native-and-so.md`, `references/native-dbi-and-deobfuscation.md` |
| Extracted / virtualised dex (instruction-抽取, dex VMP) | no — the original method bodies may not exist as dex at all | `references/advanced-unpacking.md` |
| Flutter / Dart AOT business logic | no — Dart is not Java; the Java layer only hosts the shell | `references/dart-aot.md` |
| Behaviour that is *decided* server-side | irrelevant — a hook cannot remove a server rule | `references/server-api.md`, `references/server-config-and-updates.md` |
The Flutter row is the one that most often surprises: hooking every Java entry point in a Flutter app
still leaves all business logic behind `libapp.so`. Confirm which layer owns your target before
building a module for it (`references/dart-aot.md`).
## How injection actually works
The mechanism matters because every failure mode below is a consequence of it.
- LSPosed ships as a **Zygisk module** (`zygisk_lsposed`). Zygisk loads into `zygote`, so every app
process forked from it is a candidate for injection. [inferred: standard Magisk/Zygisk design]
- A module is **not** injected everywhere. For each forked process LSPosed asks its daemon (`lspd`)
whether this package is in the module's **scope**, and only then loads the module. Scope is therefore
the real gate; anything inside the module that filters on package name is a second, weaker gate.
- Module code is loaded **from memory**, not from a file mapping — the module's dex is read out of the
installed APK and handed to an in-memory ClassLoader. This is why a target scanning `/proc/self/maps`
for path names finds nothing (`references` below, *What detects you anyway*).
- The entry point is the class named in `assets/xposed_init`, and it receives
`handleLoadPackage(XC_LoadPackage.LoadPackageParam)` **before the application's own `Application`
object is attached** — the earliest Java-visible moment in the process. [measured: the injection
point is why `Application.attach` and `Activity.onCreate` hooks installed from here fire even under a
packer]
- `LoadPackageParam.classLoader` is the **application's** loader (the packer's stub loader when the APK
is packed). It is the handle you use to find classes the app loads later, and it is also the object
anti-Xposed code counts — see *What detects you anyway*.
## Minimal module anatomy
Four files. Nothing else is required — no `res/`, no launcher Activity, no permissions.
| File | Why it is required |
|---|---|
| `AndroidManifest.xml` with `<meta-data android:name="xposedmodule" android:value="true"/>` | without this key the APK installs as an ordinary app and never appears in the module list |
| same manifest: `xposeddescription`, `xposedminversion` (`82`) | shown in the manager UI; `82` is the classic XposedBridge API level and is accepted by LSPosed |
| `assets/xposed_init` | one line: the fully qualified entry class. A typo here produces a module that loads and silently does nothing |
| the entry class implementing `IXposedHookLoadPackage` | the only class LSPosed instantiates for you |
`scripts/lsposed_scaffold.py` writes exactly this set, plus a README containing the build chain below,
so the project is reproducible without Gradle:
```sh
lsposed_scaffold.py --package com.example.probe --name "Example probe" \
--hook-target com.example.target --out ./module
```
The generated entry class logs on **every** scoped process load before anything else, and hooks
`Application.attach` / `Activity.onCreate`. Both are diagnostics first: the first line proves injection,
the second names the real Activity classes (under a packer, these are the *unpacked* classes, not the
manifest's stub).
## Building without Gradle
There is no resource to compile and no dependency resolution to do, so the whole toolchain is five
commands. [measured on a Windows bench, JDK 17, build-tools 34.0.0, Android API 28 android.jar,
Xposed api-82 stub jar; end-to-end 5.3 s for a one-class module]
```sh
BT=/path/to/build-tools/34.0.0
AJ=/path/to/android.jar # platforms/android-28/android.jar
API=/path/to/api-82.jar # de.robv.android.xposed:api:82
OUT=build
javac -encoding UTF-8 -source 8 -target 8 -nowarn -cp "$AJ:$API" \
-d "$OUT/classes" src/com/example/probe/MainHook.java # 850 ms
jar cf "$OUT/classes.jar" -C "$OUT/classes" . # 259 ms
"$BT/d8" --min-api 24 --lib "$AJ" --output "$OUT" "$OUT/classes.jar" # 1143 ms -> classes.dex
"$BT/aapt2" link -o "$OUT/base.apk" -I "$AJ" --manifest AndroidManifest.xml \
--min-sdk-version 24 --target-sdk-version 28 -A assets # 126 ms
cp "$OUT/base.apk" "$OUT/unsigned.apk"
cp "$OUT/classes.dex" . # must sit next to the apk
(cd "$OUT" && "$BT/aapt" add unsigned.apk classes.dex) # 97 ms
"$BT/zipalign" -f -p 4 "$OUT/unsigned.apk" "$OUT/aligned.apk" # 76 ms
"$BT/apksigner" sign --ks mod.keystore --ks-pass pass:android --key-pass pass:android \
--v2-signing-enabled true --out "$OUT/module.apk" "$OUT/aligned.apk" # 1794 ms
"$BT/apksigner" verify --print-certs "$OUT/module.apk" # 725 ms -> v2/v3 OK
```
Four traps, all measured rather than guessed:
- **`d8` rejects a directory.** Pointing it at `build/classes/` fails with *Unsupported source file
type*. Jar the classes first and pass the jar.
- **`aapt add` resolves its argument relative to the current directory and stores the same name.** Run
it from the output directory with `classes.dex` present there; a path like `dex/classes.dex` lands
inside the APK as `dex/classes.dex` and the module never loads.
- **`jar` and `keytool` are frequently not on `PATH` even when `javac` is.** Oracle's `javapath` shim
exposes only `java`/`javac`; call the JDK's `bin` directory explicitly.
- **`-bootclasspath` no longer exists on JDK 9+**, so the Android API comes from `-cp` together with the
Xposed stub jar. `-source 8 -target 8` keeps the class-file version low enough for `d8`.
The generated README carries the same chain in copy-paste form, including the Windows variants
(`.bat` wrappers, `;` classpath separator).
## Deploy, enable, and verify
**There are two independent switches.** Getting one right and not the other is the single most common
"I built a module and nothing happens" report.
| Switch | Where | What it actually controls |
|---|---|---|
| package enabled state | `pm enable <module>` / `pm disable <module>` | whether Android allows the package's components to run at all |
| module enabled | LSPosed Manager (module list) | whether LSPosed loads the module into scoped processes |
| scope | LSPosed Manager (module → scope) | *which* packages the module is injected into |
[measured: a freshly installed module can be in the module database yet disabled — the package
manager reported `enabled=0` for the module and `pm enable` flipped it to `enabled=1`, while the
LSPosed-side enable flag was still 0 in its own database]
A third, device-level gate sits on vendor ROMs: the *install* itself can be intercepted by the ROM's
security centre. The shape is a shell-identity `pm install` returning a bare `Failure [-99]` while the
vendor security app takes the foreground, and the **same APK installing cleanly as root**
(`su -c 'pm install -r <apk>'`). If a module APK "will not install" on a phone that is otherwise
healthy, try root before suspecting the APK. [measured; the extension record has the transcript]
Verification has **two channels**, and on a device with a broken platform log only one of them works:
```sh
# 1. the platform log — where the module's line normally appears
adb logcat -s <TAG> # then start the target app; do NOT clear the buffer first
# 2. LSPosed's own module log — where it appears when logd is broken
adb shell "su -c 'cat /data/adb/lspd/log/modules_<timestamp>.log'"
```
The expected first line in either channel is the one the scaffold writes on entry — it fires before
any app code:
```
<TAG> injected: <target.package>/<process> cl=<loader>@<hash>
```
[measured] On a device whose `logd` route is broken, channel 1 is **completely empty** — not merely
`logcat -s <TAG>`, but `logcat -s LSPosed-Bridge` and a full-buffer search for the tag as well — while
channel 2 shows a complete, successful injection for every process start. A ROM whose LSPosed log
opens with `Logd maybe crashed (err=Socket operation on non-socket)` is exactly this case, and it had
nine successful injections in it while logcat showed nothing at all. Debugging with `logcat` alone
there produces the confident and wrong conclusion "the module never ran".
Decision order when that line is missing — stop at the first hit:
1. module enabled in LSPosed Manager?
2. target package present in the module's **scope**?
3. module APK still installed (`pm path <module>`)?
4. **was the target process started after the scope change?** Scope is read for newly forked
processes; a process that was already running keeps the decision it got at fork time.
[external, matches LSPosed behaviour reported independently: a scope change takes effect on the
target's next start, no device reboot required — 看雪 thread-291750]
The LSPosed-side state is inspectable from a root shell:
| Path | Contents |
|---|---|
| `/data/adb/lspd/config/modules_config.db` | SQLite: `modules(mid, module_pkg_name, apk_path, enabled)`, `scope(mid, app_pkg_name, user_id)`, `configs(...)` [measured] |
| `/data/adb/lspd/log/` | `modules_<timestamp>.log`, `verbose_<timestamp>.log`, `kmsg.log`, `props.txt` [measured] |
| process `lspd` | the daemon that serves scope decisions; it is a separate process from the target [measured] |
Two measured caveats about that log directory, because both waste time:
- `modules_*.log` **is** the module log: it is the file LSPosed appends your `XposedBridge.log()` lines
to. It may *also* contain `Logd maybe crashed (err=Socket operation on non-socket), retrying in 1s...`,
which means the platform log channel is unavailable — not that your hook failed. Check this file
**and** `logcat -s <TAG>`; a device can deliver one and not the other. [measured: nine successful
injections were in this file while logcat showed nothing]
- `verbose_*.log` is a *logcat snapshot* that includes the whole system, so it is useful for
correlating a system-side event with your run, and useless as a module log.
**Do not kill `lspd` to force a configuration reload.** [measured] On the bench it is started by
`/data/adb/modules/zygisk_lsposed/service.sh`, which runs `unshare -m sh -c "$MODDIR/daemon --from-service &"`;
the `daemon` script ends in `exec /system/bin/app_process ... org.lsposed.lspd.Main`. Magisk runs
`service.sh` once per boot, so an externally killed `lspd` is not restarted by anything you can see
from a root shell. The consequence is worse than a dead daemon: newly forked processes stop getting
scope decisions. Configure scope through the manager, which talks to the running daemon.
The same reasoning applies to editing `modules_config.db` by hand: the file is the daemon's
**persisted** state, while the decisions actually served to `zygote` come from the daemon's live copy.
A hand-edited row is not wrong — it is simply not read until the daemon reloads it, and there is no
supported way to make it reload. [inferred from the storage layout and the daemon lifecycle; the
manager path is the one that updates both]
## Hiding the framework from the target
Injecting a Java hook is trivial to detect **if the target is allowed to see the root/Zygisk
environment at all**. On a rooted device the hiding layer is a separate module, and the two common
choices differ in exactly one operational detail: how they learn which apps to hide from.
| | Zygisk Assistant | Shamiko |
|---|---|---|
| source | open | closed-source, LSPosed project |
| target selection | Magisk **DenyList** entries (or KernelSU profiles); no UI of its own | also reads Magisk's DenyList, **but requires DenyList enforcement to be OFF** |
| extra mode | — | creating `/data/adb/shamiko/whitelist` switches to whitelist mode without a reboot; documented as costly in memory/performance and test-only |
| mechanism | unmounts root-related paths and masks Zygisk presence for the selected process | same family of process-level hiding, plus its own mount/`maps` handling |
[external: Zygisk Assistant module description and Shamiko README]
**The DenyList/enforcement distinction is where people lose afternoons.** Enforcement is Magisk's own
feature that unmounts Magisk-provided files for listed processes; the *list* is shared, the *enforcement
toggle* is not the same thing. Shamiko wants the list without enforcement; Zygisk Assistant is
documented to work with the list as configured.
[measured on the bench: the DenyList was **enforced but empty** — `magisk --denylist status` reported
`Denylist is enforced`, `magisk --denylist ls` printed nothing, `/data/adb/shamiko` did not exist, and
Zygisk Assistant v2.1.4 was installed. So on that device nothing was being hidden from any app, while
LSPosed and `lspd` were running normally. If a target seems to know it is on a rooted device, check
this before blaming the module.]
Practical rules:
- **Keep the scope minimal.** Every extra scoped package is both an extra place your hook can break
something and an extra ClassLoader in that process (next section).
- Hiding and hooking are separate problems. A module that is perfectly hidden can still be detected by
the ClassLoader count; a target that never checks cannot see either.
- If the target is the *only* app you care about, scoping to it alone is both the smallest blast radius
and the least observable configuration.
## What detects you anyway
Traditional Java-level anti-Xposed checks — `Class.forName("de.robv.android.xposed.XposedBridge")`,
exception-stack scanning for Xposed frames, reflection on `findAndHookMethod`, enumerating
in-memory-ClassLoader instances — are all **query interfaces**, and hiding layers exist precisely to
falsify their answers. They are no longer a reliable signal that a module is present or absent.
The check that does not depend on a query interface is the **ClassLoader count**. [external: 看雪
thread-291750, which reports a clean baseline of 3 versus 12 with a module injected, threshold ≥9; the
original idea is traced there to thread-289567]
The reason it works, in one paragraph: ART's `ClassLinker` keeps a `class_loaders_` list of every live
ClassLoader, and that list is part of GC reachability. A module's loader must stay on that list or the
GC will collect the module's code and the hook dies. So a module cannot both remain alive and be absent
from a structure the runtime itself walks. Hiding layers can fake lookups; they cannot remove a node
from a GC-traversal list without unloading the module.
The same source reports two further native-side traces of the same injection, which are worth knowing
because they are independent of ClassLoader counting: the module's dex shows up as **anonymous
executable memory** (it is loaded from memory, so no file mapping exists), and Zygisk's patching of
`libart` leaves **private-dirty pages** in the library's executable segments.
Engineering consequences for anyone choosing this route:
- **Scope discipline is detection hygiene.** Fewer scoped packages means fewer injected processes; a
multi-module stack inflates the same count. The number is per-process, so a clean device elsewhere
does not help this process.
- **A count check needs a calibrated baseline.** On complex hosts (WebView, split APKs, plugin
frameworks, other modules) the clean count is already high, and the threshold has to be measured per
host, never copied. [external: same source]
- **Detection of the framework is not the same as detection of your change.** If the target reacts to
the count by refusing to run, that is an environment finding to report
(`references/detection-and-anti-analysis.md`), not something to escalate against indefinitely.
- If the target's check is native and inline-hooks *your* detector's counterpart, you are in DBI
territory: `references/native-dbi-and-deobfuscation.md`.
## LSPosed vs Frida — the division of labour
They are not competitors; they are the two answers to "how long must this hook exist".
| Need | Frida | LSPosed module |
|---|---|---|
| Understand a flow once, now | **yes** — interactive, no build step | no: build + install + restart per iteration |
| Ship something that works every launch, unattended | no: needs a server process | **yes** |
| Hook a `.so` function directly | **yes** (`Interceptor`, Stalker) | no: Java hooks stop at JNI |
| Survive a target that kills external injectors | weak: `ptrace`-based attach is the thing being detected | **stronger: no external process, no attach, no port** |
| Replace a method's return value in app code | yes | yes |
| Be re-runnable after a target update | yes (re-attach) | usually yes (class/method names auto-update far better than byte offsets) |
| Need no root on the target device | no | no |
The productive pattern is to use **both in sequence**: Frida to discover which class and method matter
and what the real call chain is (`references/dynamic-frida.md`), then a module to make that finding
permanent without touching the APK. Rebuilding a module for every question is the expensive way to
explore; exploring with an interactive script and only then writing the module is the cheap way.
A third option exists when the goal is *calling* target code rather than changing it — exporting a
native function over RPC: `references/emulation-and-rpc.md`.
## Failure modes
| Symptom | Most likely cause | Check |
|---|---|---|
| module never appears in the manager | `xposedmodule` meta-data missing/mistyped after manifest merge | `aapt2 dump xmltree` the built APK, or re-read the manifest |
| module listed, no `injected:` line in either channel | module disabled in manager, package not in scope, **target process not restarted** after the scope change, or you looked at only one channel | the four-step order above, then the two-channel check |
| the platform log is empty but the module log is not | the ROM's `logd` route is broken; the module is working | the tell is `Logd maybe crashed (err=Socket operation on non-socket)` at the top of the module log |
| `injected:` line present, but `TARGETS` gate skips the process | in-module gate, not the framework | read the module's own log line, then its gate |
| hook installed, method never fires | wrong class/loader: packers and plugin frameworks hold several ClassLoaders | resolve the loader at runtime; enumerate `/proc/<pid>/maps`-independent evidence via `references/dex-patching.md` |
| target dies right after injection | target side: ClassLoader counting or anonymous-memory heuristics (above); device side: ROM behaviour | instrument-free control run first (`references/detection-and-anti-analysis.md`) |
| `pm enable` had no effect on injection | `pm` state and LSPosed state are different switches | the two-switch table above |
| `d8` fails on a directory / `aapt add` cannot find the dex / `keytool` not found | build-chain traps, all three measured | the four traps above |
## Verification for the record
- which module APK, its hash, and what it was built from (scaffold output or hand-written);
- the build commands and whether `apksigner verify` passed;
- `pm path`/`dumpsys package` output for the module (installed, enabled state);
- the scope list actually configured;
- the target process start time relative to the scope change;
- the module's logcat lines, in order, showing injection and any hook installs;
- whether the target misbehaved, and the instrument-free control result for the same build.
## See also
- `references/dynamic-frida.md` — the exploration half of the workflow above
- `references/detection-and-anti-analysis.md` — when the target fights back and when to stop
- `references/native-and-so.md`, `references/native-dbi-and-deobfuscation.md` — the layer a Java hook stops at
- `references/dart-aot.md` — the layer that owns a Flutter app's logic
- `references/advanced-unpacking.md` — extracted dex and the VMP boundary
- `references/repack-and-sign.md`, `references/signature-derived-keys.md` — what you are avoiding, and why it is sometimes unavoidable
- `references/on-device-tooling.md` — MT Manager and the rest of the on-device kit
- `references/verification.md` — what "done" means, including the control-build rule
- `scripts/lsposed_scaffold.py` — generates the project skeleton described here
@@ -0,0 +1,271 @@
# Native DBI and deobfuscation
**Load this when static disassembly of a `.so` has stopped producing information** — an exported
function decompiles into a dispatcher loop and arithmetic soup, a symbol you need has no name, or you
must answer "what actually ran" instead of "what could run". This file covers instruction-level
dynamic tracing: what a trace can and cannot decide, how to record one with the scripts in
`scripts/`, and where it hands off to emulation and symbolic execution.
**Hand-off.** `native-and-so.md` owns the APK-side conclusions about a library — which `.so` is
loaded, which ABI is executing, whether a hook can observe anything, how to neutralise a terminate
path by returning. This file owns execution-level evidence. If the question is "did my patch cause
the death", that is `native-and-so.md` and `native-tamper-and-suicide.md`; if it is "which blocks did
this function really execute, and how often", it is here.
**Claim strength.** `measured` = an exact command and its output exist in
`docs/tool-verification/EXTENSION-native-dbi.md`. `inferred` = it follows from measured behaviour or
from documented behaviour of the tool. `unverified` = reported by someone else or reasoned from
first principles without a run. The distinction matters more here than usual, because the honest
result of this pass is that **the trace pipeline is unverified on the test device** — see §6.
## 1. Which obfuscation are you looking at
Obfuscator-LLVM ships three transforms, and one target usually carries all three. Identify by
**which one made static reading fail**, because each is undone by a different observation.
| Transform | Static shape | Dynamic signature | What removes it |
|---|---|---|---|
| **Control-flow flattening** | One dominator block at the top of the function, reached from everywhere; a state variable (register or stack slot) assigned a constant before each jump back; a `switch`/jump table dispatch; the original block order is gone | The dispatcher block dominates the execution histogram by a wide margin; real blocks appear between dispatcher entries; execution sequence looks like `D R1 D R2 D R3 D` | Trace histogram + the state variable's constants: each dispatcher entry is preceded by a store of the next real block's id |
| **Bogus control flow (opaque predicate)** | A branch whose condition is algebraically constant (`(x*x) >= 0`, `x*x % 2 == 0`), with a junk block on the impossible side; junk blocks reference unreachable names | The junk branch **never appears** in the trace at all: not once, at any input | Trace absence, and then dead-code deletion of the never-taken side. Absence in a trace is only evidence if the trace covers the input that would take it |
| **Instruction substitution** | Arithmetic that is correct but unrecognisable: add chains with negated constants, `xor`/`and`/`or` rewrites of a comparison, MBA identities | The function's **result** is still correct at its boundary, and the single-step value at a known point (e.g. the return register) matches the un-obfuscated expectation | Symbolic execution or a brute-force input sweep; a trace alone does not simplify arithmetic |
Worked example of the distinction: a flattened function with substituted instructions produces a
trace whose histogram has an obvious top, but the arithmetic between dispatcher entries still tells
you nothing. Flattening is a **control**-flow problem and the trace answers it; substitution is a
**data**-flow problem and needs §5.
**Reported, not verified here:** a community write-up of this exact pipeline — trace, aggregate,
solve with a symbolic executor, patch the binary — is
[基于动态指令追踪与符号执行对抗OLLVM控制流平坦化的工程化实践](https://cloud.tencent.com/developer/article/2721228)
(cloud.tencent.com/developer/article/2721228, published 2026-08-05). It reports, on a 2,800-block
x64 fixture: 15 s of tracing ≈ 220 MB of raw log, aggregation to 48 KB of block records, ~12 min of
parallel symbolic execution resolving 67 dispatcher targets, and 1.2 s of binary patching over 147
sites. **Those numbers are the author's, on a Windows x64 DLL, and were not reproduced here** —
treat them as an order-of-magnitude sketch for the data-reduction ratio (raw log to block table is
roughly 4000:1 there), not as a budget for an arm64 Android target. The article's code snippets are
illustrative rather than runnable: its `onReceive` handler indexes parsed events by field name
(`item.kind`, `item.start`), while `Stalker.parse(..., {stringify: false})` returns **positional
arrays**. Take the method from that article; take the API shape from this repository and from the
script header in `scripts/stalker_trace.js`.
## 2. Pick the observation before you pick the tool
| Question | Observation | Tool |
|---|---|---|
| Which blocks executed, and how often? | Block-level trace with execution counts | `scripts/stalker_trace.js` + `scripts/stalker_report.py` |
| Which functions inside the module call each other? | Call edges from the same trace | same pair (`call` events) |
| Which imported function does this stub reach? | Relocation table, not trace | `scripts/elf_plt.py` |
| Where did the process die, and did it look arranged? | Crash record, signal, fault address, backtrace split by owner | `scripts/native_crash.py` |
| What value must the state variable have to reach block X? | Constraint solving over the dispatcher | angr / Triton (§5) |
| What is the value at a specific point for a specific input? | Deterministic per-instruction replay with memory operands | QBDI (§4) |
| What does this code do with no device at all? | Emulation of the `.so` with a synthetic environment | unidbg / Unicorn / QEMU |
The first two rows are one run of one script — take both. `elf_plt.py` and `native_crash.py` are not
competitors here: they answer a symbol and a death respectively, and both work when no trace can be
taken at all.
## 3. Recording a trace with `scripts/stalker_trace.js`
Frida Stalker recompiles every basic block a followed thread executes and hands the events back to
JavaScript. It needs no symbols, no source and no disassembler on the host, which is exactly why it
works on stripped OLLVM output.
**Three rules, each one a failure mode if broken**
1. **Follow one trigger, not the whole process.** An unrestricted follow of a busy thread produces
gigabytes and slows the target down until it dies.
2. **Filter to one module.** `targetModule` is the only module whose blocks are reported; call edges
report when either end is inside it. Filtering happens on the device, not in post-processing,
which is what keeps the log usable.
3. **Cap the volume.** `maxBlocks` stops the trace instead of letting the log eat the disk, and the
`DONE` line records whether truncation happened.
**Configuration** (edit `CONFIG` in the script, or override at runtime through `rpc.exports.config`
/ `script.post({type:'cfg', payload:{...}})`):
| Key | Meaning |
|---|---|
| `targetModule` | the one `.so` whose blocks are reported |
| `trigger` | `{kind:'export', module, export}` — start on a named export (a JNI function is the classic); `{kind:'offset', module, offset}` — start at module-relative offset; `{kind:'java', cls, method}` — start at the Java→native boundary; `{kind:'main'}` — follow the thread right after load |
| `followMs` | hard stop, so a forgotten trace cannot kill the process |
| `maxBlocks` | event cap; the `DONE` line reports truncation |
| `events.compile` | first translation of each block — deduplicated block set in first-visit order |
| `events.block` | every executed block — the execution histogram |
| `events.call` | call edges |
| `events.exec` | **per instruction; enormous.** Enable only around a known point |
| `events.ret` | return edges |
**Customising what gets translated (`transform`).** Event flags shape *what you are told*; the
`transform` callback shapes *what runs*. It fires before a block is translated and receives the
instruction iterator, so it can rewrite the code Stalker is about to execute — inline a counter at one
call site, neutralise a logging call inside a hot loop, or substitute a value at the one address you
care about. Reach for it when the question is "is this site reached, and how often" rather than "which
blocks ran"; do not reach for it when the answer must be an observation, because a transform changes
the process's behaviour and stops being passive measurement. Two properties to respect: it can run
once per block per thread, so any rewrite must be idempotent, and the rewritten bytes are the DBI's
copy, so a crash inside them will not point at a file offset. `inferred`: `scripts/stalker_trace.js`
uses events and `onReceive` only; the transform route is documented here, not exercised by this
repository's pass.
**Running it.** With the bundled injector, which writes every event to a log file *and* stdout:
```
python scripts/run_probe.py scripts/stalker_trace.js 1 --pkg <pkg> --via usb --log trace.log
```
With any driver that speaks Frida's rpc, so no file edit is needed:
```js
script.exports.config({ targetModule: 'libapp.so',
trigger: { kind: 'offset', module: 'libapp.so', offset: 0x9f6c0 },
followMs: 3000, maxBlocks: 50000 });
script.exports.start(<tid>); // follow this thread
script.exports.status();
script.exports.stop();
```
Pass `start(tid)` explicitly rather than relying on the default. **`Process.getMainThreadId()` is
not the Android main thread in practice**: on the measured run below, a process with pid `19938` was
followed on tid `25606`, and an idle-looking thread produced zero events. On Android the main thread
tid equals the pid, which is the value to start from.
**Output grammar** (one logical line per event; `scripts/stalker_report.py` parses it, including
logs where each line is wrapped by `run_probe.py` as `[host ts] [dev ts] TRACE ...`):
```
READY ... config echo and module status; nothing works before it
MOD name base=0x.. size=.. path=..
BB <seq> <mod>+0x<offset> block first translated (dedup'd skeleton)
BLK <seq> <mod>+0x<offset> [size=n] block executed (histogram input)
CALL <depth> <from> -> <to> call edge
DONE reason=timeout|trigger-leave|maxBlocks|stop-rpc blocks=n blk=n calls=n truncated=0|1
FATAL / TRIG-FAIL what did not install and why; the script keeps running
```
**Reducing the log**
```
python scripts/stalker_report.py trace.log --top 30 --skeleton 80 --edges 15 --json report.json
```
Four reductions, each answering a different question: the **execution histogram** (top of the list =
dispatcher candidate), the **first-visit order** (deduplicated block set ≈ CFG skeleton with the
flattening state machine stripped out), the **call-edge table** (module-internal communication with
no symbols), and the **collapsed execution sequence** (`block*N -> block -> ...`, which is where the
`D -> R -> D -> R` flattening rhythm becomes visible).
Diagnostics the report prints, and what they mean:
- `DONE ... truncated=1` — the trace hit `maxBlocks`. Ratios remain useful; **absolute counts do
not**, and a claim about a dispatcher's multiplicity must be re-measured with a higher cap.
- `zero BLK with nonzero BB` — the thread was translated but executed nothing in-window: the window
closed, or the trigger returned immediately.
- `zero BB and zero BLK with DONE present` — the module never ran on the followed thread. Change the
thread or the trigger; do not tune the follow time.
- Everything zero **and no `DONE`** — the trace never started. Read the `READY` / `TRIG-FAIL` lines
first; that is a plumbing problem, not an analysis result.
## 4. Stalker, QBDI, or emulation
| Situation | Choice | Why |
|---|---|---|
| Need block-level coverage and execution counts on a real device, no per-instruction semantics | **Stalker** | Cheapest to start, no host toolchain, works on code with no symbols |
| Need per-instruction values, memory operands, or a deterministic replay that can be re-run at a recorded PC | **QBDI** (QuarkslaB Dynamic Binary Instrumentation), via its Frida binding | An independent DBI engine with its own register/memory API; the trace is a program, not a log. It instruments at a different layer than Stalker, which matters on ART: Stalker translates the code it sees, QBDI exposes the instruction stream and its operands directly |
| Need to hurt the target as little as possible while instrumenting a hot path | **QBDI** | Deterministic, no reliance on the app's own JIT/AOT output |
| Need a result with **no device and no app process** — a hardened sample refuses to run, or the algorithm must be called thousands of times | **Emulation** (unidbg, Unicorn, QEMU) | Runs the `.so` in a synthetic environment with JNI stubs; completely different trade-off (environment fidelity for scale) |
| Need "what input reaches block X" rather than "what happened for input I" | **Symbolic execution** (§5) | A trace is one path; a solver enumerates the condition |
**Stalker and ART do not compose for free.** The followed thread's code can be recompiled by ART's
JIT while Stalker has already translated it, and a block's address is only meaningful inside one
process lifetime. Practical consequences: keys in a log are `module+offset` and stay comparable
across runs only for code that is mapped from file; do not compare a `libart`-materialized block
address between two runs; and never place a follow/unfollow pair on a hot function (measured failure
in §6).
## 5. From a trace to a deobfuscated function (inferred)
This is the part the community write-up above also describes, and it is **inferred** here — the
trace end was not reproducible on the test device, so the steps below are a method, not a record.
1. **Find the dispatcher.** Rank by execution count. In a flattened function the dispatcher runs
once per real block; loops multiply it further. A block that is (a) at the top by a wide margin,
(b) entered from many distinct predecessors, and (c) followed by many distinct successors, is the
dispatcher. `stalker_report.py` prints exactly the three items needed to check that.
2. **Find the state variable.** Disassemble the dispatcher entry window statically (the offset is in
the trace, so no symbol is needed). Look for the register or stack slot written immediately
before the indirect branch; in flattened output this is the value the dispatch table is indexed
by. If more than one candidate exists, correlate: the state variable is the one whose written
constants match the distinct block ids seen in the trace.
3. **Recover the real CFG.** Convert the flat sequence into edges: `dispatcher → real block →
dispatcher`. The real blocks' order and repetition come from the trace; the state constants come
from step 2; the mapping `state value → real block` turns the dispatcher into a jump table you
can then remove in the binary (the LIEF step in the write-up).
4. **Solve what the trace did not cover.** A trace is one input's path. For a state value you never
observed, symbolically execute the dispatcher **only** (a few tens of bytes: load the state,
bounds-check it, index the table) rather than the whole function. This is where angr or Triton
earns its cost: the entry point is the dispatcher offset the trace gave you, and the goal is the
table index, not the program's semantics. Reported pitfall from the same write-up, worth repeating
because it is structural: OLLVM inserts transitions that land outside the table, so prune states
whose index exceeds the table bound instead of letting the solver chase them.
5. **Only then patch the binary.** Direct-branch rewriting must respect instruction length: an
absolute jump needs more bytes than the `mov; jmp` pair it replaces, so pad rather than move
anything. `scripts/elf_plt.py` is the tool that tells you what a rewritten site actually reaches
(by relocation, not by position), and a byte-diff of two builds is how you prove your patch set is
what you think it is.
## 6. Failure modes
**Zero events, follow installed (measured, cause unverified).** With host frida 16.7.19 and a
matching on-device frida-server 16.7.19 on Android 11 / arm64, `Stalker.follow` on a main thread for
4 s produced `blocks=0 blk=0 calls=0` on two different system processes, and an `export`-triggered
follow produced `reason=trigger-leave blocks=0` on every one of hundreds of firings. Every line
before that was healthy: `READY`, `TRIG following tid=…`, `MOD libc.so base=0x…`. The conclusion to
carry forward is narrow and should not be widened: **on that combination, follow installs but events
do not arrive in `onReceive`.** It is not a licence to assume Stalker is broken everywhere, and not
evidence about any other ROM, frida version or target. Validate the pipeline before trusting a zero
result: follow a thread you control executing a known loop, and confirm nonzero `BLK` lines.
**High-frequency follow/unfollow crashes the target (measured).** Using a hot libc export as the
trigger — every call starts a follow and every return ends it — a system UI process died with
`SIGSEGV` after hundreds of cycles; the crash record's frame `#00` sat in an anonymous region (the
DBI's code cache) and the return address led into `libart`. The process restarted under a new pid.
The lesson is not "Stalker is unsafe"; it is **do not use a hot function as a follow trigger**, and
do not build a follow/unfollow cycle per-call in a hot path. A single follow of a chosen thread for a
bounded window is the shape that works.
**The device becomes the experiment (measured).** While this pipeline was running, the test device's
`load average` reached `34.11` on an 8-core mid-range phone, and a co-running dynamic job on the same
phone (a dex-dumping attach belonging to another task) was destroyed mid-flight. On a shared device
these are not independent experiments: one heavy DBI run makes every other dynamic result
unattributable. Announce the window, keep `followMs` in the low seconds, cap `maxBlocks`, never spawn
when attach is enough, and treat a `script has been destroyed` in a *different* job as a signal that
your load — not that job's code — is the variable. This is `long-task-discipline.md` §single-variable
discipline applied to hardware.
**A trace of a VM is a trace of the interpreter.** If the target is a virtualized function (private
bytecode executed by a handler loop), Stalker will happily report the interpreter's blocks: a huge,
flat, repetitive histogram around one dispatch loop. That is a valid finding — it tells you the code
is virtualized — but it is **not** the guest program's control flow. Recovering that needs handler
identification and a private opcode table; see
`code-virtualization-and-custom-linkers.md`, and do not present an interpreter trace as the
deobfuscated function.
**Instrumentation was detected before you started.** If the process dies when you attach, refuses to
run under root, or the module you want is never loaded while attached, the problem is upstream of
this file: read the first section of `detection-and-anti-analysis.md` before escalating the trace,
because the cheap answer is usually to switch to static analysis with `elf_plt.py` and
`native_crash.py`, not to fight the detector.
## 7. Reporting what a trace proves
- A trace proves **what executed on the followed thread inside the followed window**. It does not
prove absence: `BB` never appearing means it did not run *for that input, in that window* — which
is meaningful for an opaque-predicate junk block only when the rest of the analysis says the input
would have taken it.
- Counts are evidence only when `truncated=0`. State the cap.
- A dispatcher identification is a hypothesis about a block's role. Confirm it by disassembling the
block and finding the table it indexes; a high count alone is also what a spin loop or a memory
allocator's fast path looks like.
- Write the product's before/after into `docs/tool-verification/`, with the exact command, the
module, the offsets, and the strength label. The next person's first question is "was the pipeline
known to work when you got that zero", and the answer belongs in that record, not in a footnote.
@@ -0,0 +1,142 @@
# On-device tooling — MT Manager, APK MCP, LSPosed, Termux
Sometimes the PC is the wrong place to work: the device already has the APK installed, the edit is
one string, the target is a 38 MB repack you would otherwise push back and forth, or there simply
is no laptop in the loop. This file covers the **on-device toolchain** and — more importantly —
when each tool beats its PC counterpart and when it does not.
Evidence basis: the facts below come from a real configured environment (Android 11, Magisk +
Zygisk, LSPosed v1.9.2, MT Manager 2.26.9), archived in `tools/_phone-modules/`. Framework
activation and the module set are `observed` there; per-workflow usability notes are `measured`
where marked, otherwise `inferred`. The MT MCP tool surface is from MT's official documentation
(`observed` as a list; live invocation requires the service to be running — see §2).
## 1. MT Manager as a reverse-engineering workbench
MT Manager (`bin.mt.plus`) is a file manager plus APK editor. For this skill's purposes it is a
**complete repack pipeline that runs on the phone**: view, edit, rebuild, sign.
What it covers, mapped to this skill's workflow stages:
| Skill stage | MT capability | Notes |
|---|---|---|
| Recon (manifest, SDKs) | APK viewer: manifest, entry list, string search across dex/resources | String search is the fast path; no full Java decompile in the editor workflow |
| Dex reading/editing | Dex viewer + smali-level editing | Smali is the editing granularity — same discipline as `dex-patching.md` |
| Removing signature verification | Built-in "去除签名校验" (signature-check killer) feature | Convenience feature; audit what it actually patched — a Java-layer signature killer can be a decoy while a native check still kills you (`code-virtualization-and-custom-linkers.md` §decoy) |
| Extracting artifacts | Pull `classes.dex`, `.so`, `resources.arsc`, axml out of any APK/zip | Useful to move a single `.so` to the PC toolchain without a full unzip |
| Repack + sign | Rebuild APK and sign it on device | Output lands in MT's working directory; verify with the same discipline as `repack-and-sign.md` (alignment, `resources.arsc` rules still apply — the platform enforces them regardless of which machine built the file) |
**When MT beats the PC pipeline:** quick single-file edits, on-the-spot verification on the same
device the app is installed on, and sessions where shuffling 40 MB APKs over USB dominates the
work. **When the PC wins:** anything scriptable/repeatable, dex-wide cross-referencing
(`find_refs.py`), byte-precision patching with header recomputation, and anything needing a real
decompiler. The honest split: MT for **breadth on device**, PC for **depth and repeatability**.
`inferred`.
## 2. MT's built-in APK MCP server
MT 2.26.9+ ships an "APK MCP" service: it exposes MT's analysis and modification capabilities to
an MCP (Model Context Protocol) client — which in practice means an AI agent drives MT's tooling
over HTTP while the human sees the results on the phone. The official framing: AI understands the
request and calls the tools; MT does the local read/modify/repack/sign.
**Transport and endpoint** (`measured` on the reference environment):
- Streamable HTTP MCP at `http://127.0.0.1:8787/mcp` from the PC, via `adb forward tcp:8787
tcp:8787`; or directly `http://<phone-ip>:8787/mcp` on the LAN.
- **The service must be started by hand in the MT UI** (side drawer → Tools → APK MCP → Start).
adb cannot start it. Before it is started, the port is simply not listening — probe with
`scripts/mt_mcp_probe.py`, which prints waiting instructions in that state.
**Tool surface** (official documentation; names observed from the published list):
| Category | Tools |
|---|---|
| Open/selection | `mt_apk_list_available_apks`, `mt_apk_open` |
| Reading/search | `mt_apk_list`, `mt_apk_search`, `mt_apk_read_text`, `mt_apk_read_bytes`, `mt_apk_continue` |
| Dex analysis | `mt_apk_dex_outline_class`, `mt_apk_dex_xref` |
| Resources | `mt_apk_resource_read`, `mt_apk_resource_xref` |
| Native static | `mt_apk_native_inspect`, `mt_apk_native_read_items`, `mt_apk_native_map_address`, `mt_apk_native_xref`, `mt_apk_native_disassemble`, `mt_apk_native_function_cfg` |
| Modification | `mt_apk_edit_open`, `mt_apk_edit_text`, `mt_apk_edit_resource`, `mt_apk_patch_bytes`, `mt_apk_native_patch_instructions`, `mt_apk_native_patch_string`, `mt_apk_edit_check`, `mt_apk_build` |
| Cleanup | `mt_apk_close` |
**Official constraints — budget your plans around these, not around hopes:**
1. **No Java decompilation.** The stated position: AI reads smali directly; decompiled Java of
hardened/R8'd code misleads more than it helps. Cross-references (`dex_xref`) and class
outlines are the structural view.
2. **`resources.arsc`: existing entries only.** No new locales or new entries — edit what ships,
do not plan feature-additions through arsc.
3. **`.so` support is static analysis only.** No dynamic execution, no emulation, no C/C++
pseudocode. Xrefs and CFG are "best-effort within a limited budget" — direct static results,
**not** proof of a complete call chain or of runtime behaviour. For depth, the PC side (IDA/
Ghidra-class, see `toolchain.md`) remains the answer.
**Handing an APK to the server** (three supported ways): open an APK in MT's file list and stay
on its info dialog ("the current APK file"); open an installed app's info dialog the same way; or
drop the APK into MT's configured MCP working directory and refer to it by filename/package. The
working directory is also where rebuild output lands.
**Probing from the PC:** `python scripts/mt_mcp_probe.py` does the full JSON-RPC handshake
(initialize → initialized → tools/list) with no MCP SDK dependency and prints a grouped tool
inventory. If MT's MCP has not been started in the UI, it exits with waiting instructions and
code 2 — usable as a loop check ("is it up yet") while you start it by hand. `measured`.
## 3. LSPosed Manager — the module route on device
LSPosed (via Zygisk) gives you a **Java-layer hook platform that needs no PC at runtime**: write/
install a module once, and it applies to target apps at every launch.
Facts from the reference environment (`observed`, archived in `tools/_phone-modules/`):
- Activation is verifiable from logs: the `ZygiskCompanion: welcome to LSPosed!` banner, the
version line, the `lspd` daemon process running as system.
- Install discipline: `magisk --install-module` unpacks to `/data/adb/modules_update/` and only
**merges after a reboot** — a module that "did not install" is usually one that has not merged
yet. `ls /data/adb/modules/` is the truth; `modules_update/` non-empty means pending.
- Zygisk itself needs one reboot after being enabled before its injection layer exists at all.
Limits that matter for this skill: LSPosed hooks **Java/ART** — it cannot hook inside a native
`.so` (that is Frida/IDA territory, and the reason `framework-runtimes.md`'s runtime check
exists), and it does nothing for Flutter/Dart AOT logic below the platform channel. Use it for
the layer it owns: Java API interception, intent/telemetry rewriting, feature gates that live in
Java. A hook module is also **not a deliverable** for a request that wants an installable APK —
it is an environment change on your device (`detection-and-anti-analysis.md` Step 4 keeps these
separate).
## 4. Termux + frida-server — device-side dynamic analysis
The phone can run the whole dynamic stack alone: Termux (or a plain root shell) hosts
`frida-server`, and scripts run through Termux's own Python.
- **frida-server version must match the PC-side frida tooling** when the PC is also in the loop
(`dynamic-frida.md` owns this). Device-only operation still needs a matching `frida` client in
Termux.
- **Disguise the server when the target hunts it**: a renamed binary and a non-default port are
the minimum; a detection-savvy target scans process names and default ports. The reference
environment carried renamed server copies from prior work — the technique is standard, and the
detection mechanics are `kernel-and-environment-hardening.md` §1.
- **32/64-bit**: a `zygote64_32` device runs both ABIs; make sure the frida-server architecture
matches the process you are attaching to (`environment.md` §which architecture is actually
executing).
- Keep sessions simple: attach-mode on a hardened target inherits every §1 problem of
`kernel-and-environment-hardening.md`; prefer spawn, and prefer `spawn_patch_detach.py`-style
patch-then-detach when you only need a memory fix to stick.
## 5. On-device forensics — where the data is
Rooted-phone data inspection does not need a PC round-trip. The full layout, formats and
ownership rules live in `runtime-data.md` (DataStore/MMKV/SQLite paths, `chown`/`restorecon`
after restores, the "app rewrites your edit" decision tree) — on device, MT Manager's file
browser with root covers the same reads, and Termux covers scripted pulls. The two on-device
cautions that most often bite: edit files **only with the app force-stopped** (the in-memory
copy wins otherwise), and re-check ownership after any reinstall (the uid increments).
## Checklist
- [ ] Chose the workbench deliberately: MT (on-device, fast) vs PC (scriptable, deep) — not by habit
- [ ] MCP started in MT's UI and probed (`mt_mcp_probe.py` exits 0) before planning agent-driven edits
- [ ] MCP plans respect the three official constraints (no Java decompile, arsc entries-only, `.so` static-only)
- [ ] LSPosed modules verified merged (`/data/adb/modules/`, not `modules_update/`) before testing
- [ ] frida-server architecture matches the target process; disguised if the target scans
- [ ] Data edits done with the app stopped; ownership fixed after reinstalls
@@ -0,0 +1,270 @@
# Protocol reverse engineering
**Load this when the app's traffic is not readable by the usual means**: the body is protobuf with no
schema, the transport is gRPC, the connection is QUIC rather than TCP, or the client refuses to trust
your proxy because it validates the certificate inside a native library.
Everything in this file assumes you have already decided the traffic matters and that a proxy is
allowed to see it. If a *feature-scoped* TLS failure has appeared while the rest of the app works,
that is a different problem with its own file: read `tls-and-cert.md` first — it owns the trust-chain
attribution and the permissive-defaults template, and this file deliberately does not repeat them.
**Claim strength.** `measured` = an exact command and output exist in
`docs/tool-verification/EXTENSION-native-dbi.md`. `inferred` = documented behaviour or a step that
follows directly from a measured one. `unverified` = reported by others, not reproduced here. The
wire-format section is `measured` on a self-built fixture; every tool named below is `unverified`
unless stated otherwise.
## 1. Protobuf on the wire (measured)
Protobuf has no field names on the wire and no header. A payload is a flat sequence of
`tag, value` pairs, and a nested message is just a value of type "bytes whose content is another
sequence". That is the whole format; the schema supplies meaning and nothing else.
| Element | Encoding |
|---|---|
| Varint | base-128, least-significant group first, high bit set on every byte but the last |
| Tag | `(field_number << 3) \| wire_type`, itself a varint |
| Wire type 0 | varint value (int32/int64/uint/bool/enum) |
| Wire type 1 | fixed 8 bytes (fixed64/sfixed64/double) |
| Wire type 2 | length-delimited: length varint, then that many bytes (string, bytes, nested message, packed repeated) |
| Wire type 5 | fixed 4 bytes (fixed32/sfixed32/float) |
| Wire types 3/4 | group start/end, legacy; treat as unsupported when walking a modern payload |
A host-side check of the rules, including the canonical `150 -> 96 01`, lives in
`tools/_work/t4-dbi/pb_selftest.py` (workbench, not shipped with the skill). Measured output on the
fixture built there:
```
message (29 B): 089601120774657374696e671a0508011201782206038e029ea7052800
field 1 varint 150
field 2 len-delimited(7) 'testing'
field 3 len-delimited(5) nested message:
field 1 varint 1
field 2 len-delimited(1) 'x'
field 4 len-delimited(6) hex '038e029ea705'
field 5 varint 0
rebuild from the walked rows equals original: True
```
Three consequences that decide how you interpret any decoded body:
1. **Field numbers are local to their message.** In the walk above, field 3 of the outer message is a
nested message whose own field 1 exists independently. Nothing on the wire says which message a
field number belongs to; only a schema does.
2. **A packed repeated field is invisible without a schema.** Field 4 above is three varints
(`3, 270, 86942`) packed into one length-delimited value. A schema-free decode can only report it
as opaque bytes — the length is known, the element boundaries are not.
3. **An explicit zero is byte-identical to an absent field** in proto3 (`28 00` versus no bytes at
all). A decoded `0` is not evidence that the sender set the field, and "the server sent 0" is not
a safe conclusion from a decode alone.
### Decoding without a schema
- `protoc --decode_raw < body.bin` — the reference implementation's own raw decode; prints field
numbers and values in exactly the shape above. Note it prints strings and nested messages without
distinguishing them, which is why the fallback order matters: try a nested walk first, then
printable UTF-8, then hex.
- `protobuf-inspector` and `blackboxprotobuf` are the pip-installable equivalents, and both add
heuristics: guessing whether a length-delimited value is a string or a submessage, and (for
`blackboxprotobuf`) inferring a candidate type set per field across many samples. Useful when you
have traffic but no `protoc`; still unverified here.
- Decode **many samples of the same message**, not one. The number of distinct field numbers in a
large sample set is what tells you which fields are optional, which repeat, and which are enums
whose value set you can then enumerate.
- Anything the app stores locally is a sample source that needs no proxy at all: an OkHttp disk cache
(the `journal` file plus its entries), a DataStore file, or a Room blob column. `runtime-data.md`
covers reading these, and `datastore_inject.py` can re-encode an edited DataStore value once you
know the message.
## 2. Recovering the schema from the APK
### What generated protobuf code looks like
| Marker in the decompiled output | What it tells you |
|---|---|
| `extends GeneratedMessageLite` / `GeneratedMessageV3` | protobuf class; `Lite` means the reflection/schema runtime, not the descriptor-based one |
| `static final int FIELD_NUMBER = 3;` (or `int <name>_ = 3`) | the field number, usually right next to the field's getter |
| `switch (tag >>> 3)` with `case` constants | the parse loop's field dispatch — each `case` is a field number, in declaration order |
| `input.readInt32()`, `readInt64()`, `readBool()`, `readStringRequireUtf8()`, `readBytes()`, `readMessage(...)`, `readEnum()` | the field's wire type and semantic type, read *after* the tag |
| `input.readTag()` returning 0 as the loop exit | the standard `parsePartialFrom` skeleton; the loop body is where all field knowledge lives |
| `writeTo(CodedOutputStream)` / `getSerializedSize()` / `dynamicMethod(...)` | the class really is a generated message, not a hand-written DTO |
| `newMessageInfo(instance, "<escaped string>", ...)` | protobuf-lite's compact schema blob (see below) |
The generator keeps those framework calls even after R8, so an obfuscated app usually still carries
readable protobuf structure: class and field *names* are gone, field *numbers* and wire types are
not.
### Two routes to a `.proto`
**Route A — read the field table out of the bytecode (inferred).** Decompile the class, walk
`parsePartialFrom`, and record `case <n>` → the `read*` call that follows. Field name unknown? Name
it `field_<n>`; a valid `.proto` does not need the original identifiers, and the app's own getter
names often survive anyway. Then verify immediately against captured bytes with
`protoc --decode=<message> <schema.proto>`: a decode that produces a coherent structure for **every**
sample is the proof that your field table is right, and it costs seconds. A field that decodes into
nonsense means a wrong wire type, not a wrong field number — check the `read*` call before moving on.
**Route B — read protobuf-lite's own schema blob (inferred).** protobuf-java-lite 3.x embeds a
compact schema string (`rawMessageInfo`) per message class, consumed by `MessageSchema` at runtime.
Recovering it means locating that blob and feeding it to a matching runtime build. It is a strictly
larger win when it works — it carries field numbers, types, and labels in one place — and it is
version-sensitive, so treat Route A as the default and Route B as the acceleration. `unverified`
here: no target in this repository was analysed this way.
**Tooling that automates this (unverified):** `pbtk`/`protodump`-style scanners walk dex/JAR inputs
looking for the generated-code shape above and emit `.proto` files, and a protobuf-aware decompiler
plugin can do the same from a loaded APK. Use them to produce a first draft, then verify it with
`protoc --decode` against real captured bytes — that verification is the step that turns a guess into
a schema, and it is the step worth spending time on.
## 3. gRPC
gRPC is HTTP/2 with a message framing convention, so the first decision is whether you can see
HTTP/2 at all.
- **Recognise it.** A request carries `:method: POST`, `content-type: application/grpc[+proto]` (also
`+json`, `+thrift`), and `:path: /<package>.<Service>/<Method>` — that path shape is the reliable
fingerprint; the package in it usually matches a package name visible in the APK, which is how you
connect traffic to a client class.
- **Message framing.** Each message is: one compression-flag byte, then a 4-byte **big-endian**
length, then that many bytes of (possibly compressed) protobuf. Several messages can share one
DATA frame and one message can span frames, so reassemble by length, not by frame. The call's
outcome is in **trailers** (`grpc-status`, `grpc-message`), which many proxies display separately
from the body — a `200` with no body and a nonzero `grpc-status` is a normal gRPC error.
- **Read it after capture.** Extract the reassembled message bytes and hand them to
`protoc --decode_raw` or your recovered schema. `grpcurl -plaintext -protoset file.protoset`
replays against an endpoint once you have a schema, which is also the fastest way to confirm that
a recovered `.proto` has the right shape.
- **Capture it.** A transparent TCP proxy sees HTTP/2 fine; a tool that only understands HTTP/1.1 may
show the tunnel without the frames, which looks like "the app is not making requests". Interception
tooling for this comes in two shapes: a proxy add-on that understands the gRPC framing and prints
messages (`grpc-dump` and similar mitmproxy add-ons, or a gRPC-Web decoder when the client is a
browser-style stack), and a command-line client (`grpcurl`) for replay against a live endpoint. If
the app uses TLS (gRPC-Java does by default), the certificate question comes first — see
`tls-and-cert.md`, and the native-material trust chain below.
## 4. QUIC / HTTP/3
The failure to expect: a working HTTP proxy, a working CA, and **an empty capture**.
- **Why.** An HTTP proxy is a TCP endpoint, and a client reaches it with `CONNECT`. QUIC is a
UDP-based transport with TLS 1.3 built into the handshake; there is no TCP connection for a
`CONNECT` to carry and no separate TLS layer for a proxy to terminate.
- **Recognise it before debugging anything else.** `Alt-Svc: h3=":443"` in an earlier HTTP response
announced the upgrade; on the wire you see UDP traffic to port 443 whose first packets are QUIC
Initials (long header, version field, and a TLS ClientHello inside), and the client's ALPN is `h3`.
Check for UDP activity when a TCP proxy stays idle while the app plainly works.
- **Options, in order of how little they change:**
1. **Force a fallback to TCP.** Block or blackhole UDP 443 for the device. A client that cannot
reach an origin over QUIC falls back to TCP/HTTP2 if the server also offers it, and then your
existing proxy works unchanged. This is the cheapest option and the one to try first, but it is
a **network-condition change**: state it in the report, because "the app failed to load over
QUIC" and "the app failed" look identical in a screenshot.
2. **Decrypt with keys, not with a proxy.** TLS 1.3 key logging (`SSLKEYLOGFILE`-style) works for
QUIC exactly as it does for TLS-over-TCP, and a packet capture plus the key log can be
decrypted in Wireshark. It requires the client to support a key-log callback — Chromium-based
stacks and BoringSSL generally do, Java/OkHttp-based stacks generally do not — so this is a
per-client property, not a general solution.
3. **Turn HTTP/3 off in the client** by hooking whatever enables it (a library version check, a
remote-config flag, or a build-time constant). This is a client-side patch and therefore
belongs to the repack decision, not to the capture step.
- Everything in this section is `inferred`/`unverified` here: no HTTP/3 target was exercised in this
repository. Treat the ordering as a plan whose first step (block UDP 443) needs no tool support to
test.
## 5. SSL pinning that lives inside a native library
Three different mechanisms are routinely called "pinning", and only the last one survives a system
certificate module.
| Mechanism | Where it runs | What defeats it |
|---|---|---|
| OkHttp `CertificatePinner` (or a custom `TrustManager`) in Java/Kotlin | app's own client | Client-level, **not** the system path: `tls-and-cert.md` §Step 4 and §"If OkHttp is the failing path" own this case — do not apply the permissive-defaults template to it |
| System trust decisions via `HttpsURLConnection` / platform stack | platform | System store policy — see `tls-and-cert.md` §Step 5 |
| Verification performed by a **library the app ships**, e.g. a Flutter app's own BoringSSL, or a bundled `libcurl`/`mbedtls` | `libflutter.so`, `libapp.so`, another `.so` | Only an in-memory change to that library's verification path (below), because the library does not consult the platform trust manager you can influence from Java |
**Flutter, specifically.** A Flutter app's `dart:io` HTTP client runs on the engine's BoringSSL
inside `libflutter.so`; the app's own Dart code can additionally supply a custom trusted-certificate
context or a bad-certificate callback. Two consequences that decide which direction to work in:
- If the app is **not** pinning and simply fails to trust your CA, getting your CA into the **system**
store is the normal fix. `MoveCertificate`-style Magisk modules exist precisely because Android 7+
ignores user-store CAs for app traffic; moving the CA into the system store is a **device change**,
not an artifact, and it must be labelled as a fallback rather than the deliverable. Its boundary is
exactly this: it changes what the platform trust store contains, so it can only help a client that
reads that store.
- If the app **is** pinning, or supplies its own verification context, the system store is irrelevant
and the change has to land on the library's verification function.
**Locating the verifier inside `libflutter.so` (unverified — reported method).** The published
approach in
[universal-flutter-ssl-pinning](https://github.com/vichhka-git/universal-flutter-ssl-pinning)
(`github.com/vichhka-git/universal-flutter-ssl-pinning`) automates the anchor search with PyGhidra:
1. load `libflutter.so` headlessly in Ghidra and scan its defined strings for `ssl_client`;
2. resolve cross-references from that string to the **containing functions**;
3. decompile each candidate to count its parameters;
4. take the **3-parameter** function — that is BoringSSL's
`ssl_crypto_x509_session_verify_cert_chain`, the certificate-chain verification entry point;
5. emit the discovered RVA into two ready-to-run artifacts: a Frida script that attaches to that
address and replaces the return value with `1` (success), and a Renef script that patches the
function entry with the ARM64 sequence `MOV X0, #1 ; RET`.
The repository reports it working on Google Flutter arm64-v8a and Shorebird-patched builds with
Frida 16.x/17.x, and notes the RVA is identical across build types for the same engine version. The
same project also ships an HTTP monitor that auto-locates BoringSSL's `SSL_write`/`SSL_read` in
`libflutter.so` and prints reassembled, de-chunked plaintext — which is the route to take when the
traffic cannot be proxied at all, because it never needs a certificate the app will accept.
**Two things to verify before trusting that recipe on your target.** First, the string anchor is a
build artifact: a stripped or repacked engine can lose `ssl_client` while keeping the function, in
which case fall back to the structural search — find the `X509_verify_cert`-shaped call sequence in
the handshake code, or identify the function called with the handshake structure during
`certificate_verify`. Second, the failure mode of a wrong anchor is a **silent** success: replacing a
return value in a function that merely *looks* like the verifier makes the certificate check pass
in a process that then fails somewhere else, which is easy to misread as "the app detected my hook".
Always confirm the hook fires on a connection that would otherwise fail, and confirm it is
`SSL_VERIFY`-shaped semantics (the same value the library itself uses for success), rather than
assuming `1` is right.
**When the string anchor is gone (the `session_creator` route).** A second family of anchors does not
depend on the `ssl_client` literal at all: instead of finding the verifier through a string it
references, find it through the call chain that reaches it. BoringSSL's handshake creates the session
and then verifies the peer certificate chain, so the target is the function invoked with the
handshake/session structure on that path — this is the shape that Flutter-unpinning write-ups call the
session-creator route. It survives string and symbol stripping, because the call graph survives, and
it costs more: you must identify the handshake structure first, which is why the string anchor is the
fast path and this is the fallback when an engine build has dropped the string. `unverified` here — no
engine binary was analysed in this repository.
**When the system store is genuinely enough.** If the client is Java-side and non-pinning, moving the
CA into the system store is the least invasive change and needs no per-library work. The decision is
therefore: identify the client first (`tls-and-cert.md` §Step 4 attribution), then choose the
mechanism. Patching a library that was never consulting the store is work with no effect; installing
a system CA when a native verifier ignores it produces the same empty capture you started with.
## 6. Failure modes
**A decode that looks valid but is not.** protobuf is self-synchronising enough that random bytes
often decode into a plausible-looking field list. Guard against it by (a) decoding several samples of
the same message and expecting the same field set, (b) checking that nested lengths exactly consume
their parents, and (c) when you have a schema, re-encoding the decoded structure and comparing bytes
with the input — the same round-trip check used in §1, which caught a decoder bug in this
repository's own fixture.
**Assuming the proxy sees everything.** The proxy sees what the client sends through it. An app that
uses QUIC (§4), a raw socket, a native client bypassing Java's HTTP stack, or a certificate-pinned
connection shows up as silence. Silence is evidence about the transport, not about the app: check
UDP activity, check whether a native library is doing the I/O (`lib_map.py`, `dynamic-frida.md`),
and only then conclude that a feature is client-side.
**Patching the wrong verifier.** Covered in §5: the failure is silent, and the resulting state is
worse than a clean failure because it looks like progress. Verify the hook against a connection
known to fail.
**Treating a recovered schema as ground truth for the server contract.** A schema recovered from the
client tells you what the client expects to send and parse — it does not prove the server honours
those fields, and it says nothing about authorization. `server-api.md` owns that question. The
recurring expensive mistake is to assume that because a field exists and is settable client-side, the
server will act on it.
@@ -93,6 +93,23 @@ grepping a hand-exported smali tree.
The division of labour is worth stating plainly: **ASC locates, `ddc` reads.** Running a full `ddc`
export first, then grepping it, is the slow path this tool exists to replace.
**Measured in the extension pass** (droidasc `0.1.1.post1`, installed with `python -m pip install
droidasc`; dependency is androguard only, no JVM, no SDK):
| Command | Result on a 38.7 MB hardened APK |
|---|---|
| `getmanifest` | 0.44 s → 32,345 B of complete XML |
| `findrefs … string jiagu` | 0.42 s → hits inside the shell class's `<clinit>` and `attachBaseContext` |
| `getclass com/stub/StubApp` | 0.33 s → 22,802 B of Java |
| `listclass` (whole APK) | 0.18 s → **4 classes** |
Two facts from that run are worth carrying into any recon: the CLI name is **`droidasc`**, not `asc`
(there is no `asc` binary, and `asc --version` is simply "command not found" — `python -m droidasc`
also works), and on a packed APK a full `listclass` returning four classes is not a broken tool: the
business dex is not in the file. Reaching for `getclass` on a class that is not there exits **1** with
`Class … not found in APK.` — treat ASC as a manifest-and-shell inspector on hardened input, and take
the business-logic question to a different layer.
### ddc — dex-to-Java with query subcommands (worth adopting)
A single-file Rust binary, no install, no JVM. Two things make it more useful than
@@ -109,6 +126,22 @@ ddc app.apk -o out/ # full decompile, a few seconds for a norma
Measured on a 4.7 MB APK (4,070 classes / 30k methods): `info` ~0.13 s, `findrefs`
~0.11 s, one class ~0.25 s, full decompile ~2.8 s producing ~4,000 files.
**Measured in the extension pass** (ddc `0.1.8`, a single Rust binary — on Windows `bin/ddc.exe`,
1,028,096 B, **not on PATH** and carrying no PE version resource, so `ddc -V` is the only way to read
its version; source: the project's GitHub releases):
| Command | Result on a 38.7 MB hardened APK |
|---|---|
| `ddc info` | 0.24 s → label / package / version / application / launcher / sdk / size / md5, plus per-dex class, method, field and string counts |
| `ddc findrefs <apk> string jiagu` | 0.13 s → tabulated `dex | kind | class | method | refs` |
| `ddc strings -f jiagu --with-locations` | 0.14 s → strings mapped to the methods that hold them |
**The trap on this one is the exit code.** Asked for a class that is not present, `ddc` exits **2**
*and still prints its help text to stdout* — so a wrapper that tests "did anything come back?" reads a
usage error as an answer. Branch on the exit code, never on output emptiness. The same run also
confirms the layered picture from the other direction: `info`'s per-dex counters report 4 classes and
29 methods with code for the whole 8.9 MB shell dex.
Why the query subcommands matter more than the speed: **string cross-referencing
becomes a lookup instead of a crawl.** Asking "which class mentions this config
field name" is a sub-second command here and easily an hour of smali grepping by
@@ -0,0 +1,304 @@
#!/usr/bin/env python3
"""Validate a directory of dumped dex files: dedupe, structural checks, stub-body ratio.
A memory dump (frida-dexdump & co.) hands you a pile of images: duplicate copies of
one dex, SDK plugin dexes that were never in the APK, structurally broken fragments,
extraction-shell skeletons whose method bodies are stubbed, and -- if you are lucky --
the original. `references/recon.md` states the rule (dedupe by content hash, validate
structure before trusting); this script is the tool that rule was missing.
Per file it reports: size, sha256, dex version, checksum/signature verdicts
(`dexutil.verify_dex_header`), class count, method-body census (no-code / real /
trivial-stub / empty), the trivial-body ratio that flags an extraction-shell
skeleton, and --find pattern hits across the string table. Files are grouped by
sha256 and the survivors are ranked: most likely original first.
Exit code 0 unless nothing in the input parses as a dex at all (exit 1).
Examples:
python dex_dump_validate.py dumps/ --find 'Lcom/example/app/'
python dex_dump_validate.py dumps/ --find 'Lcom/stub/' --json > report.json
python dex_dump_validate.py one_dumped.dex
"""
import argparse
import hashlib
import json
import os
import sys
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from dexutil import OFFSETS, read_uleb, u16, u32, verify_dex_header # noqa: E402
MAGIC = b"dex\n"
KNOWN_VERSIONS = {b"035", b"036", b"037", b"038", b"039"}
RETURN_OPS = {0x0E, 0x0F, 0x10, 0x11} # return-void / return / return-wide / return-object
def classify_body(data, code_off):
"""Classify one code_item's instruction stream: 'empty' | 'stub' | 'real'.
'stub' = skip plain nop units (0x0000) and exactly one return* remains. That is
what an extraction shell leaves behind when it defers decryption to first
invocation, and what a repair fixture writes when mimicking one. Anything with a
second meaningful unit is real code, however small.
"""
insns_size = u32(data, code_off + 12)
if insns_size == 0:
return "empty"
base = code_off + 16
meaningful = 0
last_unit = 0
for k in range(insns_size):
unit = u16(data, base + k * 2)
if unit == 0x0000: # plain nop / cleared slot
continue
meaningful += 1
last_unit = unit
if meaningful > 1:
return "real" # early exit: two units can never be a stub
if meaningful == 1:
op = last_unit & 0xFF # first byte holds the opcode for 10x/11x
if op == 0x0E and last_unit == 0x000E: # return-void, no register
return "stub"
if op in (0x0F, 0x10, 0x11): # 11x returns: high byte is the register
return "stub"
return "real"
def walk_methods(data, header):
"""Yield code_off for every method defined in class_defs (0 = abstract/native)."""
for i in range(header["class_defs_size"]):
cd = header["class_defs_off"] + i * 32
p = u32(data, cd + 24) # class_data_off
if p == 0:
continue
static_f, p = read_uleb(data, p)
inst_f, p = read_uleb(data, p)
direct_m, p = read_uleb(data, p)
virtual_m, p = read_uleb(data, p)
for _ in range(static_f + inst_f):
_, p = read_uleb(data, p) # field_idx_diff
_, p = read_uleb(data, p) # access_flags
for _ in range(direct_m + virtual_m):
_, p = read_uleb(data, p) # method_idx_diff
_, p = read_uleb(data, p) # access_flags
code_off, p = read_uleb(data, p)
yield code_off
def string_find_hits(data, header, patterns):
"""Count string-table entries containing each pattern."""
hits = {}
for pat in patterns:
pat_bytes = pat.encode("utf-8", "surrogateescape")
n = 0
for idx in range(header["string_ids_size"]):
p = u32(data, header["string_ids_off"] + idx * 4)
try:
_, p = read_uleb(data, p)
end = data.index(b"\x00", p)
except Exception:
continue
if pat_bytes in data[p:end]:
n += 1
hits[pat] = n
return hits
def profile_dex(path, patterns, trim=False):
"""Build the report dict for one file. 'error' key marks a rejected image.
With trim=True, an image whose header file_size is *shorter* than the file is
accepted after cutting the tail: /proc/<pid>/mem dumps are page-aligned, so the
recorded VMA range is always longer than the dex it holds (measured on a real
root-side dump: 17/17 images overran by 68-3724 bytes). A file *shorter* than
its own file_size is still rejected -- that is a truncated read, not padding.
"""
name = os.path.basename(path)
with open(path, "rb") as fh:
data = fh.read()
prof = {
"path": os.path.abspath(path),
"name": name,
"size": len(data),
"sha256": hashlib.sha256(data).hexdigest(),
}
if len(data) < 112:
prof["error"] = "too small (%d B) to carry a dex header" % len(data)
return prof
if data[:4] != MAGIC:
prof["error"] = "magic=%r" % data[:4]
return prof
version = data[4:7]
prof["version"] = version.decode("ascii", "replace")
if version not in KNOWN_VERSIONS:
prof["error"] = "unknown version %r" % version
return prof
header = {k: u32(data, v) for k, v in OFFSETS.items()}
if header["file_size"] != len(data):
if trim and 0 < header["file_size"] < len(data):
prof["trimmed_from"] = len(data)
prof["trimmed_to"] = header["file_size"]
data = data[: header["file_size"]]
prof["size"] = len(data)
else:
prof["error"] = "file_size=%d actual=%d" % (header["file_size"], len(data))
return prof
if header["header_size"] != 112:
prof["error"] = "header_size=%d (expected 112)" % header["header_size"]
return prof
for key in ("string_ids_off", "type_ids_off", "proto_ids_off",
"field_ids_off", "method_ids_off", "class_defs_off"):
off = header[key]
if off and not (0 < off < len(data)):
prof["error"] = "%s=0x%x out of range" % (key, off)
return prof
cksum_ok, sig_ok = verify_dex_header(bytearray(data))
prof["checksum_ok"] = cksum_ok
prof["signature_ok"] = sig_ok
prof["classes"] = header["class_defs_size"]
no_code = with_code = stubs = empties = 0
try:
for code_off in walk_methods(data, header):
if code_off == 0: # abstract / native declaration
no_code += 1
continue
if code_off + 16 > len(data):
continue # broken pointer: skip, don't die
with_code += 1
kind = classify_body(data, code_off)
if kind == "stub":
stubs += 1
elif kind == "empty":
empties += 1
except Exception as exc: # desynced class_data: keep counts
prof["walk_error"] = str(exc)
prof["methods_no_code"] = no_code
prof["methods_with_code"] = with_code
prof["bodies_real"] = with_code - stubs - empties
prof["bodies_stub"] = stubs
prof["bodies_empty"] = empties
prof["trivial_ratio"] = (stubs / with_code) if with_code else 0.0
if patterns:
try:
prof["find_hits"] = string_find_hits(data, header, patterns)
except Exception as exc:
prof["find_hits_error"] = str(exc)
return prof
def collect_files(paths):
out = []
for p in paths:
if os.path.isdir(p):
out += [os.path.join(p, n) for n in sorted(os.listdir(p))
if n.endswith(".dex")]
elif os.path.isfile(p):
out.append(p)
else:
print("warning: %s is not a file or directory, skipped" % p,
file=sys.stderr)
return out
def rank_key(prof):
return (prof["trivial_ratio"],
0 if prof["checksum_ok"] else 1,
0 if prof["signature_ok"] else 1,
prof["name"])
def main(argv=None):
ap = argparse.ArgumentParser(
description="Dedupe and structurally validate a directory of dumped dex "
"files; rank which image is the most likely original.")
ap.add_argument("path", nargs="+",
help="a directory of *.dex dumps, or individual .dex files")
ap.add_argument("--find", action="append", default=[], metavar="PATTERN",
help="count string-table hits for PATTERN (repeatable), "
"e.g. --find 'Lcom/example/app/'")
ap.add_argument("--json", action="store_true",
help="emit the full report as JSON (deterministic; redirect "
"to a file to keep it)")
ap.add_argument("--trim", action="store_true",
help="accept page-aligned dumps: cut a tail longer than the header's "
"file_size (/proc/<pid>/mem exports always overrun; a file shorter "
"than its own file_size is still rejected)")
args = ap.parse_args(argv)
files = collect_files(args.path)
if not files:
print("no .dex files found in the given path(s)", file=sys.stderr)
return 1
profiles = [profile_dex(f, args.find, args.trim) for f in files]
valid = [p for p in profiles if "error" not in p]
ranking = sorted(valid, key=rank_key)
if args.json:
print(json.dumps({"profiles": profiles,
"ranking": [p["name"] for p in ranking]}, indent=2))
return 0 if valid else 1
# ---- human-readable report -------------------------------------------------
print("== dex dump validation: %d file(s), %d parse, %d rejected =="
% (len(profiles), len(valid), len(profiles) - len(valid)))
fmt = "%-28s %9s %-12s %3s %-7s %-7s %6s %5s %6s %7s"
print(fmt % ("name", "size", "sha256[:12]", "ver", "cksum", "sig",
"class", "noco", "code", "stub%"))
for p in profiles:
if "error" in p:
print("%-28s %9s %-12s %3s REJECTED: %s"
% (p["name"], p["size"], p["sha256"][:12],
p.get("version", "?"), p["error"]))
continue
print(fmt % (p["name"], p["size"], p["sha256"][:12], p["version"],
"ok" if p["checksum_ok"] else "BAD",
"ok" if p["signature_ok"] else "BAD",
p["classes"], p["methods_no_code"], p["methods_with_code"],
"%.1f%%" % (100.0 * p["trivial_ratio"])))
if p.get("trimmed_from"):
print("%-28s trimmed %d -> %d B (page-aligned dump)"
% ("", p["trimmed_from"], p["trimmed_to"]))
if p.get("walk_error"):
print("%-28s walk stopped early: %s" % ("", p["walk_error"]))
for pat, n in sorted(p.get("find_hits", {}).items()):
print("%-28s find %-24s %d" % ("", pat, n))
groups = {}
for p in valid:
groups.setdefault(p["sha256"], []).append(p["name"])
dup_groups = {h: n for h, n in groups.items() if len(n) > 1}
print("\ndedupe: %d unique image(s) among %d valid file(s)"
% (len(groups), len(valid)))
for h, names in sorted(dup_groups.items()):
print(" %s %s" % (h[:16], ", ".join(names)))
if ranking:
print("\nranking (most likely original first):")
for i, p in enumerate(ranking, 1):
note = ""
if p["trivial_ratio"] >= 0.5:
note = " <-- SKELETON: stub%%=%.0f, extraction-shell shape" \
% (100.0 * p["trivial_ratio"])
print(" %d. %-28s stub%%=%.1f cksum=%s sig=%s classes=%d%s"
% (i, p["name"], 100.0 * p["trivial_ratio"],
"ok" if p["checksum_ok"] else "BAD",
"ok" if p["signature_ok"] else "BAD",
p["classes"], note))
top = ranking[0]
copies = len(groups.get(top["sha256"], []))
print("\nverdict: %s is the most likely original (%d copy(ies) in this set)"
% (top["name"], copies))
else:
print("\nverdict: no image parsed as a dex -- nothing to rank")
return 0 if valid else 1
if __name__ == "__main__":
sys.exit(main())
+231
View File
@@ -0,0 +1,231 @@
#!/usr/bin/env python3
"""Scan memory captures for embedded dex images and optionally extract them.
A packer can keep a decrypted dex in a buffer that never appears in
`/proc/<pid>/maps` under a dex-looking name -- it sits inside an anonymous rw-p
mapping. Neither `maps` analysis nor a per-mapping dump finds that on its own;
searching the bytes for the dex magic does. This script does the search and, with
`--dump`, writes each hit out at the size its own header declares.
Typical use, after taking raw regions from a live process (root required):
adb shell 'su -c "cat /proc/<pid>/mem"' ... # or per-region dd exports
python skills/apk-reverse/scripts/dex_mem_scan.py region_dir/ --dump out/
Feeding the extracted images to `dex_dump_validate.py` is the next step: this
script only *finds* and *cuts*; that one judges whether what came out is a real
body or an extraction-shell skeleton.
Scope note: the header's `file_size` field decides the cut. When the declared size
does not fit inside the capture, the hit is reported and skipped rather than
guessed at -- a dex whose tail is missing is not recoverable by truncating the
wrong end.
"""
import argparse
import hashlib
import json
import os
import struct
import sys
MAGIC = b"dex\n0"
HEADER_SIZE = 112
OVERLAP = 0x80 # enough to complete a header straddling two chunks
def valid_version(four_bytes):
"""`dex\\n0XY` -> 'XY' when both digits are decimal, else None."""
ver = four_bytes[4:7]
if len(ver) != 3 or not (ver[0:1].isdigit() and ver[1:2].isdigit()
and ver[2:3].isdigit()):
return None
return ver.decode("ascii")
def find_offsets(path, chunk_size):
"""Yield (absolute offset, buffer, index in buffer, buffer base) for each magic.
Chunks overlap by OVERLAP bytes so a header straddling a chunk boundary is
still seen whole; the caller dedupes repeated offsets.
"""
size = os.path.getsize(path)
carry = b""
pos = 0
with open(path, "rb") as fh:
while pos < size:
fh.seek(pos)
buf = carry + fh.read(chunk_size)
base = pos - len(carry)
start = 0
while True:
i = buf.find(MAGIC, start)
if i < 0:
break
start = i + 1
yield base + i, buf, i, base
if len(buf) <= OVERLAP:
break
carry = buf[-OVERLAP:]
pos += len(buf) - len(carry)
def read_header(fh, offset):
"""Return (file_size, class_defs_size, link_size) or None if the header is short."""
fh.seek(offset)
head = fh.read(HEADER_SIZE)
if len(head) < HEADER_SIZE:
return None
if head[:4] != b"dex\n"[:4]:
return None
file_size = struct.unpack_from("<I", head, 32)[0]
class_defs_size = struct.unpack_from("<I", head, 96)[0]
link_size = struct.unpack_from("<I", head, 104)[0]
return file_size, class_defs_size, link_size
def scan_file(path, chunk_size, min_size, do_dump, dump_dir, keep_partial):
"""Scan one capture; return (records, extracted_count, skipped_count)."""
records = []
extracted = 0
skipped = 0
seen = set()
size = os.path.getsize(path)
with open(path, "rb") as fh:
for offset, buf, i, base in find_offsets(path, chunk_size):
ver = valid_version(buf[i:i + 8]) if i + 8 <= len(buf) else None
if ver is None:
continue
if offset in seen:
continue
seen.add(offset)
head = read_header(fh, offset)
if head is None:
continue
file_size, class_defs_size, link_size = head
if file_size < 112 or file_size > (1 << 32):
continue
fits = file_size <= (size - offset)
rec = {
"capture": os.path.basename(path),
"offset": offset,
"version": ver,
"file_size": file_size,
"class_defs_size": class_defs_size,
"link_size": link_size,
"fits": fits,
}
if fits and file_size >= min_size:
takes = file_size
elif keep_partial and not fits:
takes = size - offset
rec["partial"] = takes
else:
rec["skipped"] = ("declared %d B, %d B available"
% (file_size, size - offset))
skipped += 1
records.append(rec)
continue
fh.seek(offset)
blob = fh.read(takes)
rec["sha256"] = hashlib.sha256(blob).hexdigest()
if do_dump:
stem = os.path.splitext(os.path.basename(path))[0]
name = "%s+0x%08x.dex" % (stem, offset)
out = os.path.join(dump_dir, name)
with open(out, "wb") as ofh:
ofh.write(blob)
rec["written"] = out
extracted += 1
records.append(rec)
return records, extracted, skipped
def collect_targets(paths):
targets = []
for p in paths:
if os.path.isdir(p):
for name in sorted(os.listdir(p)):
full = os.path.join(p, name)
if os.path.isfile(full) and not name.endswith((".txt", ".json", ".md")):
targets.append(full)
else:
targets.append(p)
return targets
def main(argv=None):
ap = argparse.ArgumentParser(
description="Scan memory captures (or any blob) for embedded dex images "
"'dex\\n03x', report each hit, and optionally extract them at "
"the size their own headers declare. Pair with "
"dex_dump_validate.py, which judges what was extracted.")
ap.add_argument("path", nargs="+",
help="a capture file, or a directory of region exports")
ap.add_argument("--dump", metavar="DIR",
help="write each hit into DIR as <capture>+0x<offset>.dex")
ap.add_argument("--json", action="store_true",
help="emit the record list as JSON")
ap.add_argument("--chunk-size", type=int, default=64 << 20, metavar="N",
help="read the capture in N-byte chunks (default 64 MiB); use a "
"smaller value for very large captures")
ap.add_argument("--min-size", type=int, default=4096, metavar="N",
help="ignore hits whose declared file_size is below N bytes "
"(default 4096) -- stray magics in unrelated data")
ap.add_argument("--keep-partial", action="store_true",
help="also write hits whose declared size runs past the end of "
"the capture (truncated region); the result is NOT a dex")
args = ap.parse_args(argv)
targets = collect_targets(args.path)
if not targets:
print("no capture files found in the given path(s)", file=sys.stderr)
return 1
dump_dir = None
if args.dump:
dump_dir = os.path.abspath(args.dump)
os.makedirs(dump_dir, exist_ok=True)
all_records = []
total_extracted = 0
total_skipped = 0
for t in targets:
records, extracted, skipped = scan_file(
t, args.chunk_size, args.min_size,
dump_dir is not None, dump_dir or ".", args.keep_partial)
all_records.extend(records)
total_extracted += extracted
total_skipped += skipped
if args.json:
print(json.dumps({"records": all_records,
"extracted": total_extracted,
"skipped": total_skipped}, indent=2))
return 0 if all_records else 1
print("== dex memory scan: %d capture(s), %d hit(s) =="
% (len(targets), len(all_records)))
fmt = "%-34s %12s %3s %12s %10s %-6s"
print(fmt % ("capture", "offset", "ver", "file_size", "classes", "state"))
for r in all_records:
state = "ok" if r.get("fits") and not r.get("partial") else (
"partial" if r.get("partial") else "skipped")
print(fmt % (r["capture"][:34], "0x%x" % r["offset"], r["version"],
r["file_size"], r["class_defs_size"], state))
if r.get("written"):
print("%-34s wrote %s" % ("", r["written"]))
if r.get("skipped"):
print("%-34s skipped: %s" % ("", r["skipped"]))
unique = {r["sha256"] for r in all_records if r.get("sha256")}
print("\n%d hit(s) with a complete declared size, %d unique by sha256, "
"%d skipped" % (total_extracted, len(unique), total_skipped))
if total_extracted:
print("next: python dex_dump_validate.py %s" % (dump_dir or "<dump dir>"))
return 0 if all_records else 1
if __name__ == "__main__":
sys.exit(main())
@@ -0,0 +1,424 @@
#!/usr/bin/env python3
"""Bridge a Frida script's rpc.exports to local Python, a REPL, or a tiny HTTP endpoint.
Given a device, a target process and a Frida script that defines `rpc.exports`,
this tool keeps a long-lived session alive (with automatic reconnect) and lets
you invoke those exports three ways:
--mode call one shot: --export add --args '[1, 2]' -> prints the result, exits
--mode repl interactive: `list`, `name [json-args]`, `reload`, `quit`
--mode http POST /call {"export": "add", "args": [1, 2]} -> JSON result;
GET /exports lists them; POST /reload re-creates the script
The typical use is running a hardened target's own crypto (the function the
shell or SDK uses to sign/encrypt) as if it were a local function: spawn or
attach, keep the session resident, and call it from automation instead of from
a hand-driven `frida -l` session. See references/emulation-and-rpc.md for when
this beats emulating the .so offline (unidbg) and when it does not.
Reconnect policy: a detached session (app restart, server death, ROM killing
the server — see references/dynamic-frida.md) marks the bridge dead; the next
call re-attaches (re-spawning first if --spawn was given), reloads the script
and retries, with exponential backoff up to --retries times.
Device selection follows the skill's rule of explicitness: --device-serial
picks that exact USB device; --remote HOST:PORT attaches through an explicit
`adb forward` (preferred when several devices/emulators are attached); with
neither, frida's default USB device is used.
Examples:
python frida_rpc_serve.py --device-serial SSBY... --package com.example.app \
--script rpc_template.js --mode call --export add --args '[1, 2]'
python frida_rpc_serve.py --remote 127.0.0.1:27042 --package com.example.app \
--script rpc_template.js --mode repl
python frida_rpc_serve.py --device-serial SSBY... --spawn --package com.example.app \
--script rpc_template.js --mode http --port 8765
"""
import argparse
import http.server
import json
import sys
import threading
import time
try:
import frida
except ImportError: # pragma: no cover
sys.stderr.write("frida is required: pip install frida (host package must match the device server)\n")
sys.exit(2)
# Device-side failures worth retrying: a target that is still starting, a server
# that was reaped, a process that vanished. frida.TimedOutError is *not* a
# TransportError subclass (measured on frida 16.7.19: attaching to a busy app
# raised TimedOutError and escaped every handler), so collect them by name.
RETRYABLE = tuple(
getattr(frida, name)
for name in ("TransportError", "NotSupportedError", "ServerNotRunningError",
"ProcessNotFoundError", "InvalidOperationError", "TimedOutError")
if hasattr(frida, name)
)
class BridgeError(Exception):
pass
class RpcBridge:
"""Owns device -> session -> script and re-establishes them when detached."""
def __init__(self, opts):
self.opts = opts
self.device = None
self.session = None
self.script = None
self.exports = None
self.spawned_pid = None
self.alive = False
self.attempt = 0
self._lock = threading.Lock()
# -- connection lifecycle ------------------------------------------------
def _get_device(self):
if self.opts.remote:
return frida.get_device_manager().add_remote_device(self.opts.remote)
if self.opts.device_serial:
return frida.get_device(self.opts.device_serial)
return frida.get_usb_device()
def _attach_or_spawn(self, device):
if self.opts.spawn:
if not self.opts.package:
raise BridgeError("--spawn requires --package")
pid = device.spawn([self.opts.package])
self.spawned_pid = pid
return device.attach(pid)
if self.opts.pid is not None:
return device.attach(self.opts.pid)
if self.opts.package:
# attach-by-name can fail while the process list is incomplete
# (references/dynamic-frida.md); the caller may fall back to --pid.
return device.attach(self.opts.package)
raise BridgeError("need one of --package / --pid")
def connect(self):
"""Establish device, session and script. Raises on failure."""
with self._lock:
self._teardown()
if self.opts.remote:
# A cached remote device may hold the dead socket of a server
# that was killed and restarted; drop it so we reconnect fresh.
try:
frida.get_device_manager().remove_remote_device(self.opts.remote)
except Exception:
pass
device = self._get_device()
session = self._attach_or_spawn(device)
session.on("detached", self._on_detached)
with open(self.opts.script, "r", encoding="utf-8") as fh:
code = fh.read()
script = session.create_script(code, runtime=self.opts.runtime)
script.on("message", self._on_message)
script.load()
# Resume only after the script has loaded: resuming earlier loses
# the first hook window (references/dynamic-frida.md).
if self.spawned_pid is not None:
device.resume(self.spawned_pid)
self.device, self.session, self.script = device, session, script
# frida >= 16 prefers exports_sync; older builds expose exports.
self.exports = getattr(script, "exports_sync", None) or script.exports
self.alive = True
self.attempt = 0
def _teardown(self):
script, session = self.script, self.session
self.script = self.session = self.exports = None
self.spawned_pid = None
self.alive = False
# Unload the script *and* detach the session; without the detach every
# reload/retry cycle leaks one attached session on the device.
if script is not None:
try:
script.unload()
except Exception:
pass
if session is not None:
try:
session.off("detached", self._on_detached)
except Exception:
pass
try:
session.detach()
except Exception:
pass
def _on_detached(self, reason, *rest):
self.alive = False
sys.stderr.write("[bridge] session detached: %s %s\n" % (reason, rest or ""))
def _on_message(self, message, data):
if message.get("type") == "error":
sys.stderr.write("[script-error] %s\n" % message.get("description"))
if message.get("stack"):
sys.stderr.write(message["stack"])
else:
sys.stderr.write("[script] %s\n" % json.dumps(message, ensure_ascii=False, default=str))
def ensure(self):
"""Connect if needed; retry with backoff while the target is reachable.
Each ensure() call is its own retry cycle: a failed cycle does not
poison the next request (the device may come back seconds later).
"""
if self.alive:
return
self.attempt = 0
while True:
self.attempt += 1
if self.attempt > self.opts.retries:
raise BridgeError(
"could not (re)connect after %d attempts" % self.opts.retries)
try:
self.connect()
return
except RETRYABLE + (BridgeError, OSError) as exc:
wait = min(self.opts.backoff * (2 ** (self.attempt - 1)), 15.0)
sys.stderr.write("[bridge] connect failed (%s); retry %d in %.1fs\n"
% (exc, self.attempt, wait))
time.sleep(wait)
# -- the RPC surface -----------------------------------------------------
def call(self, name, args):
self.ensure()
# frida's export proxy fails from deep inside the transport with its own
# "unable to find method 'x'" wording; consult the advertised list first
# so the caller gets the actionable message.
try:
available = self.list_exports()
except Exception:
available = None
if available is not None and name not in available:
raise BridgeError("no such rpc export: %s (available: %s)"
% (name, " ".join(available)))
fn = getattr(self.exports, name, None)
if fn is None:
raise BridgeError("no such rpc export: %s (try `list`)" % name)
try:
return fn(*args)
except (frida.InvalidOperationError, frida.TransportError):
# Session died mid-call: one transparent reconnect + retry.
self.alive = False
self.ensure()
fn = getattr(self.exports, name, None)
if fn is None:
raise BridgeError("export disappeared after reconnect: %s" % name)
return fn(*args)
def list_exports(self):
self.ensure()
# frida 16.7 deprecates Script.list_exports() in favour of
# list_exports_sync(); try the new name first so the bridge stays
# quiet on current hosts and keeps working when the old one goes.
for attr in ("list_exports_sync", "list_exports"):
fn = getattr(self.script, attr, None)
if fn is None:
continue
try:
return fn()
except Exception:
pass
return sorted(k for k in dir(self.exports) if not k.startswith("_"))
def reload(self):
with self._lock:
self._teardown()
self.ensure()
# -- mode: one-shot call ------------------------------------------------------
def run_call_mode(bridge, opts):
# One-shot mode is meant to be scripted: report every failure as one JSON
# object plus a non-zero exit code instead of a Python traceback.
try:
args = json.loads(opts.args) if opts.args else []
except ValueError as exc:
print(json.dumps({"ok": False, "error": "--args is not valid JSON: %s" % exc},
ensure_ascii=False))
return 1
if not isinstance(args, list):
print(json.dumps({"ok": False, "error": "--args must be a JSON array"},
ensure_ascii=False))
return 1
try:
result = bridge.call(opts.export, args)
except BridgeError as exc:
print(json.dumps({"ok": False, "export": opts.export, "error": str(exc)},
ensure_ascii=False))
return 1
except Exception as exc: # a JS-side throw arrives as frida.core.RPCException
print(json.dumps({"ok": False, "export": opts.export,
"error": "%s: %s" % (type(exc).__name__, exc)},
ensure_ascii=False))
return 1
print(json.dumps({"ok": True, "export": opts.export, "result": result},
ensure_ascii=False, default=str))
return 0
# -- mode: REPL ---------------------------------------------------------------
def run_repl_mode(bridge, opts):
print("connected; exports are callable by name. commands: list | name [json-args] | reload | quit")
while True:
try:
line = input("rpc> ").strip()
except (EOFError, KeyboardInterrupt):
print()
return 0
if not line:
continue
if line in ("quit", "exit", "q"):
return 0
if line == "list":
try:
print(" ".join(bridge.list_exports()))
except BridgeError as exc:
print("error: %s" % exc)
continue
if line == "reload":
try:
bridge.reload()
print("reloaded")
except BridgeError as exc:
print("error: %s" % exc)
continue
parts = line.split(None, 1)
name = parts[0]
args = json.loads(parts[1]) if len(parts) > 1 and parts[1].strip() else []
if not isinstance(args, list):
print("args must be a JSON array")
continue
try:
result = bridge.call(name, args)
print(json.dumps(result, ensure_ascii=False, default=str))
except BridgeError as exc:
print("error: %s" % exc)
except Exception as exc: # JS-side throw arrives here as frida.core.RPCException
print("js-error: %s" % exc)
# -- mode: HTTP ---------------------------------------------------------------
def run_http_mode(bridge, opts):
class Handler(http.server.BaseHTTPRequestHandler):
def _send(self, code, payload):
body = json.dumps(payload, ensure_ascii=False, default=str).encode("utf-8")
self.send_response(code)
self.send_header("Content-Type", "application/json; charset=utf-8")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def do_GET(self):
if self.path == "/exports":
try:
self._send(200, {"ok": True, "exports": bridge.list_exports()})
except BridgeError as exc:
self._send(502, {"ok": False, "error": str(exc)})
else:
self._send(404, {"ok": False, "error": "GET /exports only"})
def do_POST(self):
if self.path == "/reload":
try:
bridge.reload()
self._send(200, {"ok": True})
except BridgeError as exc:
self._send(502, {"ok": False, "error": str(exc)})
return
if self.path != "/call":
self._send(404, {"ok": False, "error": "POST /call or /reload"})
return
try:
length = int(self.headers.get("Content-Length") or 0)
req = json.loads(self.rfile.read(length).decode("utf-8"))
name = req.get("export")
args = req.get("args", [])
if not name or not isinstance(args, list):
raise ValueError('body must be {"export": "name", "args": [...]}')
result = bridge.call(name, args)
self._send(200, {"ok": True, "result": result})
except BridgeError as exc:
self._send(502, {"ok": False, "error": str(exc)})
except Exception as exc:
self._send(400, {"ok": False, "error": str(exc)})
def log_message(self, fmt, *args):
sys.stderr.write("[http] " + (fmt % args) + "\n")
server = http.server.ThreadingHTTPServer((opts.host, opts.port), Handler)
print("listening on http://%s:%d (POST /call, GET /exports, POST /reload)"
% (opts.host, opts.port))
try:
server.serve_forever()
except KeyboardInterrupt:
pass
finally:
server.server_close()
return 0
def main(argv=None):
parser = argparse.ArgumentParser(
description="Bridge a Frida script's rpc.exports to Python/REPL/HTTP with auto-reconnect.",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=__doc__.split("Examples:")[-1].strip() if __doc__ else None,
)
parser.add_argument("--script", required=True, help="path to the .js defining rpc.exports")
parser.add_argument("--package", help="target package (attach by name, or spawn with --spawn)")
parser.add_argument("--pid", type=int, help="target pid (use when attach-by-name fails)")
parser.add_argument("--device-serial", help="explicit USB device serial (see adb devices -l)")
parser.add_argument("--remote", metavar="HOST:PORT",
help="explicit remote frida via adb forward, e.g. 127.0.0.1:27042")
parser.add_argument("--spawn", action="store_true",
help="spawn the package instead of attaching (catches startup)")
parser.add_argument("--mode", choices=("call", "repl", "http"), default="repl")
parser.add_argument("--export", help="export name (call mode)")
parser.add_argument("--args", help="JSON array of arguments (call mode)")
parser.add_argument("--host", default="127.0.0.1", help="HTTP bind host (http mode)")
parser.add_argument("--port", type=int, default=8765, help="HTTP bind port (http mode)")
parser.add_argument("--runtime", default="v8", choices=("v8", "qjs"),
help="script runtime (v8 carries the Java bridge)")
parser.add_argument("--retries", type=int, default=5, help="reconnect attempts before giving up")
parser.add_argument("--backoff", type=float, default=1.0,
help="first reconnect delay (seconds); doubles per attempt")
opts = parser.parse_args(argv)
if opts.mode == "call" and not opts.export:
parser.error("--mode call requires --export")
bridge = RpcBridge(opts)
try:
bridge.ensure()
except RETRYABLE + (BridgeError, OSError) as exc:
sys.stderr.write("initial connect failed: %s\n" % exc)
return 2
if opts.mode == "call":
return run_call_mode(bridge, opts)
if opts.mode == "http":
return run_http_mode(bridge, opts)
return run_repl_mode(bridge, opts)
if __name__ == "__main__":
sys.exit(main())
@@ -0,0 +1,438 @@
#!/usr/bin/env python3
"""Scaffold a minimal LSPosed module project that builds without Gradle.
Why this exists
---------------
Repackaging a hardened APK is not always the right route. When the app is
integrity-checked, signature-derived, or simply cheaper to hook than to rebuild,
the deliverable becomes a *module* instead of a patched APK, and the first
obstacle is that every tutorial assumes Android Studio. This script writes the
smallest project that a plain ``javac`` + ``d8`` + ``aapt2`` + ``apksigner``
chain can turn into an installable module, and the README it writes contains
that exact chain.
What it writes
--------------
<out>/AndroidManifest.xml the three xposed meta-data keys LSPosed reads
<out>/assets/xposed_init one line: the fully qualified entry class
<out>/src/<pkg path>/<Class>.java the entry class (IXposedHookLoadPackage)
<out>/README.md build, install, enable, verify, failure modes
The generated hook does two things on purpose, because both are diagnostics
before they are features: it logs on every load of a scoped process (so
"is the module injected at all" is answerable from logcat alone), and it hooks
``Application.attach`` / ``Activity.onCreate`` (so the log names the real
Activity classes even when a packer swaps the Application at runtime).
Note on scope: LSPosed decides *which* processes to inject into from the scope
list in its own configuration, not from anything this project declares. A
generated ``TARGETS`` array is a second gate inside the module and must not be
mistaken for the scope.
Usage
-----
lsposed_scaffold.py --package com.example.probe --name "Example probe" \\
--hook-target com.example.target --out ./module
Requirements: python3 only. No third-party imports, no network.
"""
import argparse
import os
import re
import sys
MANIFEST_TMPL = """<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="__PACKAGE__">
<uses-sdk android:minSdkVersion="__MINSDK__" android:targetSdkVersion="__TARGETSDK__" />
<application android:label="__NAME__" android:hasCode="true">
<!-- These three keys are what LSPosed Manager reads. Without
xposedmodule=true the APK installs as an ordinary app and never
appears in the module list at all. xposedminversion=82 is the
classic XposedBridge API level and is accepted by LSPosed. -->
<meta-data android:name="xposedmodule" android:value="true" />
<meta-data android:name="xposeddescription" android:value="__DESC__" />
<meta-data android:name="xposedminversion" android:value="82" />
</application>
</manifest>
"""
JAVA_TMPL = """package __PACKAGE__;
import android.app.Activity;
import android.app.Application;
import android.content.Context;
import android.os.Bundle;
import de.robv.android.xposed.IXposedHookLoadPackage;
import de.robv.android.xposed.XC_MethodHook;
import de.robv.android.xposed.XposedBridge;
import de.robv.android.xposed.XposedHelpers;
import de.robv.android.xposed.callbacks.XC_LoadPackage;
/**
* Entry class named by assets/xposed_init.
*
* Logcat is the evidence channel: LSPosed pushes XposedBridge.log() into the
* system log, so `adb logcat -s __TAG__` answers "did this module get injected"
* without attaching a debugger.
*/
public class __CLASS__ implements IXposedHookLoadPackage {
/** Short enough to stay readable in logcat. */
private static final String TAG = "__TAG__";
/**
* In-module gate, NOT the LSPosed scope. LSPosed already decides which
* processes receive handleLoadPackage; this array only keeps the hook body
* from acting on unintended processes if the scope is widened later.
*/
private static final String[] TARGETS = new String[] { __TARGETS__ };
private static boolean isTarget(String pkg) {
for (String t : TARGETS) {
if (t.equals(pkg)) {
return true;
}
}
return false;
}
@Override
public void handleLoadPackage(final XC_LoadPackage.LoadPackageParam lpp) throws Throwable {
// Fires once per scoped process, before any of the app's own code runs.
// This single line is the injection proof: if it is absent for a
// process you scoped, the problem is scope/enable state or the target
// process was never restarted, not your hook body.
try {
XposedBridge.log(TAG + " injected: " + lpp.packageName
+ "/" + lpp.processName + " cl=" + shortCl(lpp.classLoader));
} catch (Throwable t) {
XposedBridge.log(t);
}
if (!isTarget(lpp.packageName)) {
return;
}
// 1) Application.attach(Context) runs before the app's onCreate. Under a
// packer thisObject is the stub Application, not the manifest name.
try {
XposedHelpers.findAndHookMethod(Application.class, "attach", Context.class,
new XC_MethodHook() {
@Override
protected void afterHookedMethod(MethodHookParam param) throws Throwable {
XposedBridge.log(TAG + " Application.attach -> "
+ safeClass(param.thisObject));
}
});
XposedBridge.log(TAG + " hook installed: Application.attach");
} catch (Throwable t) {
XposedBridge.log(TAG + " attach-hook FAILED: " + t);
}
// 2) Activity lifecycle. Boot-classloader targets, so these install even
// when the app's own classes are not yet resolvable.
try {
XposedHelpers.findAndHookMethod(Activity.class, "onCreate", Bundle.class,
new XC_MethodHook() {
@Override
protected void afterHookedMethod(MethodHookParam param) throws Throwable {
XposedBridge.log(TAG + " Activity.onCreate -> "
+ safeClass(param.thisObject));
}
});
XposedBridge.log(TAG + " hook installed: Activity.onCreate");
} catch (Throwable t) {
XposedBridge.log(TAG + " activity-hook FAILED: " + t);
}
__HOOK_BLOCK__
}
private static String safeClass(Object o) {
try {
return o == null ? "null" : o.getClass().getName();
} catch (Throwable t) {
return "<class-name-threw " + t.getClass().getSimpleName() + ">";
}
}
private static String shortCl(ClassLoader cl) {
try {
if (cl == null) {
return "null";
}
return cl.getClass().getName() + "@"
+ Integer.toHexString(System.identityHashCode(cl));
} catch (Throwable t) {
return "<cl-threw>";
}
}
}
"""
HOOK_BLOCK_TMPL = """
// 3) Replace this with the method you actually care about. Find it at
// runtime first (enumerate loaded classes / read a stack) rather than
// guessing an obfuscated name from a decompiler.
try {
XposedHelpers.findAndHookMethod("__HOOKCLASS__", lpp.classLoader,
"__HOOKMETHOD__", __PARAMTYPES__,
new XC_MethodHook() {
@Override
protected void beforeHookedMethod(MethodHookParam param) throws Throwable {
XposedBridge.log(TAG + " __HOOKCLASS__.__HOOKMETHOD__ entered");
}
});
XposedBridge.log(TAG + " hook installed: __HOOKCLASS__.__HOOKMETHOD__");
} catch (Throwable t) {
XposedBridge.log(TAG + " target-hook FAILED: " + t);
}
"""
README_TMPL = """# __NAME__
Minimal LSPosed module generated by `lsposed_scaffold.py`.
- module package: `__PACKAGE__`
- entry class: `__PACKAGE__.__CLASS__` (named in `assets/xposed_init`)
- in-module target gate: __TARGETLIST__
- minSdk __MINSDK__ / targetSdk __TARGETSDK__
The LSPosed *scope* is separate from the target gate above: scope is configured
in LSPosed Manager, and a module is injected into a process only when the scope
contains that package **and** the module is enabled.
## Build without Gradle
You need a JDK (17 works), Android build-tools, an `android.jar` for the SDK you
declare, and the Xposed API stub jar (`de.robv.android.xposed:api:82`, about
25 KB). Set the three variables, then run the steps in order. There is no
resource to compile; the module ships only a manifest, assets and a dex.
```sh
BT=/path/to/build-tools/34.0.0
AJ=/path/to/android.jar # e.g. platforms/android-28/android.jar
API=/path/to/api-82.jar
OUT=build
# 1. Java -> class files. -source/-target 8 keeps d8 happy; Android API classes
# come from -cp, not from the JDK. (`-bootclasspath` is gone in JDK 9+.)
javac -encoding UTF-8 -source 8 -target 8 -nowarn \\
-cp "$AJ:$API" -d "$OUT/classes" src/__PATH__/__CLASS__.java
# 2. d8 wants a jar, NOT a directory -- a directory dies with
# "Unsupported source file type".
jar cf "$OUT/classes.jar" -C "$OUT/classes" .
"$BT/d8" --min-api __MINSDK__ --lib "$AJ" --output "$OUT" "$OUT/classes.jar"
# 3. manifest + assets -> base apk (no res/ in this project)
"$BT/aapt2" link -o "$OUT/base.apk" -I "$AJ" \\
--manifest AndroidManifest.xml \\
--min-sdk-version __MINSDK__ --target-sdk-version __TARGETSDK__ \\
-A assets
# 4. add the dex. aapt resolves the path relative to the cwd and stores the same
# name, so run it from $OUT with classes.dex sitting there.
cp "$OUT/base.apk" "$OUT/unsigned.apk"
cp "$OUT/classes.dex" "$OUT/classes.dex.tmp" && mv "$OUT/classes.dex.tmp" "$OUT/classes.dex"
(cd "$OUT" && "$BT/aapt" add unsigned.apk classes.dex)
# 5. align, then sign (v2 is enough for Android 7+)
"$BT/zipalign" -f -p 4 "$OUT/unsigned.apk" "$OUT/aligned.apk"
keytool -genkeypair -keystore "$OUT/test.keystore" -alias mod -keyalg RSA \\
-keysize 2048 -validity 10000 -storepass android -keypass android \\
-dname "CN=module, O=local"
"$BT/apksigner" sign --ks "$OUT/test.keystore" --ks-pass pass:android \\
--key-pass pass:android --v2-signing-enabled true \\
--out "$OUT/module.apk" "$OUT/aligned.apk"
"$BT/apksigner" verify --print-certs "$OUT/module.apk"
```
Windows: same steps; `d8`, `apksigner` and `aapt` ship as `.bat` wrappers, and
the classpath separator is `;`. Note that `jar` and `keytool` are frequently
**not** on `PATH` even when `javac` is (Oracle's `javapath` shim exposes only
`java`/`javac`), so call them from the JDK's `bin` directory explicitly.
## Install, enable, verify
```sh
adb install -r build/module.apk
adb shell pm list packages | grep __PACKAGE__ # installed
adb shell dumpsys package __PACKAGE__ | grep enabled # enabled=0 means DISABLED by the PM
adb shell pm enable __PACKAGE__ # only if it shows enabled=0
```
`pm enable` is about the *package manager* state; it is not the LSPosed module
switch. Then, in LSPosed Manager: open the module list, enable the module, and
tick the scope entry for the target package.
Verification has two channels. Use the platform log where it works, and always the module log:
```sh
adb -s <serial> shell "su -c 'cat /data/adb/lspd/log/modules_<timestamp>.log'" # module log
adb -s <serial> logcat -s __TAG__ # platform log
```
Expected first line in either: `__TAG__ injected: <target>/<process> ...`. The platform log can be
**completely empty** on a device whose `logd` route is broken (a log file that opens with
`Logd maybe crashed (err=Socket operation on non-socket)` is the tell); the module log is written
either way, so check it before concluding the module never ran. No line in either channel means the
module was not injected into that process. Check, in this order: module
enabled in LSPosed Manager, package present in scope, module APK still installed,
and **the target process restarted after the scope change** -- scope changes are
read for newly forked processes, so a running process keeps the old decision.
## Failure modes worth knowing
- `d8` on a directory: `Unsupported source file type`. Jar the classes first.
- `aapt add` says the file is missing: it resolves relative to the cwd and keeps
the given name, so `classes.dex` must exist in the directory you run it from.
- Module never appears in LSPosed Manager: the `xposedmodule` meta-data is
missing or mistyped in the merged manifest.
- Module listed but injection logs never appear: enabled state, scope, or a stale
target process -- in that order.
- Module injected but your `TARGETS` array skips everything: that is the in-module
gate, not LSPosed. Read the gate before blaming the framework.
"""
def build_parser():
p = argparse.ArgumentParser(
prog="lsposed_scaffold.py",
description="Write a minimal, Gradle-free LSPosed module project "
"(manifest, xposed_init, entry class, build README).",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="Example:\n"
" lsposed_scaffold.py --package com.example.probe \\\n"
" --name \"Example probe\" --hook-target com.example.target \\\n"
" --hook-class com.example.target.Helper --hook-method check \\\n"
" --out ./module\n")
p.add_argument("--package", required=True,
help="module package name, e.g. com.example.probe")
p.add_argument("--name", required=True,
help="human-readable module name shown in LSPosed Manager")
p.add_argument("--hook-target", action="append", default=None, dest="targets",
help="package the module acts on; repeat for several. "
"This is the in-module gate, not the LSPosed scope")
p.add_argument("--out", required=True, help="output project directory")
p.add_argument("--class-name", default="MainHook",
help="entry class name (default %(default)s)")
p.add_argument("--tag", default=None,
help="logcat tag; default derived from --class-name (max 20 chars)")
p.add_argument("--description", default="Hook module generated by lsposed_scaffold.py",
help="value of xposeddescription")
p.add_argument("--min-sdk", type=int, default=24, help="minSdkVersion (default %(default)s)")
p.add_argument("--target-sdk", type=int, default=28, help="targetSdkVersion (default %(default)s)")
p.add_argument("--hook-class", default=None,
help="optional concrete class to hook (adds a worked example block)")
p.add_argument("--hook-method", default=None,
help="method name to hook (requires --hook-class)")
p.add_argument("--hook-params", default="",
help="comma-separated parameter types for --hook-method, "
"e.g. 'java.lang.String,android.content.Context' (default: none)")
p.add_argument("--force", action="store_true",
help="overwrite files that already exist in --out")
return p
PKG_RE = re.compile(r'^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$')
CLASS_RE = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*$')
def fail(msg):
print("[!] %s" % msg, file=sys.stderr)
return 2
def write_file(path, text, force):
if os.path.exists(path) and not force:
print("[=] exists, left alone: %s" % path)
return False
d = os.path.dirname(path)
if d:
os.makedirs(d, exist_ok=True)
# newline="\n" so a scaffold written on Windows still builds on POSIX
with open(path, 'w', encoding='utf-8', newline='\n') as fh:
fh.write(text)
print("[+] %s" % path)
return True
def params_java(spec):
"""'java.lang.String,android.content.Context' -> 'java.lang.String.class,
android.content.Context.class'."""
parts = [x.strip() for x in spec.split(',') if x.strip()]
if not parts:
return ''
return ', '.join('%s.class' % x for x in parts)
def main(argv=None):
args = build_parser().parse_args(argv)
if not PKG_RE.match(args.package):
return fail("--package %r is not a valid Java package name" % args.package)
if not CLASS_RE.match(args.class_name):
return fail("--class-name %r is not a valid Java identifier" % args.class_name)
targets = args.targets or ['<target.package>']
for t in targets:
if not PKG_RE.match(t) and t != '<target.package>':
return fail("--hook-target %r is not a valid package name" % t)
if args.hook_method and not args.hook_class:
return fail("--hook-method requires --hook-class")
tag = args.tag or args.class_name.upper()[:20]
hook_block = ''
if args.hook_class and args.hook_method:
hook_block = (HOOK_BLOCK_TMPL
.replace('__HOOKCLASS__', args.hook_class)
.replace('__HOOKMETHOD__', args.hook_method)
.replace('__PARAMTYPES__', params_java(args.hook_params)))
java = (JAVA_TMPL
.replace('__PACKAGE__', args.package)
.replace('__CLASS__', args.class_name)
.replace('__TAG__', tag)
.replace('__TARGETS__', ', '.join('"%s"' % t for t in targets))
.replace('__HOOK_BLOCK__', hook_block))
manifest = (MANIFEST_TMPL
.replace('__PACKAGE__', args.package)
.replace('__NAME__', args.name)
.replace('__DESC__', args.description)
.replace('__MINSDK__', str(args.min_sdk))
.replace('__TARGETSDK__', str(args.target_sdk)))
readme = (README_TMPL
.replace('__NAME__', args.name)
.replace('__PACKAGE__', args.package)
.replace('__CLASS__', args.class_name)
.replace('__TAG__', tag)
.replace('__PATH__', args.package.replace('.', '/'))
.replace('__TARGETLIST__', ', '.join('`%s`' % t for t in targets))
.replace('__MINSDK__', str(args.min_sdk))
.replace('__TARGETSDK__', str(args.target_sdk)))
src = os.path.join(args.out, 'src', args.package.replace('.', os.sep),
'%s.java' % args.class_name)
write_file(os.path.join(args.out, 'AndroidManifest.xml'), manifest, args.force)
write_file(os.path.join(args.out, 'assets', 'xposed_init'),
'%s.%s\n' % (args.package, args.class_name), args.force)
write_file(src, java, args.force)
write_file(os.path.join(args.out, 'README.md'), readme, args.force)
print("")
print("Next: build it with the chain in %s/README.md, then install, enable"
" the module in LSPosed Manager, and add the target to its scope."
% args.out)
print("Do not confuse the scope (LSPosed Manager) with the in-module gate"
" (TARGETS in %s.java)." % args.class_name)
return 0
if __name__ == '__main__':
sys.exit(main())
+225
View File
@@ -0,0 +1,225 @@
#!/usr/bin/env python3
"""Probe the MT Manager built-in APK MCP server (Streamable HTTP).
MT Manager (bin.mt.plus) ships an "APK MCP" service that exposes its APK
analysis/edit/repack/sign capabilities to MCP clients over Streamable HTTP,
by default on device port 8787 (reachable from the PC via
``adb forward tcp:8787 tcp:8787``).
This script does the MCP handshake by hand (JSON-RPC 2.0 over plain HTTP
POSTs, no mcp SDK dependency):
1. ``initialize`` -> serverInfo + capabilities
2. ``notifications/initialized``
3. ``tools/list`` -> tool inventory
Output is a human-readable capability report grouping the ``mt_apk_*`` tools
by category. When the server is not up yet (it must be started by hand in
the MT UI; adb cannot start it), the script prints waiting instructions and
exits 2, so it can also be used as a "is it up yet" check in a loop.
Verification status of the protocol shape: measured against the MT 2.26.9
implementation on 2026-09 (see docs/tool-verification/EXTENSION-kernel-ondevice.md).
"""
import argparse
import json
import sys
import urllib.error
import urllib.request
DEFAULT_URL = "http://127.0.0.1:8787/mcp"
# Tool categories for the report, keyed by name prefix within mt_apk_*.
CATEGORIES = [
("open", "APK open/selection"),
("list", "Entry listing"),
("search", "Text/string search"),
("read", "Content read"),
("dex", "Dex analysis"),
("resource", "Resources"),
("native", "Native (.so) static analysis"),
("edit", "Edit sessions"),
("patch", "Byte/instruction patching"),
("build", "Repack + sign"),
("close", "Cleanup"),
]
def http_post(url, payload, session_id=None, timeout=10.0):
"""POST one JSON-RPC message; return (status, headers, parsed-body-or-None).
Handles both plain application/json responses and text/event-stream
(SSE-framed) responses, which Streamable HTTP servers may use for
request bodies. Returns the first JSON object found in either shape.
"""
body = json.dumps(payload).encode("utf-8")
headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
}
if session_id:
headers["Mcp-Session-Id"] = session_id
req = urllib.request.Request(url, data=body, headers=headers, method="POST")
try:
with urllib.request.urlopen(req, timeout=timeout) as resp:
raw = resp.read().decode("utf-8", "replace")
sid = resp.headers.get("Mcp-Session-Id")
return resp.status, sid, parse_body(raw, resp.headers.get("Content-Type", ""))
except urllib.error.HTTPError as e:
raw = e.read().decode("utf-8", "replace")
return e.code, None, parse_body(raw, e.headers.get("Content-Type", ""))
def parse_body(raw, ctype):
"""Extract the first JSON message from a JSON or SSE-framed body."""
raw = raw.strip()
if not raw:
return None
if "text/event-stream" in (ctype or ""):
for line in raw.splitlines():
if line.startswith("data:"):
chunk = line[len("data:"):].strip()
try:
return json.loads(chunk)
except ValueError:
continue
return None
try:
return json.loads(raw)
except ValueError:
return None
def print_waiting_help(url):
host = "127.0.0.1"
print("[waiting] MCP server is not answering at %s" % url)
print()
print("The MT APK MCP must be started by hand in the MT UI (adb cannot start it):")
print(" 1. On the phone: MT Manager -> side drawer -> Tools -> APK MCP -> Start")
print(" 2. Note the address shown on that page (host:port, default 8787)")
print(" 3. On the PC, make the port reachable over USB:")
print(" adb forward tcp:8787 tcp:8787")
print(" 4. Re-run this probe: python mt_mcp_probe.py")
print()
print("(LAN alternative: connect the PC and phone to the same network and pass")
print(" --url http://<phone-ip>:8787/mcp)")
def main():
ap = argparse.ArgumentParser(
description="Probe the MT Manager APK MCP (Streamable HTTP) and list its tools.")
ap.add_argument("--url", default=DEFAULT_URL,
help="MCP endpoint (default: %(default)s)")
ap.add_argument("--timeout", type=float, default=10.0,
help="per-request timeout in seconds (default: %(default)s)")
ap.add_argument("--json", action="store_true",
help="print raw JSON-RPC responses instead of the report")
args = ap.parse_args()
# 1) initialize
init = {
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {"name": "mt-mcp-probe", "version": "0.1"},
},
}
try:
status, session_id, body = http_post(args.url, init, timeout=args.timeout)
except (urllib.error.URLError, OSError) as e:
print_waiting_help(args.url)
if args.json:
print("[error] %s" % e)
return 2
if body is None or "result" not in (body or {}):
print("[unexpected] HTTP %d, no MCP initialize result in response" % status)
if args.json:
print(json.dumps(body, indent=2) if body is not None else "(empty body)")
return 1
result = body["result"]
server = result.get("serverInfo", {})
proto = result.get("protocolVersion", "?")
print("[online] %s | server %s %s | protocol %s | HTTP %d%s" % (
args.url, server.get("name", "?"), server.get("version", "?"),
proto, status, " | session %s" % session_id if session_id else ""))
if args.json:
print(json.dumps(result, indent=2))
# 2) initialized notification (no id -> notification; 202 expected, body ignored)
note = {"jsonrpc": "2.0", "method": "notifications/initialized"}
try:
http_post(args.url, note, session_id=session_id, timeout=args.timeout)
except (urllib.error.URLError, OSError):
pass # some servers accept it silently; tools/list will tell us
# 3) tools/list
listing = {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}
try:
status, _, body = http_post(args.url, listing, session_id=session_id,
timeout=args.timeout)
except (urllib.error.URLError, OSError) as e:
print("[error] tools/list failed after successful initialize: %s" % e)
return 1
if body is None or "result" not in (body or {}):
print("[unexpected] HTTP %d, no tools/list result" % status)
if args.json:
print(json.dumps(body, indent=2) if body is not None else "(empty body)")
return 1
tools = body["result"].get("tools", [])
if args.json:
print(json.dumps(body, indent=2))
# 4) capability report
print()
print("== MCP tool inventory: %d tool(s) ==" % len(tools))
mt_tools = [t for t in tools if t.get("name", "").startswith("mt_apk_")]
other = [t for t in tools if not t.get("name", "").startswith("mt_apk_")]
grouped = {prefix: [] for prefix, _ in CATEGORIES}
for t in sorted(mt_tools, key=lambda x: x.get("name", "")):
name = t.get("name", "")
suffix = name[len("mt_apk_"):]
placed = False
for prefix, label in CATEGORIES:
if suffix == prefix or suffix.startswith(prefix + "_"):
grouped[prefix].append(t)
placed = True
break
if not placed:
grouped.setdefault("misc", []).append(t)
for prefix, label in CATEGORIES:
items = grouped.get(prefix, [])
if not items:
continue
print("\n[%s] %s" % (label, len(items)))
for t in items:
desc = (t.get("description") or "").strip().splitlines()
first = desc[0].strip() if desc else ""
print(" %-42s %s" % (t.get("name"), first[:90]))
if grouped.get("misc"):
print("\n[other mt_apk_*] %d" % len(grouped["misc"]))
for t in grouped["misc"]:
print(" %s" % t.get("name"))
if other:
print("\n[non-mt_apk tools] %d" % len(other))
for t in other:
print(" %s" % t.get("name"))
print()
print("Constraints (from the official MT MCP docs, see on-device-tooling.md):")
print(" - no Java decompilation; read smali directly instead")
print(" - .so support is static analysis only (no dynamic run, no pseudo-C)")
print(" - resources.arsc: existing entries editable, no new locales/entries")
return 0
if __name__ == "__main__":
sys.exit(main())
@@ -0,0 +1,79 @@
// rpc_template.js — editable rpc.exports example for frida_rpc_serve.py.
//
// Three shapes every target needs, already wired:
// 1. add — a pure-JS export, proves the transport with zero target knowledge
// 2. getpackagename — a harmless Java probe (calls a framework method via JNI)
// 3. callnative — a native-call placeholder: wrap any exported symbol of any
// loaded module and call it with explicit types
//
// Adapt 3 to your target: the hardened .so that computes a signature or an
// encryption is usually either exported (Module.findExportByName) or bound at
// runtime via RegisterNatives (hook RegisterNatives first to learn the address,
// then pass the raw address to callnativeaddr).
'use strict';
function log(ev, data) {
try { send(Object.assign({ t: Date.now(), ev: ev }, data || {})); } catch (e) {}
}
// Export lookup that works across frida 16/17 (Module.findExportByName(null,..)
// was removed in 17; getGlobalExportByName is the replacement).
function resolveExport(name) {
try { if (Module.getGlobalExportByName) return Module.getGlobalExportByName(name); } catch (e) {}
try { if (Module.findExportByName) return Module.findExportByName(null, name); } catch (e) {}
try {
const libc = Process.findModuleByName('libc.so');
if (libc) return libc.getExportByName(name);
} catch (e) {}
return null;
}
rpc.exports = {
// 1) pure-JS demo — sanity-check the RPC transport itself.
add: function (a, b) {
return a + b;
},
ping: function () {
return 'pong';
},
// 2) harmless Java probe: the package name of the process we live in.
// Works on any app process with a live Java VM; needs no target knowledge.
getpackagename: function () {
let out = null;
Java.perform(function () {
const app = Java.use('android.app.ActivityThread').currentApplication();
out = app.getPackageName();
});
return out;
},
// 3) NATIVE CALL PLACEHOLDER — adapt module/name/ret/arg types to your target.
// moduleName null means "search every loaded module" (global export lookup).
callnative: function (moduleName, exportName, retType, argTypes, args) {
let addr = null;
if (moduleName) {
const base = Module.findBaseAddress(moduleName);
if (base === null) throw new Error('module not loaded: ' + moduleName);
addr = Module.findExportByName(moduleName, exportName);
} else {
addr = resolveExport(exportName);
}
if (addr === null) throw new Error('export not found: ' + exportName);
const fn = new NativeFunction(addr, retType, argTypes);
return fn.apply(null, args || []);
},
// Variant for symbols that never hit the export table (dynamically registered
// JNI, or an offset inside a stripped .so): pass module name + raw offset.
callnativeaddr: function (moduleName, offset, retType, argTypes, args) {
const base = Module.findBaseAddress(moduleName);
if (base === null) throw new Error('module not loaded: ' + moduleName);
const fn = new NativeFunction(base.add(offset), retType, argTypes);
return fn.apply(null, args || []);
}
};
log('RPC-READY', { exports: Object.keys(rpc.exports) });
@@ -0,0 +1,236 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""Summarize a stalker_trace.js log: block histogram, skeleton, call edges.
WHY THIS EXISTS
---------------
scripts/stalker_trace.js records, for one target module, the basic blocks a
thread really executed. Raw, that log answers nothing -- the value comes from
three reductions, and each maps to a deobfuscation decision:
* execution histogram (BLK lines) -- in a control-flow-flattened function
the dispatcher block runs orders of magnitude more often than any real
block; the top of this histogram IS the dispatcher;
* first-visit order (BB lines) -- the deduplicated block set in first-visit
order approximates the real CFG skeleton with the flattening state machine
stripped out;
* call edges (CALL lines) -- which functions inside the module talk to each
other, independent of symbol names.
This tool is deliberately stdlib-only and parses text, so it works on logs
written by run_probe.py (each event line embedded in a `[host ts] [dev ts]
TRACE ...` wrapper) and on raw one-event-per-line logs alike.
Usage
-----
python stalker_report.py trace.log
python stalker_report.py trace.log --top 30 --skeleton 80
python stalker_report.py trace.log --json report.json
python stalker_report.py trace.log --quiet # summary only
Reading the output
------------------
* DONE ... truncated=1 -- the trace hit maxBlocks; ratios are still useful,
absolute counts are not.
* zero BLK but nonzero BB -- the thread stopped between translation and
execution (short follow, or the trigger returned immediately).
* zero BB and zero BLK with DONE present -- module never ran on the followed
thread; pick a real trigger instead of `main`.
* everything zero, no DONE -- the trace never started: check READY/TRIG-FAIL
lines in the log first.
"""
import argparse
import json
import re
import sys
from collections import Counter, OrderedDict
MOD_RE = re.compile(r'\bMOD (\S+) base=(0x[0-9a-fA-F]+) size=(\d+)(?:\s+path=(\S+))?')
BB_RE = re.compile(r'\bBB (\d+) (\S+)\+0x([0-9a-fA-F]+)')
BLK_RE = re.compile(r'\bBLK (\d+) (\S+)\+0x([0-9a-fA-F]+)(?:\s+size=(\d+))?')
CALL_RE = re.compile(r'\bCALL (\S+) (\S+) -> (\S+)')
DONE_RE = re.compile(r'\bDONE reason=(\S+) blocks=(\d+) blk=(\d+) calls=(\d+) truncated=(\d)')
FATAL_RE = re.compile(r'\b(FATAL|TRIG-FAIL) (.*)')
def parse_log(path):
stats = {
'mods': OrderedDict(), # name -> {base, size, path}
'bb': [], # (seq, mod, offset) first-visit order
'blk': [], # (seq, mod, offset, size|None) executions
'calls': [], # (depth, from, to)
'done': None,
'fatals': [],
}
with open(path, encoding='utf-8', errors='replace') as fh:
for raw in fh:
m = MOD_RE.search(raw)
if m:
name, base, size, path = m.groups()
if name not in stats['mods']:
stats['mods'][name] = {
'base': base, 'size': int(size), 'path': path or ''}
continue
m = BLK_RE.search(raw)
if m:
seq, mod, off, size = m.groups()
stats['blk'].append((int(seq), mod, int(off, 16),
int(size) if size else None))
continue
m = BB_RE.search(raw)
if m:
seq, mod, off = m.groups()
stats['bb'].append((int(seq), mod, int(off, 16)))
continue
m = CALL_RE.search(raw)
if m:
stats['calls'].append(m.groups())
continue
m = DONE_RE.search(raw)
if m and stats['done'] is None:
stats['done'] = m.groups()
continue
m = FATAL_RE.search(raw)
if m:
stats['fatals'].append(m.group(0).strip())
return stats
def blockkey(mod, off):
return '%s+0x%x' % (mod, off)
def collapse_consecutive(items):
"""[(mod, off), ...] -> [(key, repeats), ...] with runs collapsed."""
out = []
for mod, off in items:
key = blockkey(mod, off)
if out and out[-1][0] == key:
out[-1] = (key, out[-1][1] + 1)
else:
out.append((key, 1))
return out
def main():
ap = argparse.ArgumentParser(
description='Summarize a stalker_trace.js log into a block histogram, '
'a first-visit CFG skeleton, and call-edge tables.')
ap.add_argument('log', help='trace log written by run_probe.py (wrapped '
'lines are fine) or a raw event-per-line log')
ap.add_argument('--top', type=int, default=20,
help='rows in the execution histogram (default 20)')
ap.add_argument('--skeleton', type=int, default=40,
help='rows of the first-visit order to print (default 40)')
ap.add_argument('--edges', type=int, default=15,
help='rows in the call-edge table (default 15)')
ap.add_argument('--seq', type=int, default=60,
help='entries of the collapsed execution sequence to print '
'(default 60)')
ap.add_argument('--json', metavar='PATH', default=None,
help='also write the full reduced data as JSON')
ap.add_argument('--quiet', action='store_true',
help='print the summary block only')
args = ap.parse_args()
st = parse_log(args.log)
print('== summary ==')
for name, info in st['mods'].items():
print(' module %-24s base=%s size=%d %s'
% (name, info['base'], info['size'],
('(target)' if st['bb'] and st['bb'][0][1] == name else '')))
print(' unique blocks first-seen (BB) : %d' % len(st['bb']))
print(' block executions (BLK) : %d' % len(st['blk']))
print(' call edges (CALL) : %d' % len(st['calls']))
if st['done']:
reason, nb, nk, nc, trunc = st['done']
print(' DONE reason=%s truncated=%s (device-side counts: bb=%s blk=%s call=%s)'
% (reason, trunc, nb, nk, nc))
else:
print(' DONE line missing -- trace ended without a clean stop '
'(detach or crash?)')
for f in st['fatals'][:5]:
print(' NOTE %s' % f)
if not st['bb'] and not st['blk']:
print('\n no target-module blocks at all. In order of likelihood:\n'
' 1. the module was never loaded on the followed thread '
'(check the MOD lines);\n'
' 2. the trigger never fired (TRIG-FAIL above, or the app '
'never called it);\n'
' 3. the follow window closed before any code ran '
'(raise followMs, or use a call trigger instead of main).')
return 0 if st['done'] else 1
first_seen = {}
for seq, mod, off in st['bb']:
first_seen.setdefault(blockkey(mod, off), seq)
if not args.quiet:
hist = Counter(blockkey(mod, off) for _, mod, off, _ in st['blk'])
total = sum(hist.values())
if hist:
print('\n== execution histogram: top %d (dispatcher candidates) ==' % args.top)
print(' %-6s %-8s %-7s %-28s %s'
% ('rank', 'count', 'pct', 'block', 'firstSeen'))
for rank, (key, cnt) in enumerate(hist.most_common(args.top), 1):
pct = 100.0 * cnt / total if total else 0.0
print(' %-6d %-8d %5.1f%% %-28s #%s'
% (rank, cnt, pct, key, first_seen.get(key, '-')))
print(' (a block at the top by a wide margin, with many distinct '
'successors below,\n is the classic control-flow-'
'flattening dispatcher; see\n references/'
'native-dbi-and-deobfuscation.md)')
if st['bb']:
print('\n== first-visit order (CFG skeleton, first %d of %d) =='
% (min(args.skeleton, len(st['bb'])), len(st['bb'])))
for seq, mod, off in st['bb'][:args.skeleton]:
print(' #%d %s' % (seq, blockkey(mod, off)))
if st['calls']:
edges = Counter('%s -> %s' % (frm, to) for _, frm, to in st['calls'])
print('\n== call edges (top %d of %d) ==' % (args.edges, len(edges)))
for edge, cnt in edges.most_common(args.edges):
print(' %-8d %s' % (cnt, edge))
collapsed = collapse_consecutive([(mod, off) for _, mod, off, _ in st['blk']])
if collapsed:
print('\n== collapsed execution sequence (first %d runs of %d) =='
% (min(args.seq, len(collapsed)), len(collapsed)))
line = ' '
for key, reps in collapsed[:args.seq]:
piece = key + ('*%d' % reps if reps > 1 else '')
if len(line) + len(piece) > 100:
print(line)
line = ' '
line += piece + ' -> '
if line.strip():
print(line[:-4])
if args.json:
payload = {
'modules': st['mods'],
'summary': {
'bb': len(st['bb']), 'blk': len(st['blk']),
'calls': len(st['calls']), 'done': st['done'],
},
'first_seen': first_seen,
'histogram': dict(Counter(
blockkey(mod, off) for _, mod, off, _ in st['blk'])),
'bb_sequence': [blockkey(mod, off) for _, mod, off in st['bb']],
'collapsed': collapsed if st['blk'] else [],
'call_edges': dict(Counter('%s -> %s' % (f, t)
for _, f, t in st['calls'])),
}
with open(args.json, 'w', encoding='utf-8') as fh:
json.dump(payload, fh, indent=1)
print('\njson written to %s' % args.json)
return 0
if __name__ == '__main__':
sys.exit(main())
+456
View File
@@ -0,0 +1,456 @@
/*
* stalker_trace.js -- record a basic-block-level Stalker trace of one native module.
*
* WHY THIS SHAPE
* --------------
* Static disassembly of an obfuscated library (OLLVM control-flow flattening and
* friends) answers "what COULD run". The question that actually breaks the
* obfuscation is "what DID run, and how often" -- the dispatcher block of a
* flattened function executes orders of magnitude more often than the real
* blocks, and that ratio is invisible statically. Frida Stalker answers it:
* it re-compiles every basic block the target thread executes and reports each
* block back, without needing symbols, source, or even a loadable disassembler
* on the host.
*
* Three rules keep the trace usable, and violating each one is a documented
* failure mode:
*
* 1. FOLLOW ONE TRIGGER, NOT THE WHOLE PROCESS. Stalker on an unrestricted
* thread produces gigabytes and the app dies of slowdown. The trace starts
* when a trigger fires (an export call, an offset call, a Java method, or
* the main thread) and stops after followMs or when the trigger returns.
* 2. FILTER TO ONE MODULE. Only blocks whose address falls inside
* CONFIG.targetModule are reported (call edges report when either end is
* inside). Everything else is dropped on the device, not in post.
* 3. CAP THE VOLUME. maxBlocks stops the trace instead of letting the log
* eat the disk; the DONE line says whether truncation happened.
*
* ADAPT TO YOUR TARGET (CONFIG below, or rpc/recv at runtime)
* -----------------------------------------------------------
* targetModule : the .so you are analyzing ('libapp.so', 'libflutter.so', ...)
* trigger.kind : 'export' -- trigger.module + trigger.export (e.g. a JNI fn)
* | 'offset' -- trigger.module + trigger.offset (mod-relative)
* | 'java' -- trigger.cls + trigger.method (Java bridge; the
* classic java->native boundary)
* | 'main' -- follow the main thread right after load; use on
* a quiet/attached process and poke the UI
* followMs : hard stop, so a forgotten trace cannot kill the process
* events : compile = first time a block is translated (dedup'd block
* set + first-visit order = CFG skeleton);
* block = every executed block (execution counts; the
* histogram that exposes the dispatcher);
* call = call edges (call graph into/out of the module);
* exec = per-instruction (ENORMOUS; only for a few hundred
* instructions around a known point; off by default);
* ret = return edges (off by default).
*
* HOW TO RUN
* ----------
* With the bundled injector (constants must be baked into CONFIG):
* python run_probe.py stalker_trace.js 2 --pkg com.example.app --log t.log
* With any driver that speaks rpc (no file edit needed):
* script.exports.config({ targetModule: 'libapp.so',
* trigger: { kind: 'offset', module: 'libapp.so',
* offset: 0x1234 } })
* script.exports.start()
* Or post a config message instead of rpc:
* script.post({ type: 'cfg', payload: {...same shape as CONFIG...} })
*
* OUTPUT FORMAT (one logical line per event; multi-line batches share one send)
* ----------------------------------------------------------------------------
* READY ... config echo + module status; nothing works before it
* MOD name base=0x.. size=.. path=..
* module base, so offline tools map offsets back
* BB <seq> <mod>+0x<offset>
* block first translated (dedup'd CFG skeleton)
* BLK <seq> <mod>+0x<offset> [size=<n>]
* block executed (weighted histogram input)
* CALL <depth> <from> -> <to>
* call edge; addresses are <module>+0x<off> when the
* module is known, raw hex otherwise
* DONE reason=timeout|trigger-leave|maxBlocks|stop-rpc blocks=<n>
* blk=<n> calls=<n> truncated=<0|1>
* FATAL / TRIG-FAIL what did not install and why (the script keeps running)
*
* Feed the log to scripts/stalker_report.py for the histogram, the dedup'd
* block order, and the call-edge table. See references/
* native-dbi-and-deobfuscation.md for the workflow around this trace.
*
* TESTED
* ------
* frida 16.7.19 host + frida-server 16.7.19 on Android 11 arm64. See
* docs/tool-verification/EXTENSION-native-dbi.md for the observed runs.
*/
'use strict';
/* ===================================================================
* 1. ADAPT THESE LINES (runtime override also possible -- see the tail)
* =================================================================== */
var CONFIG = {
// The only module whose blocks are reported.
targetModule: 'libc.so',
// What starts/stops the trace. Examples:
// { kind: 'main' }
// { kind: 'export', module: 'libnative-lib.so', export: 'Java_com_example_App_check' }
// { kind: 'offset', module: 'libapp.so', offset: 0x9f6c0 }
// { kind: 'java', cls: 'com.example.app.NativeBridge', method: 'sign' }
trigger: { kind: 'main' },
followMs: 4000, // unfollow after this long, no matter what
maxBlocks: 100000, // stop recording past this many reported events
autoStart: true, // false = arm triggers but wait for rpc start()
events: {
compile: true, // first translation of each block (skeleton)
block: true, // every executed block (weights)
call: true, // call edges
exec: false, // per-instruction: huge, opt-in only
ret: false
}
};
/* ===================================================================
* 2. plumbing (no target knowledge below this line)
* =================================================================== */
var state = {
started: false, // trigger installed / main follow armed
following: false,
followTid: null,
target: null, // Module object of CONFIG.targetModule
modByName: {}, // addr-cache for cross-module name lookup
seq: 0, nBB: 0, nBLK: 0, nCALL: 0,
truncated: false,
timer: null,
pending: [], // batched lines waiting for one send()
pendingSince: 0
};
function ts() { return new Date().toISOString(); }
function emit(tag, msg) { send({ t: ts(), tag: tag, msg: msg }); }
function flush(force) {
if (!state.pending.length) return;
var now = Date.now();
if (!force && now - state.pendingSince < 120 && state.pending.length < 256) return;
send({ t: ts(), tag: 'TRACE', msg: state.pending.join('\n') });
state.pending = [];
state.pendingSince = now;
}
function line(text) {
state.pending.push(text);
flush(false);
}
/* Stalker.parse() with stringify:false yields raw addresses that may arrive
* as NativePointer, number, or UInt64 depending on the frida version. ptr()
* normalizes all of them; a null address stays null. */
function asPtr(v) {
if (v === null || v === undefined) return null;
if (v && typeof v.equals === 'function') return v; // already a pointer
try { return ptr(v); } catch (e) { return null; }
}
function moduleOf(addr) {
// target module first: the hot path never hits Process.findModuleByAddress
if (state.target && addr.compare(state.target.base) >= 0 &&
addr.compare(state.target.base.add(state.target.size)) < 0)
return state.target;
// one shared cache for everything else (call edges leaving the module)
var hit = Process.findModuleByAddress(addr);
if (hit && !state.modByName[hit.name]) {
state.modByName[hit.name] = hit;
line('MOD ' + hit.name + ' base=' + hit.base + ' size=' + hit.size +
' path=' + hit.path);
}
return hit || null;
}
/* <module>+0x<offset> when the module is known, raw hex otherwise. */
function fmtAddr(addr) {
var m = moduleOf(addr);
if (m) return m.name + '+0x' + addr.sub(m.base).toString(16);
return addr.toString();
}
/* ===================================================================
* 3. the follow engine
* =================================================================== */
function onStalkEvents(events) {
var entries;
try {
entries = Stalker.parse(events, { stringify: false, annotate: false });
} catch (e) {
emit('FATAL', 'Stalker.parse failed: ' + e);
endFollow('parse-error');
return;
}
for (var i = 0; i < entries.length; i++) {
var ev = entries[i];
var kind = ev[0];
if (kind === 'compile') {
var a = asPtr(ev[1]);
if (!a || !moduleOf(a)) continue;
state.seq++; state.nBB++;
line('BB ' + state.seq + ' ' + fmtAddr(a));
} else if (kind === 'block') {
var b = asPtr(ev[1]);
if (!b || !moduleOf(b)) continue;
state.seq++; state.nBLK++;
var sz = (ev.length > 2 && typeof ev[2] === 'number') ? ev[2] : null;
line('BLK ' + state.seq + ' ' + fmtAddr(b) +
(sz !== null ? ' size=' + sz : ''));
} else if (kind === 'call') {
var from = asPtr(ev[1]), to = asPtr(ev[2]);
var depth = (ev.length > 3 && typeof ev[3] === 'number') ? ev[3] : '?';
if (!from || !to) continue;
var fromIn = !!moduleOf(from), toIn = !!moduleOf(to);
if (!fromIn && !toIn) continue; // drop unrelated edges
state.seq++; state.nCALL++;
line('CALL ' + depth + ' ' + fmtAddr(from) + ' -> ' + fmtAddr(to));
}
// 'exec'/'ret' are opt-in; if enabled they are reported as X/RET lines
else if (kind === 'exec' && CONFIG.events.exec) {
var x = asPtr(ev[1]);
if (!x || !moduleOf(x)) continue;
state.seq++;
line('X ' + state.seq + ' ' + fmtAddr(x));
}
if (state.seq >= CONFIG.maxBlocks) { endFollow('maxBlocks'); return; }
}
flush(true);
}
function beginFollow(tid, why) {
if (state.following) return;
if (!state.target) {
emit('FATAL', 'target module not loaded, refusing to follow (see READY)');
return;
}
state.following = true;
state.followTid = tid;
emit('TRIG', 'following tid=' + tid + ' (' + why + ') module=' +
state.target.name + ' base=' + state.target.base);
line('MOD ' + state.target.name + ' base=' + state.target.base +
' size=' + state.target.size + ' path=' + state.target.path);
Stalker.follow(tid, {
events: {
call: CONFIG.events.call,
ret: CONFIG.events.ret,
exec: CONFIG.events.exec,
block: CONFIG.events.block,
compile: CONFIG.events.compile
},
onReceive: onStalkEvents
});
if (CONFIG.followMs > 0) {
state.timer = setTimeout(function () { endFollow('timeout'); },
CONFIG.followMs);
}
}
function endFollow(reason) {
if (!state.following) return;
state.following = false;
if (state.timer !== null) { clearTimeout(state.timer); state.timer = null; }
try { Stalker.flush(); } catch (e) { /* already gone */ }
try { Stalker.unfollow(state.followTid); } catch (e) { /* already gone */ }
flush(true);
emit('DONE', 'reason=' + reason + ' blocks=' + state.nBB +
' blk=' + state.nBLK + ' calls=' + state.nCALL +
' truncated=' + (state.truncated || reason === 'maxBlocks' ? 1 : 0));
}
/* ===================================================================
* 4. triggers
* =================================================================== */
function installTrigger() {
var t = CONFIG.trigger || { kind: 'main' };
state.target = Process.findModuleByName(CONFIG.targetModule);
if (!state.target) {
// Hardened apps and Flutter apps load their interesting library after
// Application start; wait for the linker instead of failing.
emit('TRIG-FAIL', 'module ' + CONFIG.targetModule + ' not loaded yet; ' +
'hooking dlopen to wait for it');
hookDlopen(CONFIG.targetModule, function (mod) {
state.target = mod;
armTrigger(t);
emit('TRIG', 'module ' + mod.name + ' loaded at ' + mod.base +
'; trigger armed');
});
return;
}
armTrigger(t);
}
function armTrigger(t) {
try {
if (t.kind === 'export' || t.kind === 'offset') {
var mod = Process.findModuleByName(t.module || CONFIG.targetModule);
if (!mod) { emit('TRIG-FAIL', 'trigger module missing: ' + t.module); return; }
var addr = null;
if (t.kind === 'export') {
addr = mod.findExport ? mod.findExport(t.export) : null;
if (!addr) addr = Module.findExportByName(mod.name, t.export);
if (!addr) {
emit('TRIG-FAIL', 'export not found: ' + mod.name + '!' + t.export);
return;
}
} else {
addr = mod.base.add(t.offset || 0);
}
Interceptor.attach(addr, {
onEnter: function () { beginFollow(this.threadId, 'trigger ' + addr); },
onLeave: function () { endFollow('trigger-leave'); }
});
emit('TRIG', 'armed ' + t.kind + ' trigger at ' + addr);
} else if (t.kind === 'java') {
if (typeof Java === 'undefined') {
emit('TRIG-FAIL', 'java trigger requested but no Java bridge; ' +
'align host frida and frida-server to the same 16.x');
return;
}
Java.perform(function () {
var Klass;
try { Klass = Java.use(t.cls); }
catch (e) { emit('TRIG-FAIL', 'class not found: ' + t.cls); return; }
var hit = false;
var names = t.method instanceof Array ? t.method : [t.method];
for (var i = 0; i < names.length && !hit; i++) {
var ov = Klass[names[i]];
if (!ov || !ov.overloads) continue;
ov.overloads.forEach(function (o) {
// implementations run on the calling thread, so the
// current thread id IS the java->native boundary thread
o.implementation = function () {
beginFollow(Process.getCurrentThreadId(),
'java ' + t.cls + '.' + names[i]);
try {
return o.apply(this, arguments);
} finally { endFollow('trigger-leave'); }
};
});
hit = true;
}
if (hit) emit('TRIG', 'armed java trigger ' + t.cls + '#' + names.join(','));
else emit('TRIG-FAIL', 'method not found on ' + t.cls + ': ' + names.join(','));
});
} else if (t.kind === 'main') {
if (CONFIG.autoStart === false) {
emit('TRIG', 'main trigger armed (autoStart=false); call start()');
return;
}
var tid = null;
try { tid = Process.getMainThreadId(); } catch (e) { /* older gum */ }
if (!tid || tid <= 0) {
// getMainThreadId may not exist on older gum; on Android the
// first thread frida lists is the process's main thread.
var threads = Process.enumerateThreads();
tid = threads.length ? threads[0].id : Process.getCurrentThreadId();
}
beginFollow(tid, 'main-thread follow (pid=' + Process.id + ')');
} else {
emit('TRIG-FAIL', 'unknown trigger kind: ' + t.kind);
}
} catch (e) {
emit('TRIG-FAIL', String(e));
}
}
/* Wait for a library the dynamic linker has not mapped yet. */
function hookDlopen(basename, onLoaded) {
var seen = false;
['dlopen', 'android_dlopen_ext'].forEach(function (name) {
var a = Module.findExportByName(null, name);
if (!a) return;
Interceptor.attach(a, {
onEnter: function (args) {
var p = args[0];
this.path = (p && !p.isNull()) ? p.readCString() : null;
},
onLeave: function (res) {
if (seen || !this.path) return;
if (this.path.indexOf(basename) === -1) return;
var mod = Process.findModuleByName(basename);
if (mod) { seen = true; onLoaded(mod); }
}
});
});
}
/* ===================================================================
* 5. runtime control: rpc.exports + post('cfg')
* =================================================================== */
rpc.exports = {
config: function (patch) {
if (!patch || typeof patch !== 'object')
return { ok: false, error: 'config needs an object' };
for (var k in patch) {
if (k === 'trigger' && patch.trigger && typeof patch.trigger === 'object') {
CONFIG.trigger = patch.trigger;
} else if (k === 'events' && patch.events) {
for (var e in patch.events) CONFIG.events[e] = !!patch.events[e];
} else {
CONFIG[k] = patch[k];
}
}
// a re-config that changes WHAT we trace must not race the old follow
if (state.following &&
(patch.trigger !== undefined || patch.targetModule !== undefined ||
patch.autoStart !== undefined)) {
endFollow('reconfig');
}
installTrigger();
return { ok: true, config: CONFIG };
},
start: function (argTid) {
var tid = argTid || null;
if (!tid || tid <= 0) {
// never follow the rpc thread: it sleeps while waiting for us and
// produces an empty trace. Prefer the process's main thread.
try { tid = Process.getMainThreadId(); } catch (e) { /* older gum */ }
if (!tid || tid <= 0) {
var threads = Process.enumerateThreads();
tid = threads.length ? threads[0].id : Process.getCurrentThreadId();
}
}
beginFollow(tid, 'start-rpc');
return { following: state.following, followingTid: tid };
},
stop: function () { endFollow('stop-rpc'); return status(); },
status: function () { return status(); }
};
function status() {
return {
following: state.following,
targetLoaded: !!state.target,
target: state.target ? state.target.name : CONFIG.targetModule,
seq: state.seq, blocks: state.nBB, blk: state.nBLK, calls: state.nCALL
};
}
try {
recv('cfg', function onCfg(message, payload) {
rpc.exports.config(payload);
recv('cfg', onCfg); // stay armed for further updates
});
} catch (e) { /* recv unavailable in this runtime; constants mode still works */ }
/* ===================================================================
* 6. go
* =================================================================== */
state.started = true;
// safety flush so lines emitted before/after a follow still reach the host
setInterval(function () { flush(true); }, 500);
emit('READY', 'stalker_trace loaded; target=' + CONFIG.targetModule +
' trigger=' + JSON.stringify(CONFIG.trigger) + ' followMs=' + CONFIG.followMs +
' maxBlocks=' + CONFIG.maxBlocks +
' moduleLoaded=' + !!Process.findModuleByName(CONFIG.targetModule));
installTrigger();