references/long-task-discipline.md
New section: "Keep the observation window clean". Every conclusion rests on "the
build I am looking at is the build I made", and that assumption fails silently:
something else installs/reverts/clears the target mid-capture, the process was never
actually restarted, or the installed artifact is not the one on disk. Guards, cheapest
first: pin identity by hash (not filename, and immediately before the window, not
hours earlier); declare a capture window and run no install/uninstall/clear inside it;
timestamp it; prefer one continuous capture over several short ones. When a window
turns out to be contaminated, discard and re-capture rather than salvage - a re-run
costs minutes, a wrong conclusion costs the rest of the task and gets re-derived from
the same bad evidence.
references/updates-and-forced-upgrade.md
New Step 6: "when the check is not where you expect", covering three shapes that break
the flip-the-comparison plan.
- The check is native: a declared update entry point with zero Java callers means the
invocation lives in a .so. Ordered remedies, starting with the one that needs no
native work at all - attack the response, or feed the check a version it likes. "No
Java caller" is not "unpatchable".
- The dialog hands off to a browser or WebView: there is no installer call to find,
and logcat truncates the URL to `dat=https://host/...`, so a grep gives you a host
and no path. Approach table for recovering the real URL, with hooking intent
construction as the reliable one.
- Server-issued gate with a local fallback: read the failure branch first. If failure
defaults to "no update", failing the request is the whole fix and also gives you an
offline verification signal; if it defaults to "must update", it makes things worse.
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
Terminate paths read the environment, not your patch, so the same build can die in one setup and live in another. Adds the common probes (ptrace/TracerPid, replaced parent, SIGSTOP/SIGTRAP, instrumentation artifacts, non-standard environment), the two consequences that invalidate experiments (a pass under translation is not a pass on hardware; your own tooling can be what trips the check), and the rule to run the unmodified original through identical conditions first.
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.
A process that dies right after attach is frequently the ROM, not a detector: backgrounding the app on aggressive OEM ROMs triggers a freeze whose logcat signature (state: R -> F) and lack of a Java stack look identical to a detector killing the session. Rule it out before building an anti-anti plan.
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.
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