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.
Files changed (63) hide show
  1. libhbc-0.3.0/CMakeLists.txt +41 -0
  2. libhbc-0.3.0/LICENSE +21 -0
  3. libhbc-0.3.0/PKG-INFO +417 -0
  4. libhbc-0.3.0/README.md +398 -0
  5. libhbc-0.3.0/bindings/CMakeLists.txt +21 -0
  6. libhbc-0.3.0/bindings/_libhbc.pyi +1191 -0
  7. libhbc-0.3.0/bindings/bindings.cpp +740 -0
  8. libhbc-0.3.0/bindings/genstub.py +109 -0
  9. libhbc-0.3.0/bindings/py.typed +0 -0
  10. libhbc-0.3.0/core/CMakeLists.txt +40 -0
  11. libhbc-0.3.0/core/include/hbc/format.h +161 -0
  12. libhbc-0.3.0/core/include/hbc/format_v94.h +14 -0
  13. libhbc-0.3.0/core/include/hbc/format_v95.h +14 -0
  14. libhbc-0.3.0/core/include/hbc/format_v96.h +14 -0
  15. libhbc-0.3.0/core/include/hbc/format_v98.h +82 -0
  16. libhbc-0.3.0/core/include/hbc/format_version.h +145 -0
  17. libhbc-0.3.0/core/include/hbc/hbc.h +646 -0
  18. libhbc-0.3.0/core/include/hbc/module.h +325 -0
  19. libhbc-0.3.0/core/src/analysis/analysis.cpp +418 -0
  20. libhbc-0.3.0/core/src/analysis/analysis.h +60 -0
  21. libhbc-0.3.0/core/src/analysis/dataflow.h +123 -0
  22. libhbc-0.3.0/core/src/analysis/environments.cpp +228 -0
  23. libhbc-0.3.0/core/src/analysis/values.cpp +782 -0
  24. libhbc-0.3.0/core/src/cfg/cfg.cpp +226 -0
  25. libhbc-0.3.0/core/src/cfg/cfg.h +30 -0
  26. libhbc-0.3.0/core/src/decompiler/decompiler.cpp +1093 -0
  27. libhbc-0.3.0/core/src/decompiler/decompiler.h +75 -0
  28. libhbc-0.3.0/core/src/disasm/disasm.cpp +171 -0
  29. libhbc-0.3.0/core/src/disasm/disasm.h +42 -0
  30. libhbc-0.3.0/core/src/format/format_legacy.cpp +171 -0
  31. libhbc-0.3.0/core/src/format/format_v98.cpp +200 -0
  32. libhbc-0.3.0/core/src/format/format_version.cpp +23 -0
  33. libhbc-0.3.0/core/src/format/identifier_hash.cpp +27 -0
  34. libhbc-0.3.0/core/src/format/opcode_categories.h +79 -0
  35. libhbc-0.3.0/core/src/format/opcodes.cpp +40 -0
  36. libhbc-0.3.0/core/src/format/opcodes.h +49 -0
  37. libhbc-0.3.0/core/src/format/opcodes_v94.cpp +275 -0
  38. libhbc-0.3.0/core/src/format/opcodes_v95.cpp +275 -0
  39. libhbc-0.3.0/core/src/format/opcodes_v96.cpp +275 -0
  40. libhbc-0.3.0/core/src/format/opcodes_v98.cpp +275 -0
  41. libhbc-0.3.0/core/src/parser/bigint_table.cpp +103 -0
  42. libhbc-0.3.0/core/src/parser/bigint_table.h +34 -0
  43. libhbc-0.3.0/core/src/parser/cjs_module_table.cpp +43 -0
  44. libhbc-0.3.0/core/src/parser/cjs_module_table.h +39 -0
  45. libhbc-0.3.0/core/src/parser/exception_table.cpp +69 -0
  46. libhbc-0.3.0/core/src/parser/exception_table.h +26 -0
  47. libhbc-0.3.0/core/src/parser/function_source_table.cpp +51 -0
  48. libhbc-0.3.0/core/src/parser/function_source_table.h +32 -0
  49. libhbc-0.3.0/core/src/parser/function_table.cpp +94 -0
  50. libhbc-0.3.0/core/src/parser/function_table.h +21 -0
  51. libhbc-0.3.0/core/src/parser/parser.cpp +921 -0
  52. libhbc-0.3.0/core/src/parser/section_layout.h +67 -0
  53. libhbc-0.3.0/core/src/parser/string_kind.cpp +35 -0
  54. libhbc-0.3.0/core/src/parser/string_kind.h +19 -0
  55. libhbc-0.3.0/core/src/parser/string_table.cpp +201 -0
  56. libhbc-0.3.0/core/src/parser/string_table.h +28 -0
  57. libhbc-0.3.0/core/src/patcher/module.cpp +1221 -0
  58. libhbc-0.3.0/core/src/patcher/patcher.cpp +133 -0
  59. libhbc-0.3.0/core/src/util/sha1.cpp +77 -0
  60. libhbc-0.3.0/core/src/util/sha1.h +14 -0
  61. libhbc-0.3.0/core/src/util/slp.cpp +68 -0
  62. libhbc-0.3.0/core/src/util/slp.h +39 -0
  63. 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
+ [![Mentioned in Awesome Reverse Engineering](https://awesome.re/mentioned-badge.svg)](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).