soSaver 1.0.1
Utility for dumping .so files from Android applications using Frida.
License: MIT
Requires Python: >=3.10
Keywords: android, frida, reverse-engineering, security

# soSaver
![soSaver banner](resources/banner.png)

[![PyPI](https://img.shields.io/pypi/v/soSaver.svg)](https://pypi.org/project/soSaver/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Frida Version](https://img.shields.io/badge/frida-15.0.0%2B-orange)](https://frida.re/)


A utility for extracting and saving native (.so) libraries from the memory of Android applications using Frida.

## Description

soSaver is a tool for dynamic analysis of Android applications, enabling extraction of native libraries (.so files) from running applications' memory. Unlike static file system analysis, soSaver can access libraries that are:

- Encrypted in the APK and decrypted only at runtime
- Dynamically loaded from the internet or other sources
- Unpacked or generated during application execution
- Protected against extraction by standard methods

## Features

- Extraction of native libraries from running Android applications
- Interception of library loader calls (`dlopen`, `android_dlopen_ext`)
- Periodic memory scanning to detect libraries loaded through non-standard methods
- Fallback mechanism for extracting libraries from the file system
- Informative output and statistics on extracted modules
- Simple CLI interface

## Installation

### From PyPI

```bash
pip install sosaver
```

### Requirements

- Python 3.10 or higher
- Android device (physical or emulator) with root access
- Frida server running on the target device

## Usage

### Basic Usage

```bash
# Extract libraries from an application by package name
sosaver com.example.app

# Extract from an application by PID
sosaver 1234

# Save results to a specified directory
sosaver -o /path/to/output com.example.app

# Enable debug mode
sosaver --debug com.example.app
```

### Usage Examples

```bash
# Extract libraries from a game
sosaver com.example.game

# Extract with detailed output
sosaver --debug com.unity.game
```

## Architecture

soSaver consists of two main components:

1. **Python application** (`sosaver/`) — responsible for:
   - Connecting to Android devices
   - Injecting the Frida script into the target process
   - Processing messages from the Frida agent
   - Saving extracted libraries

2. **Frida agent** (`agent/`, written in TypeScript) — responsible for:
   - Intercepting library loaders in the application
   - Scanning memory for ELF headers
   - Reading library data from memory
   - Sending data to the Python application

## How It Works

1. soSaver connects to an Android device via Frida
2. Injects a JavaScript agent into the target process
3. The agent performs:
   - Initial scanning of already loaded modules
   - Setting up hooks for library loading functions
   - Periodic memory scanning for new libraries
4. When a library is detected:
   - Reading content from memory in blocks
   - Transferring data via Frida messages to the host application
   - In case of memory read error, attempting to read from the file system
5. The Python application saves the extracted libraries to disk
6. Upon completion, statistics on extracted modules are displayed

## Building from Source

The Frida agent is pre-built and included as `sosaver/frida/scripts/agent.js`. To modify the agent:

```bash
# Clone the repository
git clone https://github.com/TheQmaks/sosaver.git
cd sosaver

# Install agent dependencies and build
cd agent && npm install && npm run build

# Install the Python package in development mode
cd .. && pip install -e .
```

## Development and Contribution

This is a monorepo containing both the Python CLI and the TypeScript Frida agent:

- `sosaver/` — Python CLI application
- `agent/` — TypeScript Frida agent source

To set up a development environment:

```bash
pip install -e ".[dev]"
cd agent && npm install
```

## License

This project is distributed under the MIT license. See the [LICENSE](LICENSE) file for details.