Metadata-Version: 2.4
Name: mobile-security-mcp
Version: 0.1.3
Summary: MCP server exposing Android security research tools for authorised penetration testing
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: frida>=16.0.0
Requires-Dist: frida-tools>=12.0.0
Requires-Dist: androguard>=3.4.0a1
Requires-Dist: apkid>=2.1.0
Requires-Dist: apkleaks>=2.6.0
Requires-Dist: quark-engine>=23.0.0
Requires-Dist: mitmproxy>=10.0.0
Requires-Dist: textual>=0.50.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: sse
Requires-Dist: starlette>=0.30.0; extra == "sse"
Requires-Dist: uvicorn>=0.23.0; extra == "sse"

# mobile-security-mcp

> **Legitimate penetration testing toolkit** — for use only on applications you are authorised to test.

An MCP (Model Context Protocol) server that effortlessly transforms any AI agent (Claude Code, Cline, Goose, OpenCode) into an elite Android security researcher by providing them direct access to the industry's most powerful reverse-engineering stack.

## ✨ Zero-Touch Automation

This MCP server features **Zero-Touch automated configuration**. It comes equipped with native Python downloaders that securely fetch, extract, and configure all the massive reverse-engineering binaries directly into `~/tools/`—injecting them dynamically into your environment without forcing you to manually run `brew`, `apt`, or `choco` commands.

Just run the setup command, and it builds the entire penetration testing environment out of thin air:

```bash
# 1. Install via pip
pip install mobile-security-mcp

# 2. Run the Zero-Touch Setup (installs apktool, jadx, adb, frida, etc.)
python -m mobile_security_mcp --setup
```

## 🛠️ The Arsenal (Tools for Agents)

When an AI Agent connects to this server, they gain autonomous execution capability over the following tools:

### Static Analysis & Reversing
* **`apk_decompile`**: Unpacks APK via `apktool` (Smali).
* **`apk_decompile_java`**: Hardware-accelerated source code extraction via `jadx`.
* **`apk_identify`**: Uses `apkid` to fingerprint packers, obfuscators, and SDKs.
* **`apk_scan_secrets`**: Scans the codebase for high-entropy secrets and keys.
* **`search_strings`**: Ultra-fast regex string hunting over decompiled code.

### Dynamic Instrumentation (Frida)
* **`frida_spawn`**: Spawns an app with early-instrumentation capabilities.
* **`frida_attach`**: Attaches to a running application process.
* **`frida_inject`**: Pushes raw JS or executes library bypass scripts live in memory.
* **`objection_run`**: High-level commands to explore application memory, classes, and SSL.

### RASP & Anti-Tamper Bypass
* **`rasp_identify`**: Identifies active enterprise app protections (Zimperium, DexGuard, Promon, Arxan).
* **`rasp_bypass`**: Dynamically generates targeted Frida bypass scripts for root detection, SSL pinning, and emulator checks.

### Cross-Platform Scaffolding
* **`hermes_decode`**: Extracts and decompiles React Native `.hbc` bundles to raw JSX.
* **`flutter_blutter`**: Scaffolds Flutter engine un-stripping and dart-compile recovery.

### Device Control & Visuals
* **`adb_shell`** / `adb_pull` / `adb_push`: Direct device bridging.
* **`scrcpy_start`**: Starts a background hardware-accelerated screen mirror.
* **`scrcpy_screenshot`**: Takes a pristine UI screenshot so the Agent can visually understand the app state.

### Manipulation & Signing
* **`apk_sign`**: Zipsigner & uber-apk-signer automation.
* **`apk_rebuild_sign`**: Re-compiles a modified Smali directory and re-signs it for immediate device installation.

## 🧠 Master Agent Workflow

This server ships with a massive built-in knowledge-base (`master-agent-workflow`) that AI agents read when they boots up. It enforces strict, logical reverse engineering methodologies, forcing agents to:
1. Start with static mapping instead of blind dynamic analysis.
2. Establish "Memory Profiles" using `memory_write` to keep persistent states over long sessions.
3. Consult built-in escalation playbooks (`bypass-ssl`, `bypass-root`) if they get stuck.

## 🚀 Installation & Agent Integration

### Claude Code
```json
// .claude/mcp.json
{
  "mcpServers": {
    "mobile-security": {
      "command": "python",
      "args": ["-m", "mobile_security_mcp"]
    }
  }
}
```

### Cline (VSCode)
```json
"cline.mcpServers": {
  "mobile-security": {
    "command": "python",
    "args": ["-m", "mobile_security_mcp"]
  }
}
```

## 🤝 Contributing & Requesting Tools

We want to build the ultimate open-source, AI-driven Mobile Security framework. We welcome forks, pull requests, and community-driven knowledge!

**Visit the Repository**: [github.com/mobile-security-mcp/mobile-security-mcp](https://github.com/mobile-security-mcp/mobile-security-mcp) *(Replace with actual repository link)*

### Have a tool suggestion?
If you maintain a fork or just love a specific open-source tool (like `MobSF`, `RMS`, `Medusa`, etc.), please **open an issue** at the link above! We are actively looking to add new handlers for:
* iOS decryption and LLDB bridging.
* Advanced unpacking tools.
* Web3 / Wallet security analyzers.

Feel free to fork the repo, create a new handler in `mobile_security_mcp/handlers/`, and submit a Pull Request!

---
> **Disclaimer**: This tool is for educational and authorized penetration testing purposes only. You are solely responsible for ensuring you have explicit written permission before testing any application.
