Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ch0pin/medusa
Binary instrumentation framework based on FRIDA
https://github.com/ch0pin/medusa
android android-malware dynamic-analysis frida frida-scripts frida-snippets malware medusa penetration-testing pentest
Last synced: 1 day ago
JSON representation
Binary instrumentation framework based on FRIDA
- Host: GitHub
- URL: https://github.com/ch0pin/medusa
- Owner: Ch0pin
- License: gpl-3.0
- Created: 2020-06-24T08:21:13.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-01-10T11:21:02.000Z (15 days ago)
- Last Synced: 2025-01-16T09:24:34.819Z (9 days ago)
- Topics: android, android-malware, dynamic-analysis, frida, frida-scripts, frida-snippets, malware, medusa, penetration-testing, pentest
- Language: Python
- Homepage: https://github.com/Ch0pin/medusa/wiki
- Size: 51.1 MB
- Stars: 1,617
- Watchers: 44
- Forks: 237
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Description
**MEDUSA** is an extensible and modularized framework that automates processes and techniques practiced during the **dynamic analysis** **of Android and iOS Applications**.
# Installation
1. Clone this repo
2. Navigate to the medusa's directory
3. Run the following command:
```
$ pip install -r requirements.txt
```
# Using Stheno (Σθενώ) with Medusa
[Stheno](https://github.com/Ch0pin/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:
```bash
medusa> add intents/start_activity
```
2. **Run the Socket Server**:
Start the Medusa socket server to facilitate communication:
```bash
medusa> startserver
```
3. **Launch Stheno**:
Open Stheno and navigate to the Intent Monitor menu, then click on **Start** to begin monitoring intents.
## Known issues
### macOS Installation
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 this issue on macOS, 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
```
## Using docker
You can find the docker file in the medusa/ directory.
1. Build with
```
$ docker build -t medusa:tag1 ./
```
2. Run with
```
$ docker run --name medusa --net=host --rm -it medusa:tag1
```
3. Run adbd in tcp/ip mode in your physical device or emulator
```
$ adb tcpip 5555
```
4. Connect to from the image to your device using:
```
root@docker# adb connect device_ip:5555
```
**System requirements:**
- Linux or macOS (currently medusa doesn't support windows)
- Python 3 (Use the latest python release and not the one shipped with macOS to avoid issues with using libedit instead of GNU's readline)
- Rooted device or emulator
- adb
- FRIDA server (running on the mobile device)
# Usage
### Check our [wiki page](https://github.com/Ch0pin/medusa/wiki) for usage details.
**Demos:**
- [MEDUSA | Android Penetration tool](https://www.youtube.com/watch?v=4hpjRuNJNDw) (credits [@ByteTheories](https://www.youtube.com/@ByteTheories))
- [MEDUSA | Android Malware Analysis 101](https://www.youtube.com/watch?v=kUqucdkVtSU) (credits [@ByteTheories](https://www.youtube.com/@ByteTheories))
- [Unpacking Android malware with Medusa](https://www.youtube.com/watch?v=D2-jREzCE9k) (credits [@cryptax](https://twitter.com/cryptax))
- [Unpacking Android APKs with Medusa](https://www.youtube.com/watch?v=ffM5R2Wfl0A) (credits [@LaurieWired](https://twitter.com/LaurieWired))
- [#Medusa - Extensible binary instrumentation framework based on #FRIDA for Android applications](https://www.youtube.com/watch?v=Hon7zETJawA) (credits [@AndroidAppSec](https://www.youtube.com/@AndroidAppSec))
- [Memory inspection with Medusa](https://www.youtube.com/watch?v=odt21wiUugQ)
- [Bypassing root detection](https://twitter.com/ch0pin/status/1381216805683924994)
Medusa consists of two main scripts: **medusa.py** and **mango.py**:
## Using medusa.py
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.
## Using mango.py
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
# Updates:
### (12/2022) Using the translator script:
1. Replace the default google_trans_new.py of you google_trans_new python package with the one from the utils/google_trans_new.py
2. Import it with medusa>use helpers/translator
# Contribute by:
- Making a pull request
- Creating a medusa module (see [how to](https://github.com/Ch0pin/medusa/wiki/Medusa#creating-a-medusa-module))
- Reporting an error/issue
- Suggesting an improvement
- Making this project more popular by sharing it or giving a star
- Buying a treat:
**Bitcoin (BTC) Address**: bc1qhun6a7chkav6mn8fqz3924mr8m3v0wq4r7jchz
**Ethereum (ETH) Address**: 0x0951D1DD2C9F57a9401BfE7D972D0D5A65e71dA4
# Screenshots
#### - SSL Unpinning
#### - Intent Monitoring
#### - Webview Monitoring
#### - File/Content provider monitoring
#### - Native Libraries Enumeration
#### - Memory READ/WRITE/SEARCH (interactive mode):
#### - Personal information exfiltration monitoring
> 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
#### - Translation
> Translates the application's UI by hooking 'setText' calls
**CREDITS**:
- Special Credits to [@rscloura](https://github.com/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