marijo/apk-debuggable
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: Add support for local APKs, multi-device workflows, and anti-tampering detection

Browse source 
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.
This commit is contained in:
benjamin-luescher 2026-03-05 08:58:43 +01:00
parent 0c5c835263
commit 86d8393dd4
4 changed files with 339 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

15
README.md
View file

@ -39,6 +39,12 @@ Example: intercepting Wikipedia's API calls with mitmproxy after patching the ap
# 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:
@ -52,6 +58,7 @@ The script will:
| 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) |
@ -85,6 +92,14 @@ 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](https://frida.re/), 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](lib/README.md) for details on: