Hermes Bytecode Reverse Engineering Tool (Assemble/Disassemble Hermes Bytecode)

Overview

hbctool

Python 3.x PyPI version Software License

A command-line interface for disassembling and assembling the Hermes Bytecode.

Since the React Native team created their own JavaScript engine (named Hermes) for running the React Native application, the JavaScript source code is often compiled to the Hermes bytecode. In the penetration test project, I found that some React Native applications have already been migrated to the Hermes engine. It is really head for me to analyze or patch those applications. Therefore, I created hbctool for helping any pentester to test the Hermes bytecode.(Now only support Hermes Bytecode version 74).

Hermes is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an opt-in React Native feature, and this guide explains how to enable it.

Special thanks to ErbaZZ and Jusmistic for helping me research and develop this tool.

Screenshot

hbctool Example

This video with MP4 format can be found at /image/hbctool_example.mp4.

Installation

To install hbctool, simply use pip:

pip install hbctool

Usage

Please run hbctool --help to show the usage.

hbctool --help   
A command-line interface for disassembling and assembling
the Hermes Bytecode.

Usage:
    hbctool disasm <HBC_FILE> <HASM_PATH>
    hbctool asm <HASM_PATH> <HBC_FILE>
    hbctool --help
    hbctool --version

Operation:
    disasm              Disassemble Hermes Bytecode
    asm                 Assemble Hermes Bytecode

Args:
    HBC_FILE            Target HBC file
    HASM_PATH           Target HASM directory path

Options:
    --version           Show hbctool version
    --help              Show hbctool help manual

Examples:
    hbctool disasm index.android.bundle test_hasm
    hbctool asm test_hasm index.android.bundle

For Android, the HBC file normally locates at assets directory with index.android.bundle filename.

Support

hbctool currently supports only Hermes Bytecode version 74.

Contribution

Feel free to create an issue or submit the merge request. Anyway you want to contribute this project. I'm very happy about it.

However, please run the unit test before submiting the pull request.

cd hbctool
python test.py

I use poetry to build this tool. To build it yourself, simply execute:

poetry install

Next Step

  • Add the other Hermes bytecode versions
  • Create a class abstraction
  • Support overflow patching
  • Do all TODO, NOTE, FIXME in source code
Comments
  • Support for version 62

    Support for version 62

    Hi, thanks for making this tool, I thought I wouldn't be able to analyze react native apps anymore ! Anyway, I don't know if I should create another issue, but could you also add support for version 62 please ? Used by: com.canaltp.ametis

    Thank you

    opened by Karim0x1 3
  • HBC Version (84) Error

    HBC Version (84) Error

    • I recently tried to decompile the index.android.bundle file with hbctool
    • But when tried I faced with this issue
    # error
    (hbctool) dnoscp@arupadaiveedu:~/Desktop/data/PATCH2$ hbctool disasm apktool/assets/index.android.bundle decompiled
    [*] Disassemble 'apktool/assets/index.android.bundle' to 'decompiled' path
    Traceback (most recent call last):
      File "/opt/tools/hbctool/bin/hbctool", line 8, in <module>
        sys.exit(main())
      File "/opt/tools/hbctool/lib/python3.10/site-packages/hbctool/__init__.py", line 61, in main
        disasm(args['<HBC_FILE>'], args['<HASM_PATH>'])
      File "/opt/tools/hbctool/lib/python3.10/site-packages/hbctool/__init__.py", line 33, in disasm
        hbco = hbc.load(f)
      File "/opt/tools/hbctool/lib/python3.10/site-packages/hbctool/hbc/__init__.py", line 29, in load
        assert version in HBC, f"The HBC version ({version}) is not supported."
    AssertionError: The HBC version (84) is not supported.
    
    • The information of the file
    # file info
    (hbctool) dnoscp@arupadaiveedu:~/Desktop/data/PATCH2$ file apktool/assets/index.android.bundle 
    apktool/assets/index.android.bundle: Hermes JavaScript bytecode, version 84
    
    • Someone please help to solve this issue.
    opened by dhaneshnarmatha 2
  • Jump to an address in instruction file

    Jump to an address in instruction file

    Hi,

    First thank you for the support of Version 59. It works well for me.

    I am trying to understand the bytecode in the instruction file and have a hard time knowing the offset of the jump.

    I looked at the source code of Hermes, they mentioned clearly that : "The address is relative to the offset of the instruction."

    In the instruction file, I don't see the addresses of instructions.

    Here is my question let's say the code says: Line 100 JmpFalse Addr8:18, Reg8:0 my understanding is if Reg8:0 is false, then the instruction will jump to a relative address to the JumpFalse instruction by 18. Is that means it will jump to line 118?

    The number 18 in Addr8:18 is what I don't understand. How I will know where the code will jump if Reg8:0 is False? If it is True, I imagine the next instruction will be executed, but if it is false, I can't see the addresses to knows what will be the next executed instruction.

    I know it is Hermes question, but I hope you can make it clear for me.

    Thank you.

    opened by euzada 2
  • i am getting the following error on the 84 version

    i am getting the following error on the 84 version

    [*] Disassemble 'index.android.bundle' to 'hbctool' path Traceback (most recent call last): File "/usr/local/bin/hbctool", line 8, in sys.exit(main()) File "/usr/local/lib/python3.9/site-packages/hbctool/init.py", line 61, in main disasm(args['<HBC_FILE>'], args['<HASM_PATH>']) File "/usr/local/lib/python3.9/site-packages/hbctool/init.py", line 33, in disasm hbco = hbc.load(f) File "/usr/local/lib/python3.9/site-packages/hbctool/hbc/init.py", line 29, in load assert version in HBC, f"The HBC version ({version}) is not supported." AssertionError: The HBC version (84) is not supported.

    opened by Philmon43 1
  • Add support to Hermes version 83, 89 and improve contribution process

    Add support to Hermes version 83, 89 and improve contribution process

    • Version support added 84 (via niosega), 85,89,83
    • Test cases are now running some fixing was needed
    • Added a readme on how to add new versions.

    Very thank for @cyfinoid @anantshri

    opened by bongtrop 1
  • hbc v85

    hbc v85

    Hey there, this is a pull request based on the work of https://github.com/niosega/hbctool/tree/draft/hbc-v84/hbctool, to add support for hermes bytecode v85 I'm not super sure how stable it is, as I know practically nothing about React Native, all I know, is that I was able to disassemble a react native app with hbc v85 with this. Feel free to let me if there are any other requirements to getting this merged, other than running tests, which ran successfully

    opened by hugohabicht01 1
  • where is the build output of hbctool?

    where is the build output of hbctool?

    When execute this command poetry install,terminal says "Installing the current project: hbctool (0.1.3)", but where is the output, or where did it installed?

    opened by joshuachenn 1
  • AssertionError

    AssertionError

    ======================================================================
    FAIL: test_get_function (hbctool.hbc.hbc76.test.TestHBC76)
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "/media/x/all/hack_tools/android_pentest/hbctool/hbctool/hbc/hbc76/test.py", line 22, in test_get_function
        self.assertEqual(functionCount, len(target_offsets))
    AssertionError: 31666 != 3946
    
    ======================================================================
    FAIL: test_get_string (hbctool.hbc.hbc76.test.TestHBC76)
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "/media/x/all/hack_tools/android_pentest/hbctool/hbctool/hbc/hbc76/test.py", line 43, in test_get_string
        self.assertEqual(stringCount, len(target_strings))
    AssertionError: 57366 != 4656
    
    ----------------------------------------------------------------------
    Ran 23 tests in 43.542s
    

    I recieved error when try to disasm hermes 76. Please! Help me :(

    opened by phongngan 0
  • The HBC version (84) is not supported.

    The HBC version (84) is not supported.

    C:\Users\Max\feeld\co.feeld\assets>hbctool disasm index.android.bundle test_hasm
    [*] Disassemble 'index.android.bundle' to 'test_hasm' path
    Traceback (most recent call last):
      File "C:\Users\Max\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 196, in _run_module_as_main
        return _run_code(code, main_globals, None,
      File "C:\Users\Max\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 86, in _run_code
        exec(code, run_globals)
      File "C:\Users\Max\AppData\Local\Programs\Python\Python310\Scripts\hbctool.exe\__main__.py", line 7, in <module>
      File "C:\Users\Max\AppData\Local\Programs\Python\Python310\lib\site-packages\hbctool\__init__.py", line 61, in main
        disasm(args['<HBC_FILE>'], args['<HASM_PATH>'])
      File "C:\Users\Max\AppData\Local\Programs\Python\Python310\lib\site-packages\hbctool\__init__.py", line 33, in disasm
        hbco = hbc.load(f)
      File "C:\Users\Max\AppData\Local\Programs\Python\Python310\lib\site-packages\hbctool\hbc\__init__.py", line 29, in load
        assert version in HBC, f"The HBC version ({version}) is not supported."
    AssertionError: The HBC version (84) is not supported.
    
    opened by BaseMax 3
  • List index out of range: version 84

    List index out of range: version 84

    I get the following error when trying to disassemble an android bundle using hermes bytecode version 84:

    [*] Disassemble 'index.android.bundle' to 'out' path
    [*] Hermes Bytecode [ Source Hash: d47dd92ea0ad2ab0ad46438a7f6f4a2ee383dbf5, HBC Version: 84 ]
    Traceback (most recent call last):
      File "hbctool\.venv\Scripts\\hbctool", line 6, in <module>
        sys.exit(main())
                 ^^^^^^
      File "hbctool\hbctool\__init__.py", line 61, in main
        disasm(args['<HBC_FILE>'], args['<HASM_PATH>'])
      File "hbctool\hbctool\__init__.py", line 41, in disasm
        hasm.dump(hbco, hasmpath)
      File "hbctool\hbctool\hasm.py", line 67, in dump
        write_func(f, hbc.getFunction(i), i, hbc)
                      ^^^^^^^^^^^^^^^^^^
      File "hbctool\hbctool\hbc\hbc84\__init__.py", line 59, in getFunction
        insts = disassemble(bc)
                ^^^^^^^^^^^^^^^
      File "hbctool\hbctool\hbc\hbc84\translator.py", line 33, in disassemble
        opcode = opcode_mapper[bc[i]]
                 ~~~~~~~~~~~~~^^^^^^^
    IndexError: list index out of range
    
    opened by Puyodead1 1
  • Add support to Hermes version 83, 89 and improve contribution process

    Add support to Hermes version 83, 89 and improve contribution process

    • Version support added 84 (via niosega), 85,89,83
    • Test cases are now running some fixing was needed
    • Added a readme on how to add new versions.

    Very thank for https://github.com/cyfinoid @anantshri

    opened by bongtrop 7
  • FYI : updates version 84,85,89 and test corrections

    FYI : updates version 84,85,89 and test corrections

    Hi @bongtrop Thanks for the nice tool.

    I have been working on updating few things here : https://github.com/cyfinoid/hbctool

    I see 84,85 support got merged recently hence cant open a clear pull request. Following changes are available in my branch if you want to cherrypick

    1. Version support added 84 (via niosega), 85,89,83
    2. Test cases are now running some fixing was needed
    3. Added a readme on how to add new versions.

    Feel free to pick and choose

    opened by anantshri 2
  • HBC-76 examples include version 74 bytecode file

    HBC-76 examples include version 74 bytecode file

    The example index.android.bundle file is version 74 and not 76

    00000000: c61f bc03 c103 191f 4a00 0000 d031 0a88  ........J....1..
    

    byte 0x9 should be 4c and not 4a

    opened by hexpwn 0
  • disasm error

    disasm error

    Hi, i got error with command "hbctool disasm index.android.bundle test_hasm". Please help: [*] Disassemble 'index.android.bundle' to 'test_hasm' path Traceback (most recent call last): File "C:\Program Files\Python310\lib\runpy.py", line 196, in run_module_as_main return run_code(code, main_globals, None, File "C:\Program Files\Python310\lib\runpy.py", line 86, in run_code exec(code, run_globals) File "C:\Program Files\Python310\Scripts\hbctool.exe_main.py", line 7, in File "C:\Program Files\Python310\lib\site-packages\hbctool_init.py", line 61, in main disasm(args['<HBC_FILE>'], args['<HASM_PATH>']) File "C:\Program Files\Python310\lib\site-packages\hbctool_init.py", line 33, in disasm hbco = hbc.load(f) File "C:\Program Files\Python310\lib\site-packages\hbctool\hbc_init_.py", line 28, in load assert magic == MAGIC, f"The magic ({hex(magic)}) is invalid. (must be {hex(MAGIC)})" AssertionError: The magic (0x55425f5f20726176) is invalid. (must be 0x1f1903c103bc1fc6)

    opened by blueveno 0
Owner
Pongsakorn Sommalai
IT Security Consultant, OSCE, Pentest+
Pongsakorn Sommalai
Reverse engineering multi-device WhatsApp Web.

whatsapp-web-multi-device-reveng In this repository, the research for reverse engineering multi-device WhatsApp Web takes place, see here for a descri

null 84 Jan 1, 2023
This is a repository for the Duke University Cloud Computing course project on Serveless Data Engineering Pipeline. For this project, I recreated the below pipeline.

AWS Data Engineering Pipeline This is a repository for the Duke University Cloud Computing course project on Serverless Data Engineering Pipeline. For

null 15 Jul 28, 2021
Intelligent Trading Bot: Automatically generating signals and trading based on machine learning and feature engineering

Intelligent Trading Bot: Automatically generating signals and trading based on machine learning and feature engineering

Alexandr Savinov 326 Jan 3, 2023
This is my personal version of Pac-Man using python, which is the first assignment of EA Software Engineering Virtual Experience Program from Forage.com

Vac-Man in Python This is my personal version of Vax-man game using python, which is the first task of EA Software Engineering Virtual Experience Prog

ZiXiang Luo 3 Jan 5, 2022
My attempt to reverse the Discord nitro token generation function.

discord-theory-I PART: I My attempt to reverse the Discord nitro token generation function. The Nitro generation tools thing is common in Discord now,

Jakom 29 Aug 14, 2022
Reverse engineered connection to the TradingView ticker in Python

Tradingview-ticker Reverse engineered connection to the TradingView ticker in Python. Makes a websocket connection to the Tradeview website and receiv

Aaron 20 Dec 2, 2022
Discord-shell - Reverse shell accessible via discord.py bot

Discord-shell reverse shell on discord bot. (STILL IN DEVELOPMENT) Installation

Skultz 6 Oct 21, 2022
📷 Instagram Bot - Tool for automated Instagram interactions

InstaPy Tooling that automates your social media interactions to “farm” Likes, Comments, and Followers on Instagram Implemented in Python using the Se

Tim Großmann 13.5k Dec 1, 2021
A tool for extracting plain text from Wikipedia dumps

WikiExtractor WikiExtractor.py is a Python script that extracts and cleans text from a Wikipedia database dump. The tool is written in Python and requ

Giuseppe Attardi 3.2k Dec 31, 2022
A tool that helps keeping track of your AWS quota utilization

aws-quota-checker A tool that helps keeping track of your AWS quota utilization. It'll determine the limits of your AWS account and compare them to th

Max 63 Dec 14, 2022
An automated tool that fetches information about your crypto stake and generates historical data in time.

Introduction Yield explorer is a WIP! I needed a tool that would show me historical data and performance of my staked crypto but was unable to find a

Sedat Can Yalçın 42 Nov 26, 2022
An integrated information collection tool

infoscaner 环境配置 目前infoscaner仅支持在linux上运行,建议运行在最新版本的kali中 infoscaner是基于python3版本实现的,运行之前首先安装python库 如果同时存在python2和python3,请输入以下命令 pip3 install -r requi

CMACCKK 74 Sep 13, 2021
Yandex OSINT tool

YaSeeker Description YaSeeker - an OSINT tool to get info about any Yandex account using email or login. It can find: Fullname Photo Gender Yandex UID

HowToFind 110 Jan 3, 2023
A tool for exporting Telegram group chats into static websites, preserving chat history like mailing list archives.

tg-archive is a tool for exporting Telegram group chats into static websites, preserving chat history like mailing list archives. Preview The @fossuni

Kailash Nadh 400 Dec 27, 2022
OSINT tool to get information from a Github and Gitlab profile and find user's email addresses leaked on commits.

gitrecon OSINT tool to get information from a Github or Gitlab profile and find user's email addresses leaked on commits. ?? How does this work? GitHu

GOΠZO 211 Dec 17, 2022
A little proxy tool based on Tencent Cloud Function Service.

SCFProxy 一个基于腾讯云函数服务的免费代理池。 安装 python3 -m venv .venv source .venv/bin/activate pip3 install -r requirements.txt 项目配置 函数配置 开通腾讯云函数服务 在 函数服务 > 新建 中使用自定义

Mio 716 Dec 26, 2022
修改自SharpNoPSExec的基于python的横移工具 A Lateral Movement Tool Learned From SharpNoPSExec -- Twitter: @juliourena

PyNoPSExec A Lateral Movement Tool Learned From SharpNoPSExec -- Twitter: @juliourena 根据@juliourena大神的SharpNOPsExec项目改写的横向移动工具 Platform(平台): Windows 1

b0b@c 23 Nov 9, 2022
GG Dorking is a tool to generate GitHub and Google dorking for pentesters and bug bounty hunters.

GG-Dorking GG Dorking is a python tool to generate GitHub and Google dorking links for pentesters and bug bounty hunters. It will help you to find imp

Eslam Akl 80 Nov 24, 2022