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

# Use a local APK file (useful for emulators without Play Store)
./apk-debuggable.sh --apk ./some-app.apk --device emulator-5554

# Use a local split-APK directory
./apk-debuggable.sh --apk ./split-apks/ --proxy

The script will:

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

Options

| Flag | Description | |------|-------------| | --apk <path> | Use a local APK file or split-APK directory instead of pulling from the device | | --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:

1. Open Settings → search "certificate"
2. Tap "Install a certificate" → "CA certificate"
3. Tap "Install anyway"
4. 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

Limitations

Anti-tampering protection — Some apps include native integrity-checking libraries (e.g. PairIP, DexGuard) that detect APK modifications and crash on launch. The script detects known anti-tampering libraries and warns you, but it cannot bypass them.

Workaround: Use a "Google APIs" emulator image (not "Google Play") — these are userdebug builds where all apps are debuggable by default (ro.debuggable=1), no APK patching needed. Since these images don't include the Play Store, use --apk to install a local APK: ./apk-debuggable.sh --apk ./app.apk --device emulator-5554.

Certificate pinning — Apps that pin specific server certificates (common in banking apps) will reject connections even with the CA installed. Bypassing pinning requires tools like Frida, which is out of scope.

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