hermes-dec 0.1.6

hermes-dec is a reverse-engineering tool which can be used for disassembling and decompiling React Native files compiled into the Hermes VM bytecode (HBC) format.

For a wider presentation of its purpose, please see our presentation blog post.

Background

The Hermes VM for React Native was announced by Facebook on the 12 July 2019. The initial release of Hermes was version 0.1.0 (bytecode version 59), Github tags 0.0.1 to 0.0.3 correspond to pre-public release.

However, Hermes is the default compilation target for React Native on Android only since React Native 0.70 (released on 5 September 2022), as explained here.

Before that, and since React Native 0.60.2, the Hermes VM was an opt-in feature. Hermes for iOS is supported since version 0.64 of React Native (released on the 12 March 2021).

React Native is used by a wide variety of significant mobile applications, as exposed on the React Native showcase page.

A variety of technical documentation regarding the Hermes VM, which is published as an open-source project under the BSD license, including various design documents in the Markdown format, which can be read on Github as well as on Facebook's website for React documentation.

In Android applications released under the .APK format, the Hermes bytecode (HBC) file is usually located at:

$ file assets/index.android.bundle
assets/index.android.bundle: Hermes JavaScript bytecode, version 84

On non-Hermes based setups of React Native, this file usually contains minified/Webpacked JavaScript code.

Installation

The application itself only relies on the Python 3.x standard library for now.

You can install the tool through one the following commands:

# With Snap (recommended with Ubuntu):
sudo snap install hermes-dec
# Note: the commands to use will then be:
# - hermes-dec.hbc-disassembler
# - hermes-dec.hbc-file-parser
# - hermes-dec.hbc-decompiler

# With AUR (recommended with Archlinux):
yay -S hermes-dec

# With uv (all distributions):
sudo snap install --classic astral-uv
uv tool install hermes-dec

# With pipx (all distributions):
pipx install hermes-dec

Usage

If you didn't install the tool system-wide using the command above, you can also download the source using this command and find the same utilities at the root:

$ git clone git@github.com:P1sec/hermes-dec.git
$ cd hermes-dec/

For an Android application, you should extract the Hermes bundle file from the .APK file through using your favorite unzipping tool (an .APK file is a renamed .ZIP archive):

$ 7z x my_application.apk
$ cd my_application

And check the type of the assets/index.android.bundle React Native bundle file which, in the case of a React Native-based application, should be either a plain-text minified JavaScript bundle file or an Hermes bytecode file:

$ file assets/index.android.bundle
assets/index.android.bundle: Hermes JavaScript bytecode, version 84

If the concerned file is indeed an Hermes JavaScript bytecode file, you may then decode most of its file headers using the following utility (which output may not be stable over time):

hbc-file-parser assets/index.android.bundle

You may then disassemble the contents of the React Native bytecode file to the /tmp/my_output_file.hasm output file using the following command (leave out the second parameter in order to send the disassembled content to the standard output):

hbc-disassembler assets/index.android.bundle /tmp/my_output_file.hasm

And perform the decompilation to pseudo-code (which is not valid JavaScript yet as it does not retranscribe loop/conditional structures) using the following command:

hbc-decompiler assets/index.android.bundle /tmp/my_output_file.js

Extra documentation

You can find auto-generated documentation for the Hermes VM opcodes here.

This is an useful tool to understand the generated assembly code.