Metadata-Version: 2.4
Name: rosal
Version: 0.1.0
Summary: Reverse Obfuscated Standard Android Libraries (ROSAL)
Author-email: MRF <nope@nope.com>
Maintainer-email: MRF <nope@nope.com>
Project-URL: Repository, https://github.com/mariorobertofortunato/rosal
Project-URL: Issues, https://github.com/mariorobertofortunato/rosal/issues
Keywords: android,reverse engineering,R8,ProGuard,deobfuscation,kotlin,Java,JADX
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: androguard>=4.1.3
Requires-Dist: loguru>=0.7.2
Requires-Dist: tqdm>=4.66.0
Dynamic: license-file

 # ROSAL

ROSAL (Reverse Obfuscated Standard Android Libraries) helps reverse-engineer Android applications by mapping obfuscated classes from an APK to their plain-text equivalents in the declared standard libraries (androidx, core, ...).

It helps recover actual names for classes like RecyclerView, LiveData, Fragment, CompatActivity, and so on, partly automating the manual process of reverse engineering and allowing for an easier Static Analysis of Android apps.

The mapping is limited to the classes from the standard libraries: it does not involve the mapping of the proprietary classes of the app.

Fully deterministic, no heuristics.
No AI is involved in the process.

```text
!!!! DISCLAIMER !!!!
This software is intended for research and for testing on authorized targets EXCLUSIVELY.
Any other purpose is not supported or endorsed by the creators by any means.
Don't be a cunt.
```

## How it works

R8/ProGuard can rename any class, method or field that belongs to the app itself, but cannot rename references to platform APIs (`android/*`, `java/*`, `javax/*`). Those symbols must stay intact to be resolved by the OS at runtime.

Rosal treats every reference to a platform API found inside a method (a call, a parameter type, an annotation type, a superclass) as an **anchor** = something that the obfuscator can't touch. 
Two methods that share the exact same set of anchors are, with very high confidence, the same method.

The standard libraries used in the matching process are not a fixed set of references. 
Instead, rosal uses the `META-INF/*.version` markers embedded in the APK to know exactly which group/artifact/version was bundled, so the matching library `.dex` files are fetched from the same Maven repositories the original build used.

## Getting started

### Prerequisites & Dependencies
Dependencies on `Androguard`, `loguru` and `tqdm` should be resolved automatically during installation... If not, install manually.

The tool relies on the Android SDK. You'll definitely need D8 and platform-tools. 

Install it in `~/Android/Sdk` ( <<-- please use this exact path, otherwise things will break)

```
https://developer.android.com/tools/releases/build-tools
https://developer.android.com/tools/releases/platform-tools
```

`Java` is also required. Install it if you haven't already.

### Installing from local repository

Clone the repository, then `cd` to its directory and:

```bash
python -m pip install .
```

### Installing from PyPi (recommended)

```bash
pip install rosal
```

## Run

```bash
# (Optional) Define APK path
export APK=...
```

Basic usage:

```bash
rosal --apk "$APK" # or <path_to_apk>
```

The command runs the fetch, extraction, catalog, matching and mapping stages in sequence.

By default, intermediate files and `matches.tiny` are written to `~/rosal`. 
Use `--work-dir` to specify another directory:

```bash
rosal --apk "$APK" --work-dir ./anything_you_want
```

### Relevant sample outputs

`matches.json`

```json
{
  "matches": [
    {
      "library_class": "Landroidx/activity/Api34Impl;",
      "target_class": "Landroidx/activity/a;",
      "provenance": "androidx.activity_activity-1.8.1.dex",
      "methods": [
        {
          "library_name": "createOnBackEvent",
          "target_name": "a",
          "library_descriptor": "(FFFI)Landroid/window/BackEvent;",
          "target_descriptor": "(FFFI)Landroid/window/BackEvent;"
        },
        {
          "library_name": "progress",
          "target_name": "b",
          "library_descriptor": "(Landroid/window/BackEvent;)F",
          "target_descriptor": "(Landroid/window/BackEvent;)F"
        },
        {
          "library_name": "swipeEdge",
          "target_name": "c",
          "library_descriptor": "(Landroid/window/BackEvent;)I",
          "target_descriptor": "(Landroid/window/BackEvent;)I"
        },
        {
          "library_name": "touchX",
          "target_name": "d",
          "library_descriptor": "(Landroid/window/BackEvent;)F",
          "target_descriptor": "(Landroid/window/BackEvent;)F"
        },
        {
          "library_name": "touchY",
          "target_name": "e",
          "library_descriptor": "(Landroid/window/BackEvent;)F",
          "target_descriptor": "(Landroid/window/BackEvent;)F"
        }
      ],
      "fields": []
    },
    ...
```
`matches.tiny`

```text
tiny	2	0	obf	named
c	androidx/activity/a	androidx/activity/Api34Impl
	m	(FFFI)Landroid/window/BackEvent;	a	createOnBackEvent
	m	(Landroid/window/BackEvent;)F	b	progress
	m	(Landroid/window/BackEvent;)I	c	swipeEdge
	m	(Landroid/window/BackEvent;)F	d	touchX
	m	(Landroid/window/BackEvent;)F	e	touchY
c	androidx/activity/p	androidx/activity/ComponentActivity
c	androidx/activity/q	androidx/activity/ComponentDialog
c	androidx/activity/s	androidx/activity/OnBackPressedCallback
c	androidx/activity/w	androidx/activity/OnBackPressedDispatcher$Api33Impl
```

### Files and Directories involved

With the exception of `matches.tiny`, these files are intermediates that can end up being quite large.
Feel free to delete them if you don't need them for further analysis.

```text
markers_file = work_dir / "markers.txt"
library_dex_dir = work_dir / "library_dex"
target_dex_dir = work_dir / "target_dex"
features_file = work_dir / "features.ndjson"
matches_file = work_dir / "matches.json"
mapping_file = work_dir / "matches.tiny"
```

### Applying the `matches.tiny` file

Once the command has (hopefully) run successfully, you can apply the generated `matches.tiny` to an instance of `jadx` / `jadx-gui`

```bash
jadx-gui --mappings-path <path_to>/matches.tiny "$APK"
```

## License

This project is licensed under the MIT License - see the LICENSE.md file for details

## Acknowledgments

* Android SDK
* [Androguard](https://github.com/androguard/androguard) Team, and their fantastic job
* [tqdm](https://github.com/tqdm/tqdm)
* Inspiration: [LibScan](https://github.com/wyf295/LibScan), [deoptfuscator](https://github.com/Gyoonus/deoptfuscator), [DexKit](https://github.com/LuckyPray/DexKit), [KMparse](https://github.com/mforlini/KMparse)
