Skip to content

Latest commit

 

History

History
115 lines (76 loc) · 4.82 KB

TROUBLESHOOTING.md

File metadata and controls

115 lines (76 loc) · 4.82 KB

❱ Troubleshooting

In case of problems when running Obfuscapk, here's a list of steps you can try to solve the most common errors. For more general questions, see the FAQ.

RTFM

Really. The readme contains everything you need to get started with Obfuscapk. If something is not clear, the source code is your friend 😉.

Always use the latest version

It might seem obvious, but unless you just cloned the repository, make sure to be using the latest version of Obfuscapk from the master branch. If you are using Docker, make sure to pull the latest official Obfuscapk Docker image from Docker Hub.

Install the additional tools correctly

If you are not using the Docker image, make sure to install and setup properly the additional tools needed for Obfuscapk to work: apktool, jarsigner and zipalign. Please ensure to be using a recent release of apktool (some systems, like Kali Linux, have an old version of apktool pre-installed by default). Check the readme for more information.

Run the help command

Run Obfuscapk by passing only the --help flag to display the help message (the exact command depends on how Obfuscapk was installed). Besides showing how to use Obfuscapk, this command also checks that the additional tools are available and correctly installed. If you aren't getting any error at this point, it means that Obfuscapk is configured properly and ready to be used.

Enable verbose logging

By default Obfuscapk shows only error messages. To better understand the cause of an issue, you can enable debug log messages by setting LOG_LEVEL environment variable to DEBUG or by modifying src/obfuscapk/main.py file as follows:

-    log_level = logging.ERROR
+    log_level = logging.DEBUG

If you only want to see progress bars during the obfuscation operations, use -p/--show-progress flag instead.

Try running with minimal configuration

Some applications use anti-repackaging techniques and/or apktool is not able to decompile/build the application and in such cases Obfuscapk won't work. To check if an application can be repackaged (and thus obfuscated) run Obfuscapk using only Rebuild, NewSignature and NewAlignment obfuscators. If this operation works without errors, then you can continue adding more obfuscators, otherwise, there's an issue that can't be solved by just patching Obfuscapk.

Find the problematic obfuscator

If Obfuscapk works with the minimal configuration but fails in more complex scenarios, you can try to find if a specific obfuscator is causing the problem:

  • run the obfuscation again by adding -i/--ignore-libs flag to ignore known third party libraries (the code belonging to such libraries won't be modified);

  • the order of the obfuscators matters, so if something is not working as expected, try changing the order in which the obfuscators are passed as parameters with -o/--obfuscator (but preserve the order of Rebuild, NewSignature and NewAlignment and always put them at the end of the list);

  • if the error persists, try adding the obfuscators one by one until you find which is causing the error(s): e.g., instead of running -o ConstStringEncryption -o ResStringEncryption -o LibEncryption all at once, try only -o ConstStringEncryption and check if the resulting application still works as expected, then continue with -o ConstStringEncryption -o ResStringEncryption an so on (Rebuild, NewSignature and NewAlignment were omitted in this example).

After you found which obfuscator is causing the problem, you have three choices: ignore it and use other obfuscators that work, open a bug report issue on GitHub or try to find a solution by modifying the obfuscator's source code.

Check FAQ and existing issues

If you couldn't solve the errors with the above steps, or if you have a different problem not covered here, then check the FAQ and the existing issues on GitHub. If you still can't find an answer then submit a new issue on GitHub.