libhbc 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- libhbc-0.3.0/CMakeLists.txt +41 -0
- libhbc-0.3.0/LICENSE +21 -0
- libhbc-0.3.0/PKG-INFO +417 -0
- libhbc-0.3.0/README.md +398 -0
- libhbc-0.3.0/bindings/CMakeLists.txt +21 -0
- libhbc-0.3.0/bindings/_libhbc.pyi +1191 -0
- libhbc-0.3.0/bindings/bindings.cpp +740 -0
- libhbc-0.3.0/bindings/genstub.py +109 -0
- libhbc-0.3.0/bindings/py.typed +0 -0
- libhbc-0.3.0/core/CMakeLists.txt +40 -0
- libhbc-0.3.0/core/include/hbc/format.h +161 -0
- libhbc-0.3.0/core/include/hbc/format_v94.h +14 -0
- libhbc-0.3.0/core/include/hbc/format_v95.h +14 -0
- libhbc-0.3.0/core/include/hbc/format_v96.h +14 -0
- libhbc-0.3.0/core/include/hbc/format_v98.h +82 -0
- libhbc-0.3.0/core/include/hbc/format_version.h +145 -0
- libhbc-0.3.0/core/include/hbc/hbc.h +646 -0
- libhbc-0.3.0/core/include/hbc/module.h +325 -0
- libhbc-0.3.0/core/src/analysis/analysis.cpp +418 -0
- libhbc-0.3.0/core/src/analysis/analysis.h +60 -0
- libhbc-0.3.0/core/src/analysis/dataflow.h +123 -0
- libhbc-0.3.0/core/src/analysis/environments.cpp +228 -0
- libhbc-0.3.0/core/src/analysis/values.cpp +782 -0
- libhbc-0.3.0/core/src/cfg/cfg.cpp +226 -0
- libhbc-0.3.0/core/src/cfg/cfg.h +30 -0
- libhbc-0.3.0/core/src/decompiler/decompiler.cpp +1093 -0
- libhbc-0.3.0/core/src/decompiler/decompiler.h +75 -0
- libhbc-0.3.0/core/src/disasm/disasm.cpp +171 -0
- libhbc-0.3.0/core/src/disasm/disasm.h +42 -0
- libhbc-0.3.0/core/src/format/format_legacy.cpp +171 -0
- libhbc-0.3.0/core/src/format/format_v98.cpp +200 -0
- libhbc-0.3.0/core/src/format/format_version.cpp +23 -0
- libhbc-0.3.0/core/src/format/identifier_hash.cpp +27 -0
- libhbc-0.3.0/core/src/format/opcode_categories.h +79 -0
- libhbc-0.3.0/core/src/format/opcodes.cpp +40 -0
- libhbc-0.3.0/core/src/format/opcodes.h +49 -0
- libhbc-0.3.0/core/src/format/opcodes_v94.cpp +275 -0
- libhbc-0.3.0/core/src/format/opcodes_v95.cpp +275 -0
- libhbc-0.3.0/core/src/format/opcodes_v96.cpp +275 -0
- libhbc-0.3.0/core/src/format/opcodes_v98.cpp +275 -0
- libhbc-0.3.0/core/src/parser/bigint_table.cpp +103 -0
- libhbc-0.3.0/core/src/parser/bigint_table.h +34 -0
- libhbc-0.3.0/core/src/parser/cjs_module_table.cpp +43 -0
- libhbc-0.3.0/core/src/parser/cjs_module_table.h +39 -0
- libhbc-0.3.0/core/src/parser/exception_table.cpp +69 -0
- libhbc-0.3.0/core/src/parser/exception_table.h +26 -0
- libhbc-0.3.0/core/src/parser/function_source_table.cpp +51 -0
- libhbc-0.3.0/core/src/parser/function_source_table.h +32 -0
- libhbc-0.3.0/core/src/parser/function_table.cpp +94 -0
- libhbc-0.3.0/core/src/parser/function_table.h +21 -0
- libhbc-0.3.0/core/src/parser/parser.cpp +921 -0
- libhbc-0.3.0/core/src/parser/section_layout.h +67 -0
- libhbc-0.3.0/core/src/parser/string_kind.cpp +35 -0
- libhbc-0.3.0/core/src/parser/string_kind.h +19 -0
- libhbc-0.3.0/core/src/parser/string_table.cpp +201 -0
- libhbc-0.3.0/core/src/parser/string_table.h +28 -0
- libhbc-0.3.0/core/src/patcher/module.cpp +1221 -0
- libhbc-0.3.0/core/src/patcher/patcher.cpp +133 -0
- libhbc-0.3.0/core/src/util/sha1.cpp +77 -0
- libhbc-0.3.0/core/src/util/sha1.h +14 -0
- libhbc-0.3.0/core/src/util/slp.cpp +68 -0
- libhbc-0.3.0/core/src/util/slp.h +39 -0
- libhbc-0.3.0/pyproject.toml +65 -0
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
cmake_minimum_required(VERSION 3.20)
|
|
2
|
+
project(hermit VERSION 0.3.0 LANGUAGES CXX)
|
|
3
|
+
|
|
4
|
+
set(CMAKE_CXX_STANDARD 20)
|
|
5
|
+
set(CMAKE_CXX_STANDARD_REQUIRED ON)
|
|
6
|
+
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
|
|
7
|
+
|
|
8
|
+
# Dependencies
|
|
9
|
+
# Development.Module (not the full Development) so manylinux wheels build: they
|
|
10
|
+
# ship the module headers/libs but not the embed library (Development.Embed).
|
|
11
|
+
find_package(Python3 COMPONENTS Interpreter Development.Module REQUIRED)
|
|
12
|
+
|
|
13
|
+
# pybind11: prefer one already provided (pip/Homebrew/system) so a sandboxed
|
|
14
|
+
# build with no network - Homebrew's clean room, cibuildwheel's isolated build
|
|
15
|
+
# env - still configures. A plain `cmake -B build` finds none and falls back to
|
|
16
|
+
# FetchContent, version-pinned and cached under build/_deps after the first
|
|
17
|
+
# configure. Bump GIT_TAG to upgrade.
|
|
18
|
+
find_package(pybind11 CONFIG QUIET)
|
|
19
|
+
if(NOT pybind11_FOUND)
|
|
20
|
+
include(FetchContent)
|
|
21
|
+
FetchContent_Declare(
|
|
22
|
+
pybind11
|
|
23
|
+
GIT_REPOSITORY https://github.com/pybind/pybind11.git
|
|
24
|
+
GIT_TAG v2.13.6
|
|
25
|
+
GIT_SHALLOW TRUE
|
|
26
|
+
)
|
|
27
|
+
FetchContent_MakeAvailable(pybind11)
|
|
28
|
+
endif()
|
|
29
|
+
|
|
30
|
+
# Core library
|
|
31
|
+
add_subdirectory(core)
|
|
32
|
+
|
|
33
|
+
# Python bindings
|
|
34
|
+
add_subdirectory(bindings)
|
|
35
|
+
|
|
36
|
+
option(HERMIT_BUILD_TESTS "Build the Catch2 unit tests" ON)
|
|
37
|
+
|
|
38
|
+
if(HERMIT_BUILD_TESTS)
|
|
39
|
+
enable_testing()
|
|
40
|
+
add_subdirectory(tests)
|
|
41
|
+
endif()
|
libhbc-0.3.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Valerio Pio De Nicola
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
libhbc-0.3.0/PKG-INFO
ADDED
|
@@ -0,0 +1,417 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: libhbc
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Hermes bytecode (HBC) parser, disassembler, decompiler and structural patcher — native bindings
|
|
5
|
+
Keywords: hermes,hbc,react-native,bytecode,reverse-engineering
|
|
6
|
+
Author: Valerio Pio De Nicola
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Topic :: Security
|
|
12
|
+
Classifier: Topic :: Software Development :: Disassemblers
|
|
13
|
+
Classifier: Programming Language :: C++
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Project-URL: Homepage, https://github.com/xV4L3x/hermit
|
|
16
|
+
Project-URL: Repository, https://github.com/xV4L3x/hermit
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
|
|
20
|
+
<img width="1774" height="887" alt="Hermit Banner" src="https://github.com/user-attachments/assets/bf7fcdb8-6d7a-4aab-9f19-7ded6d76858e" />
|
|
21
|
+
|
|
22
|
+
# Hermit
|
|
23
|
+
|
|
24
|
+
**Hermes Reverse Engineering & Manipulation Interactive Toolkit.**
|
|
25
|
+
|
|
26
|
+
[](https://github.com/morluto/awesome-reverse-engineering)
|
|
27
|
+
|
|
28
|
+
hermit inspects, decompiles and structurally patches Hermes bytecode (HBC), the
|
|
29
|
+
format React Native apps ship their JavaScript in. Open an `.hbc` file, browse
|
|
30
|
+
its functions, read the decompiled JavaScript, edit instructions, strings and
|
|
31
|
+
literals in an interactive editor, and write back a file that the Hermes VM
|
|
32
|
+
still loads and runs.
|
|
33
|
+
|
|
34
|
+
Unlike tools that only analyse bytecode, or that patch it in place without
|
|
35
|
+
changing sizes, hermit re-serializes the whole file. It can insert and delete
|
|
36
|
+
instructions, relocate jumps and exception handlers, rebuild the string and
|
|
37
|
+
literal tables, add new functions and recompute the SHA-1 footer. An unmodified
|
|
38
|
+
file round-trips byte for byte.
|
|
39
|
+
|
|
40
|
+
- [Features](#features)
|
|
41
|
+
- [Supported HBC versions](#supported-hbc-versions)
|
|
42
|
+
- [Install](#install)
|
|
43
|
+
- [Build from source](#build-from-source)
|
|
44
|
+
- [Getting an `.hbc` file](#getting-an-hbc-file)
|
|
45
|
+
- [Using the REPL](#using-the-repl)
|
|
46
|
+
- [Editing and patching](#editing-and-patching)
|
|
47
|
+
- [Python API](#python-api)
|
|
48
|
+
- [Tests](#tests)
|
|
49
|
+
- [Project layout](#project-layout)
|
|
50
|
+
- [Limitations](#limitations)
|
|
51
|
+
|
|
52
|
+
## Features
|
|
53
|
+
|
|
54
|
+
- **Parser**: header, string table (UTF-16 and overflow entries included),
|
|
55
|
+
function table (overflow headers and shared bytecode bodies included),
|
|
56
|
+
literal buffers, exception handlers, debug info, function source table.
|
|
57
|
+
- **Disassembler** with per-version opcode tables (94, 95, 96, 98).
|
|
58
|
+
- **Control-flow graph** with DOT export, call graph, string cross-references,
|
|
59
|
+
Metro module recovery.
|
|
60
|
+
- **Decompiler** from the CFG to readable JavaScript: if/else, loops,
|
|
61
|
+
try/catch, closures, array and object literals. Deterministic, no AI.
|
|
62
|
+
- **Structural patcher**: edit a function body, change string and literal
|
|
63
|
+
values, add a function. Branch relaxation, exception-handler relocation,
|
|
64
|
+
overflow function headers, byte-identical round-trip.
|
|
65
|
+
- **Interactive REPL** (GDB style) with a full-screen bytecode editor.
|
|
66
|
+
|
|
67
|
+
## Supported HBC versions
|
|
68
|
+
|
|
69
|
+
| Version | Role |
|
|
70
|
+
|---|---|
|
|
71
|
+
| **96** | Primary target. What shipping React Native apps use: RN 0.73 to 0.83, and RN 0.84+ with Hermes V1 disabled. |
|
|
72
|
+
| 94, 95 | Validated. The format is identical to 96, only the opcode tables differ. |
|
|
73
|
+
| **98** | Static Hermes (Hermes V1), the default from RN 0.84. A separate wire format (12-byte function headers, object shape table, renumbered opcodes); parsed, round-tripped and patched like 96. |
|
|
74
|
+
|
|
75
|
+
Per-version differences are handled by a `FormatVersion` module selected at
|
|
76
|
+
runtime (like the opcode tables), not by inline version branches. Format notes
|
|
77
|
+
are in [`doc/hbc-format/`](doc/hbc-format/).
|
|
78
|
+
|
|
79
|
+
## Install
|
|
80
|
+
|
|
81
|
+
The quickest way, on macOS or Linux, any architecture:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
pipx install hermit-hbc # isolated; recommended
|
|
85
|
+
# or: pip install hermit-hbc
|
|
86
|
+
hermit app.hbc
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
This pulls the compiled engine (`libhbc`) as a dependency. To use just the
|
|
90
|
+
native bindings, without the REPL:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
pip install libhbc
|
|
94
|
+
python -c "import _libhbc; print(_libhbc.HBCFile)"
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
**Homebrew** (macOS, Linuxbrew):
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
brew install xV4L3x/hermit/hermit
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
**Debian / Ubuntu** — download `hermit_<version>_<arch>.deb` from a
|
|
104
|
+
[release](https://github.com/xV4L3x/hermit/releases) and:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
sudo apt install ./hermit_0.3.0_amd64.deb
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**No package manager** — each release also has a self-contained
|
|
111
|
+
`hermit-<version>-<platform>.tar.gz` for macOS and Linux (arm64 and x86_64),
|
|
112
|
+
needing no Python or compiler:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
tar -xzf hermit-0.3.0-macos-arm64.tar.gz
|
|
116
|
+
./hermit-0.3.0-macos-arm64/hermit --version
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
The macOS archive is not signed; clear the quarantine flag once with
|
|
120
|
+
`xattr -dr com.apple.quarantine hermit-0.3.0-macos-arm64`. The Linux archive and
|
|
121
|
+
`.deb` need glibc 2.35 or newer. The `cfg` command needs `graph-easy` installed
|
|
122
|
+
(any install method). Releases are produced by `.github/workflows/release.yml`
|
|
123
|
+
and `.github/workflows/wheels.yml` on a `v*` tag.
|
|
124
|
+
|
|
125
|
+
## Build from source
|
|
126
|
+
|
|
127
|
+
### Requirements
|
|
128
|
+
|
|
129
|
+
- CMake 3.20 or newer and a C++20 compiler (Clang or GCC).
|
|
130
|
+
- Python 3.10+ with development headers (needed by pybind11).
|
|
131
|
+
- Network access on the first configure: pybind11 and Catch2 are fetched with
|
|
132
|
+
CMake `FetchContent` unless they are already installed.
|
|
133
|
+
- Optional: [`graph-easy`](https://metacpan.org/pod/Graph::Easy) for the `cfg`
|
|
134
|
+
command (`cpanm Graph::Easy`), `less` as its pager.
|
|
135
|
+
|
|
136
|
+
### Compile
|
|
137
|
+
|
|
138
|
+
Run everything from this directory (the one containing `CMakeLists.txt`):
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
cmake -B build
|
|
142
|
+
cmake --build build -j
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
This builds the `libhbc` static library, the Python module `_libhbc` (in
|
|
146
|
+
`build/bindings/`) and the unit tests. The REPL only needs the Python module:
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
cmake --build build --target _libhbc
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The tests can be left out of a build, for example for a release:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
cmake -B build -DCMAKE_BUILD_TYPE=Release -DHERMIT_BUILD_TESTS=OFF
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Rebuild with the same command after every change to `core/` or `bindings/`.
|
|
159
|
+
|
|
160
|
+
> **macOS:** if linking fails with an error about a malformed SDK, point the
|
|
161
|
+
> build at a complete SDK, for example
|
|
162
|
+
> `SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk cmake --build build`.
|
|
163
|
+
|
|
164
|
+
### Python environment
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
python3 -m venv .venv
|
|
168
|
+
.venv/bin/pip install -r requirements.txt
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
The module `_libhbc` is not installed into the virtualenv. Add its build
|
|
172
|
+
directory to `PYTHONPATH` whenever you run hermit:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
export PYTHONPATH=$PWD/build/bindings:$PYTHONPATH
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
## Getting an `.hbc` file
|
|
179
|
+
|
|
180
|
+
A React Native app ships its bundle as a plain file:
|
|
181
|
+
|
|
182
|
+
| Platform | Location inside the package |
|
|
183
|
+
|---|---|
|
|
184
|
+
| Android (`.apk`, a zip) | `assets/index.android.bundle` |
|
|
185
|
+
| iOS (`.ipa`, a zip) | `Payload/<App>.app/main.jsbundle` |
|
|
186
|
+
|
|
187
|
+
If the file starts with the bytes `C6 1F BC 03 C1 03 19 1F`, it is Hermes
|
|
188
|
+
bytecode. The REPL only opens files with the `.hbc` extension, so rename it:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
unzip -p app.apk assets/index.android.bundle > app.hbc
|
|
192
|
+
xxd app.hbc | head -1 # c61f bc03 c103 191f ...
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Only analyse apps you are allowed to study, for example your own, or
|
|
196
|
+
open-source apps for research.
|
|
197
|
+
|
|
198
|
+
### Building test bundles from source
|
|
199
|
+
|
|
200
|
+
To get small, controlled inputs, compile JavaScript or TypeScript with a Hermes
|
|
201
|
+
compiler that emits HBC 96 (for example `hermesc` from `react-native` 0.73 to
|
|
202
|
+
0.83, under `node_modules/react-native/sdks/hermesc/`):
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
hermes -emit-binary -g0 -out hello.hbc hello.js # -g0: no debug info
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
The `seeder/` package automates this for the sample programs in
|
|
209
|
+
`seeder/samples/` and writes the results to `seeder/corpus/`:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
.venv/bin/python -m seeder.compile # all samples
|
|
213
|
+
.venv/bin/python -m seeder.compile --g0 seeder/samples/loop_sum.js
|
|
214
|
+
.venv/bin/python -m seeder.compile --debug seeder/samples/greeting.js
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
`--g0` writes `<name>_g0.hbc` without debug info, `--debug` writes
|
|
218
|
+
`<name>_g.hbc` with full debug info. `.ts` samples need `tsc` on your `PATH`;
|
|
219
|
+
the compiler is taken from `--hermes` (default `hermes`). `seeder/build-real-bundle.sh`
|
|
220
|
+
builds a real open-source React Native app into an `.hbc`.
|
|
221
|
+
|
|
222
|
+
## Using the REPL
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
export PYTHONPATH=$PWD/build/bindings:$PYTHONPATH
|
|
226
|
+
.venv/bin/python -m cli.main app.hbc
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Without a file argument the REPL starts empty; use `open <file.hbc>`. The
|
|
230
|
+
prompt shows the HBC version and the file name, with a `+` when there are
|
|
231
|
+
unsaved changes: `[hbc v96 | app+] >`. History is kept in `~/.hermit_history`
|
|
232
|
+
and commands are tab-completed.
|
|
233
|
+
|
|
234
|
+
```
|
|
235
|
+
> info
|
|
236
|
+
> strings --identifiers filter:fetch
|
|
237
|
+
> functions
|
|
238
|
+
> disasm func:12
|
|
239
|
+
> decompile func:isPremium
|
|
240
|
+
> xrefs string:"api.example.com"
|
|
241
|
+
> edit func:isPremium
|
|
242
|
+
> patch patched.hbc
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Functions are addressed by index or name (`func:12`, `func:isPremium`), strings
|
|
246
|
+
by index or value (`string:42`, `string:"hello"`), literal sites by index
|
|
247
|
+
(`array:7`).
|
|
248
|
+
|
|
249
|
+
| Command | What it does |
|
|
250
|
+
|---|---|
|
|
251
|
+
| `open [--permissive] <file.hbc>` | Opens a file. A string entry whose byte range leaves the string storage is rejected; `--permissive` (also `python -m cli.main --permissive <file>`) opens such a malformed file read-only and `info strings` / `strings` report each bad entry (inside file / outside file / bad overflow index). |
|
|
252
|
+
| `info [sections\|strings\|functions\|all]` | Header summary (version, sizes, counts, global function, source hash); `sections` lists every file section with start/end/size/alignment, `strings` breaks the string table down by kind, encoding and overflow, `functions` counts small/overflow headers, flags and shared bodies. |
|
|
253
|
+
| `strings [--identifiers\|--strings] [filter:<text>]` | String table with kinds. |
|
|
254
|
+
| `arrays [--arrays\|--objects] [filter:<text>] [func:<N\|name>]` | Array and object literal sites, decoded. |
|
|
255
|
+
| `functions [--module=<id>]` | All functions with parameters, registers and flags. Every function of a Metro module (its factory and every function nested in it) is tagged `# module N`, the factory `# module N entry`. `--module` lists only the functions of one module. |
|
|
256
|
+
| `modules [module:<id>]` | Metro modules (`__d(factory, id, dependencyMap)` in the global function): factory, number of functions the module implements, entry points (`__r`), dependencies. `module:<id>` details one module, with each dependencyMap entry resolved to its module. |
|
|
257
|
+
| `disasm func:<N\|name>` | Disassembly with source lines. `s` toggles the debug source table. |
|
|
258
|
+
| `disasm module:<id>` | Disassembly of every function of a Metro module in sequence (factory first, then the nested functions by index), each under a `[N] name # module X` header. `s` toggles the debug source tables. |
|
|
259
|
+
| `src [func:<N\|name>]` | Debug source table, for all functions or one. |
|
|
260
|
+
| `cfg func:<N\|name> [--compact=true\|false]` | Control-flow graph rendered with graph-easy. |
|
|
261
|
+
| `cfg module:<id> [--compact=true\|false]` | A Metro module and its direct dependencies as a graph (graph-easy); above 40 dependencies only the first 40 are drawn unless `--compact=false`. |
|
|
262
|
+
| `xrefs` | String cross-reference summary. |
|
|
263
|
+
| `xrefs string:<value\|N>` | Every instruction that uses a string. |
|
|
264
|
+
| `xrefs func:<N\|name> [--callees]` | Callers of a function (who creates or calls it); `--callees` for what it creates or calls. |
|
|
265
|
+
| `xrefs module:<id> [--callees]` | Modules that include a Metro module (with its position in their dependencyMap); `--callees` for the modules it includes. |
|
|
266
|
+
| `decompile func:<N\|name>` | Decompiled JavaScript. |
|
|
267
|
+
| `decompile module:<id>` | Decompiled JavaScript of every function of a Metro module in sequence, each under a `[N] name # module X` header. |
|
|
268
|
+
| `decompile all [--output=<dir>]` | Decompile every function to `.js` files. |
|
|
269
|
+
| `edit func:<N\|name\|new>` | Bytecode editor; `func:new` builds a new function. |
|
|
270
|
+
| `edit string:<idx\|value\|new>` | String editor; `string:new` adds a string. On an Identifier it renames the property at every site, or at one chosen site (`O` in the prompt). |
|
|
271
|
+
| `edit identifier:new` | Adds an Identifier (a property or global name for `GetById`/`PutById`/...). |
|
|
272
|
+
| `edit array:<N>` | Array and object literal editor. |
|
|
273
|
+
| `patch [file.hbc]` | Writes the edited image to a new file. |
|
|
274
|
+
| `help`, `exit` | Help and quit. |
|
|
275
|
+
|
|
276
|
+
Long listings open in a scrollable viewer: arrow keys, PgUp/PgDn, `g`/`G` for
|
|
277
|
+
top and bottom, `/` to search as you type, `Esc` to clear the search, `q` to
|
|
278
|
+
leave. `disasm` and `decompile` open it full screen, where the mouse wheel scrolls too.
|
|
279
|
+
|
|
280
|
+
## Editing and patching
|
|
281
|
+
|
|
282
|
+
Edits happen in memory. `edit ...` opens a full-screen editor; confirming with
|
|
283
|
+
`Ctrl+X` then `Y` applies the change to the in-memory image after an integrity
|
|
284
|
+
check (the file is re-parsed and compared with what was expected). Nothing is
|
|
285
|
+
written to disk until `patch`, which never overwrites the original file.
|
|
286
|
+
|
|
287
|
+
**Instruction editor** (`edit func:`):
|
|
288
|
+
|
|
289
|
+
| Key | Action |
|
|
290
|
+
|---|---|
|
|
291
|
+
| Left / Right | Move between the mnemonic and the operands. |
|
|
292
|
+
| Up / Down, PgUp / PgDn | Move between instructions. |
|
|
293
|
+
| `Enter` | Edit the selected token. A mnemonic can become any opcode with the same operand signature; operands are validated against their type. |
|
|
294
|
+
| `o` / `O` | Insert an instruction below / above (opcode picker). For a jump, `Enter` on its address operand lets you choose the target. |
|
|
295
|
+
| `Ctrl+K` | Delete the current instruction. |
|
|
296
|
+
| `R` | Restore the current line. |
|
|
297
|
+
| `Ctrl+Z` / `Ctrl+R` | Undo / redo. |
|
|
298
|
+
| `Ctrl+X` | Save and exit (Y applies, N discards, Esc cancels). |
|
|
299
|
+
|
|
300
|
+
Same-size edits are spliced in place. Inserting or deleting instructions goes
|
|
301
|
+
through the structural serializer, which relaxes short jumps to long ones when
|
|
302
|
+
needed, remaps exception-handler ranges and rewrites every offset that moved.
|
|
303
|
+
|
|
304
|
+
**String editor** (`edit string:`): a one-line editor. Same-length values are
|
|
305
|
+
written in place; any other length appends the new bytes to the string storage
|
|
306
|
+
and re-points the entry, which also detaches strings that share storage.
|
|
307
|
+
`Ctrl+N` switches to adding a new string. Identifiers are read-only, because
|
|
308
|
+
they are tied to a hash table.
|
|
309
|
+
|
|
310
|
+
**Literal editor** (`edit array:`): select an element with Up and Down and press
|
|
311
|
+
`Enter` to retype it. `Ctrl+T` changes its type (including `null`, `true` and
|
|
312
|
+
`false`), `a` appends an element or key-value pair and `d` removes the last one.
|
|
313
|
+
The key of a new pair is `string:N` of an Identifier that is not already a key of
|
|
314
|
+
that object (`edit identifier:new` creates a new one).
|
|
315
|
+
|
|
316
|
+
**Shared bytecode.** Metro and Hermes store identical function bodies once, so
|
|
317
|
+
several functions can point to the same bytes. The editor warns about it and
|
|
318
|
+
asks whether to apply the edit to all of them; editing just one is not
|
|
319
|
+
supported.
|
|
320
|
+
|
|
321
|
+
A typical session patches an in-app check and runs the result with the Hermes VM
|
|
322
|
+
of the same version:
|
|
323
|
+
|
|
324
|
+
```
|
|
325
|
+
> edit func:isPremium # change a LoadConstFalse into LoadConstTrue
|
|
326
|
+
> patch isPremium_patched.hbc
|
|
327
|
+
```
|
|
328
|
+
```bash
|
|
329
|
+
hermes isPremium_patched.hbc
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
## Python API
|
|
333
|
+
|
|
334
|
+
The REPL is a thin layer over the `_libhbc` module, which you can use directly.
|
|
335
|
+
[`doc/python-api.md`](doc/python-api.md) is the full method reference (analysis
|
|
336
|
+
entry points, return shapes, recipes); a type stub ships next to the built module
|
|
337
|
+
so editors autocomplete it.
|
|
338
|
+
|
|
339
|
+
```python
|
|
340
|
+
import _libhbc
|
|
341
|
+
|
|
342
|
+
f = _libhbc.HBCFile.open("app.hbc")
|
|
343
|
+
print(f.version(), len(f.functions()), "functions")
|
|
344
|
+
|
|
345
|
+
for fn in f.functions()[:5]:
|
|
346
|
+
print(fn.index, fn.name, fn.bytecodeSizeInBytes)
|
|
347
|
+
|
|
348
|
+
print(f.decompile(3)) # JavaScript for function 3
|
|
349
|
+
for ins in f.disasm(3):
|
|
350
|
+
print(f"{ins.offset:#06x} {ins.mnemonic}")
|
|
351
|
+
cfg = f.cfg(3) # basic blocks and edges
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
Structural patching goes through `Module`: queue one kind of edit, serialize,
|
|
355
|
+
write.
|
|
356
|
+
|
|
357
|
+
```python
|
|
358
|
+
m = _libhbc.Module.from_hbcfile(f)
|
|
359
|
+
idx = m.add_string("hello from hermit") # index of the new string
|
|
360
|
+
open("patched.hbc", "wb").write(m.serialize())
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
A `Module` accepts one kind of edit per `serialize()` (`set_function_body`,
|
|
364
|
+
`add_string`, `set_string_value`, `set_literal_value`, `resize_literal` or
|
|
365
|
+
`add_function`); for several edits, apply them one after the other, re-opening
|
|
366
|
+
the result each time.
|
|
367
|
+
|
|
368
|
+
## Tests
|
|
369
|
+
|
|
370
|
+
```bash
|
|
371
|
+
ctest --test-dir build --output-on-failure # C++ unit tests (Catch2)
|
|
372
|
+
.venv/bin/python -m pytest tests/ # integration tests
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
Most tests read files from `seeder/corpus/`, which is generated and not stored
|
|
376
|
+
in git. A test whose input is missing is skipped, so generate the corpus first
|
|
377
|
+
(see [Building test bundles from source](#building-test-bundles-from-source)).
|
|
378
|
+
Some tests also use real bundles under `seeder/real-apps/`.
|
|
379
|
+
|
|
380
|
+
Many tests patch a file and run it on the Hermes VM to check its output. They
|
|
381
|
+
need a `hermes` binary on your `PATH` (HBC 96), and for the multi-version tests
|
|
382
|
+
a binary per version: `$HERMES94` / `$HERMES95` / `$HERMES98`, or
|
|
383
|
+
`~/.local/share/hermit/hermes/hermes{94,95,98}`. Tests whose VM is not
|
|
384
|
+
available are skipped. (HBC 98 is built from the Static Hermes `static_h` branch;
|
|
385
|
+
see [`doc/hbc-format/bytecode-versions.md`](doc/hbc-format/bytecode-versions.md).)
|
|
386
|
+
|
|
387
|
+
## Project layout
|
|
388
|
+
|
|
389
|
+
| Path | Content |
|
|
390
|
+
|---|---|
|
|
391
|
+
| `core/` | C++ library `libhbc`: parser, disassembler, CFG, analysis, decompiler, patcher. Public API in `core/include/hbc/hbc.h`. |
|
|
392
|
+
| `bindings/` | pybind11 module `_libhbc`. |
|
|
393
|
+
| `cli/` | Python REPL (`repl.py`), project state (`project.py`), output formatting, and the editors in `editor/`. |
|
|
394
|
+
| `packaging/` | Distribution: PyPI (`pyproject.toml` + `packaging/pypi/`), Homebrew formula, `nfpm` Debian config, PyInstaller `build-release.sh`. |
|
|
395
|
+
| `seeder/` | Corpus generation: samples compiled with the Hermes compiler. |
|
|
396
|
+
| `tests/` | Catch2 unit tests (`unit/`) and pytest integration tests (`integration/`). |
|
|
397
|
+
| `doc/` | HBC format notes. |
|
|
398
|
+
|
|
399
|
+
## Limitations
|
|
400
|
+
|
|
401
|
+
- Object-literal *resize* on v94-96 rewrites inline operands; on v98 it appends a
|
|
402
|
+
new object shape entry. Both are supported, but editing the *keys* of an
|
|
403
|
+
existing shared shape is not.
|
|
404
|
+
- Functions containing `SwitchImm` or generator state (`SaveGenerator`) cannot
|
|
405
|
+
be edited, and those opcodes cannot be inserted.
|
|
406
|
+
- Increasing the register count of a function with an exception handler is
|
|
407
|
+
rejected: it crashes the Hermes runtime.
|
|
408
|
+
- New strings are ASCII only. A string cannot grow from the small to the
|
|
409
|
+
overflow format, and non-BMP characters cannot be written into UTF-16 strings.
|
|
410
|
+
- A new function has fixed metadata: one parameter (`this`), no name, strict
|
|
411
|
+
mode, no exception handlers or debug info.
|
|
412
|
+
- Debug source locations are not re-encoded after a structural edit, so stack
|
|
413
|
+
traces may show wrong lines. Compile with `-g0` to avoid that.
|
|
414
|
+
|
|
415
|
+
## Author
|
|
416
|
+
|
|
417
|
+
Valerio De Nicola. Released under the [MIT License](LICENSE).
|