mirror of
https://codeberg.org/reverse-skill-lab/apk-reverse
synced 2026-11-16 21:14:35 +08:00
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:
@@ -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/
|
||||
|
||||
@@ -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
|
||||
```
|
||||
@@ -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.
|
||||
@@ -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
@@ -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())
|
||||
@@ -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())
|
||||
@@ -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())
|
||||
@@ -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();
|
||||
Reference in New Issue
Block a user