apk-debuggable/lib/README.md

Helper Scripts

These scripts can be used standalone for more control over individual steps. For the automated end-to-end flow, see the root README.

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-setup.sh only)	Docker Desktop
Android Emulator	proxy-setup.sh only	Included with Android Studio

make-debuggable.sh

Converts release APKs into debuggable versions by disassembling, patching AndroidManifest.xml, reassembling, and re-signing with a debug keystore.

Usage

# Single APK
./lib/make-debuggable.sh <path-to-apk> [output-apk] [--trust-user-certs]

# Split APK directory (contains base.apk + split APKs)
./lib/make-debuggable.sh <directory> [output-directory] [--trust-user-certs]

Single APK Mode

./lib/make-debuggable.sh app.apk
# Output: app_debuggable.apk

adb install app_debuggable.apk

Split APK Mode

For apps distributed as split APKs, put all APKs in a directory and pass the directory path:

./lib/make-debuggable.sh ./my-app-apks
# Output: ./my-app-apks_debuggable/

adb install-multiple ./my-app-apks_debuggable/*.apk

The script will:

1. Disassemble base.apk with apktool
2. Add android:debuggable="true" to AndroidManifest.xml
3. Reassemble with apktool
4. Re-sign all APKs with a debug keystore

--trust-user-certs

Android API 24+ apps only trust system CA certificates by default. This flag injects a network_security_config.xml that tells the app to also trust user-installed certificates (like the mitmproxy CA).

./lib/make-debuggable.sh ./my-app-apks --trust-user-certs

proxy-setup.sh

Starts mitmproxy in Docker, restarts a running Android emulator with HTTP proxy enabled, and installs the mitmproxy CA certificate.

Usage

# Start proxy and restart emulator with proxy enabled
./lib/proxy-setup.sh

# Use a custom proxy port
./lib/proxy-setup.sh --port 9090

# Stop the proxy
./lib/proxy-setup.sh --stop

Workflow

For a typical interception setup using proxy-setup.sh separately:

# Start proxy and restart emulator with proxy enabled
./lib/proxy-setup.sh

# Make the app trust user-installed CA certs and install it
./apk-debuggable.sh myapp --trust-user-certs

# When done, stop the proxy
./lib/proxy-setup.sh --stop

Troubleshooting

INSTALL_FAILED_MISSING_SPLIT

The APK requires split APKs. Pull all APKs from the device and use directory mode.

Signature mismatch

Uninstall the original app before installing the debuggable version:

adb uninstall <package-id>

apktool not found

brew install apktool
# or download apktool.jar to the script directory