t1k:android-aab-obfuscation
| Field | Value |
|---|---|
| Module | t1k-reverse-engineering |
| Version | 2.17.24 |
| Effort | low |
| Tools | — |
Keywords: aab obfuscation, dex obfuscation, obfuscation ratio, obfuscation threshold, play obfuscation, proguard map, r8 ratio
How to invoke
Section titled “How to invoke”/t1k:android-aab-obfuscation<aab> [--threshold 25] [--json] | compare <old.aab> <new.aab> [depth] | r8 <aab> | inputs <aab> [aab2]Android AAB obfuscation: measure and diagnose
Section titled “Android AAB obfuscation: measure and diagnose”Answers “will Google Play accept this bundle’s obfuscation, and if it dropped, from where?” without re-uploading. It is a proxy. Play computes its metric on the DEX, and only Play’s own upload is authoritative. This skill measures the closest thing an AAB exposes locally.
AAB is not APK. Read the bundle. Local .apk analysis (dex string tables, class-name heuristics) is
the wrong surface for a Play review that runs on the bundle.
No build tool, no Editor, no network. Pure zip reads, parallel-safe. Run the scripts; do not rebuild the app to measure it.
Headline number
Section titled “Headline number”Prefer Google’s Android CLI when it is installed. android analyze --analysis=optimization --format=json app.aab
prints mappingObfuscationRatio, the figure Android vitals falls back to when r8.json does not match the
DEX (r8DexChecksumStatus: NO_MATCH). It counts classes, methods and fields, so it tracks Play more closely
than the class ratio. Install without root or Java: download
https://dl.google.com/android/cli/latest/linux_x86_64/android to ~/.local/bin.
The class-only ratio is a diagnostic, not the gate. It is renamed classes divided by total classes from
BUNDLE-METADATA/com.android.tools.build.obfuscation/proguard.map (see Method). It ignores members, and
narrowing a keep rule can lower it while more classes get renamed, because renamed and kept classes leave
the numerator and the denominator together. Never call a narrowing a win or a failure from the class ratio
alone: read mappingObfuscationRatio and the per-package obfuscation_compare.py table beside it.
Gate: 25% minimum (the script default), aim for 28% or more.
r8.json is a cross-check, never the headline. R8 writes stats.noObfuscationPercentage,
noOptimizationPercentage and noShrinkingPercentage to BUNDLE-METADATA/com.android.tools/r8.json. The
100 - value formula has matched Play on some bundles and not on others. A negative or above-100 stat
proves that block is unusable for that bundle; r8_stats.py prints a WARNING. When r8.json and the map
disagree, the map wins. Optimization and shrinking percentages exist only in r8.json: report them as
unverified when the obfuscation stat already disagrees with the map. The options object in the same file
shows what R8 actually ran; read it before blaming a keep rule.
No r8.json or no proguard.map means R8 did not run. That is an error, never a pass.
Method (what the numbers mean)
Section titled “Method (what the numbers mean)”BUNDLE-METADATA/com.android.tools.build.obfuscation/proguard.mapis the R8 mapping the bundle carries. It may be gzipped (check the magic bytes1f 8bbefore reading it as text).- Column-0 lines of the form
original.Name -> new:are classes. Indented lines are members; skip them.original != newmeans renamed (obfuscated); equal means kept. Skip entries starting with[. obfuscation % = renamed classes / total classesin the map.- Clean stray punctuation or inner-class names before trusting a cross-version delta. A dotted package prefix is what makes the per-package table readable.
- Calibration: the map ratio tracked Play’s reported figure within about four points, in both directions, on the bundles measured so far. Confirm which Play version a Console figure belongs to (by version code) before comparing.
R8 configuration report
Section titled “R8 configuration report”obfuscation_check.py prints four R8 settings after the ratio verdict (on exit 0 and 1; exit 2 prints nothing new):
| Item | Source | ENABLED when |
|---|---|---|
| R8 Full Mode | r8.json options (compat key) | the compat key is false (not ProGuard compatibility mode) |
| Repackage Classes | r8.json options | isRepackageClassesEnabled is true |
| Resource Shrinking | android analyze --analysis=optimization, resourceOptimizationStatus | STANDARD or OPTIMIZED |
| Resource Shrinking Optimized | same status | OPTIMIZED |
Each item is ENABLED, DISABLED or UNKNOWN. UNKNOWN means the value could not be read, and the reason is
printed (for example no r8.json in the bundle, android CLI not found on PATH). UNKNOWN is not a pass: it is
never shown as ENABLED, and r8_options_all_enabled is null when nothing is disabled and at least one item is
unknown. A disabled or unknown item never changes the exit code.
The two resource items need the Android CLI on PATH. It is optional: without it those two items are UNKNOWN and
the r8.json items still read. The CLI may print a first-run download line on stdout; the check ignores it. For Unity builds, the R8 options and their remediation live in the Play
obfuscation remediation skill of theonekit-unity (base module).
Every run prints the same note: R8 Full Mode, Resource Shrinking, Resource Shrinking Optimized and Repackage
Classes must all be enabled. JSON keys: r8_options (state per item), r8_options_all_enabled (true, false
or null), r8_options_unknown (reason per unknown item) and r8_options_note.
S="$(ls -d .claude/skills/t1k-android-aab-obfuscation "$HOME/.claude/skills/t1k-android-aab-obfuscation" 2>/dev/null | head -1)/scripts"python3 -I "$S/obfuscation_check.py" app.aab # PASS/FAIL vs 25%, plus the R8 configuration reportpython3 -I "$S/obfuscation_check.py" app.aab --threshold 28 # margin gatepython3 -I "$S/obfuscation_check.py" app.aab --json # machine-readablepython3 -I "$S/obfuscation_compare.py" old.aab new.aab 3 # which packages stopped being renamedpython3 -I "$S/obfuscation_compare.py" old.aab new.aab 4 --jsonpython3 -I "$S/r8_stats.py" app.aab [aab2 ...] [--json] # cross-check onlypython3 -I "$S/aab_inputs.py" app.aab [aab2] [--json] # library list, or diff of two bundlesbash "$S/waydroid_test.sh" app.aab <outdir> [seconds=60] # install and launch smoke on a test deviceOn Windows, run the Python scripts as python -I or py -I: the python.org installer ships no python3 command.
Required environment for waydroid_test.sh: BUNDLETOOL_DIR (a directory holding bundletool-all.jar; a
throwaway test keystore is created there), APP_ID, LAUNCH_ACTIVITY. Optional: JDK_BIN (otherwise the
java on PATH is used), WAYDROID_ADB (the device address; set it explicitly for your device).
| Script | --json | Exit codes |
|---|---|---|
obfuscation_check.py | yes | 0 PASS, 1 FAIL (below threshold), 2 usage, no map, or unreadable bundle. A disabled or unknown R8 item never changes the exit code |
obfuscation_compare.py | yes | 0 report written, 2 usage, unreadable bundle, or no map |
r8_stats.py | yes (JSON array of rows) | 0 read, 2 usage, unreadable bundle, or no r8.json |
aab_inputs.py | yes | 0 read, 2 usage or unreadable bundle |
waydroid_test.sh | no: prints one WAYDROID-TEST key=value summary line | 0 the smoke ran (read alive and fatal_lines), 2 setup failed (no JDK, bundletool, or install) |
A missing map is exit 2, never a pass: it means minify did not run for that build.
The scripts are read-only, except waydroid_test.sh, which writes into its <outdir> and installs the APK
on the test device it is pointed at.
Diagnosing a drop
Section titled “Diagnosing a drop”Read the compare table by its columns:
| Symptom in the compare table | Read it as |
|---|---|
| KEPT rose in a few packages | consumer rules or project keep rules kept more: the classic own-goal |
| RENAMED fell, kept flat or down | R8 removed code: fewer renamable classes (a toolchain change), not a config one |
| The library list changed as well | the toolchain or SDK set moved: correlate the version with the drop first |
A renamed fall with a flat kept count is not a configuration regression, and trimming keep rules cannot fix it. Build the same source with the previous toolchain version to prove it.
Dependencies that ship their own consumer rules (ad networks, analytics, attribution SDKs) keep code that no project rule can undo. Measure before and after removing one dependency rather than editing its rules.
Hard rules
Section titled “Hard rules”- Gzipped map. Read the first two bytes before opening the file as text. A gzip body read as text yields zero classes and a bogus 0% or a divide-by-zero.
- Member lines look like class lines. Only column-0
->lines are classes. Counting members inflates the denominator and flattens the percentage. # {...sourceFile...}lines carry JSON, not->entries. A regex parse that treats them as entries miscounts.- The base module is not the only split. Feature and asset-pack modules carry their own
proguard.map. A ratio read only from the base split misses those classes. The tool reads the base one and says so; pass--entryto measure another. - Read
r8.jsonoptionsbefore concluding. The options R8 actually ran change the numbers more than most keep rules do. - Do not read large binaries whole (native libraries, dex files) to find a version. Scan the small metadata entries the tool names; a whole-file read balloons memory for no gain.
- A bundle without
r8.jsonis not a clean bundle. It is a bundle where R8 did not run; stop and fix the build before measuring again.
Remediation (out of scope)
Section titled “Remediation (out of scope)”Raising the ratio (keep-rule edits, toolchain or optimisation options, padding classes, SDK rule files) changes the build. It belongs to the engine kit that produces the bundle, and this skill only measures and diagnoses. Engine-specific remediation lives in the engine kit’s own skill, and the Unity kit ships one. Do not ask this skill to propose keep-rule changes.
Executed by
Section titled “Executed by”The four Python tools and waydroid_test.sh are deterministic reads or a smoke run. Any caller may run them
and quote their output verbatim. The diagnosis (which packages stayed kept, what a drop means) and any change
to keep rules stay with the reasoning caller.
Measuring and diagnosing the obfuscation ratio of an Android App Bundle, and an install-and-launch smoke on a
test device. Not: build gates, build toolchain edits, bundle size, the Play upload, or the obfuscator’s own
settings. To prove an obfuscated build actually ran and can be debugged, see
references/obfuscated-build-verification.md.