Android Make APK Debuggable

Extracts APKs from a connected Android device, makes them debuggable, and reinstalls — all in one command.

macOS only — uses BSD sed and searches macOS-specific paths for Android Studio and JDK.

Why?

Release APKs ship without the android:debuggable flag, which locks out most development tools. This project patches that flag back in so you can:

Inspect layouts and view hierarchies with Android Studio's Layout Inspector — useful for understanding how a third-party app builds its UI, debugging rendering issues, or reverse-engineering screen flows.
Attach a debugger to a running process via Android Studio's "Attach Debugger to Android Process", allowing you to set breakpoints and step through code in apps you don't have the source for.
Intercept HTTPS traffic with mitmproxy (via the --proxy flag) — the script also patches the app's network security config to trust user-installed CA certificates, which Android blocks by default since API 24. This lets you inspect API requests, debug authentication flows, or audit data the app sends over the network.

Example: intercepting Wikipedia's API calls with mitmproxy after patching the app with ./apk-debuggable.sh wikipedia --proxy:

Requirements

Tool	Purpose	Install
Android SDK	`adb`, `apksigner`	Included with Android Studio
Java / JDK	`keytool`	Bundled with Android Studio, or `brew install --cask temurin`
apktool	APK disassembly / reassembly	`brew install apktool`
Docker	mitmproxy container (`--proxy` only)	Docker Desktop

Usage

# Search for an app by name, extract, patch, and reinstall
./apk-debuggable.sh myapp

# Specify a device if multiple are connected
./apk-debuggable.sh myapp --device emulator-5554

# Keep intermediate files for inspection
./apk-debuggable.sh myapp --keep

# Intercept HTTPS traffic with mitmproxy (requires Docker)
./apk-debuggable.sh myapp --proxy

The script will:

Find connected devices (interactive menu if multiple)
Search for matching packages (interactive menu if multiple)
Pull APKs from the device
Make them debuggable (via lib/make-debuggable.sh)
Uninstall the original and install the debuggable version

Options

Flag	Description
`--device <serial>`	Use a specific device (from `adb devices`)
`--keep`	Keep intermediate files (pulled APKs and patched APKs)
`--trust-user-certs`	Trust user-installed CA certificates (for HTTPS interception)
`--proxy`	Start mitmproxy in Docker (implies `--trust-user-certs`, requires Docker)

Traffic Interception (mitmproxy)

The --proxy flag handles everything — makes the app debuggable, patches it to trust user CA certs, reinstalls it, starts mitmproxy in Docker, and pushes the CA certificate to the device:

./apk-debuggable.sh myapp --proxy

Then install the CA certificate on the device:

Open Settings → search "certificate"
Tap "Install a certificate" → "CA certificate"
Tap "Install anyway"
Select "mitmproxy-ca-cert.cer" from internal storage

Open the mitmproxy web UI to inspect traffic:

http://localhost:8081
Password: proxy

Stop the proxy when done:

docker stop mitmproxy-android

Advanced / Standalone Usage

The helper scripts in lib/ can be used independently for more control over individual steps. See lib/README.md for details on:

lib/make-debuggable.sh — Patch a single APK or split APK directory to be debuggable
lib/proxy-setup.sh — Start mitmproxy and restart an emulator with proxy enabled

4 KiB Executable file Raw Blame History