phobos

A modular web platform for Android Mobile Application Penetration Testing (MAPT), focused on automating the repetitive setup tasks involved in dynamic analysis.

---

Features

Module	Description	Status
Device Manager	Discover and manage local (USB/TCP) and remote devices (Corellium)	✅ Available
Shell	Interactive terminal via WebSocket (adb shell)	✅ Available
Proxy Setup	Configure Wi-Fi proxy on device to intercept traffic with Burp Suite	✅ Available
Certificate Manager	Push and install Burp CA certificate (user store + system store)	🚧 In progress
File System Browser	Browse app data directory, download files and folders	🔜 Planned
Frida Bridge	Frida server management, script library, hook builder, Objection bridge	🔜 Planned

---

Requirements

System dependencies

These tools must be installed on your machine and available in your PATH:

Tool	Purpose	Install
adb (Android Debug Bridge)	Communicate with Android devices	Part of Android SDK Platform Tools
Python 3.11+	Run the backend	python.org
frida-tools	Required only for the Frida Bridge module	pip install frida-tools

Verify ADB is working:

adb version
adb devices

Android device requirements

• USB debugging enabled (Settings → Developer options → USB debugging)
• For TCP/IP connection: adb tcpip 5555 run once while connected via USB
• For system certificate installation: rooted device or Magisk installed

---

Installation

# 1. Clone the repository
git clone https://github.com/vincenzo-emanuele/phobos.git
cd phobos

# 2. Create and activate a virtual environment (recommended)
python -m venv venv

# Mac/Linux
source venv/bin/activate
# Windows
venv\Scripts\activate

# 3. Install Python dependencies
pip install -r backend/requirements.txt

# 4. Install the project package (makes imports work correctly)
pip install -e .

---

Running the server

# From the project root (phobos)
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000.
Interactive API docs (Swagger UI): http://localhost:8000/docs

---

API Overview

Device Manager

Method	Endpoint	Description
GET	/api/devices	List known devices
POST	/api/devices/refresh	Re-discover ADB devices
POST	/api/devices/connect	Connect a device via TCP/IP
POST	/api/devices/disconnect/{serial}	Disconnect a TCP/IP device
POST	/api/devices/active	Set the active device
GET	/api/devices/active	Get active device info

Shell

Method	Endpoint	Description
WS	/api/shell/ws/{serial}	Interactive shell (WebSocket)
POST	/api/shell/execute	Run a single command and get output

Health

Method	Endpoint	Description
GET	/api/health	Server health check

---

Usage workflow

1. Start the server
2. POST /api/devices/refresh        → discover connected devices
3. POST /api/devices/connect        → (optional) connect remote/TCP device
4. POST /api/devices/active         → select the device to work on
5. Use any module (shell, proxy, filesystem, ...)

---

Running tests

# Unit tests only (no device required)
python -m pytest tests/ -v -m "not integration"

# Integration tests (requires a connected ADB device or running emulator)
python -m pytest tests/ -v -m integration

---

Project structure

phobos/
├── backend/
│   ├── main.py                  # FastAPI entrypoint
│   ├── config.py                # Global settings
│   ├── requirements.txt
│   ├── core/
│   │   ├── adb_client.py        # ADB wrapper
│   │   ├── device_manager.py    # Device registry and factory
│   │   └── corellium_client.py  # Corellium API client (planned)
│   └── modules/
│       ├── device_router.py     # Device Manager REST endpoints
│       ├── shell/
│       │   └── router.py        # Shell WebSocket + execute endpoint
│       ├── proxy/
│       ├── certificates/
│       ├── filesystem/
│       └── frida_bridge/
│           └── scripts/         # Built-in Frida script library
│               ├── ssl/
│               ├── root/
│               └── crypto/
├── tests/
│   └── test_device_manager.py
├── pyproject.toml
├── pytest.ini
└── README.md

---

Adding a new module

Each module is self-contained. To add one:

1. Create a folder under backend/modules/your_module/
2. Add __init__.py and router.py
3. Register the router in backend/main.py:

   from backend.modules.your_module.router import router as your_router
   app.include_router(your_router, prefix="/api")

No other files need to be touched.

---

Compatibility

Target	Notes
Android 10 – 14	Fully supported
Android 15+	Tested where noted per module
Corellium	Remote device support via TCP/IP ADB
Local emulator	Supported (AVD, Genymotion)

---

Disclaimer

This tool is intended for authorized security testing only. Only use it against devices and applications you own or have explicit written permission to test. The authors are not responsible for any misuse.

---

License

MIT