# Mobile Pentest MCP Server — Extended

A full-featured MCP server for **authorized Android security testing** on your own
devices/accounts: static analysis (apktool, jadx, manifest, secrets scan), dynamic
analysis (Frida SSL/root bypass, intent fuzzing, deep links), storage inspection
(shared_prefs, SQLite), logcat, screenshots, traffic interception, and more.

Extends the original scaffold — **all original tools are preserved unchanged**.

## ⚠️ Authorization & scope

Use this **only** against apps where:

1. You have **written authorization** (public bug bounty with safe-harbor counts).
2. The mobile app is **explicitly in-scope**.
3. The program permits SSL pinning bypass / runtime instrumentation.
4. You test **only on your own test account(s)**.

For practice with no permission needed: **DVIA-v2**, **InsecureBankv2**,
**OWASP MSTG crackmes**, or your own builds.

---

## Components

```
mobile-pentest-mcp/
├── server.py                       # MCP server (39 tools)
├── setup_device.sh                 # one-time emulator + host setup
├── requirements.txt
├── claude_desktop_config.example.json
├── frida_scripts/
│   ├── ssl_pin_bypass.js           # TrustManager, OkHttp, Conscrypt, WebView, NSC
│   └── root_bypass.js              # File/Runtime/Build/PackageManager/RootBeer
├── apks/                           # pulled APKs
├── decoded/                        # apktool output
├── jadx_out/                       # jadx Java sources
├── appdata/                        # pulled /data/data/<pkg>
├── captures/                       # mitmproxy flow files
└── screenshots/                    # screencaps + recordings
```

## Prerequisites

**Python**: 3.10+, `pip install -r requirements.txt`

**System binaries** (install via your package manager):

| Tool | Purpose | Install |
|---|---|---|
| `adb` | device control | Android platform-tools |
| `frida`, `frida-server` | runtime instrumentation | `pip install frida-tools` + script setup |
| `mitmproxy` / `mitmdump` | HTTPS intercept | bundled in requirements.txt |
| `apktool` | decode APK resources/smali | `apt install apktool` / `brew install apktool` |
| `jadx` | Java decompile | `apt install jadx` / `brew install jadx` |
| `aapt` | APK metadata | Android SDK build-tools (`apt install aapt`) |
| `sqlite3` | DB queries | `apt install sqlite3` / `brew install sqlite` |

`setup_device.sh` checks each of these and tells you what's missing.

**Device**: Android Studio emulator with Google-APIs image (NOT Google Play), so
`adb root` succeeds. Pixel images work well.

---

## One-time setup

```bash
pip install -r requirements.txt

# Generate mitmproxy CA (run once, press q to quit)
mitmproxy

# Start your emulator from Android Studio, then:
chmod +x setup_device.sh
./setup_device.sh

# On the emulator: Settings > Security > Install certificate
#   -> /sdcard/mitmproxy-ca.cer  (install as CA cert)
```

## Register with Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac)
or `~/.config/Claude/claude_desktop_config.json` (Linux):

```json
{
  "mcpServers": {
    "mobile-pentest": {
      "command": "/full/path/to/venv/bin/python3",
      "args": ["/full/path/to/mobile-pentest-mcp/server.py"]
    }
  }
}
```

Important: use the **venv's python**, not system python, or `mcp`/`frida-tools`
modules won't be found. Restart Claude Desktop fully (Cmd+Q).

For **Claude Code**:

```bash
claude mcp add mobile-pentest /full/path/to/venv/bin/python3 /full/path/to/server.py
```

---

## Tools reference (39 total)

### Original — device + Frida + proxy (10)

| Tool | Purpose |
|---|---|
| `list_devices` | adb devices -l |
| `list_installed_apps` | user-installed packages |
| `pull_apk` | extract installed APK to apks/ |
| `install_apk` | install local APK |
| `launch_with_bypass` | spawn app with SSL pin + root bypass |
| `run_frida_script` | run a custom Frida JS |
| `start_proxy` | start mitmdump capture |
| `stop_proxy` | stop capture |
| `get_captured_flows` | summarize captured HTTPS flows |
| `check_safe_harbor_ack` | record scope acknowledgement |

### Static analysis (8)

| Tool | Purpose |
|---|---|
| `decode_apk_apktool` | apktool decode → resources + smali |
| `decompile_apk_jadx` | jadx → Java source |
| `get_apk_info` | aapt badging: pkg, version, SDK, native libs |
| `get_apk_manifest` | parsed AndroidManifest.xml + summary |
| `list_exported_components` | exported activities/services/receivers/providers |
| `check_security_flags` | debuggable, allowBackup, cleartext, NSC presence |
| `extract_apk_strings` | regex-grep smali/XML for any pattern |
| `scan_for_secrets` | preset regex pack: AWS, GCP, JWT, Slack, GitHub, HTTP URLs, Firebase |

### Dynamic / device (10)

| Tool | Purpose |
|---|---|
| `start_activity` | `am start -n pkg/.Activity` with extras |
| `send_intent` | broadcast / start / startservice with action+extras |
| `test_deep_link` | trigger URI scheme handler |
| `get_logcat` | filtered logcat (level, tag, PID) |
| `clear_logcat` | clear logcat buffers |
| `dumpsys_package` | parsed granted permissions + raw dumpsys |
| `get_running_processes` | ps -A on device |
| `take_screenshot` | screencap → screenshots/ |
| `record_screen` | screenrecord (N sec, max 180) → mp4 |
| `adb_shell` | allow-listed adb shell command runner |

### App storage (4)

| Tool | Purpose |
|---|---|
| `pull_app_data` | full /data/data/<pkg>/ (requires root) |
| `read_shared_prefs` | parse all SharedPreferences XML |
| `pull_databases` | pull all SQLite DBs |
| `query_sqlite` | run SELECT against pulled DB (read-only) |

### Network (3)

| Tool | Purpose |
|---|---|
| `check_cleartext_traffic` | manifest + NetworkSecurityConfig review |
| `adb_reverse_setup` | adb reverse tcp:X tcp:X |
| `device_netstat` | ss/netstat on device |

### Helpers (4)

| Tool | Purpose |
|---|---|
| `list_frida_scripts` | list scripts in frida_scripts/ |
| `save_frida_script` | write a new Frida JS file |
| `stop_frida` | kill running frida session |
| `get_state` | dump .state.json |

---

## Typical workflow

```text
1.  check_safe_harbor_ack(program, url, in_scope=true, test_account=true)
2.  install target via Play Store on emulator (manually)
3.  pull_apk(package)
4.  decode_apk_apktool(package=...)
5.  decompile_apk_jadx(package=...)
6.  get_apk_info / get_apk_manifest / list_exported_components
7.  check_security_flags / check_cleartext_traffic
8.  scan_for_secrets(package)
9.  start_proxy(8080)         # or run mitmweb separately
10. launch_with_bypass(package)
11. exercise the app on your test account
12. get_captured_flows(filter_host="api.target.com")
13. pull_app_data / read_shared_prefs / pull_databases / query_sqlite
14. get_logcat(package_pid_only=package)
15. start_activity / send_intent / test_deep_link  for exported components
16. stop_proxy / stop_frida
```

---

## Notes & limitations

- **Pinning bypass ≠ vulnerability**. SSL pinning is defense-in-depth.
  A bug report needs an actual impact (auth bypass, IDOR, exposed PII).
- **Native pinning** (BoringSSL in NDK) won't be caught by the JS bypass.
- **Frida detection**: some apps detect `frida-server` — try renaming binary
  or use a stealth fork.
- **Play Integrity / SafetyNet** will fail on rooted emulator. Apps that
  hard-block on it won't run.
- `adb_shell` is allow-listed (read-ish commands only). For destructive ops,
  use the specific named tool.
- `query_sqlite` only allows SELECT/PRAGMA — write operations are blocked.
- `pull_app_data`, `read_shared_prefs`, `pull_databases` require **root** on
  the device. Google-APIs emulators support `adb root`; Google Play emulators
  do not.

## What this is *not*

- Not a way to attack apps you don't have permission for.
- Not a way to bypass auth, scrape other users' data, or distribute modified APKs.
- Not a vulnerability scanner — it gives you visibility so you can find issues.