Home

Awesome

<p align="center"> <img width=100% src="/assets/cover.png"> </a> </p> <p align="center"> 🤖 <b> Obfu[DE]scate: A De-obfuscation and Comparison tool for Android APKs. 📱 </b> </p> <div align="center">

GitHub contributors GitHub Repo stars GitHub watchers GitHub last commit <br>

</div>

Obfu[DE]scate is a Python tool designed to simplify the process of de-obfuscating and comparing two versions of an Android APK - even if the functions have been renamed as part of obfuscation. With fuzzy comparison logic, Obfu[DE]scate can identify similarities between functions and help you uncover changes between APK versions.

➡️ Getting Started

Installation

Getting started with Obfu[DE]scate is easy! Follow these steps:

  1. Clone the repository to your local machine.
  2. Install the dependencies manually or via the included requirements file using the following command:
pip install -r REQUIREMENTS.txt
  1. Download APKTool for your system from their website. and make sure it's installed and available in your PATH.

Obfu[DE]scate has been tested on Windows 11, but should work on other systems as well.

Running

Obfu[DE]scate provides several command-line options to customize its behavior:

ShorthandParameterDescriptionRequired
-a1apk_file_path_1The path to the original APK. This is the APK that the second APK will be compared against (i.e. an older version of the APK)True
-a2apk_file_path_2The path to the newer APK. The output will show changes between APK 1 and this APK.True
-cpclass_pathA reverse domain notation path that will be used to filter reviewed functions (i.e. provide com.example.class to only compare functions on this path).False
-ooutput_dirA directory to save the output mapping, html, and dissasembled APKs to.False
-apktoolapk_tool_pathIf APKTool is not on your path use this parameter to tell ObfuDeScate where APKTool is located.False

To compare two APK files, simply run Obfu[DE]scate with the following command:

python ObfuDeScate.py -a1 "old_example.apk" -a2 "new_example.apk" -cp "com.example.path"

In the above example, Obfu[DE]scate will review all functions in the old_example.apk APK at the class path com.example.path and compare them against all functions found at the same class path in new_example.apk.

🔎 Outputs

Obfu[DE]scate generates two output files: a mapping file in newline-separated list format, and an interactive HTML file. These output files include:

<p align="center"> <img src="/assets/html_example.png" width="400" /> <img src="/assets/mapping_example.png" width="400" /> <img src="/assets/running.gif" width="400" /> </p>

🙏 Contributions

Obfu[DE]scate is an open-source project and welcomes contributions from the community. If you would like to contribute to Obfu[DE]scate, please follow these guidelines:

⚖️ Code of Conduct

Obfu[DE]scate follows the Contributor Covenant Code of Conduct. Please make sure to review. and adhere to this code of conduct when contributing to Obfu[DE]scate.

🐛 Bug Reports and Feature Requests

If you encounter a bug or have a suggestion for a new feature, please open an issue in the GitHub repository. Please provide as much detail as possible, including steps to reproduce the issue or a clear description of the proposed feature. Your feedback is valuable and will help improve Obfu[DE]scate for everyone.

💛 Thanks

This tool wouldn't work without APKTool! Secondly, many of the examples in this README use the Chess.com app as a base, check it out here.

📜 License

GNU General Public License v3.0