Skip to content

t1k:android-aab-obfuscation

FieldValue
Modulet1k-reverse-engineering
Version2.17.24
Effortlow
Tools—

Keywords: aab obfuscation, dex obfuscation, obfuscation ratio, obfuscation threshold, play obfuscation, proguard map, r8 ratio

/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.

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.

  1. BUNDLE-METADATA/com.android.tools.build.obfuscation/proguard.map is the R8 mapping the bundle carries. It may be gzipped (check the magic bytes 1f 8b before reading it as text).
  2. Column-0 lines of the form original.Name -> new: are classes. Indented lines are members; skip them. original != new means renamed (obfuscated); equal means kept. Skip entries starting with [.
  3. obfuscation % = renamed classes / total classes in the map.
  4. 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.
  5. 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.

obfuscation_check.py prints four R8 settings after the ratio verdict (on exit 0 and 1; exit 2 prints nothing new):

ItemSourceENABLED when
R8 Full Moder8.json options (compat key)the compat key is false (not ProGuard compatibility mode)
Repackage Classesr8.json optionsisRepackageClassesEnabled is true
Resource Shrinkingandroid analyze --analysis=optimization, resourceOptimizationStatusSTANDARD or OPTIMIZED
Resource Shrinking Optimizedsame statusOPTIMIZED

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.

Terminal window
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 report
python3 -I "$S/obfuscation_check.py" app.aab --threshold 28 # margin gate
python3 -I "$S/obfuscation_check.py" app.aab --json # machine-readable
python3 -I "$S/obfuscation_compare.py" old.aab new.aab 3 # which packages stopped being renamed
python3 -I "$S/obfuscation_compare.py" old.aab new.aab 4 --json
python3 -I "$S/r8_stats.py" app.aab [aab2 ...] [--json] # cross-check only
python3 -I "$S/aab_inputs.py" app.aab [aab2] [--json] # library list, or diff of two bundles
bash "$S/waydroid_test.sh" app.aab <outdir> [seconds=60] # install and launch smoke on a test device

On 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--jsonExit codes
obfuscation_check.pyyes0 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.pyyes0 report written, 2 usage, unreadable bundle, or no map
r8_stats.pyyes (JSON array of rows)0 read, 2 usage, unreadable bundle, or no r8.json
aab_inputs.pyyes0 read, 2 usage or unreadable bundle
waydroid_test.shno: prints one WAYDROID-TEST key=value summary line0 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.

Read the compare table by its columns:

Symptom in the compare tableRead it as
KEPT rose in a few packagesconsumer rules or project keep rules kept more: the classic own-goal
RENAMED fell, kept flat or downR8 removed code: fewer renamable classes (a toolchain change), not a config one
The library list changed as wellthe 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.

  • 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 --entry to measure another.
  • Read r8.json options before 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.json is not a clean bundle. It is a bundle where R8 did not run; stop and fix the build before measuring again.

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.

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.