110 lines
3.2 KiB
Markdown
110 lines
3.2 KiB
Markdown
# 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](../README.md).
|
|
|
|
## 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-setup.sh` only) | [Docker Desktop](https://www.docker.com/products/docker-desktop/) |
|
|
| [Android Emulator](https://developer.android.com/studio/run/emulator) | `proxy-setup.sh` only | Included with [Android Studio](https://developer.android.com/studio) |
|
|
|
|
## `make-debuggable.sh`
|
|
|
|
Converts release APKs into debuggable versions by disassembling, patching `AndroidManifest.xml`, reassembling, and re-signing with a debug keystore.
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./lib/make-debuggable.sh ./my-app-apks
|
|
# Output: ./my-app-apks_debuggable/
|
|
|
|
adb install-multiple ./my-app-apks_debuggable/*.apk
|
|
```
|
|
|
|
The script will:
|
|
1. Disassemble `base.apk` with `apktool`
|
|
2. Add `android:debuggable="true"` to `AndroidManifest.xml`
|
|
3. Reassemble with `apktool`
|
|
4. 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).
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
adb uninstall <package-id>
|
|
```
|
|
|
|
### apktool not found
|
|
```bash
|
|
brew install apktool
|
|
# or download apktool.jar to the script directory
|
|
```
|