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.
108 lines
5.2 KiB
Markdown
Executable file
108 lines
5.2 KiB
Markdown
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 `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](https://developer.android.com/studio/debug/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](https://mitmproxy.org/) (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](https://developer.android.com/studio) | `adb`, `apksigner` | Included with [Android Studio](https://developer.android.com/studio) |
|
|
| [Java / JDK](https://adoptium.net/) | `keytool` | Bundled with Android Studio, or `brew install --cask temurin` |
|
|
| [apktool](https://apktool.org/) | APK disassembly / reassembly | `brew install apktool` |
|
|
| [Docker](https://www.docker.com/products/docker-desktop/) | mitmproxy container (`--proxy` only) | [Docker Desktop](https://www.docker.com/products/docker-desktop/) |
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
- **`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
|