Close the byte-patching gap, add the server-config path, fix two script crashes

Worked end-to-end on a real unobfuscated commercial app (single-dex, no packer, server-driven launch screen) and folded back everything that cost time. Net +17 files, no new dependencies, no sample-specific identifiers. New references byte-level-patching.md The technique that was missing entirely. Equal-length in-place edits beat method rebuilding (measured on a real sample: method rewrite grew debug_info 924 B -> 22.8 KB and the dex 4.32 MB -> 7.73 MB), but four failure modes are silent: same-length is not enough, branch polarity, verifier legality, and stale dex header fields. Covers locating an instruction's exact offset (why listings and byte-pattern guesses both fail), the instruction width table and the two traps that desynchronise a decode, neutralise-a-branch vs redirect-it, and the header's signature-then-checksum order. server-config-and-updates.md The most common shape of "ad" in a modern app, and the one usually mis-diagnosed: the server supplies UI the client renders. The two-layer fetch (local fallback then remote override) that proves it, finding the config DTOs through the field names data classes keep, why you patch the decision and not the data, deciding the scope of "remove", and remote re-enable / cached config durability. New scripts dexutil.py dependency-free dex reader: structural walk, exact instruction decode, dex header recompute/verify in the correct order, branch-target and operand helpers dex_find_insn.py locate an instruction by decoded semantics, print its exact byte offset with context and BOTH sides of any branch dex_patch_bytes.py equal-length byte patches from a JSON spec: semantic match, polarity pin via expect_next, equal-length enforcement, verifier check, header recompute, re-decode to prove it landed dex_check_verifier.py does any conditional branch target a move-result (bypassing its producer)? Compares builds and separates pre-existing findings from regressions the patch introduced coldstart.py cold-launch capture: timed screenshot burst + logcat signals + installed-build facts + launch timing, and a warning when the foreground activity is not the app check_repo.py maintenance check: every script parses and answers --help, every referenced path resolves, every file is documented Fixes found while running the above repack.py wrote archives with a plain zipfile writer, which cannot satisfy the Android R+ install gate: resources.arsc must be STORED *and* 4-byte aligned, and a zip extra record cannot express a 1-3 byte pad (a stored filler entry is inserted instead). Also fixes the central-directory pointer and adds an alignment gate to the output. usb_net_proxy.py, dex_strpatch.py crashed on --help with a traceback instead of printing usage. Updated toolchain.md ddc added (single-binary dex->Java with query subcommands, with measured timings and its real limits); "not on PATH is not not-installed" with the search commands; which signer to use and why jarsigner breaks alignment repack-and-sign.md alignment requirement and its arithmetic; dex header recompute; jarsigner hazard; vendor install interception ([N] with no symbolic constant -> root pm install); the installer can keep owning the screen after an install recon.md resolve package identity from a tool, not from hand-read AXML strings (a wrong package sends all later device queries nowhere); snapshot the config surface during recon long-task-discipline.md captures you never looked at are not evidence (incl. the consistent-but-wrong-window variant); long-context decay and the record shape that survives it dynamic-frida.md when live attach cannot work at all: static instrumentation, static read, and self-recorded evidence, with the control build caveat each one carries ad-removal.md server-driven config is usually the EASIEST case, not the hardest; a three-way zero result is a positive finding; scope note on local brand splash vs promotional content pitfalls.md P37 stale dex header checksum, P38 [-124] alignment, P39 bare-numeric install failure, P40 wrong-window evidence, P41 inverted branch polarity, P42 decode desynchronisation SKILL.md, README.md symptom index, reference/script indexes and requirements updated for all of the above
2026-09-20 02:05:41 +08:00
parent d1349b3cfa
commit a552157f1b
20 changed files with 3179 additions and 52 deletions
@@ -9,12 +9,48 @@ Ten minutes here prevents hours of wrong work. Answer the five questions from `S
 aapt dump badging app.apk | head -20
 # or, from the extracted manifest:
 #   package name, versionName, versionCode, sdkVersion, targetSdkVersion
+# or, if you have ddc (no JVM, single binary, also gives the launcher):
+ddc info app.apk
 ```

 Record: package name, version name/code, min/target SDK, all requested permissions, all declared components.

+**Do not hand-parse the package name out of the binary manifest as your primary
+source.** Real AXML string tables are full of class-name fragments that look
+exactly like package names — in one sample, the strings visible without a real
+parser suggested `com.<app>.offline` (a service class prefix) while the actual
+package was `com.<vendor>.app`. Every later `pm list packages`,
+`dumpsys package`, `/data/data/<pkg>` and `pm install` command depends on this
+value, so getting it wrong sends the whole recon down a path where nothing is
+found and the natural conclusion is "the tool is broken".
+
+Cross-check two independent sources and require agreement:
+
+- `ddc info app.apk` → `package`, `label`, `launcher`
+- `aapt2 dump badging app.apk | head -1` (or `aapt dump badging`)
+
+If they disagree, resolve it before proceeding. A single `label` value is also
+worth having: it is what appears on the launcher, which makes device-side
+identification unambiguous later.
+
 **Note:** some `aapt` builds choke on non-ASCII paths. Normalize sample paths to ASCII before running tooling.

+## 1b. Snapshot the config surface early
+
+If the app has a remote-config endpoint, its DTOs are the cheapest thing in the
+package to find, because data classes serialise their own field names into strings
+that survive R8:
+
+```bash
+ddc findrefs app.apk string "SplashConfig"       # or Config, Popup, Banner, Tabbar...
+ddc strings app.apk -f "enabled" --with-locations
+```
+
+Do this during recon rather than later: it tells you immediately whether the
+launch screen, popups and tab set are **client decisions** or **server data**,
+which is the difference between a five-minute patch and a dead end. See
+`server-config-and-updates.md`.
+
 ## 2. Is it packed?

 Read `AndroidManifest.xml` → `application android:name`.
@@ -29,6 +65,14 @@ Read `AndroidManifest.xml` → `application android:name`.
 | One or more large high-entropy `assets/` blobs, possibly **disguised as JPEG** (valid magic bytes, no decodable image) | Encrypted payload. |
 | `assets/` contains a second `.apk` or `.jar` | Wrapped/loader build. |

+**A clean shape is also a result: record it and move on.** An app whose
+`application android:name` is its own class, with a single plain `classes.dex` and
+no native libraries, is directly editable — and that finding is what lets you skip
+the entire packer/unpack branch of this skill. It is worth one explicit line in the
+record ("no packer: application is the app's own class; dex readable; no lib/") so
+that later steps cannot re-open a question that was already answered. Most real
+targets are this shape; the packer material in this repository exists for the rest.
+
 Decide from sizes and structure, not from names:

 ```bash