Medusa: a modular Frida layer for Android and iOS runtime analysis

What the framework is actually wrapping

Medusa describes itself as a modular automation framework and script repository for runtime testing and investigating Android and iOS apps, and it runs on Frida underneath. That last clause is the important one. Medusa is not an instrumentation engine; it is a curated, organised, reusable layer of Frida scripts with a command line in front of them.

The module count is the headline: 90-plus reusable modules, so a test that would otherwise be twenty lines of hand-written hooking becomes a directory you select. The README lists the categories those modules cover: bypassing protections such as SSL pinning, inspecting network and WebView activity, tracing API calls, examining memory and crypto, and monitoring malware behaviour.

The framing is notable. This is written for penetration testers and malware analysts, and the malware monitoring category is not a secondary use case, it is one of the stated ones. That is the same reason Frida exists, and understanding that tells you what kind of tool you are installing before you read a single module.

Install, and the readline trap on macOS

System requirements are Linux or macOS with limited functionality on Windows, Python 3, a rooted device or emulator, adb, and a Frida server running on the mobile device. That last item is the one people underestimate. Nothing works without it.

The install is a clone and a dependency install, and the README recommends a virtualenv:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

The dependency list is short and tells you what you are getting: frida, frida-tools, androguard, requests, apkInspector, cmd2, click, colorama, pick, PyYAML, packaging and urllib3. `cmd2` is the reason the CLI has tab completion, `androguard` and `apkInspector` do static work, and `colorama` colours the output.

Then the documented failure mode, which is worth reading before you hit it. On macOS, installation can print a warning that readline features including tab completion have been disabled because no supported version of readline was found. The fix is:

pip install gnureadline

For Python 3.12 specifically, the README pins a commit rather than the latest release, which is the kind of detail that saves an hour of debugging.

Running Medusa in a container over ADB

A Dockerfile ships in the repository, and the four-step sequence in the README is specific enough to follow exactly.

The image is built with `docker build -t medusa:latest ./` and run with:

docker run --name medusa --net=host --rm -it medusa:latest

Host networking is not incidental. Step three is enabling ADB over TCP on the device or emulator with `adb tcpip 5555`, and step four is connecting from inside the container with `adb connect <device_ip>:5555`. Without host networking the container cannot reach the device port you just opened. The Dockerfile installs `android-tools-adb` and `git`, clones the repository, upgrades pip, and installs requirements.

Note that the container is a convenience for having the Python environment already correct. It does not solve the rooting requirement, and the container itself still needs a device it can talk to.

The interactive loop: loaddevice, use, run

Starting the tool picks the right entry point per platform, and both scripts then enumerate available devices and let you choose one:

python3 medusa.py
python3 medusa_ios.py

The shell is a REPL. `help` lists commands, `show all` lists modules, `info` gives detail on one, `use` adds a module with Tab completion on the path, `list` shows packages installed on the device, `run -f` instruments a package by its package name, and `loaddevice` shows and selects devices.

The order matters and is the thing to internalise before you start exploring. You load a device, you add modules, then you run against a package. Loading `http_communications/` and then running against a target gives you network interception with pinning bypass already attached, which is exactly the workflow the demos show.

There is also a socket server, started with `startserve`, which is how the Stheno subproject talks to Medusa. Stheno is a separate project for intent monitoring, and the README shows adding the `intents/start_activity` module with `add intents/start_activity` as the setup step.

Mango for the static half, and what belongs in the database

Mango is described as a lightweight companion CLI for static prep and automation: manifest parsing, attack-surface enumeration, app tracking and simple device or proxy automation. It runs as `python3 mango.py <database-name>`, which creates or loads a database for storing results.

That database is the part with a maintenance cost. Mango results persist, which means a Mango database from one version may not match the schema of a later one. The README calls this out directly, pointing at a `DATABASE_MIGRATIONS.md` guide in the assets documentation, and the v3.2.0 release notes carry a pull request adding a migration guide for Mango compatibility against issue 88.

The Mango commands mirror Medusa's where it overlaps: `loaddevice`, `pull` by package name, `import /path/to/apk` for analysis of a file you already have. Later releases added manifest diffing across app versions, so you can compare permissions and components between two builds, and multi-session support for running several Medusa sessions in parallel.

The MCP server, and where the documentation actually is

v3.9.6, published 2026-04-28, added an MCP server, and this is the newest thing in the project. It is optional and separate from the CLI workflow. Installing it means the MCP requirements, then starting it with an explicit transport:

MEDUSA_MCP_TRANSPORT=streamable-http python medusa_android_mcp.py

The client configuration block the README shows points at `http://127.0.0.1:8000/mcp` over http. The practical reading is that an agent can now drive Medusa's Android instrumentation rather than a person typing `use` and `run` at a prompt. That is a real change in how the tool gets used, and it is also the least documented part, so expect to read the wiki.

Almost everything advanced lives at the wiki rather than in the README. The README's own scope is install, first run, the two CLIs, and the MCP server. Modules, module creation and workflow detail are wiki territory. The README compensates by linking a list of community demos: penetration testing walkthroughs and malware analysis sessions credited to ByteTheories, an APK unpacking session credited to cryptax, another credited to LaurieWired, a memory inspection session, and a bypass-root-detection writeup.

Editorial conclusion

Medusa is for the part of mobile security work that static analysis cannot answer: what the app does after it launches, which endpoints it actually calls, and where it decides something is being tampered with. The cost is a rooted device or emulator and a willingness to learn a module-oriented workflow rather than write raw Frida scripts each time. Two things to check before committing an afternoon: whether your target is instrumentable at all, since the framework depends on Frida server running on the device, and whether the Mango database you already have needs migrating. Start with the pip install in a virtualenv, attach to one emulator with `loaddevice`, and run `info` on a single module before loading a whole directory. The last push was on 2026-09-06 and v3.9.6 shipped on 2026-04-28.

Frequently asked questions

Official sources

1. Ch0pin/medusa on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases