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. |
||
|---|---|---|
| .. | ||
| make-debuggable.sh | ||
| proxy-setup.sh | ||
| 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:
- Disassemble
base.apkwithapktool - Add
android:debuggable="true"toAndroidManifest.xml - Reassemble with
apktool - 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