hbctool-cli 0.1.6

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

A Hermes bytecode disassembler and assembler for React Native bundles.
Originally created by baba01hacker and continued by Doraemon cyber team.

Why hbctool

React Native apps can ship JavaScript through the Hermes engine, which compiles application code into Hermes bytecode. That makes reverse engineering, inspection, and patching harder than working with plain JavaScript bundles.

hbctool helps with that workflow by letting you:

• disassemble a Hermes bundle into a readable HASM representation
• modify metadata, strings, and instructions
• rebuild a valid Hermes bytecode bundle from the edited output
• use either the pure-Python path or the optional native C++ acceleration path

Features

• Disassemble Hermes bytecode bundles into a directory with metadata, strings, and instructions.
• Assemble edited HASM output back into a Hermes bundle.
• Optional C++ acceleration for faster low-level operations.
• Test coverage for pure-Python and native execution paths.
• Support for Hermes bytecode versions 59, 62, 74, 76, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, and 96.

Installation

Quick install

python3 -m pip install hbctool-cli

Local development install

python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install -e .

Build the optional native extension

python3 setup.py build_ext --inplace

Enable the accelerated path at runtime:

export HBCTOOL_FASTUTIL=1

Verify that the native modules are available:

python3 -c "import hbctool._fastutil, hbctool._bitcodec; print('native extensions ok')"

If the extensions are not present, hbctool still works in pure-Python mode.

Usage

Show help:

hbctool --help

CLI syntax:

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

Examples:

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

By default:

• disasm writes to hasm/
• asm reads from hasm/ and writes index.android.bundle

For Android targets, the Hermes bundle is commonly found under the app assets/ directory as index.android.bundle.

Output Layout

A disassembly writes three files:

• metadata.json
• string.json
• instruction.hasm

This makes it practical to inspect strings, metadata, and instructions separately before rebuilding.

Benchmarking

You can benchmark the round-trip path and compare pure Python against the native path with the helper script:

python3 scripts/benchmark_roundtrip.py Testfiles/index.android.bundle --iterations 2 --max-size-ratio 1.10 --min-core-speedup 2.0 --json output/bench/report.json

The report includes:

• timing for both execution modes
• computed speedup
• output-to-input size ratio checks
• a low-level memcpy speedup check

The script exits non-zero when configured safety or performance thresholds are not met, which makes it suitable for CI gating.

Development

Run the test suite:

python3 -m pytest -q

Run the test suite with the native path enabled:

HBCTOOL_FASTUTIL=1 python3 -m pytest -q

Build distributable artifacts:

python3 -m pip install --upgrade build
python3 -m build

If the built wheel includes the compiled extension, it will be platform-tagged rather than py3-none-any.

Credits

• Original work: baba01hacker
• Ongoing maintenance and remastering: Doraemon cyber team

License

This project is released under the MIT License. See LICENSE.