National Cyber Warfare Foundation (NCWF)login

medusa for coordinated runtime testing of Android and iOS apps


0 user ratings
2026-11-17 21:25:22
milo
Red Team (CNA)
"medusa

medusa is a modular FRIDA-based automation framework that unifies runtime instrumentation, traffic inspection, and malware investigation for authorized mobile pentesters and analysts.








ToolCh0pin/medusa — modular runtime testing and instrumentation framework for Android and iOS apps, built on FRIDA
CategoryMobile application dynamic analysis and instrumentation framework
Primary UseAuthorized penetration testing and malware analysis of mobile apps: SSL pinning bypass, WebView and intent monitoring, API tracing, memory and crypto inspection via FRIDA hooks
Safe UseIntended for penetration testers and malware analysts working on applications and devices they are explicitly authorized to test, in lab environments or sanctioned engagements
Telemetry NoteRequires a FRIDA server on the target device and produces instrumented process behavior; anti-tampering and EDR-on-device controls commonly detect FRIDA injection, so its use is observable by defensive tooling

medusa, hosted at Ch0pin/medusa, describes itself as a modular automation framework and script repository for runtime testing and investigating Android and iOS applications. It sits squarely in the professional mobile security toolkit space: rather than scattering dozens of one-off FRIDA scripts across a working directory, it coordinates them under a single interactive shell with a module system, tab-completion, and per-platform command sets. With roughly 2,300 stars, a GPL-3.0 license, and a Python codebase, it is one of the more actively shaped entries in the mobile instrumentation niche, and the README makes clear that its audience is penetration testers and malware analysts rather than casual tinkerers.


The architecture is what makes medusa interesting. Under the hood it runs on FRIDA, the standard dynamic instrumentation toolkit, but it wraps that engine in a curated repository of more than 100 reusable modules. Each module encapsulates a specific investigative task — the README names SSL pinning bypass under http_communications/ssl-pinning-bypass, network and WebView inspection, API call tracing, memory and crypto examination, and malware behavior monitoring. The effect is that a tester composes an engagement from pre-built, reviewable pieces instead of writing ad-hoc hooking code for every target, which makes results repeatable and the methodology auditable after the fact.


Platform coverage is unified in the current development line. The launcher enumerates available devices at startup and lets the operator pick one, with device OS detection selecting either the Android or iOS command set. The loaddevice command switches platforms within the same process while retaining each platform's staged work, and an explicit override exists through --platform android or --platform ios. That symmetry matters for consultants who regularly move between an Android APK assessment in the morning and an iOS IPA in the afternoon without relearning a separate toolchain for each.


Installation is more involved than a typical pip package, and the README is candid about it. The requirements are Linux or macOS (Windows gets limited functionality), Python 3.12 or newer, Node.js and npm for building the Java and ObjC bridges, adb, a FRIDA-compatible device, and a running FRIDA server on that device. The unified development version lives on the dev branch, and setup follows the standard pattern: create a virtual environment, install requirements.txt (or requirements-mcp.txt for MCP support), run npm ci, then npm run build:bridges. The bridge build produces the Java and ObjC agents used with FRIDA 17, and the README notes they must be rebuilt after changing npm dependencies — a hint that the agent compilation is a genuine build step, not a vendored binary.


The interactive workflow will feel familiar to anyone who has used Metasploit-style consoles. help and help cover discovery, show all lists available modules, and info http_communications/ssl-pinning-bypass surfaces quick documentation for a specific module. Loading a module uses use http_communications/ with tab completion on module paths, list enumerates installed packages on the connected device, and run -f com.my.app attaches instrumentation to a target package by name. The mango companion extends this: a lightweight CLI for static preparation and automation, including manifest parsing, attack-surface enumeration, app tracking, and device/proxy automation, with pull com.my.app and import /path/to/apk for getting specimens into a database-backed workspace via python3 mango.py .


A notable modern addition is MCP server support. The optional Android MCP server, medusa_android_mcp.py, runs with MEDUSA_MCP_TRANSPORT=streamable-http and exposes the framework over an HTTP endpoint at http://127.0.0.1:8000/mcp, per the sample configuration. This positions medusa to be driven by AI-assisted workflows and agent tooling rather than only by a human at a terminal — a meaningful architectural signal about where the maintainers see mobile testing heading. The README is explicit that this is optional and not required for the standard CLI workflow, which keeps the core tool dependency-light.


The project's engineering hygiene is visible in its development checks. The README documents installing requirements-dev.lock.txt and running python -B -m unittest discover -s /path/to/medusa/tests, with test coverage spanning original command definitions, startup output, platform switching, generated-agent retention, compilation output, and script lifecycle behavior. Device-specific runtime coverage is kept separate from these host tests, an honest split given how hard real-device CI is. Ruff and mypy are configured in the project metadata with an incremental scope for new CLI and core code, and lockfiles record the tested dependency sets — all signs of a codebase being actively hardened rather than left to rot.


In an authorized engagement, medusa slots into the dynamic-analysis phase after static recon. A typical legitimate flow is: mango parses the manifest and enumerates the attack surface of an in-scope app, then the medusa console attaches to the target and layers observation modules — intent monitoring, WebView monitoring, file and content provider monitoring, native library enumeration, and interactive memory read/write/search — while the SSL unpinning module clears the way for legitimate traffic capture through an authorized interception proxy. The screenshots in the README illustrate exactly these categories, and the external demo videos cover Android penetration testing, malware analysis fundamentals, and unpacking Android malware and APKs, confirming the dual pentest/DFIR audience.


For malware analysts, the value proposition is behavioral monitoring under controlled conditions: instead of detonating a specimen blind, the analyst traces API calls, watches crypto usage, and monitors process behavior through FRIDA hooks, producing evidence that feeds directly into a report or detection engineering. The credits section acknowledges lineage from projects like frida/frida, dpnishant/appmon, brompwnie/uitkyk, and shivsahni/APKEnum, which frames medusa as a consolidation of a decade of community mobile-instrumentation work into one maintainable framework rather than a novel engine.


From a defensive perspective, it is worth understanding what medusa looks like from the other side of the glass. It requires a FRIDA server running on the target device, and FRIDA injection is among the most heavily monitored signals in modern mobile hardening — anti-tampering SDKs, root-detection logic, and runtime application self-protection routinely flag it. This is also the dual-use tension in the toolset: the same pinning bypass and root-detection bypass capabilities used legitimately to test an app you own are exactly what malicious actors abuse against apps they do not. App publishers should treat FRIDA-visibility and certificate-pinning integrity as first-class detection objectives precisely because frameworks like this make such techniques accessible.


Contribution is straightforward and documented: writing new medusa modules via the wiki guide, pull requests, issue reports, or sponsorship, with the project sponsored by mobilehackinglab.com. The module-authoring path is arguably the most important sustainability feature — the hundred-plus module repository grows with community tradecraft, and each module is inspectable FRIDA script rather than opaque binary, which is exactly what an authorized professional should demand from instrumentation tooling. Stable releases are published on the GitHub releases page for those who prefer not to track the dev branch.



Official project repository for Ch0pin/medusa.

Download Tool

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.






Source: OffensiveSec
Source Link: https://www.offsecblog.com/2026/11/medusa-for-coordinated-runtime-testing.html


Comments
new comment
Nobody has commented yet. Will you be the first?
 
Forum
Red Team (CNA)



Copyright 2012 through 2026 - National Cyber Warfare Foundation - All rights reserved worldwide.