MEDUSA is an extensible, modular framework for automated dynamic runtime analysis of Android and iOS applications, built for penetration testers, mobile security researchers, and malware analysts. It serves as a centralized FRIDA script repository, allowing you to add or remove modules dynamically — combining hooks and behaviors into a single main script tailored to the needs of each pentest or malware analysis session. MEDUSA automates key tasks such as SSL-pinning bypasses, attack surface enumeration, network and WebView inspection, and proxy orchestration, while providing deep behavioral insight through API call tracing, memory inspection, cryptographic data extraction, and malware-specific monitoring (exfiltration, camera/mic abuse, SMS or call interception). With over 90 plug-and-play modules, MEDUSA makes large-scale instrumentation, triage, and behavioral investigation efficient, scalable, and reusable.

System requirements:

• Linux or macOS (limited functionality available on Windows)
• Python 3
• Rooted device or emulator
• adb
• FRIDA server (running on the mobile device)

1. Clone this repository.
2. CD into the medusa directory.
3. Install dependencies:

# using the system python3/pip
pip3 install -r requirements.txt

# or inside a virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

A preconfigured Dockerfile is available in the medusa/ directory.

1. Build the image: docker build -t medusa:latest ./

2. Run the container: docker run --name medusa --net=host --rm -it medusa:latest

3. Enable ADB over TCP/IP on your physical device or emulator: adb tcpip 5555

4. Connect to the device from inside the container: root@docker# adb connect <device_ip>:5555

During installation on macOS, you might encounter the following issue:

Readline features including tab completion have been disabled because no supported version of readline was found. To resolve this, install pyreadline3 on Windows or gnureadline on Linux/Mac.

To resolve, install the gnureadline package for Python:

pip install gnureadline

For Python 3.12, use the following command to install gnureadline from a specific commit:

pip install git+https://github.com/ludwigschwardt/python-gnureadline.git@8474e5583d4473f96b42745393c3492e2cb49224

If you're upgrading from an older version of Medusa and encounter database compatibility issues with Mango, please refer to DATABASE_MIGRATIONS.md for migration instructions.

Important: If you have an existing Mango database and receive errors after updating, check the migration guide to update your database schema.

Demos:

• MEDUSA | Android Penetration tool (credits @ByteTheories)
• MEDUSA | Android Malware Analysis 101 (credits @ByteTheories)
• Unpacking Android malware with Medusa (credits @cryptax)
• Unpacking Android APKs with Medusa (credits @LaurieWired)
• #Medusa - Extensible binary instrumentation framework based on #FRIDA for Android applications (credits @AndroidAppSec)
• Memory inspection with Medusa
• Bypassing root detection

The main idea behind MEDUSA is to be able to add or remove hooks for Java or Native methods in a large scale while keeping the process simple and effective. MEDUSA has more than 90 modules which can be combined, each one of them dedicated to a set of tasks. Indicatively, some of these tasks include:

• SSL pinning bypass
• UI restriction bypass (e.g. Flag secure, button enable)
• Class enumeration
• Monitoring of:
  • Encryption process (keys, IVs, data to be encrypted)
  • Intents
  • Http communications
  • Websockets
  • Webview events
  • File operations
  • Database interactions
  • Bluetooth operations
  • Clipboard
• Monitoring of API calls used by malware applications, such as:
  • Spyware
  • Click Fraud
  • Toll Fraud
  • Sms Fraud

Furthermore, you can intercept Java or Native methods that belong to 3rd party apps or create complex frida modules with just few simple commands.

Mango is medusa's twin brother which can be used to:

• Parse and analyse the Android manifest
• Enumerate an application's attack entry points (exported activities, deeplinks, services etc.)
• Keep track of all your analysed applications
• Automate boring processes like:
  • Set up a MITM
  • Patching
  • Wrap adb commands
  • Set/View/Reset the device's proxy configuration

...and many many more

• Making a pull request
• Creating a medusa module (see how to)
• Reporting an error/issue
• Suggesting an improvement
• Making this project more popular by sharing it or giving a star

Hooks api calls which found to be common for this kind of malware, including:

• Contact exfiltration
• Call log exfiltration
• Camera usage
• Microphone usage
• Location tracking
• File uploading
• Media recording
• Clipboard tracking
• Device recon
• Screenshot capture

Translates the application's UI by hooking 'setText' calls

Stheno is a subproject of Medusa, specifically designed for intent monitoring within this framework. Below is a quick guide on how to set up and use Stheno effectively.

1. Include the Intent Module: Add the intents/start_activity module to your Medusa project:

   medusa> add intents/start_activity

2. Run the Socket Server: Start the Medusa socket server to facilitate communication:

   medusa> startserver

3. Launch Stheno: Open Stheno and navigate to the Intent Monitor menu, then click on Start to begin monitoring intents.

CREDITS:

• Special Credits to @rscloura for his contributions
• Logo Credits: https://www.linkedin.com/in/rafael-c-ferreira
• https://github.com/frida/frida
• https://github.com/dpnishant/appmon
• https://github.com/brompwnie/uitkyk
• https://github.com/hluwa/FRIDA-DEXDump.git
• https://github.com/shivsahni/APKEnum
• https://github.com/0xdea/frida-scripts
• https://github.com/Areizen/JNI-Frida-Hook