# 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`:

![Intercepting Wikipedia API traffic with mitmproxy](doc/screenshot.png)

## 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