86d8393dd4
This change introduces the ability to patch local APK files or directories, support for separate source and target devices, and detection of common anti-tampering libraries. Key changes: - **Local APK Support**: Added `--apk <path>` flag to use local `.apk` files or split-APK directories instead of pulling from a device. - **Two-Device Workflow**: Added `--source <serial>` flag to pull an APK from one device (e.g., a Play Store emulator) and install the patched version on another (e.g., a `userdebug` emulator). - **Anti-Tampering Detection**: The patching script now scans for known integrity-protection libraries (e.g., PairIP, DexGuard, Bangcle) and issues a warning if detected. - **Improved Disassembly**: Introduced a `--no-res` optimization when user certificate trust is not required, avoiding common `apktool` resource decoding errors. - **Package Name Extraction**: Integrated `aapt2` to automatically detect package names from local APK files for cleaner uninstalls. - **Enhanced Device Selection**: Updated the interactive menu to handle source/target selection and filter unauthorized devices more effectively. - **Documentation**: Updated `README.md` and `CLAUDE.md` with new usage examples and information regarding anti-tampering limitations.
5.2 KiB
Executable file
Android Make APK Debuggable
Extracts APKs from a connected Android device, makes them debuggable, and reinstalls — all in one command.
macOS only — uses BSD
sedand 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
--proxyflag) — 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:
- 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 |
|---|---|
--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:
- 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
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 debuggablelib/proxy-setup.sh— Start mitmproxy and restart an emulator with proxy enabled