Obfuscapk A Black-Box Obfuscation Tool For Android Apps
Obfuscapk A Black-Box Obfuscation Tool For Android Apps

Obfuscapk: A Black-Box Obfuscation Tool For Android Apps

Obfuscapk is a modular Python tool for obfuscating Android apps without needing their source code, since apktool is used to decompile the original apk file and to build a new application, after applying some obfuscation techniques on the decompiled smali code, resources and manifest. The obfuscated app retains the same functionality as the original one, but the differences under the hood sometimes make the new application very different from the original (e.g., to signature-based antivirus software).


More details about Obfuscapk can be found in the paper “Obfuscapk: An open-source black-box obfuscation tool for Android apps“. You can cite the paper as follows:

    title = "Obfuscapk: An open-source black-box obfuscation tool for Android apps",
    journal = "SoftwareX",
    volume = "11",
    pages = "100403",
    year = "2020",
    issn = "2352-7110",
    doi = "https://doi.org/10.1016/j.softx.2020.100403",
    url = "http://www.sciencedirect.com/science/article/pii/S2352711019302791",
    author = "Simone Aonzo and Gabriel Claudiu Georgiu and Luca Verderame and Alessio Merlo",
    keywords = "Android, Obfuscation, Program analysis"


Demo Obfuscapk
Demo Obfuscapk


Obfuscapk is designed to be modular and easy to extend, so it’s built using a plugin system. Consequently, every obfuscator is a plugin that inherits from an abstract base class and needs to implement the method obfuscate. When the tool starts processing a new Android application file, it creates an obfuscation object to store all the needed information (e.g., the location of the decompiled smali code) and the internal state of the operations (e.g., the list of already used obfuscators). Then the obfuscation object is passed, as a parameter to the obfuscate method, to all the active plugins/obfuscators (in sequence) to be processed and modified. The list and the order of the active plugins is specified through command line options.

Architecture Obfuscapk
Architecture Obfuscapk

The tool is easily extensible with new obfuscators: it’s enough to add the source code implementing the obfuscation technique and the plugin metadata (a <obfuscator-name>.obfuscator file) in the src/obfuscapk/obfuscators directory (take a simple existing obfuscator like Nop as a starting example). The tool will detect automatically the new plugin, so no further configuration is needed (the new plugin will be treated like all the other plugins bundled with the tool).


There are two ways of getting a working copy of Obfuscapk on your own computer: either by using Docker or by using directly the source code in a Python 3 environment. In both cases, the first thing to do is to get a local copy of this repository, so open up a terminal in the directory where you want to save the project and clone the repository:

$ git clone https://github.com/ClaudiuGeorgiu/Obfuscapk.git

Docker image


This is the suggested way of installing Obfuscapk, since the only requirement is to have a recent version of Docker installed:

$ docker --version             
Docker version 19.03.0, build aeac949

Official Docker Hub image

The official Obfuscapk Docker image is available on Docker Hub (automatically built from this repository):

$ # Download the Docker image.
$ docker pull claudiugeorgiu/obfuscapk
$ # Give it a shorter name.
$ docker tag claudiugeorgiu/obfuscapk obfuscapk


If you downloaded the official image from Docker Hub, you are ready to use the tool so go ahead and check the usage instructions, otherwise execute the following command in the previously created Obfuscapk/src/ directory (the folder containing the Dockerfile) to build the Docker image:

$ # Make sure to run the command in Obfuscapk/src/ directory.
$ # It will take some time to download and install all the dependencies.
$ docker build -t obfuscapk .

When the Docker image is ready, make a quick test to check that everything was installed correctly:

$ docker run --rm -it obfuscapk --help
usage: python3 -m obfuscapk.cli [-h] -o OBFUSCATOR [-w DIR] [-d OUT_APK]

Obfuscapk is now ready to be used, see the usage instructions for more information.

From source


Make sure to have a recent version of apktooljarsigner and zipalign installed and available from the command line:

$ apktool
Apktool v2.4.1 - a tool for reengineering Android apk files
$ jarsigner
Usage: jarsigner [options] jar-file alias
       jarsigner -verify [options] jar-file [alias...]
$ zipalign
Zip alignment utility
Copyright (C) 2009 The Android Open Source Project

To install and use apktool you need a recent version of Java, which should also have jarsigner bundled. zipalign is included in the Android SDK. The location of the executables can also be specified through the following environment variables: APKTOOL_PATHJARSIGNER_PATH and ZIPALIGN_PATH (e.g., in Ubuntu, run export APKTOOL_PATH=/custom/location/apktool before running Obfuscapk in the same terminal).

Apart from the above tools, the only requirement of this project is a working Python 3 (at least 3.6) installation (along with its package manager pip).


Run the following commands in the main directory of the project (Obfuscapk/) to install the needed dependencies:

$ # Make sure to run the commands in Obfuscapk/ directory.
$ # The usage of a virtual environment is highly recommended, e.g., virtualenv.
$ # If not using virtualenv (https://virtualenv.pypa.io/), skip the next 2 lines.
$ virtualenv -p python3 venv
$ source venv/bin/activate
$ # Install Obfuscapk's requirements.
$ python3 -m pip install -r src/requirements.txt

After the requirements are installed, make a quick test to check that everything works correctly:

$ cd src/
$ # The following command has to be executed always from Obfuscapk/src/ directory
$ # or by adding Obfuscapk/src/ directory to PYTHONPATH environment variable.
$ python3 -m obfuscapk.cli --help
usage: python3 -m obfuscapk.cli [-h] -o OBFUSCATOR [-w DIR] [-d OUT_APK]

Obfuscapk is now ready to be used, see the usage instructions for more information.


From now on, Obfuscapk will be considered as an executable available as obfuscapk, so you need to adapt the commands according to how you installed the tool:

  • Docker image: a local directory containing the application to obfuscate has to be mounted to /workdir in the container (e.g., the current directory "${PWD}"), so the command:
$ obfuscapk [params...]


$ docker run --rm -it -u $(id -u):$(id -g) -v "${PWD}":"/workdir" obfuscapk [params...]
  • From source: every instruction has to be executed from the Obfuscapk/src/ directory (or by adding Obfuscapk/src/ directory to PYTHONPATH environment variable) and the command:
$ obfuscapk [params...]


$ python3 -m obfuscapk.cli [params...]

Let’s start by looking at the help message:

$ obfuscapk --help
obfuscapk [-h] -o OBFUSCATOR [-w DIR] [-d OUT_APK] [-i] [-p] [-k VT_API_KEY]
          [--keystore-file KEYSTORE_FILE] [--keystore-password KEYSTORE_PASSWORD]
          [--key-alias KEY_ALIAS] [--key-password KEY_PASSWORD]

There are two mandatory parameters: <APK_FILE>, the path (relative or absolute) to the apk file to obfuscate and the list with the names of the obfuscation techniques to apply (specified with a -o option that can be used multiple times, e.g., -o Rebuild -o NewSignature -o NewAlignment). The other optional arguments are as follows:

  • -w DIR is used to set the working directory where to save the intermediate files (generated by apktool). If not specified, a directory named obfuscation_working_dir is created in the same directory as the input application. This can be useful for debugging purposes, but if it’s not needed it can be set to a temporary directory (e.g., -w /tmp/).
  • -d OUT_APK is used to set the path of the destination file: the apk file generated by the obfuscation process (e.g., -d /home/user/Desktop/obfuscated.apk). If not specified, the final obfuscated file will be saved inside the working directory. Note: existing files will be overwritten without any warning.
  • -i is a flag for ignoring known third party libraries during the obfuscation process, to use fewer resources, to increase performances and to reduce the risk of errors. The list of libraries to ignore is adapted from LiteRadar project.
  • -p is a flag for showing progress bars during the obfuscation operations. When using the tool in batch operations/automatic builds it’s convenient to have progress bars disabled, otherwise this flag should be enabled to see the obfuscation progress.
  • -k VT_API_KEY is needed only when using VirusTotal obfuscator, to set the API key(s) to be used when communicating with Virus Total. Can be set multiple times to cycle through the API keys during the requests (e.g., -k VALID_VT_KEY_1 -k VALID_VT_KEY_2).
  • --keystore-file KEYSTORE_FILE--keystore-password KEYSTORE_PASSWORD--key-alias KEY_ALIAS and --key-password KEY_PASSWORD can be used to specify a custom keystore (needed for the apk signing). If --keystore-file is used, --keystore-password and --key-alias must be specified too, while --key-password is needed only if the chosen key has a different password from the keystore password. By default (when --keystore-file is not specified), a keystore bundled with Obfuscapk is used for the signing operations.

Let’s consider now a simple working example to see how Obfuscapk works:

$ # original.apk is a valid Android apk file.
$ obfuscapk -o RandomManifest -o Rebuild -o NewSignature -o NewAlignment original.apk

When running the above command, this is what happens behind the scenes:

  • since no working directory was specified, a new working directory (obfuscation_working_dir) is created in the same location as original.apk (this can be useful to inspect the smali files/manifest/resources in case of errors)
  • some checks are performed to make sure that all the needed files/executables are available and ready to be used
  • the actual obfuscation process begins: the specified obfuscators are executed (in order) one by one until there’s no obfuscator left or until an error is encountered
    • when running the first obfuscator, original.apk is decompiled with apktool and the results are stored into the working directory
    • since the first obfuscator is RandomManifest, the entries in the decompiled Android manifest are reordered randomly (without breaking the xml structures)
    • Rebuild obfuscator simply rebuilds the application (now with the modified manifest) using apktool, and since no output file was specified, the resulting apk file is saved in the working directory created before
    • NewSignature obfuscator signs the newly created apk file with a custom certificate contained in a keystore bundled with Obfuscapk (though a different keystore can be specified with the --keystore-file parameter)
    • NewAlignment obfuscator uses zipalign tool to align the resulting apk file
  • when all the obfuscators have been executed without errors, the resulting obfuscated apk file can be found in obfuscation_working_dir/original_obfuscated.apk, signed, aligned and ready to be installed into a device/emulator

As seen in the previous example, RebuildNewSignature and NewAlignment obfuscators are always needed to complete an obfuscation operation, to build the final obfuscated apk. They are not actual obfuscation techniques, but they are needed in the build process and so they are included in the list of obfuscators to keep the overall architecture modular.

Not working as expected? See FAQ and troubleshooting.


The obfuscators included in Obfuscapk can be divided into different categories, depending on the operations they perform:

  • Trivial: as the name suggests, this category includes simple operations (that do not modify much the original application), like signing the apk file with a new signature.
  • Rename: operations that change the names of the used identifiers (classes, fields, methods).
  • Encryption: packaging encrypted code/resources and decrypting them during the app execution. When Obfuscapk starts, it automatically generates a random secret key (32 characters long, using ASCII letters and digits) that will be used for encryption.
  • Code: all the operations that involve the modification of the decompiled source code.
  • Resources: operations on the resource files (like modifying the manifest).
  • Other

The obfuscators currently bundled with Obfuscapk are briefly presented below (in alphabetical order). Please refer to the source code of the project for more details.

NOTE: not all the obfuscators below correspond to real obfuscation techniques (e.g., RebuildNewSignatureNewAlignment and VirusTotal), but they are implemented as obfuscators to keep the architecture modular and easy to extend with new functionality.


Questions, bug reports and pull requests are welcome on GitHub at https://github.com/ClaudiuGeorgiu/Obfuscapk. Make sure to also check FAQ and troubleshooting, since some of the most common questions are already answered there.

Dark Mode

Obfuscapk (este enlace se abre en una nueva ventana) por ClaudiuGeorgiu (este enlace se abre en una nueva ventana)

An automatic obfuscation tool for Android apps that works in a black-box fashion, supports advanced obfuscation features and has a modular architecture easily extensible with new techniques


You are free to use this code under the MIT License.


This software was developed for research purposes at the Computer Security Lab (CSecLab), hosted at DIBRIS, University of Genoa.


Mi Carro Close (×)

Tu carrito está vacío
Ver tienda