Why
The reference material was good and mostly went unread in practice. The failure mode was
not ignorance - it was reading the file, agreeing with it, and then reasoning from first
principles anyway, because everything in it was phrased as guidance. Guidance can be
acknowledged and set aside; a gate cannot be cleared without doing the thing.
SKILL.md is now a procedure
New top matter, in the order a reader meets it:
- "How to use this file" states plainly that this is a procedure with gates, that this
file wins over intuition until evidence overrides it, and why (every rule is residue
of a failure that cost hours).
- Four override rules R1-R4, each with a one-line claim, the concrete trap, and a
pointer. R1 deliverable-as-a-testable-sentence, R2 one variable plus a control build,
R3 never ship or claim an unverified artifact, R4 identify the owning layer and
re-classify when reality disagrees.
- The symptom index is retitled "a matching row is a stop signal" and now carries an
explicit instruction: load the file before your next command, not after your next
three attempts.
- Four gates G1-G4, each an action with a pass criterion and a fail description:
deliverable form, environment truth (doctor.py + preflight), code location (including
the virtualization check even when recon says "no packer"), and baseline/control with
recorded time-to-death.
- The workflow gains a skip-condition line per step ("it seems unnecessary" is not a
condition) and a two-strike rule: two failures of the same shape mean the model is
wrong, not the parameters, so re-classify instead of running a third variant.
- New "What done means": six items, all required, with an explicit rule that a clean log
is not evidence and that anything short of six is a checkpoint to be labelled as one.
- New "Stop conditions": the six moments where pushing forward is the wrong move -
repeated same-shape failure, a no-effect patch about to be retried, an unexplained
failure, an unproven "blocked" verdict, a success claimed from absence of errors, and
a measurement that disagrees with a settled conclusion.
README
Documents the gated design and why it exists, and tells an agent reading it what to act
on rather than read: the four rules, the symptom index as a stop signal, the gates, the
two-strike rule, and the definition of done. Points at scripts/doctor.py as the cheapest
first command.
Not changed
Three section references (`ad-removal.md` server-driven, `recon.md` code-location,
`dex-patching.md` finding-the-call-site) do not match a `##` heading textually. Each
target does exist - two are bolded inline subheadings and one is "## Finding the call
site" - so they resolve for a reader. Left alone deliberately: rewriting them would add
churn without changing behaviour.
Observed problem this addresses
In real use the references went mostly unread. The index at the end of SKILL.md
lists what each file *contains*, which does not help when what you have in hand is a
symptom, not a file name: "SIGSEGV with pc=0", "no packer and it still dies",
"UnsatisfiedLinkError after I deleted a library". The retrieval cost of "which file
covers this" was higher than "reason about it myself", so reasoning won - and some of
what was reasoned out by hand was already written down verbatim in packers.md.
What was added
A "Symptom index" table near the top of SKILL.md, before the classification questions,
mapping an observed symptom to the file and section that has already paid for that
lesson. Twenty-one rows covering the failure shapes that actually recur: the
deliberate-crash signature, the no-packer-but-still-dying layer, a Java-layer check
logging success while a native check kills the process, the deleted-library deadlock,
classes that are all native declarations, a SONAME that disagrees with its filename,
edits with no effect, hangs with no crash record, death only while attached, mixed-up
capture windows, missing tools, feature-scoped network failures, silent signed-request
failures, ads that survive the patch, update gates including the non-Java and
browser-handoff shapes, gates that are still locked after the dialog is gone, and the
two "before you write this route off" reminders.
Two invented section suffixes were removed during verification: the index must only
point at headings that exist, since a pointer to a section that is not there is worse
than no pointer at all.
New reference: references/code-virtualization-and-custom-linkers.md
Covers the layer between "packed" and "clean" - manifests whose Application is the
app's own and whose dex is readable, yet a re-signed build dies before user code runs.
Contents: three cheap identification tells (whole classes as native declarations, the
registerNativesForClass/special_clinit pair, SONAME-vs-filename mismatch); the
keep-the-library / delete-the-library deadlock and why both routes fail; the
checker-vs-implementation question that resolves it; the string-redirect technique
(equal-length rewrite of an isolated constant so a loadLibrary call reaches an
already-mapped library, so no offsets move and no death path needs neutralizing);
expected private-loader log shapes; a single-variable experiment to determine whether
the native check reads in-APK certificate material or the PMS-reported signature; and
why a Java-layer signature killer logging success proves nothing.
New tool: scripts/doctor.py
Cheapest first command. Capability report and per-script runnability, with
APKREV_TOOLS support so tools installed off-PATH or as runnable jars are found rather
than reported missing. Surfaces the environment facts that silently poison
experiments: clock skew, leftover adb forward entries, a leftover device proxy, and a
frida process already running on the device (which makes the target look like it
detects instrumentation when nothing has been attached yet).
New tool: scripts/so_constpatch.py
Implements the string-redirect technique. Enforces equal length, refuses to patch a
substring of a longer identifier, reports whether each hit sits in an ELF constant
pool, and patches inside an APK or a bare .so. Field-tested on a real protected
library: find, equal-length replace, unequal-length refusal, multi-hit guard, --force
and absent-name paths all verified.
Updated:
SKILL.md fix question count (ten -> thirteen); index the new reference and
both new scripts; make doctor.py the first step of the workflow;
add the "no packer but still dying" pointer during recon
packers.md cross-reference the new layer so "no packer" is not read as
"editable"
ad-removal.md make log evidence a count rather than an impression (n -> 0 is a
measurement; a tag that goes quiet without reaching zero is a
weaker result)
repack-and-sign.md warn that a full apktool rebuild rewrites obfuscated resource
paths (hundreds of rename pairs) - a tool artifact that must not be
read as breakage - and prefer a dex-only swap when that is the only
edit
pitfalls.md generalize the ServiceLoader example so it is not tied to one
sample's third-party library
README.md document the new files and scripts; document APKREV_TOOLS and the
cross-platform intent
A decision file for when the app fights back or the tool cannot run here: separating
detection from a broken environment, choosing between workaround / change-route /
accept by cost instead of escalating, recognising an environment where dynamic
analysis genuinely cannot work (and switching to static rather than proving it
impossible), and keeping 'blocks my analysis' separate from 'blocks the deliverable'.
- references/updates-and-forced-upgrade.md: keeping a patched build alive (locating the
version check, the two-layer patch, what not to touch, self-update and hot-update
channels, verifying no version request is issued)
- references/account-gates.md: client-side sign-in/binding gates vs account-scoped
resources, why forging a session is worse than being signed out, session loss after
reinstall
- SKILL.md / README.md: wire both into the decision list, workflow and indexes
- scripts/dex_classdiff.py: had no argparse, so --help crashed with IndexError; added
proper CLI, non-zero exit on structural difference, removed a dead duplicate read
- scripts/dex_strings.py: --find compiled the regex as bytes but matched decoded text,
raising TypeError on the main path; split into text and byte patterns, added
--max-print output cap
references/native-tamper-and-suicide.md - how a hardened library terminates its own process: the mechanisms and their signatures, how to tell which one actually fires, arranged faults that call nothing (defeating every PLT-level fix), resolving a stub to its symbol, forged section headers, function boundaries from PT_GNU_EH_FRAME, scanner traps, and neutralising by returning rather than spinning.
references/toolchain.md - what to install, non-interactive invocation, GUI-only tools (ask for a human instead of silently substituting a weaker method), version-alignment traps, and working offline.
scripts/elf_plt.py - PLT stub to imported symbol on x86_64 and aarch64 from the relocation table; caller listing; library byte-diff naming each changed stub's symbol. scripts/apk_diff.py - entry-level diff by content hash, so same-size replacements are caught. scripts/native_crash.py - locate a native death from a log or tombstone and flag an arranged fault.
pitfalls P31-P36; SKILL.md gains a decision question, a hard constraint on neutralising terminate paths, and cross-references from packers/native-and-so.
- references/patch-audit.md (new): two independent questions for any self-made patch —
did it land, and is it legal. Length-vs-bytes comparison and the ~800-false-positive
signal that makes byte diffing useless; the equal-length-replacement blind spot that
hides patches from length-only audits (and why tier-2 checking must be driven by the
patch set's own declared targets, not by tier-1 output); verifier-level legality
(move-result must immediately follow its producer) checked as a set-difference so it
runs before the device; text-matching patch traps (whitespace, line endings,
instruction names, anchor uniqueness, re-emitted old fragments, one block per doc);
and auditing the patch set rather than a patch.
- pitfalls P28-P30: stale events-buffer records that read as this build's crash;
a patch that lands and changes nothing because the edited data is not the data the UI
consumes; two observations that cannot distinguish the hypotheses reported as a result.
- verification.md: point the known code-item blind spot at the new reference.
- Unify the four remaining script docstrings (and their inline comments) into English,
and generalise a sample-specific class name out of one of them.
New: references/signature-derived-keys.md (apps that use their own signing certificate as crypto key material: detection greps, why offline extraction is unreliable -- the runtime value is a certificate DER from inside the PKCS#7 chain, not the .RSA container -- plus the hardcode-then-verify procedure); scripts/sig_probe.py (offline candidates via --apk, authoritative read via --live, both exercised); pitfalls.md P27 (rebuilt APK installs and renders but every signed request returns empty/-1 signing params).
Updated: dynamic-frida.md (attach by PID when enumerate_processes omits the target; verify runtime/Java-bridge availability before blaming the script); runtime-data.md (MMKV format, parse/write snippet, crc32 and in-memory-overwrite traps); server-api.md (route the signature-derived-key case to the new reference); SKILL.md and README.md (new classification question, corrected question count, index entries).
New reference:
- dart-aot.md: pinning the Dart version, building a matching decompiler, the object-pool
model and reference indexes, register/boolean conventions, the three assembly signatures
that identify most business logic, the locating workflow, patch strategy, and the traps
specific to this layer (including ambiguous identifiers that resolve to protocol fields).
New scripts (parameterized, no machine-specific paths):
- dart_pprefs.py: object-pool offset -> code-site index, decoded arithmetically. Avoids the
full-capstone pass that costs minutes and 1-2 GB and reads as a hang.
- dart_pool_strings.py: framed literal recovery with file offsets. Defaults to one-byte
because automatic two-byte (UTF-16) detection is unreliable; --find searches both
encodings and is the reliable way to locate a known literal.
- dart_disasm.py: annotated windowed disassembly (pool + boolean annotations) and a B/BL
caller index that needs no disassembler.
Fixes and integration:
- framework-runtimes.md: point the Dart depth at dart-aot.md, and make the string-encoding
rule precise (ASCII is one-byte/UTF-8; CJK is UTF-16LE) instead of leaving it as 'try both'.
- pitfalls.md: P26 -- self-built tooling that fails in a way that reads as a target finding
(silent arithmetic, helper shadowing a stdlib module, measuring against an incomplete
reference, and a knob that does not move the metric).
- SKILL.md / README.md: index the new reference and scripts.
Validated by running all three scripts against a real Dart AOT sample: the pool-ref index
agrees with an independently built index to 99.2%, and the literal extractor's one-byte
output was verified string-by-string against a decompiler's pool listing.
Generalized from a long hardened-target engagement. Additions target the failure
modes that cost the most time and are not yet covered; nothing here is sample-specific.
New discipline
- SKILL.md: a third override rule -- deliver in the environment the request requires.
A root-only or live-instrumentation result can look like success while failing the
actual requirement (unrooted, installable, self-contained). Also adds two classify
questions: what form the deliverable must take, and which architecture/library is
actually executing.
- long-task-discipline.md: "the most expensive drift" -- a constraint table (privilege,
modification form, ABI, network, persistence, distribution), the checkpoint question,
and how to report a privileged workaround as a fallback rather than a deliverable.
Plus "bound every wait": timeouts on every command, budgets calibrated from
measurement so slow and hung are distinguishable, and sampling an observable you can
inspect instead of sleeping blind.
- environment.md: look at the screen instead of driving blind; which of the two screen
evidence kinds is trustworthy (an empty accessibility tree is common for
runtime-rendered UI, where the image is primary rather than a fallback); emulator
console control and adb recovery; preflight before every experiment block.
- native-and-so.md: what the device claims vs what the package manager chose vs what is
actually mapped; translation layers and their consequences for hooks and native
checks; fat-APK ABI selection.
- runtime-data.md: when the app rewrites your edit (server refresh vs local
regeneration), why chmod/chown cannot work because the app deletes and recreates the
file, and the immutable-attribute fix; decoding a value that only looks encrypted.
- framework-runtimes.md: string encoding traps (a UTF-8 scan of a UTF-16 snapshot
returns nothing and reads as "the strings were stripped"), and non-ASCII obfuscated
identifiers -- resolve by shape, not by name.
- pitfalls.md: P23 the fix lives in a file the app rewrites; P24 the artifact changed
but the wrong one is executing; P25 "search found nothing" treated as "not there".
New scripts (parameterized, path-agnostic, all with explicit timeouts)
- preflight.py environment check: device, root, ABI/translation, clock skew, leftover
proxy/forwards, dead device server, chosen ABI, free space
- lib_map.py what is actually mapped into a live process: path, base, architecture
from the ELF header, and whether it came from the APK or was
materialized at runtime
- blob_decode.py search (don't guess) the framing of a stored value, then re-encode the
edited payload with the same parameters
- snap.py bounded burst screenshots + control-tree capture, with a stall detector
and an explicit verdict on whether the tree is usable
All four were exercised against a live device while writing: preflight correctly
flags multi-device ambiguity and detected the ARM translation layer; lib_map read real
ELF headers and identified the translation shim; blob_decode round-tripped a
rotation+deflate+base64 blob at realistic size in ~0.2s; snap detected a stalled screen
across three hashes.
New references (loaded on demand, one topic each):
- packers.md: reading the shell's rejection signal, distinguishing self-inflicted
failures from genuine refusals, mapping the validation boundary via single-variable
tests, component-type rules (providers vs activities), picking a native host
- framework-runtimes.md: identifying Flutter/RN/Unity/Cordova, the wrong-layer trap,
how to tell which layer draws a given UI before committing to a patch direction
- native-and-so.md: host-library selection criteria, DT_NEEDED does-not-call-JNI_OnLoad,
relocation vs page-permission constraints and relocation-free bootstrapping,
replacing Java methods from native code with trampolines and fail-safe guards
- long-task-discipline.md: live record structure, conclusion grading, drift checkpoints,
handover contents, and the opposite failure of over-documenting
Pitfalls: +P18 install reported success but the build was never installed,
+P19 internal signal substituted for the user-visible outcome,
+P20 not-captured treated as not-present, +P21 two changes then attributing the result,
+P22 waiting on something that needs a human to advance.
SKILL.md: index the new references; add a runtime check for layer ownership to Q3;
add long-task rule; strengthen the verify step; add three hard constraints
(user-visible definition of done, no route discarded on compound evidence,
prove the device changed before measuring).
No app names, package names, or sample-specific identifiers anywhere.
references: recon gains packer identification + unpacking workflow (payload/plaintext size mapping, dump validation, hash de-duplication, business-dex heuristic); repack-and-sign gains the de-shelled repack pipeline, why apktool over binary AXML, and the apksigner scheme-selection caveat; new tls-and-cert documents feature-scoped network failures, dual trust chains and the fix template; new third-party-builds covers auditing a cracked/modded APK before trusting it; dynamic-frida gains version pinning, remote-device path, the four-layer probe and hook-never-fires triage; environment gains UI automation pitfalls; ad-removal gains the single convergence point, dynamic-plugin SDKs and the global timestamp gate; pitfalls gains P13-P17; verification gains rung 7 and the three-signal ad check.
scripts: new frida_probe.js (four-layer runtime probe), run_probe.py and tls_check.py; repack.py fixes two crash-on-default bugs and a misleading META-INF note; datastore_inject.py, PatchMethodExample.java and build_scripts.py lose hardcoded values - the example class name did not match its file and could not compile.
inliver233