diff --git a/.agents/skills/reverse-engineer-anything/SKILL.md b/.agents/skills/reverse-engineer-anything/SKILL.md
index 5fe6b6f0a..45240351d 100644
--- a/.agents/skills/reverse-engineer-anything/SKILL.md
+++ b/.agents/skills/reverse-engineer-anything/SKILL.md
@@ -2,7 +2,7 @@
name: reverse-engineer-anything
description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
metadata:
- version: "38"
+ version: "39"
---
# REA
diff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md
index 0a2810676..9f09ad82f 100644
--- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md
+++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md
@@ -150,6 +150,13 @@ For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI
analysis: the entry is `0x10100`, file offset zero, with imposed real-mode segment
context. PSP/stack/device state remains unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/ghidra-dos.md).
+For other headerless images (embedded firmware without ELF/Mach-O/PE/MZ
+headers), open with `format: "raw-binary"`, `architecture` (`x86`, `x86_64`,
+`arm`, or `arm64`), and `entry_point` (`0x` hex). File offset 0 is mapped at
+that address. Hopper and IDA refuse this interpretation; Ghidra uses
+`BinaryLoader` with a little-endian generic language. Big-endian, Thumb-only,
+and Cortex-M variants are unsupported. See [raw binary guide](https://github.com/morluto/rea/blob/main/docs/raw-binary.md).
+
### Function annotations in Ghidra
Use `annotate_native_function` for one function name and/or entry comments, with at least one explicit change. Review its annotation readback and refreshed dossier inline. Changes are atomic and session-scoped; empty comments clear them, omitted fields preserve them. Later MCP calls observe edits until close. CLI `annotate-native-function` returns the updated analysis before discarding the session. Original executable bytes are unchanged; edits invalidate immutable snapshots. Windows P0 does not admit database mutations. For naming only, `set_address_name` / `set_addresses_names` also work with Ghidra: they name function entries or data addresses (primary labels) and return compact per-address success booleans instead of a dossier.
diff --git a/README_fr.md b/README_fr.md
index c2c0bb46e..f3b0de61c 100644
--- a/README_fr.md
+++ b/README_fr.md
@@ -52,7 +52,7 @@ Vous avez repéré dans une application une fonctionnalité que vous aimeriez av
REA connecte votre agent à des outils d'inspection de binaires natifs, d'applications JavaScript et Electron, d'assemblys .NET et de sites web. Les mêmes outils sont aussi disponibles depuis votre terminal. L'analyse s'exécute localement, et chaque conclusion s'accompagne des preuves et des limites sur lesquelles elle repose.
-Setup enregistre REA auprès de votre agent et installe les instructions de workflow correspondantes. L'analyse native peut utiliser une installation existante de Hopper ou de Ghidra ; Setup peut aussi installer Hopper après votre accord. L'analyse statique JavaScript ne nécessite aucun de ces moteurs.
+Setup enregistre REA auprès de votre agent et installe les instructions de workflow correspondantes. L'analyse native peut utiliser une installation existante de Hopper, de Ghidra ou d'IDA ; Setup peut aussi installer Hopper après votre accord. L'analyse statique JavaScript ne nécessite aucun moteur d'analyse natif.
> **[Visitez le site web de REA](https://rea.tools/fr/)** pour les instructions d'installation, des guides illustrés et des études de cas réelles.
@@ -102,12 +102,14 @@ Pour l'analyse native, configurez d'abord un fournisseur. Consultez le [guide CL
REA évolue rapidement, et les nouvelles versions apportent fréquemment des corrections de bugs. Maintenez votre installation à jour.
-Pour une CLI installée avec npm :
+Pour une CLI installée avec `npm install --global` ou `bun add --global` :
```bash
rea update
```
+Les mises à jour globales avec Bun nécessitent Bun 1.2.17 ou une version ultérieure. Avec une version plus ancienne de Bun, mettez à jour Bun manuellement avant d'exécuter `rea update`.
+
Pour actualiser les enregistrements de vos agents et le skill, exécutez la commande setup affichée par la mise à jour.
Si vous utilisez `npx`, mettez à jour la configuration de votre agent avec :
@@ -116,7 +118,7 @@ Si vous utilisez `npx`, mettez à jour la configuration de votre agent avec :
npx rea-agents@latest setup
```
-Vérifiez les modifications proposées par Setup et redémarrez votre agent. Pour des commandes CLI ponctuelles, utilisez `npx rea-agents@latest` suivi de la commande.
+Vérifiez les modifications proposées par Setup et redémarrez votre agent. Pour des commandes CLI ponctuelles, utilisez `npx rea-agents@latest` suivi de la commande. Avec Bun, utilisez `bunx rea-agents@latest` à la place de `npx rea-agents@latest`.
## Comment fonctionne REA
@@ -136,6 +138,7 @@ REA nécessite Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, ainsi que npm. Les
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Binaires natifs | Pseudo-code, assembleur, chaînes, symboles, appels et références | Hopper, Ghidra ou IDA ; [analyse native](https://rea.tools/fr/guides/native/) |
| Structure ELF hors ligne | Sections, segments, symboles et relocations d'origine, et protections statiques candidates | pwntools fourni par l'utilisateur sous Linux x64 ; [diagnostics binaires](docs/binary-diagnostics.md) |
+| Artefact WASM | Validation, sections, formes WAT exactes d'import/export et WAT décodé | WABT 1.0.42 fourni par l'utilisateur ; `inspect_wasm_artifact` |
| Bytecode EVM | Sélecteurs de dispatch, offsets en octets, arguments inférés et mutabilité | Fichier local brut ou hexadécimal sous Linux x64 ; [guide EVM hors ligne](docs/evm-bytecode.md) |
| Crashs Linux enregistrés | Notes brutes, registres et signaux de chaque thread enregistré, et correspondances de mappings facultatives | pwntools fourni par l'utilisateur sous Linux x64 ; GDB/pwndbg en option ; [crashs enregistrés](docs/recorded-crashes.md) |
| JavaScript / Electron | Modules, imports, source maps, routes, IPC et relations avec les modules natifs | Node.js et npm ; [analyse d'applications](https://rea.tools/fr/guides/javascript/) |
@@ -229,7 +232,7 @@ REA analyse les cibles localement. Votre agent reçoit les résultats des outils
Commencez par mettre à jour ; une version récente l'a peut-être déjà corrigé.
-Pour une CLI installée avec npm :
+Pour une CLI installée avec `npm install --global` ou `bun add --global` :
```bash
rea update
@@ -250,7 +253,7 @@ Si vous utilisez un agent, terminez l'[actualisation de la configuration](#mettr
Commencez par les [guides pas à pas](https://rea.tools/fr/guides/) du site web. Pour les options exactes, les prérequis et les contrats de résultats :
- [Installation et configuration](docs/installation.md) : enregistrement des agents, configuration des fournisseurs, mises à jour et désinstallation.
-- [Vérification et dépannage](docs/installation.md#check-readiness-for-your-task) : diagnostiquer un agent ou un moteur d'analyse précis.
+- [Vérification et dépannage](docs/installation.md#check-readiness-for-your-task) : diagnostiquer un agent ou un moteur d'analyse donné.
- [CLI et Evidence](docs/cli.md) : commandes, choix du fournisseur, snapshots, import/export et codes de sortie.
- [Contrats MCP](docs/mcp-contracts.md) et [prompts pour agents](docs/mcp-prompts.md) : résultats des outils, sessions et investigations guidées.
- [Catalogue des outils](docs/mcp-contracts.md#generated-catalog) : inventaire des outils, fournisseurs et commandes CLI, généré lors du build.
@@ -280,7 +283,7 @@ REA fournit des outils destinés à la recherche, à l'analyse et à la reconstr
Votre aide sur REA est la bienvenue ! [Ouvrez une issue](https://github.com/morluto/rea/issues) pour signaler un bug ou proposer une fonctionnalité, ou [envoyez une pull request](https://github.com/morluto/rea/pulls) pour améliorer le code ou la documentation.
-Consultez [CONTRIBUTING.md](CONTRIBUTING.md) pour l'environnement de développement et les vérifications, la page [tests](docs/testing.md) pour les filières de vérification, et la [carte de l'architecture](docs/architecture.mermaid) pour la structure du projet.
+Consultez [CONTRIBUTING.md](CONTRIBUTING.md) pour l'environnement de développement et les vérifications, la page [tests](docs/testing.md) pour les procédures de vérification, et la [carte de l'architecture](docs/architecture.mermaid) pour la structure du projet.
## Licence
diff --git a/README_id.md b/README_id.md
index 432ebd464..d992e9908 100644
--- a/README_id.md
+++ b/README_id.md
@@ -101,12 +101,14 @@ Untuk analisis native, konfigurasikan penyedia terlebih dahulu. Lihat [Panduan C
REA berkembang dengan cepat, dan rilis baru sering menyertakan perbaikan bug. Pastikan instalasi Anda selalu diperbarui.
-Untuk CLI yang dipasang melalui npm:
+Untuk CLI yang dipasang melalui `npm install --global` atau `bun add --global`:
```bash
rea update
```
+Pembaruan global dengan Bun memerlukan Bun 1.2.17 atau yang lebih baru. Pada rilis Bun yang lebih lama, perbarui Bun secara manual sebelum menjalankan `rea update`.
+
Untuk memperbarui pendaftaran agen dan skill Anda, jalankan perintah penyiapan yang ditampilkan oleh proses pembaruan.
Jika Anda menggunakan `npx`, perbarui penyiapan agen dengan:
@@ -115,7 +117,7 @@ Jika Anda menggunakan `npx`, perbarui penyiapan agen dengan:
npx rea-agents@latest setup
```
-Tinjau perubahan penyiapan dan mulai ulang agen Anda. Untuk menjalankan perintah CLI sekali pakai, gunakan `npx rea-agents@latest` diikuti dengan perintah yang diinginkan.
+Tinjau perubahan penyiapan dan mulai ulang agen Anda. Untuk menjalankan perintah CLI sekali pakai, gunakan `npx rea-agents@latest` diikuti dengan perintah yang diinginkan. Dengan Bun, gunakan `bunx rea-agents@latest` sebagai pengganti `npx rea-agents@latest`.
## Cara Kerja REA
@@ -139,6 +141,7 @@ Alat tambahan dan dukungan sistem host bergantung pada target yang dianalisis:
| -------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Biner native | Pseudocode, assembly, string, simbol, pemanggilan, dan referensi | Hopper, Ghidra, atau IDA; [analisis native](https://rea.tools/id/guides/native/) |
| Tata letak ELF offline | Bagian, segmen, simbol/relokasi asli, dan kandidat mitigasi statis | pwntools yang disediakan pemanggil pada Linux x64; [diagnostik biner](docs/binary-diagnostics.md) |
+| Artefak WASM | Validasi, bagian, bentuk WAT import/ekspor yang tepat, dan WAT yang didekode | WABT 1.0.42 yang disediakan pemanggil; `inspect_wasm_artifact` |
| Bytecode EVM | Selector dispatch, offset byte, argumen yang disimpulkan, dan sifat mutabilitas | Pembawa data raw/hex lokal; [panduan EVM offline](docs/evm-bytecode.md) |
| Crash Linux yang direkam | Catatan mentah, register/sinyal setiap thread yang direkam, dan kandidat pemetaan opsional | pwntools yang disediakan pemanggil; GDB/pwndbg opsional; [crash yang direkam](docs/recorded-crashes.md) |
| JavaScript / Electron | Modul, impor, source map, rute, IPC, dan hubungan add-on native | Node.js dan npm; [analisis aplikasi](https://rea.tools/id/guides/javascript/) |
@@ -246,7 +249,7 @@ REA menganalisis target secara lokal. Agen Anda menerima hasil alat, sedangkan p
Perbarui terlebih dahulu. Rilis terbaru mungkin sudah memperbaiki masalah tersebut.
-Untuk CLI yang dipasang melalui npm:
+Untuk CLI yang dipasang melalui `npm install --global` atau `bun add --global`:
```bash
rea update
diff --git a/README_it.md b/README_it.md
index ea1a11eba..b9bbeb5a9 100644
--- a/README_it.md
+++ b/README_it.md
@@ -20,7 +20,7 @@
**[Sito web](https://rea.tools/it/) · [Guide](https://rea.tools/it/guides/) · [Showcase](https://rea.tools/it/showcase/)**
-[Quick start](#quick-start) · [Come funziona REA](#come-funziona-rea) · [Cosa puoi analizzare](#cosa-puoi-analizzare) · [Showcase](#showcase) · [FAQ](#faq) · [Documentazione](#documentazione)
+[Avvio rapido](#avvio-rapido) · [Come funziona REA](#come-funziona-rea) · [Cosa puoi analizzare](#cosa-puoi-analizzare) · [Showcase](#showcase) · [FAQ](#faq) · [Documentazione](#documentazione)
npx rea-agents setup
@@ -56,7 +56,7 @@ La configurazione registra REA con il tuo agente e installa le istruzioni di wor
> **[Visita il sito web di REA](https://rea.tools/it/)** per istruzioni di configurazione, guide illustrate e veri casi studio.
-## Quick start
+## Avvio rapido
### Configura il tuo agente
@@ -102,12 +102,14 @@ Per l'analisi nativa, configura prima un provider. Vedi la [guida CLI ed Evidenc
REA cambia rapidamente e le nuove versioni includono correzioni di bug frequenti. Tieni aggiornata la tua installazione.
-Per una CLI installata via npm:
+Per una CLI installata con `npm install --global` o `bun add --global`:
```bash
rea update
```
+Gli aggiornamenti globali con Bun richiedono Bun 1.2.17 o versioni successive. Con una versione precedente di Bun, aggiorna Bun manualmente prima di eseguire `rea update`.
+
Per aggiornare le registrazioni del tuo agente e lo skill, esegui il comando di configurazione mostrato dall'aggiornamento.
Se usi `npx`, aggiorna la configurazione del tuo agente con:
@@ -116,7 +118,7 @@ Se usi `npx`, aggiorna la configurazione del tuo agente con:
npx rea-agents@latest setup
```
-Rivedi le modifiche di configurazione e riavvia il tuo agente. Per comandi CLI singoli, usa `npx rea-agents@latest` seguito dal comando.
+Rivedi le modifiche di configurazione e riavvia il tuo agente. Per comandi CLI singoli, usa `npx rea-agents@latest` seguito dal comando. Con Bun, usa `bunx rea-agents@latest` al posto di `npx rea-agents@latest`.
## Come funziona REA
@@ -136,6 +138,7 @@ REA richiede Node.js 22.x (>=22.19), 24.x (>=24.11) o 26+, oltre a npm. Strument
| ---------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Binari nativi | Pseudocodice, assembly, stringhe, simboli, chiamate e riferimenti | Hopper, Ghidra o IDA; [analisi nativa](https://rea.tools/it/guides/native/) |
| Layout ELF offline | Sezioni, segmenti, simboli/relocazioni originali e candidati mitigazioni statiche | pwntools fornito dal chiamante su Linux x64; [diagnostica binaria](docs/binary-diagnostics.md) |
+| Artefatto WASM | Convalida, sezioni, forme WAT di import/export esatte e WAT decodificato | WABT 1.0.42 fornito dal chiamante; `inspect_wasm_artifact` |
| Bytecode EVM | Selettori di dispatch, offset dei byte, argomenti inferiti e mutabilità | Carrier raw/hex locale; [guida EVM offline](docs/evm-bytecode.md) |
| Crash Linux registrati | Note grezze, registri/segnai di ogni thread registrato e candidati mapping opzionali | pwntools fornito dal chiamante; GDB/pwndbg opzionale; [crash registrati](docs/recorded-crashes.md) |
| JavaScript / Electron | Moduli, import, source map, route, IPC e relazioni con add-on nativi | Node.js e npm; [analisi delle applicazioni](https://rea.tools/it/guides/javascript/) |
@@ -229,7 +232,7 @@ REA analizza i bersagli localmente. Il tuo agente riceve i risultati degli strum
Aggiorna prima; una release recente potrebbe averlo già risolto.
-Per una CLI installata via npm:
+Per una CLI installata con `npm install --global` o `bun add --global`:
```bash
rea update
diff --git a/bridge/android/ReaJadxBridge.java b/bridge/android/ReaJadxBridge.java
index aa49606ee..620e2454d 100644
--- a/bridge/android/ReaJadxBridge.java
+++ b/bridge/android/ReaJadxBridge.java
@@ -126,6 +126,20 @@ class ReaJadxBridge {
return result;
}
+ private JadxSession.SmartCode methodBody(JadxSession current, ClassSnapshot cls,
+ MethodSnapshot selected, JavaMethod method) {
+ if (!selected.shortId().equals("()V"))
+ return current.getMethodBodySmart(method, current.getMaxSourceBytes(), true);
+ // Java code generation can fold all or part of into field declarations.
+ // Its method text cannot establish coverage, even when a static block remains.
+ JadxSession.MethodSmali smali = current.getMethodSmali(cls.node(), method.getName());
+ if (!smali.getFound() || smali.getBlocks().size() != 1)
+ throw new IllegalArgumentException("Static initializer disassembly requires one exact method: " + selected.shortId());
+ return new JadxSession.SmartCode(
+ TextUtilKt.truncateToBytes(smali.getBlocks().get(0), current.getMaxSourceBytes()),
+ "smali", true, List.of("static_initializer_disassembly"));
+ }
+
private CallToolResult handle(String name, JsonObject args) {
if (name.equals("rea_jvm_status")) return json(Map.of(
"engine_reported_version", BuildInfo.VERSION,
@@ -150,7 +164,7 @@ class ReaJadxBridge {
int index = integer(args, "overload_index", 0);
if (index >= overloads.size()) throw new InputFailure("overload_index", "overload_index out of range: " + index);
JavaMethod method = method(cls, overloads.get(index));
- JadxSession.SmartCode code = current.getMethodBodySmart(method, current.getMaxSourceBytes(), true);
+ JadxSession.SmartCode code = methodBody(current, cls, overloads.get(index), method);
return json(Map.of("class_name", cls.summary().get("full_name"),
"method_name", overloads.get(index).name(), "full_name", method.getFullName(),
"overload_index", index, "overload_count", overloads.size(),
@@ -211,7 +225,7 @@ class ReaJadxBridge {
String description = switch (name) {
case "list_classes" -> "Indexed pages of all top-level class names, with offset and limit.";
case "get_class_summary" -> "Parsed member metadata for one exact class name; no source generation.";
- case "get_method_body" -> "Source for an exact class and stable same-name overload index, with smali fallback.";
+ case "get_method_body" -> "Source for an exact class and stable same-name overload index; static initializers use smali to preserve folded field initialization.";
default -> "Complete static references to an exact class or unique method; source lines are unresolved.";
};
Tool narrowed = new Tool(name, new ToolSchema(null, new JsonObject(properties),
diff --git a/bridge/ghidra/ReaGhidraBridge.java b/bridge/ghidra/ReaGhidraBridge.java
index 1a0413042..a35af8453 100644
--- a/bridge/ghidra/ReaGhidraBridge.java
+++ b/bridge/ghidra/ReaGhidraBridge.java
@@ -182,10 +182,17 @@ public final class ReaGhidraBridge extends HeadlessScript {
}
sessionDefaultAddressSpace =
currentProgram.getAddressFactory().getDefaultAddressSpace();
- if (currentProgram.getExecutableFormat().equals("Raw Binary") &&
- !currentProgram.getOptions(ghidra.program.model.listing.Program.PROGRAM_INFO)
- .getBoolean("REA DOS COM prepared", false)) {
- throw new IllegalStateException("REA DOS COM entry/context preparation failed");
+ if (currentProgram.getExecutableFormat().equals("Raw Binary")) {
+ boolean dosCom = currentProgram.getLanguageID().getIdAsString()
+ .equals("x86:LE:16:Real Mode");
+ String preparation = dosCom ? "REA DOS COM prepared" : "REA raw binary prepared";
+ if (!currentProgram.getOptions(ghidra.program.model.listing.Program.PROGRAM_INFO)
+ .getBoolean(preparation, false)) {
+ throw new IllegalStateException(
+ dosCom ? "REA DOS COM entry/context preparation failed" :
+ "REA raw binary entry preparation failed"
+ );
+ }
}
if (!Application.getApplicationVersion().equals(descriptor.providerVersion)) {
throw new IllegalStateException("Ghidra provider version does not match the session");
diff --git a/bridge/ghidra/ReaGhidraPrepareRaw.java b/bridge/ghidra/ReaGhidraPrepareRaw.java
new file mode 100644
index 000000000..1a5db9627
--- /dev/null
+++ b/bridge/ghidra/ReaGhidraPrepareRaw.java
@@ -0,0 +1,36 @@
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Program;
+
+/** Seed the caller-supplied raw-binary entry before default auto-analysis. */
+public final class ReaGhidraPrepareRaw extends GhidraScript {
+ @Override
+ public void run() throws Exception {
+ String[] arguments = getScriptArgs();
+ if (arguments.length != 2) {
+ throw new IllegalArgumentException(
+ "Raw binary preparation requires the committed language and entry address"
+ );
+ }
+ String expectedLanguage = arguments[0];
+ String entryHex = arguments[1];
+ if (!currentProgram.getLanguageID().getIdAsString().equals(expectedLanguage) ||
+ !currentProgram.getExecutableFormat().equals("Raw Binary")) {
+ throw new IllegalArgumentException(
+ "Raw binary preparation requires the committed language and BinaryLoader import"
+ );
+ }
+ Address entry = currentProgram.getAddressFactory().getDefaultAddressSpace().getAddress(entryHex);
+ Address start = currentProgram.getMinAddress();
+ if (entry == null || !entry.equals(start)) {
+ throw new IllegalArgumentException(
+ "Raw binary import must map file offset 0 at the caller-supplied entry"
+ );
+ }
+ addEntryPoint(entry);
+ if (!disassemble(entry) || createFunction(entry, "entry") == null) {
+ throw new IllegalStateException("Raw binary entry cannot be decoded as a function");
+ }
+ currentProgram.getOptions(Program.PROGRAM_INFO).setBoolean("REA raw binary prepared", true);
+ }
+}
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index e1c184993..952266a68 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -54,6 +54,7 @@ export default defineConfig({
{ text: "IDA", link: "/ida-provider" },
{ text: "Ghidra on Windows", link: "/windows-ghidra-p0" },
{ text: "Ghidra DOS analysis", link: "/ghidra-dos" },
+ { text: "Ghidra raw binary", link: "/raw-binary" },
{ text: "Ghidra NativeAOT", link: "/ghidra-nativeaot" },
{ text: "Ghidra semantics", link: "/ghidra-provider" },
],
diff --git a/docs/android-analysis.md b/docs/android-analysis.md
index 808eeea49..03fd39850 100644
--- a/docs/android-analysis.md
+++ b/docs/android-analysis.md
@@ -94,6 +94,12 @@ fallback for an overloaded method instead of attributing all bodies to one
selected overload. Native/abstract methods with no decompiled body report
`body_status: "not_available"` without inferring which implementation flag caused it.
+Static initializers (``) return smali with the
+`static_initializer_disassembly` marker. Java decompilation can move their
+instructions into field declarations, leaving an empty or incomplete method
+body. The selected method's disassembly preserves those instructions and retains
+the same source byte limit and explicit truncation reporting.
+
## Interpret the result
- Package inspection retains decoded manifest XML, summary declarations,
diff --git a/docs/cli.md b/docs/cli.md
index 7f35eb40d..875c43147 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -59,7 +59,8 @@ alone, use `rea instructions`. A macOS `.app` bundle can be supplied directly.
Run `rea --help` or a command's `--help` for arguments and output options.
The [generated catalog](product-catalog.json) lists all CLI commands and MCP
tools. Provider-specific target support is described in the
-[native guide](native-investigation.md), [DOS guide](ghidra-dos.md), and
+[native guide](native-investigation.md), [DOS guide](ghidra-dos.md),
+[raw binary guide](raw-binary.md), and
[Windows Ghidra guide](windows-ghidra-p0.md).
## Choose a provider
diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.md
index b65155dc8..c58db195f 100644
--- a/docs/mcp-contracts.md
+++ b/docs/mcp-contracts.md
@@ -150,13 +150,15 @@ structured data and matching text projection. Oversized errors are retained
as Evidence before delivery of a bounded diagnostic with an export reference;
if retention is unavailable or fails, the diagnostic reports that reason.
-REA accepts ordinary `tools/call` progress tokens. Updates are monotonic,
-rate-bounded to at most one intermediate update per 100 ms, and always allow a
-terminal update. Unknown totals are omitted; REA does not fabricate percentages.
+REA accepts ordinary `tools/call` progress tokens. The numeric `progress` counts
+emitted status observations and strictly increases, including when a waiting
+phase has completed no additional work. Updates are rate-bounded to at most one
+intermediate update per 100 ms and always allow a terminal update. `total` is
+omitted because the number of future status observations is unknown. Read
+`message` for the phase and observed work; REA does not fabricate percentages.
`capture_process_scenario` uses that boundary only when the client supplies a
-progress token. Notifications set `progress` to the count of collected terminal
-frames, process samples, and interaction events, omit `total`, and put the
-lifecycle phase, elapsed time, and final cleanup status in `message`. A client
+progress token. Notifications put the lifecycle phase, elapsed time, and final
+cleanup status in `message`. A client
that does not send a progress token receives no progress notifications. The
tool result is unchanged either way.
Provider calls receive the request cancellation signal. Artifact traversal,
@@ -230,6 +232,18 @@ engine readiness or a percentage of Ghidra auto-analysis. A longer server
startup allowance does not extend the client's deadline; progress also does not
extend it unless the client explicitly implements that policy.
+While Ghidra startup is pending, REA sends a waiting notification every ten
+seconds when the request has a progress token. Its message gives elapsed waiting
+time; import, auto-analysis and bridge readiness may all still be pending.
+Waiting notifications stop when startup settles or the caller cancels. They do
+not measure engine work completed.
+
+The pinned SDK can reset the request's inactivity timeout on progress with
+`resetTimeoutOnProgress: true`. Also set `maxTotalTimeout` to bound the complete
+request; the provider's startup deadline still applies. These options belong in
+the same second argument of `callTool`. Without that explicit client policy, the
+default 60-second request deadline still expires despite waiting notifications.
+
The 240-second setting is a measured example, not a universal timeout: a
controlled Linux x64/WSL2 fixture took about 64 seconds for its first overview
with Ghidra 12.1.4 on a mounted NTFS installation, native JDK 21, two CPUs, and a
@@ -265,9 +279,10 @@ observed process-family member remained after final close. This was a small
1,024-byte fixture, so the longer request setting remains an example, not a
guarantee for larger targets. No macOS cold-start recovery was exercised.
-With a supplied progress token, the Windows run received an operation-start
+With a supplied progress token, that earlier Windows run received an operation-start
notification before timeout and start/completion notifications for the
-successful retry. It received no intermediate import or auto-analysis progress.
+successful retry, before startup waiting notifications were added. It received
+no intermediate import or auto-analysis progress.
These operation markers do not measure analysis work completed or extend the
client's deadline. Each new provider session still imports the target into a
fresh temporary project.
diff --git a/docs/raw-binary.md b/docs/raw-binary.md
new file mode 100644
index 000000000..dd86d0107
--- /dev/null
+++ b/docs/raw-binary.md
@@ -0,0 +1,72 @@
+# Headerless raw-binary analysis with Ghidra
+
+REA admits a headerless executable when the caller supplies the CPU family and
+the address where file offset 0 should be mapped. That interpretation is not
+inferred from a `.bin` suffix or from unrecognized bytes.
+
+## Open and inspect
+
+```bash
+rea inspect /absolute/path/to/ecu.bin --target-format raw-binary --architecture arm --entry-point 0x8000000 --provider ghidra --json
+rea function /absolute/path/to/ecu.bin 0x8000000 --target-format raw-binary --architecture arm --entry-point 0x8000000 --provider ghidra --json
+rea inspect-native-load-image /absolute/path/to/ecu.bin --target-format raw-binary --architecture arm --entry-point 0x8000000 --provider ghidra --json
+```
+
+```json
+{
+ "name": "open_binary",
+ "arguments": {
+ "path": "/absolute/path/to/ecu.bin",
+ "format": "raw-binary",
+ "architecture": "arm",
+ "entry_point": "0x8000000",
+ "provider_id": "ghidra"
+ }
+}
+```
+
+`architecture` is one of `x86`, `x86_64`, `arm`, or `arm64`. `entry_point` is a
+hexadecimal address of the form `0x…`. The complete file is mapped starting at
+that address, and Ghidra seeds an `entry` function there before auto-analysis.
+ARM and AArch64 entries must be 4-byte aligned; x86 entries may be byte-aligned.
+`open_binary` and an open `binary_session` return the canonical `entry_point`
+for raw targets so callers can verify the selected mapping directly.
+Omitted `format` keeps header-based detection; architecture and entry without
+`format=raw-binary` are rejected.
+
+Ghidra imports a private snapshot with `BinaryLoader` and these little-endian
+generic languages:
+
+| architecture | language_id |
+| ------------ | ------------------- |
+| x86 | `x86:LE:32:default` |
+| x86_64 | `x86:LE:64:default` |
+| arm | `ARM:LE:32:v7` |
+| arm64 | `AARCH64:LE:64:v8A` |
+
+Those settings, the caller-supplied entry, and `language_selection:
+caller-supplied-v1` are committed in the analysis profile. A different entry
+or architecture is a different profile; snapshots from header-detected targets
+do not replay.
+
+The mapped start is independent of Ghidra's program image base, which remains
+`0x0` for BinaryLoader. Ghidra may report additional language-defined entry
+points, including unmapped ARM vectors. Load-image verification requires the
+caller-supplied entry and preserves those other entries as observations.
+Independent raw verification streams the complete private snapshot digest and
+extent with bounded memory and supports cancellation during the read.
+
+Hopper and IDA refuse raw-binary targets. Windows Ghidra P0 continues to admit
+PE applications only.
+
+## Limitations
+
+- Headers are not discovered from file bytes. This increment does not guess
+ load addresses, vector tables, or memory maps.
+- Big-endian, Thumb-only, Cortex-M, and other Ghidra processor variants are
+ unsupported.
+- Reset vectors, memory-mapped I/O, and firmware boot sequences are not
+ emulated.
+- Independent load-image verification covers source identity, mapped file
+ bytes, the bound language, and the caller-supplied entry. Original bytes
+ stay unchanged.
diff --git a/docs/testing.md b/docs/testing.md
index dbbdb0b3c..e8a02713a 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -793,6 +793,14 @@ truncation constraint, while leading-zero coordinates still resolve correctly.
It has the same Ghidra/JDK prerequisites as the MZ lane. Neither lane claims DOS
runtime or PC-98 device execution.
+`npm run verify:ghidra:raw` uses a generated ARM little-endian headerless image
+through the compiled CLI and stdio MCP server. With the same Ghidra/JDK
+prerequisites, it checks preparation and bridge startup, verified load mappings,
+instruction and byte readback, canonical-entry session reuse, replacement when
+the entry changes without `provider_id`, unchanged source bytes, and owned
+cleanup. Other raw CPU families remain covered by deterministic tests rather
+than this real-provider lane. See [raw binary analysis](raw-binary.md).
+
## Apple Interface Builder archives
`npm run verify:interface-builder` compiles the source-owned AppKit XIB into a
diff --git a/docs/user-visible-errors.csv b/docs/user-visible-errors.csv
index a1c3536f3..f4934b80b 100644
--- a/docs/user-visible-errors.csv
+++ b/docs/user-visible-errors.csv
@@ -1,10 +1,10 @@
harm_rank,location,trigger,current_copy,user_risk,proposed_replacement,implementation_status,verification_result
1,src/domain/errors.ts:AnalysisCapabilityUnavailableError,Requested analysis unavailable,"Provider {providerId} cannot execute {operation}: {reason}",Exposes provider and internal operation/reason,"This analysis is unavailable for the current target. Choose another analysis or target.",implemented,focused assertions passed; full `npm run check` passed
-2,src/domain/errors.ts:ProviderAdapterError,Provider adapter fails,"Provider {providerId} adapter failed during {operation}",Exposes provider and implementation boundary,"Analysis could not complete. Retry once; if it continues, run `rea doctor`.",implemented,focused assertions passed; full `npm run check` passed
-3,src/domain/errors.ts:HopperRemoteError,Remote analysis request fails,"Hopper request failed ({code}): {safeMessage}",Exposes provider name code and upstream text,"Analysis could not complete. Retry once; if it continues, run `rea doctor`.",implemented,focused assertions passed; full `npm run check` passed
-4,src/domain/errors.ts:HopperProtocolError,Malformed provider protocol result,Raw constructor message,Can expose provider protocol and implementation details,"Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",implemented,focused assertions passed; full `npm run check` passed
-5,src/domain/errors.ts:AnalysisOutputError,Analysis output fails parsing,"Invalid analysis output for {operation}: {reason}",Exposes internal operation and parser reason,"Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",implemented,focused assertions passed; full `npm run check` passed
-6,src/domain/errors.ts:AnalysisProtocolError,Application protocol fails,Raw constructor message,Can expose protocol internals,"Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",implemented,focused assertions passed; full `npm run check` passed
+2,src/domain/errors.ts:ProviderAdapterError,Provider adapter fails,"Provider {providerId} adapter failed during {operation}",Exposes provider and implementation boundary,"Analysis could not complete. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",implemented,focused assertions passed; full `npm run check` passed
+3,src/domain/errors.ts:HopperRemoteError,Remote analysis request fails,"Hopper request failed ({code}): {safeMessage}",Exposes provider name code and upstream text,"Analysis could not complete. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",implemented,focused assertions passed; full `npm run check` passed
+4,src/domain/errors.ts:HopperProtocolError,Malformed provider protocol result,Raw constructor message,Can expose provider protocol and implementation details,"Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",implemented,focused assertions passed; full `npm run check` passed
+5,src/domain/errors.ts:AnalysisOutputError,Analysis output fails parsing,"Invalid analysis output for {operation}: {reason}",Exposes internal operation and parser reason,"Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",implemented,focused assertions passed; full `npm run check` passed
+6,src/domain/errors.ts:AnalysisProtocolError,Application protocol fails,Raw constructor message,Can expose protocol internals,"Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",implemented,focused assertions passed; full `npm run check` passed
7,src/domain/errors.ts:HopperProcessError,Analysis subprocess stops,"Hopper bridge stopped unexpectedly with code {exitCode}",Exposes provider bridge and process code,"Analysis could not start or stopped unexpectedly. Run `rea doctor`, then try again.",implemented,focused assertions passed; full `npm run check` passed
8,src/domain/errors.ts:HopperStartError,Analysis subprocess cannot start,Hopper application bridge could not be started,Exposes provider and bridge implementation,"Analysis could not start or stopped unexpectedly. Run `rea doctor`, then try again.",implemented,focused assertions passed; full `npm run check` passed
9,src/domain/errors.ts:BinaryTargetError,Target cannot open,"Cannot open artifact: {reason}",May expose raw reason and lacks checks,"Preserve the target admission reason; directories name analyze_javascript_application and rea analyze as available alternatives.",implemented,focused assertions passed; full `npm run check` passed
@@ -21,7 +21,7 @@ harm_rank,location,trigger,current_copy,user_risk,proposed_replacement,implement
21,src/domain/errors.ts:AnalysisCancelledError,Caller cancels analysis,"Analysis operation was cancelled: {operation}",Exposes operation identifier,"Analysis was cancelled. Start it again when ready.",implemented,focused assertions passed; full `npm run check` passed
22,src/domain/errors.ts:HopperCancelledError,Caller cancels provider request,Hopper operation was cancelled,Exposes provider name,"Analysis was cancelled. Start it again when ready.",implemented,focused assertions passed; full `npm run check` passed
23,src/domain/errors.ts:NoBinaryOpenError,Analysis requested without target,"No app is open. Ask the user which app to investigate, then call open_binary with its local path.",Low risk; already supplies agent recovery,Keep current copy,implemented,focused assertions passed; full `npm run check` passed
-24,src/server/toolResult.ts:successResult,Successful value violates public output schema,AnalysisOutputError: Analysis output does not match the tool contract,Exposes internal error tag and contract implementation,"Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",implemented,focused assertions passed; full `npm run check` passed
+24,src/server/toolResult.ts:successResult,Successful value violates public output schema,AnalysisOutputError: Analysis output does not match the tool contract,Exposes internal error tag and contract implementation,"Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",implemented,focused assertions passed; full `npm run check` passed
24.5,src/server/registerOfficialTools.ts:capability unknown,Approved unknown tracking records an unavailable analysis,"TOOL_NAME is unavailable: PROVIDER_REASON",Exposes an internal tool identifier and provider diagnostic in persistent user-visible evidence,"The requested analysis is unavailable for the current target.",implemented,verified by focused MCP integration test
24.6,src/application/ReferenceSourceImportEntries.ts:failed entry,A partial reference import contains an unreadable entry,Low-level reader diagnostic stored in entry limitations,Can persist filesystem or reader implementation details,"Code- and entry-specific safe guidance with a retry, limit, exclusion, or platform recovery step.",implemented,verified by exhaustive focused projection test
24.7,src/server/registerSessionTools.ts:process residual,Capture records a residual unknown linked to capture Evidence,SCOPE: RAW_REASON,Persists adapter diagnostic and implementation wording,"Was SCOPE behavior fully observed during capture?",implemented,verified by focused session MCP test
diff --git a/package.json b/package.json
index 673b079ef..bdb4b4338 100644
--- a/package.json
+++ b/package.json
@@ -55,6 +55,7 @@
"bridge/ghidra/ReaGhidraPrepareCom.java",
"bridge/ghidra/ReaGhidraApplySeeds.java",
"bridge/ghidra/ReaGhidraNoReturnFix.java",
+ "bridge/ghidra/ReaGhidraPrepareRaw.java",
"bridge/android/ReaJadxBridge.java",
"bridge/mitmproxy/capture.py",
"scripts/rea.mjs",
@@ -166,6 +167,7 @@
"verify:ghidra:switch": "npm run build:cached && node scripts/verify-real-ghidra-switch.mjs",
"verify:ghidra:dos": "npm run build:cached && node scripts/verify-real-ghidra-dos.mjs",
"verify:ghidra:com": "npm run build:cached && node scripts/verify-real-ghidra-com.mjs",
+ "verify:ghidra:raw": "npm run build:cached && node scripts/verify-real-ghidra-raw.mjs",
"verify:ghidra:aarch64-jump-table": "npm run build:cached && node scripts/verify-real-ghidra.mjs --aarch64-jump-table",
"verify:interface-builder": "npm run build:cached && node scripts/verify/apple/interface-builder.mjs",
"verify:ghidra:cross-format": "npm run build:cached && node scripts/verify-real-ghidra.mjs --cross-format",
diff --git a/scripts/verify-packaged-ghidra-windows.mjs b/scripts/verify-packaged-ghidra-windows.mjs
index 6221c122c..0266b5f65 100644
--- a/scripts/verify-packaged-ghidra-windows.mjs
+++ b/scripts/verify-packaged-ghidra-windows.mjs
@@ -177,6 +177,7 @@ const scriptCollisions = [
"ReaGhidraPrepareCom.java",
"ReaGhidraApplySeeds.java",
"ReaGhidraNoReturnFix.java",
+ "ReaGhidraPrepareRaw.java",
];
await mkdir(callerDirectory);
for (const name of scriptCollisions) await mkdir(join(callerDirectory, name));
@@ -394,15 +395,15 @@ try {
return evidence.normalized_result;
},
);
- const expected = (
+ const { GHIDRA_MUTATING_OPERATIONS, GHIDRA_SESSION_CAPABILITIES } =
await import(
pathToFileURL(join(packageRoot, "dist/ghidra/GhidraSessionValues.js"))
- )
- ).GHIDRA_SESSION_CAPABILITIES.filter(
+ );
+ const expected = GHIDRA_SESSION_CAPABILITIES.filter(
(name) =>
name !== "ping" &&
name !== "shutdown" &&
- name !== "annotate_native_function",
+ !GHIDRA_MUTATING_OPERATIONS.has(name),
);
assert.ok(
expected.every((name) => report.mcpOperations.includes(name)),
@@ -440,7 +441,10 @@ try {
token,
"Analysis changed caller token authority.",
);
- assert.deepEqual((await readdir(callerDirectory)).sort(), scriptCollisions);
+ assert.deepEqual(
+ (await readdir(callerDirectory)).sort(),
+ [...scriptCollisions].sort(),
+ );
for (const name of scriptCollisions)
assert.deepEqual(await readdir(join(callerDirectory, name)), []);
report.callerScriptCollisionsPreserved = true;
diff --git a/scripts/verify-real-ghidra-raw.mjs b/scripts/verify-real-ghidra-raw.mjs
new file mode 100644
index 000000000..400c7f378
--- /dev/null
+++ b/scripts/verify-real-ghidra-raw.mjs
@@ -0,0 +1,219 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+
+import { parseEvidence } from "../dist/domain/evidence.js";
+import { inspectGhidraInstallation } from "../dist/ghidra/GhidraInstallation.js";
+import { requireMcpOperationResult } from "./lib/mcp-verifier-results.mjs";
+import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs";
+
+if (process.argv.length !== 2)
+ throw new Error("Usage: node scripts/verify-real-ghidra-raw.mjs");
+if (!["linux", "darwin"].includes(process.platform))
+ throw new Error(
+ "Raw-binary verification requires a Linux or macOS Ghidra host.",
+ );
+if (process.env.GHIDRA_INSTALL_DIR === undefined)
+ throw new Error(
+ "Set GHIDRA_INSTALL_DIR to a bring-your-own Ghidra installation.",
+ );
+const installation = inspectGhidraInstallation({
+ environment: process.env,
+ installDir: process.env.GHIDRA_INSTALL_DIR,
+ ...(process.env.JAVA_HOME === undefined
+ ? {}
+ : { javaHome: process.env.JAVA_HOME }),
+});
+assert.equal(installation.status, "available", JSON.stringify(installation));
+
+const run = createVerifierRun();
+const workspace = await mkdtemp(join(tmpdir(), "rea-raw-proof-"));
+const runtime = join(workspace, "runtime");
+await mkdir(runtime);
+const bytes = Buffer.from("1eff2fe1", "hex"); // ARM little-endian bx lr.
+const sha256 = createHash("sha256").update(bytes).digest("hex");
+const path = join(workspace, "image.bin");
+await writeFile(path, bytes);
+const entrypoint = fileURLToPath(new URL("./rea.mjs", import.meta.url));
+const env = {
+ PATH: process.env.PATH ?? "/usr/bin:/bin",
+ TMPDIR: runtime,
+ REA_LOG_LEVEL: "silent",
+ REA_ANALYSIS_PROVIDER: "ghidra",
+ REA_PROCESS_RUN_ID: run.run_id,
+ GHIDRA_INSTALL_DIR: process.env.GHIDRA_INSTALL_DIR,
+ ...(process.env.JAVA_HOME === undefined
+ ? {}
+ : { JAVA_HOME: process.env.JAVA_HOME }),
+};
+const transport = new StdioClientTransport({
+ command: process.execPath,
+ args: [entrypoint, "mcp"],
+ env,
+ stderr: "pipe",
+});
+const client = new Client({ name: "rea-real-raw-proof", version: "1" });
+let stderr = "";
+transport.stderr?.on("data", (chunk) => {
+ stderr = (stderr + chunk.toString()).slice(-65536);
+});
+let report;
+try {
+ await client.connect(transport);
+ const profiles = [];
+ const sessions = [];
+ for (const entryPoint of ["0x08000000", "0x8000000", "0x09000000"]) {
+ // Omit provider_id to exercise reuse of the current provider route.
+ const opened = await call("open_binary", {
+ path,
+ format: "raw-binary",
+ architecture: "arm",
+ entry_point: entryPoint,
+ });
+ const entry = `0x${BigInt(entryPoint).toString(16)}`;
+ assert.equal(opened.entry_point, entry);
+ const image = await call("inspect_native_load_image");
+ assert.equal(
+ image.normalized_result.status,
+ "verified",
+ JSON.stringify(image),
+ );
+ assert.equal(image.normalized_result.base_address, entry);
+ assert.equal(image.normalized_result.entry.address, entry);
+ assert.equal(
+ image.normalized_result.observations.language_id,
+ "ARM:LE:32:v7",
+ );
+ assert.ok(
+ image.normalized_result.observations.entry_points.includes(entry),
+ );
+ assert.equal(image.analysis_profile.parameters.entry_point, entry);
+ profiles.push(image.analysis_profile.digest);
+ const status = await call("binary_session");
+ assert.equal(status.entry_point, entry);
+ sessions.push(status.analysis_run.run_id);
+ const memory = await call("read_bytes", {
+ address: entry,
+ length: bytes.length,
+ });
+ assert.equal(memory.normalized_result.bytes_hex, bytes.toString("hex"));
+ const procedures = await call("list_procedures");
+ assert.ok(
+ procedures.normalized_result.some(
+ (procedure) => procedure.address === entry,
+ ),
+ );
+ const instruction = await call("inspect_native_instruction", {
+ address: entry,
+ });
+ assert.equal(instruction.normalized_result.address, entry);
+ }
+ assert.equal(profiles[0], profiles[1]);
+ assert.notEqual(profiles[1], profiles[2]);
+ assert.equal(sessions[0], sessions[1]);
+ assert.notEqual(sessions[1], sessions[2]);
+ const rejected = await client.callTool({
+ name: "open_binary",
+ arguments: {
+ path,
+ format: "raw-binary",
+ architecture: "arm64",
+ entry_point: "0x8000001",
+ },
+ });
+ assert.equal(rejected.isError, true);
+ assert.match(JSON.stringify(rejected.content), /must be 4-byte aligned/);
+ const unchanged = await call("binary_session");
+ assert.equal(unchanged.analysis_run.run_id, sessions[2]);
+ assert.equal(unchanged.entry_point, "0x9000000");
+ await call("close_binary");
+
+ const { stdout } = await promisify(execFile)(
+ process.execPath,
+ [
+ entrypoint,
+ "inspect-native-load-image",
+ path,
+ "--target-format",
+ "raw-binary",
+ "--architecture",
+ "arm",
+ "--entry-point",
+ "0x08000000",
+ "--provider",
+ "ghidra",
+ "--json",
+ ],
+ { env, timeout: 240000, maxBuffer: 16 * 1024 * 1024 },
+ );
+ const cli = parseEvidence(JSON.parse(stdout));
+ assert.equal(cli.subject.digest.sha256, sha256);
+ assert.equal(cli.normalized_result.status, "verified");
+ assert.equal(cli.normalized_result.base_address, "0x8000000");
+ assert.equal(cli.analysis_profile.digest, profiles[0]);
+ assert.deepEqual(await readFile(path), bytes);
+ report = {
+ ok: true,
+ mocked: false,
+ lane: "ghidra-raw",
+ host: process.platform,
+ provider: { id: "ghidra", version: installation.providerVersion },
+ target: {
+ format: "raw-binary",
+ architecture: "arm",
+ sha256,
+ bytes: bytes.length,
+ },
+ transport: { cli: true, stdio_mcp: true },
+ canonical_entry_reuses_session: true,
+ changed_entry_replaces_session: true,
+ lifecycle_entry_preserved: true,
+ invalid_entry_preserves_active_session: true,
+ load_images_verified: true,
+ original_unchanged: true,
+ };
+} catch (error) {
+ if (stderr.trim()) process.stderr.write(stderr);
+ throw error;
+} finally {
+ await client.close();
+ await transport.close();
+ await rm(workspace, { recursive: true, force: true });
+}
+const verifierRun = await completeVerifierRun(run);
+assert.equal(verifierRun.process_lineage.status, "verified");
+assert.deepEqual(verifierRun.process_lineage.descendants, []);
+process.stdout.write(
+ JSON.stringify({
+ verifier_run: verifierRun,
+ ...report,
+ cleanup: "complete",
+ }) + "\n",
+);
+
+async function call(name, args = {}) {
+ const result = await client.callTool(
+ { name, arguments: args },
+ { timeout: 240000 },
+ );
+ assert.notEqual(result.isError, true, JSON.stringify(result));
+ const projected = requireMcpOperationResult(result, name);
+ if (
+ name === "open_binary" ||
+ name === "close_binary" ||
+ name === "binary_session"
+ )
+ return projected;
+ const evidence = parseEvidence(result.structuredContent);
+ assert.equal(evidence.subject.digest.sha256, sha256);
+ assert.equal(evidence.subject.format, "raw-binary");
+ return evidence;
+}
diff --git a/scripts/verify-real-ghidra-windows.mjs b/scripts/verify-real-ghidra-windows.mjs
index d2bbb511b..5adf96009 100644
--- a/scripts/verify-real-ghidra-windows.mjs
+++ b/scripts/verify-real-ghidra-windows.mjs
@@ -21,14 +21,17 @@ import { SUPPORTED_GHIDRA_VERSION } from "../dist/ghidra/GhidraInstallationPolic
import { GhidraHeadlessLauncher } from "../dist/ghidra/GhidraLauncher.js";
import { GHIDRA_PROVIDER_IDENTITY } from "../dist/ghidra/GhidraProviderCapabilities.js";
import { windowsP0Capabilities } from "../dist/ghidra/GhidraProviderCapabilities.js";
-import { GHIDRA_SESSION_CAPABILITIES } from "../dist/ghidra/GhidraSessionValues.js";
+import {
+ GHIDRA_MUTATING_OPERATIONS,
+ GHIDRA_SESSION_CAPABILITIES,
+} from "../dist/ghidra/GhidraSessionValues.js";
import { parseBinaryTarget } from "../dist/application/BinaryTargetResolver.js";
import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";
import { verifyGhidraCompactReferences } from "./lib/real-ghidra-compact-references.mjs";
const verifierRun = createVerifierRun();
const SESSION_CAPABILITIES = GHIDRA_SESSION_CAPABILITIES.filter(
- (name) => name !== "annotate_native_function",
+ (name) => !GHIDRA_MUTATING_OPERATIONS.has(name),
);
if (process.platform !== "win32" || process.arch !== "x64")
@@ -236,10 +239,8 @@ try {
const expected = [
...GHIDRA_INVENTORY_OPERATIONS,
- ...GHIDRA_FUNCTION_OPERATIONS.filter(
- (name) => name !== "annotate_native_function",
- ),
- ];
+ ...GHIDRA_FUNCTION_OPERATIONS,
+ ].filter((name) => !GHIDRA_MUTATING_OPERATIONS.has(name));
if (
observed.size !== expected.length ||
expected.some((operation) => !observed.has(operation))
diff --git a/scripts/verify/android/analysis.mjs b/scripts/verify/android/analysis.mjs
index dad53b447..43c51d82b 100644
--- a/scripts/verify/android/analysis.mjs
+++ b/scripts/verify/android/analysis.mjs
@@ -7,13 +7,16 @@ import { promisify } from "node:util";
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { parseEvidence } from "../../../dist/domain/evidence.js";
-import { hashAndroidFile } from "../../../dist/android/AndroidTargetSnapshot.js";
+import { hashAndroidFile } from "./digest.mjs";
import { JADX_RELEASE } from "../../../dist/android/JadxRelease.js";
import fixture from "../../fixtures/android/apidemos.json" with { type: "json" };
import { verifyAndroidCliCancellation } from "./cli-cancellation.mjs";
import { verifyAndroidMetadata } from "./metadata.mjs";
import { verifyAndroidFailureRecovery } from "./failure-recovery.mjs";
-import { resolveJadxConfiguration } from "../../../dist/android/JadxConfiguration.js";
+import {
+ resolveJadxConfigurationInputs,
+ validateJadxConfiguration,
+} from "../../../dist/android/JadxConfiguration.js";
import { verifyWindowsAndroidLifecycle } from "./windows-lifecycle.mjs";
const repository = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
@@ -35,10 +38,16 @@ assert.equal(
JADX_RELEASE.sha256,
"Real Android lane requires the audited headless JADX release JAR",
);
-const { java, jvmArguments } = await resolveJadxConfiguration(
+const configuration = await resolveJadxConfigurationInputs(
process.env,
"inspect_android_package",
);
+await validateJadxConfiguration(
+ configuration,
+ process.env,
+ "inspect_android_package",
+);
+const { java, jvmArguments } = configuration;
const execute = promisify(execFile);
await execute(java, ["-version"], { timeout: 10_000 });
const entrypoint =
@@ -52,6 +61,8 @@ await verifyAndroidMetadata({
repository,
execute,
jvmArguments,
+ entrypoint,
+ environment,
bridge: resolve(dirname(entrypoint), "../bridge/android/ReaJadxBridge.java"),
});
const tasks = [
diff --git a/scripts/verify/android/digest.mjs b/scripts/verify/android/digest.mjs
new file mode 100644
index 000000000..e4ed4d0ee
--- /dev/null
+++ b/scripts/verify/android/digest.mjs
@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+
+/** Verify artifact identity without depending on private runtime snapshot helpers. */
+export const hashAndroidFile = async (path) => {
+ const hash = createHash("sha256");
+ for await (const bytes of createReadStream(path)) hash.update(bytes);
+ return hash.digest("hex");
+};
diff --git a/scripts/verify/android/initializers.mjs b/scripts/verify/android/initializers.mjs
new file mode 100644
index 000000000..93d7dab4b
--- /dev/null
+++ b/scripts/verify/android/initializers.mjs
@@ -0,0 +1,130 @@
+import assert from "node:assert/strict";
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { parseEvidence } from "../../../dist/domain/evidence.js";
+import { hashAndroidFile } from "./digest.mjs";
+
+/** Verify folded field assignments and remaining static-block calls through both public adapters. */
+export const verifyAndroidInitializers = async ({
+ apk,
+ repository,
+ entrypoint,
+ environment,
+ execute,
+}) => {
+ const digest = await hashAndroidFile(apk);
+ const cases = [
+ {
+ class_name: "fixture.InitializationPolicy",
+ witnesses: [
+ "declared-policy",
+ "->singletonList",
+ "->POLICY:Ljava/util/List;",
+ ],
+ },
+ {
+ class_name: "fixture.MixedInitialization",
+ witnesses: ["field-value", "->LABEL:Ljava/lang/String;", "->touch()V"],
+ },
+ ];
+ const check = (value, scenario) => {
+ const evidence = parseEvidence(value);
+ assert.equal(evidence.subject.digest.sha256, digest);
+ const result = evidence.normalized_result;
+ assert.equal(result.class_name, scenario.class_name);
+ assert.equal(result.method.name, "");
+ assert.equal(result.overload_count, 1);
+ assert.equal(result.body_status, "available");
+ assert.equal(result.representation, "smali");
+ assert.equal(result.fell_back, true);
+ assert.ok(result.markers.includes("static_initializer_disassembly"));
+ assert.equal(result.source.status, "complete");
+ for (const witness of scenario.witnesses)
+ assert.ok(
+ result.source.text.includes(witness),
+ `Missing initializer evidence: ${witness}`,
+ );
+ return evidence;
+ };
+ const cli = new Map();
+ for (const scenario of cases) {
+ const response = await execute(
+ process.execPath,
+ [
+ entrypoint,
+ "inspect-android-method",
+ apk,
+ scenario.class_name,
+ "",
+ "--format",
+ "json",
+ ],
+ {
+ cwd: repository,
+ env: environment,
+ timeout: 150_000,
+ maxBuffer: 8 * 1024 * 1024,
+ },
+ );
+ cli.set(scenario.class_name, check(JSON.parse(response.stdout), scenario));
+ }
+ const transport = new StdioClientTransport({
+ command: process.execPath,
+ args: [entrypoint, "mcp"],
+ cwd: repository,
+ env: environment,
+ stderr: "pipe",
+ });
+ let stderr = "";
+ transport.stderr?.on("data", (chunk) => {
+ stderr += chunk.toString();
+ });
+ const client = new Client({
+ name: "rea-real-android-initializers",
+ version: "1",
+ });
+ try {
+ await client.connect(transport, { timeout: 30_000 });
+ for (const scenario of cases) {
+ const response = await client.callTool(
+ {
+ name: "inspect_android_method",
+ arguments: {
+ path: apk,
+ class_name: scenario.class_name,
+ method_name: "",
+ },
+ },
+ { timeout: 150_000 },
+ );
+ assert.notEqual(response.isError, true, JSON.stringify(response));
+ const evidence = check(response.structuredContent, scenario);
+ assert.deepEqual(
+ evidence.normalized_result,
+ cli.get(scenario.class_name).normalized_result,
+ );
+ assert.deepEqual(
+ evidence.parameters,
+ cli.get(scenario.class_name).parameters,
+ );
+ assert.deepEqual(
+ evidence.provider,
+ cli.get(scenario.class_name).provider,
+ );
+ }
+ await client.ping();
+ } catch (cause) {
+ process.stderr.write(stderr);
+ throw cause;
+ } finally {
+ await client.close();
+ }
+ assert.equal(
+ await hashAndroidFile(apk),
+ digest,
+ "Static inspection changed fixture bytes",
+ );
+ console.log(
+ "PASS real CLI/MCP static initializer evidence, identity, parity and unchanged APK",
+ );
+};
diff --git a/scripts/verify/android/metadata.mjs b/scripts/verify/android/metadata.mjs
index a4b3b6b58..eebcaf812 100644
--- a/scripts/verify/android/metadata.mjs
+++ b/scripts/verify/android/metadata.mjs
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { delimiter, join, resolve } from "node:path";
+import { verifyAndroidInitializers } from "./initializers.mjs";
/** Prove cold metadata stays unmaterialized and overload identities survive code generation. */
export const verifyAndroidMetadata = async ({
@@ -11,6 +12,8 @@ export const verifyAndroidMetadata = async ({
bridge,
repository,
execute,
+ entrypoint,
+ environment,
jvmArguments = [],
}) => {
const javac =
@@ -55,6 +58,8 @@ export const verifyAndroidMetadata = async ({
`${classes}${delimiter}${jar}`,
"ReaJadxMetadataRegression",
apk,
+ resolve(repository, "tests/fixtures/android/static-initializers"),
+ classes,
],
{ timeout: 120_000, maxBuffer: 8 * 1024 * 1024 },
);
@@ -62,9 +67,23 @@ export const verifyAndroidMetadata = async ({
result.stdout,
/METADATA_REGRESSION_PASS classes=\d+ overloads=3/u,
);
+ assert.match(
+ result.stdout,
+ /INITIALIZER_REGRESSION_PASS folded=2 bounded=true/u,
+ );
console.log(
"PASS real cold metadata, full generic types and stable overloaded method selection",
);
+ console.log(
+ "PASS real folded and mixed static initializers, absent bodies and bounded smali",
+ );
+ await verifyAndroidInitializers({
+ apk: resolve(classes, "initializers.apk"),
+ repository,
+ entrypoint,
+ environment,
+ execute,
+ });
} finally {
await rm(classes, { recursive: true, force: true });
}
diff --git a/scripts/verify/android/windows-lifecycle.mjs b/scripts/verify/android/windows-lifecycle.mjs
index 021dbde88..5c1a9c02d 100644
--- a/scripts/verify/android/windows-lifecycle.mjs
+++ b/scripts/verify/android/windows-lifecycle.mjs
@@ -13,7 +13,10 @@ import { dirname, join } from "node:path";
import { setTimeout as delay } from "node:timers/promises";
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
-import { resolveJadxConfiguration } from "../../../dist/android/JadxConfiguration.js";
+import {
+ resolveJadxConfigurationInputs,
+ validateJadxConfiguration,
+} from "../../../dist/android/JadxConfiguration.js";
/** Verify real Windows cancellation, disconnect and abrupt CLI owner exit. */
export async function verifyWindowsAndroidLifecycle(options) {
@@ -36,7 +39,12 @@ export async function verifyWindowsAndroidLifecycle(options) {
}
async function verifyJavaSelection(environment) {
- const selected = await resolveJadxConfiguration(
+ const selected = await resolveJadxConfigurationInputs(
+ environment,
+ "inspect_android_package",
+ );
+ await validateJadxConfiguration(
+ selected,
environment,
"inspect_android_package",
);
@@ -51,7 +59,12 @@ async function verifyJavaSelection(environment) {
// The owned junction borrows the selected JDK directory without copying it.
await symlink(dirname(selected.java), alias, "junction");
pathEnvironment.Path = `"${alias}"`;
- const onPath = await resolveJadxConfiguration(
+ const onPath = await resolveJadxConfigurationInputs(
+ pathEnvironment,
+ "inspect_android_package",
+ );
+ await validateJadxConfiguration(
+ onPath,
pathEnvironment,
"inspect_android_package",
);
diff --git a/src/application/AnalysisProvider.ts b/src/application/AnalysisProvider.ts
index a922cdb40..d88da6df7 100644
--- a/src/application/AnalysisProvider.ts
+++ b/src/application/AnalysisProvider.ts
@@ -19,6 +19,13 @@ import type { ProviderOperationHealth } from "../domain/providerOperationHealth.
export interface ExecutionOptions {
readonly signal?: AbortSignal;
readonly progress?: ProgressReporter;
+ /**
+ * Set when a procedure selector came from provider output, such as a
+ * revisited callee, rather than from the caller. A provider-derived
+ * selector is never the caller's input mistake. Absent means the caller
+ * supplied it.
+ */
+ readonly selectorOrigin?: "provider";
}
/** Closed operations accepted by provider-backed analysis sessions. */
diff --git a/src/application/BinaryTargetResolver.ts b/src/application/BinaryTargetResolver.ts
index 10f310731..ca8a4ab73 100644
--- a/src/application/BinaryTargetResolver.ts
+++ b/src/application/BinaryTargetResolver.ts
@@ -26,6 +26,8 @@ import {
validateDosComLength,
type ExecutableFormatHint,
} from "../domain/dosCom.js";
+import { admitRawBinary } from "../domain/rawBinary.js";
+import type { BinaryArchitecture } from "../domain/binaryTargetTypes.js";
import { mzWindowsHeaderOffset } from "../domain/dosMz.js";
import {
hasZipSignature,
@@ -45,6 +47,8 @@ export interface BinaryTargetResolverOptions {
readonly hostArchitecture?: NodeJS.Architecture;
readonly targetKind?: BinaryTarget["kind"];
readonly formatHint?: ExecutableFormatHint;
+ readonly architecture?: BinaryArchitecture;
+ readonly entryPoint?: string;
readonly signal?: AbortSignal;
}
@@ -61,7 +65,7 @@ export const parseBinaryTarget = async (
> => {
const cwd = options.cwd ?? process.cwd();
const hostArchitecture = options.hostArchitecture ?? process.arch;
- const { targetKind, formatHint, signal } = options;
+ const { targetKind, formatHint, signal, architecture, entryPoint } = options;
const candidate = isAbsolute(input) ? input : resolve(cwd, input);
try {
throwIfTargetResolutionCancelled(signal);
@@ -83,6 +87,40 @@ export const parseBinaryTarget = async (
throwIfTargetResolutionCancelled(signal);
const metadata = await handle.stat();
throwIfTargetResolutionCancelled(signal);
+ if (formatHint === "raw-binary") {
+ if (targetKind !== undefined && targetKind !== "executable")
+ return err(
+ new BinaryTargetError(
+ path,
+ "raw-binary format requires an executable target kind",
+ ),
+ );
+ const admitted = admitRawBinary({
+ architecture,
+ entryPoint,
+ fileBytes: metadata.size,
+ });
+ if (!admitted.ok)
+ return err(new BinaryTargetError(path, admitted.error));
+ return ok({
+ path,
+ sourcePath: canonical,
+ sha256: await sha256Handle(handle, path, metadata, signal),
+ kind: "executable",
+ format: "raw-binary",
+ architecture: admitted.value.architecture,
+ availableArchitectures: [admitted.value.architecture],
+ entryPoint: admitted.value.entryPoint,
+ entryPointSource: admitted.value.entryPointSource,
+ });
+ }
+ if (architecture !== undefined || entryPoint !== undefined)
+ return err(
+ new BinaryTargetError(
+ path,
+ "architecture and entry_point apply only with format=raw-binary",
+ ),
+ );
if (formatHint === "dos-com") {
if (targetKind !== undefined && targetKind !== "executable")
return err(
@@ -194,7 +232,13 @@ const detectArtifactFormat = async (
): Promise<
| Exclude<
BinaryTarget["format"],
- "analysis-database" | "mach-o" | "elf" | "pe" | "dos-mz" | "dos-com"
+ | "analysis-database"
+ | "mach-o"
+ | "elf"
+ | "pe"
+ | "dos-mz"
+ | "dos-com"
+ | "raw-binary"
>
| undefined
> => {
@@ -244,7 +288,13 @@ const namedArtifactFormat = (
const isArchiveFormat = (
format: Exclude<
BinaryTarget["format"],
- "analysis-database" | "mach-o" | "elf" | "pe" | "dos-mz" | "dos-com"
+ | "analysis-database"
+ | "mach-o"
+ | "elf"
+ | "pe"
+ | "dos-mz"
+ | "dos-com"
+ | "raw-binary"
>,
): format is Extract["format"] =>
isZipPackageFormat(format) || ["asar", "dmg", "pkg"].includes(format);
diff --git a/src/application/CallPathTracing.ts b/src/application/CallPathTracing.ts
index b6e9eb339..c743e91a9 100644
--- a/src/application/CallPathTracing.ts
+++ b/src/application/CallPathTracing.ts
@@ -1,4 +1,7 @@
-import type { AnalysisOperation } from "./AnalysisProvider.js";
+import type {
+ AnalysisOperation,
+ ExecutionOptions,
+} from "./AnalysisProvider.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import { parseRelatedAddresses } from "../domain/hopperValues.js";
@@ -11,6 +14,7 @@ type AnalysisCall = (
name: AnalysisOperation,
arguments_: Readonly>,
signal?: AbortSignal,
+ selectorOrigin?: ExecutionOptions["selectorOrigin"],
) => Promise>;
export interface CallPathTraceInput {
@@ -114,7 +118,7 @@ const expandAddress = async (
const relation = input.direction === "forward" ? "callees" : "callers";
const tool =
input.direction === "forward" ? "procedure_callees" : "procedure_callers";
- const result = await call(tool, { procedure: address }, signal);
+ const result = await call(tool, { procedure: address }, signal, "provider");
if (!result.ok) {
state.failures.push({
address,
diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.ts
index 73b412237..2d5ac1762 100644
--- a/src/application/DirectAnalysis.ts
+++ b/src/application/DirectAnalysis.ts
@@ -1,4 +1,5 @@
import type { ExecutableFormatHint } from "../domain/dosCom.js";
+import type { BinaryArchitecture } from "../domain/binaryTargetTypes.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { DirectAnalysisDependencies } from "./DirectAnalysisDependencies.js";
import type { BinarySession } from "./binary/BinarySession.js";
@@ -91,6 +92,8 @@ export const runDirectAnalysis = async (
readonly signal?: AbortSignal;
readonly providerId?: AnalysisProviderSelector;
readonly formatHint?: ExecutableFormatHint;
+ readonly architecture?: BinaryArchitecture;
+ readonly entryPoint?: string;
} = {},
): Promise =>
withProcessCancellation(options.signal, (signal) =>
@@ -101,6 +104,12 @@ export const runDirectAnalysis = async (
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
+ ...(options.architecture === undefined
+ ? {}
+ : { architecture: options.architecture }),
+ ...(options.entryPoint === undefined
+ ? {}
+ : { entryPoint: options.entryPoint }),
...(options.providerId === undefined
? {}
: { providerId: options.providerId }),
@@ -187,6 +196,8 @@ const runAnalysis = async (
readonly signal: AbortSignal;
readonly providerId?: AnalysisProviderSelector;
readonly formatHint?: ExecutableFormatHint;
+ readonly architecture?: BinaryArchitecture;
+ readonly entryPoint?: string;
},
): Promise => {
const { logger, signal, snapshotPath } = options;
@@ -203,6 +214,12 @@ const runAnalysis = async (
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
+ ...(options.architecture === undefined
+ ? {}
+ : { architecture: options.architecture }),
+ ...(options.entryPoint === undefined
+ ? {}
+ : { entryPoint: options.entryPoint }),
});
if (!prepared.ok) return cliError(prepared.error);
const { snapshot } = prepared.value;
@@ -214,6 +231,12 @@ const runAnalysis = async (
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
+ ...(options.architecture === undefined
+ ? {}
+ : { architecture: options.architecture }),
+ ...(options.entryPoint === undefined
+ ? {}
+ : { entryPoint: options.entryPoint }),
...(options.providerId === undefined
? {}
: { providerId: options.providerId }),
@@ -246,6 +269,12 @@ const runAnalysis = async (
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
+ ...(options.architecture === undefined
+ ? {}
+ : { architecture: options.architecture }),
+ ...(options.entryPoint === undefined
+ ? {}
+ : { entryPoint: options.entryPoint }),
...(snapshot === undefined ? {} : { snapshot }),
...(options.providerId === undefined
? {}
@@ -440,6 +469,8 @@ const withProcessCancellation = async (
const prepareSnapshot = async (options: {
readonly path: string;
readonly formatHint?: ExecutableFormatHint;
+ readonly architecture?: BinaryArchitecture;
+ readonly entryPoint?: string;
readonly snapshotPath: string | undefined;
readonly signal: AbortSignal;
}): Promise<
@@ -458,6 +489,12 @@ const prepareSnapshot = async (options: {
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
+ ...(options.architecture === undefined
+ ? {}
+ : { architecture: options.architecture }),
+ ...(options.entryPoint === undefined
+ ? {}
+ : { entryPoint: options.entryPoint }),
});
if (!target.ok) return target;
if (!snapshotMatchesTarget(loaded.value.target, target.value))
diff --git a/src/application/EnhancedToolSelectorOrigin.test.ts b/src/application/EnhancedToolSelectorOrigin.test.ts
new file mode 100644
index 000000000..387d4ebfb
--- /dev/null
+++ b/src/application/EnhancedToolSelectorOrigin.test.ts
@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest";
+import {
+ createAnalysisExecution,
+ type AnalysisOperation,
+ type AnalysisOperationPort,
+} from "./AnalysisProvider.js";
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import type { JsonValue } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { EnhancedTools } from "./EnhancedTools.js";
+
+const provider = { id: "fixture", name: "Fixture", version: "1" };
+
+interface RecordedCall {
+ readonly operation: AnalysisOperation;
+ readonly procedure: unknown;
+ readonly origin: unknown;
+}
+
+/** Port that knows `main` (0x1000, calling 0x2000) and rejects `nosuch`. */
+const recordingPort = () => {
+ const calls: RecordedCall[] = [];
+ const sentParameters: Readonly>[] = [];
+ const port: AnalysisOperationPort = {
+ execute: async (operation, parameters, options) => {
+ sentParameters.push(parameters);
+ calls.push({
+ operation,
+ procedure: parameters.procedure,
+ origin: options?.selectorOrigin,
+ });
+ const known = (value: JsonValue) =>
+ ok(createAnalysisExecution(value, provider));
+ if (parameters.procedure === "nosuch")
+ return err(new AnalysisInputError(operation));
+ switch (operation) {
+ case "procedure_address":
+ return known(parameters.procedure === "main" ? "0x1000" : "0x2000");
+ case "procedure_callees":
+ return known(parameters.procedure === "0x1000" ? ["0x2000"] : []);
+ case "procedure_pseudo_code":
+ return known("int main(void) { return 0; }");
+ case "address_name":
+ return known("main");
+ default:
+ throw new Error(`Unexpected operation: ${operation}`);
+ }
+ },
+ };
+ return { calls, sentParameters, tools: new EnhancedTools(port) };
+};
+
+const of = (
+ calls: readonly RecordedCall[],
+ operation: AnalysisOperation,
+): RecordedCall[] => calls.filter((call) => call.operation === operation);
+
+describe("selector origin of composed workflows", () => {
+ it("marks every call-graph expansion as provider-derived and the root selector as caller-supplied", async () => {
+ const { calls, tools } = recordingPort();
+
+ const result = await tools.execute("get_call_graph", { address: "main" });
+
+ expect(result.ok, "the graph is built").toBe(true);
+ expect(
+ of(calls, "procedure_address"),
+ "the caller's selector carries no provider origin",
+ ).toEqual([
+ { operation: "procedure_address", procedure: "main", origin: undefined },
+ ]);
+ expect(
+ of(calls, "procedure_callees"),
+ "the canonical start and every discovered callee are provider-derived",
+ ).toEqual([
+ {
+ operation: "procedure_callees",
+ procedure: "0x1000",
+ origin: "provider",
+ },
+ {
+ operation: "procedure_callees",
+ procedure: "0x2000",
+ origin: "provider",
+ },
+ ]);
+ });
+
+ it("marks trace expansions as provider-derived and the start and goal as caller-supplied", async () => {
+ const { calls, tools } = recordingPort();
+
+ const result = await tools.execute("trace_call_path", {
+ start: "main",
+ goal: "0x2000",
+ });
+
+ expect(result.ok, "the trace completes").toBe(true);
+ expect(
+ of(calls, "procedure_address").map(({ origin }) => origin),
+ "start and goal resolutions are caller-supplied",
+ ).toEqual([undefined, undefined]);
+ expect(
+ of(calls, "procedure_callees").map(({ origin }) => origin),
+ "expansion of the resolved start is provider-derived",
+ ).toEqual(["provider"]);
+ });
+
+ it("marks the canonical retry of batch_decompile as derived and keeps the unresolved fallback caller-supplied", async () => {
+ const { calls, tools } = recordingPort();
+
+ const result = await tools.execute("batch_decompile", {
+ addresses: ["main", "nosuch"],
+ });
+
+ expect(result.ok, "per-item failures do not fail the batch").toBe(true);
+ expect(
+ of(calls, "procedure_pseudo_code")
+ .map(({ procedure, origin }) => [procedure, origin])
+ .sort(([left], [right]) => String(left).localeCompare(String(right))),
+ "the resolved canonical address is derived; the failed item keeps the caller's text",
+ ).toEqual([
+ ["0x1000", "provider"],
+ ["nosuch", undefined],
+ ]);
+ });
+
+ it("never copies the origin into the parameters sent to the provider", async () => {
+ const { sentParameters, tools } = recordingPort();
+
+ await tools.execute("get_call_graph", { address: "main" });
+ await tools.execute("trace_call_path", { start: "main" });
+ await tools.execute("batch_decompile", { addresses: ["main"] });
+
+ expect(
+ sentParameters.length,
+ "workflows issued provider calls",
+ ).toBeGreaterThan(0);
+ expect(
+ sentParameters.some((parameters) => "selectorOrigin" in parameters),
+ "the origin travels in the options only, never in Evidence-bound parameters",
+ ).toBe(false);
+ });
+});
diff --git a/src/application/EnhancedTools.ts b/src/application/EnhancedTools.ts
index c4ec83c6c..06862be0e 100644
--- a/src/application/EnhancedTools.ts
+++ b/src/application/EnhancedTools.ts
@@ -3,6 +3,7 @@ import { z } from "zod";
import type {
AnalysisOperation,
AnalysisOperationPort,
+ ExecutionOptions,
} from "./AnalysisProvider.js";
import type { EnhancedToolName } from "../contracts/enhancedInputs.js";
import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
@@ -163,8 +164,8 @@ export class EnhancedTools {
);
case "trace_call_path":
return traceCallPath(
- (name, arguments_, operationSignal) =>
- this.#call(name, arguments_, operationSignal),
+ (name, arguments_, operationSignal, selectorOrigin) =>
+ this.#call(name, arguments_, operationSignal, selectorOrigin),
call.input,
signal,
);
@@ -267,6 +268,7 @@ export class EnhancedTools {
"procedure_pseudo_code",
{ procedure: resolved.ok ? resolved.value : address },
signal,
+ resolved.ok ? "provider" : undefined,
);
if (!result.ok)
return {
@@ -361,6 +363,7 @@ export class EnhancedTools {
tool,
{ procedure: current.address },
signal,
+ "provider",
);
if (!result.ok) {
graph[level].push({
@@ -518,13 +521,13 @@ export class EnhancedTools {
name: AnalysisOperation,
arguments_: Readonly>,
signal?: AbortSignal,
+ selectorOrigin?: ExecutionOptions["selectorOrigin"],
): Promise> {
if (isAborted(signal)) return err(new AnalysisCancelledError(name));
- const execution = await this.analysis.execute(
- name,
- arguments_,
- signal === undefined ? {} : { signal },
- );
+ const execution = await this.analysis.execute(name, arguments_, {
+ ...(signal === undefined ? {} : { signal }),
+ ...(selectorOrigin === undefined ? {} : { selectorOrigin }),
+ });
if (isAborted(signal)) return err(new AnalysisCancelledError(name));
return execution.ok ? ok(execution.value.result) : execution;
}
diff --git a/src/application/Uninstall.ts b/src/application/Uninstall.ts
index 3e3099ea3..d363f950d 100644
--- a/src/application/Uninstall.ts
+++ b/src/application/Uninstall.ts
@@ -184,10 +184,7 @@ export const systemUninstallHost = (
removeClient: (client) => removeClient(client, fileSystem),
removeSkill: () =>
removeManagedSkills(home, fileSystem, environment, platform),
- purgeData: async () => [
- await removeManagedPath(join(home, ".rea/cache"), "cache", fileSystem),
- await removeManagedPath(join(home, ".rea/state"), "state", fileSystem),
- ],
+ purgeData: () => purgeManagedData(join(home, ".rea"), fileSystem),
};
};
@@ -380,6 +377,39 @@ const isOwnedRegistration = (value: unknown, client: SetupClient): boolean => {
return isOwnedClientRegistrationCommand([command, ...args]);
};
+const purgeManagedData = async (
+ root: string,
+ fileSystem: UninstallFileSystem,
+): Promise => {
+ const names = ["cache", "state"];
+ try {
+ const stats = await fileSystem.stat(root);
+ const linked = stats.isSymbolicLink();
+ if (linked || stats.isDirectory?.() !== true)
+ return names.map((name) =>
+ item(
+ name,
+ "retained",
+ `REA did not remove this item because its managed data root ${root} is ${linked ? "a symbolic link" : "not a directory"}. Verify the root before removing its data manually.`,
+ ),
+ );
+ } catch (cause: unknown) {
+ return names.map((name) =>
+ isMissing(cause)
+ ? item(name, "skipped", `${join(root, name)} does not exist.`)
+ : item(
+ name,
+ "failed",
+ `The managed data root ${root} could not be verified. Check its permissions, then rerun uninstall.`,
+ ),
+ );
+ }
+ const items: UninstallItem[] = [];
+ for (const name of names)
+ items.push(await removeManagedPath(join(root, name), name, fileSystem));
+ return items;
+};
+
const removeManagedPath = async (
path: string,
name: string,
diff --git a/src/application/binary/BinarySession.ts b/src/application/binary/BinarySession.ts
index d64e04f89..b12b310ff 100644
--- a/src/application/binary/BinarySession.ts
+++ b/src/application/binary/BinarySession.ts
@@ -497,7 +497,7 @@ export class BinarySession
execute(
name: Parameters[0],
arguments_: Readonly>,
- options?: { readonly signal?: AbortSignal },
+ options?: Pick,
): Promise> {
const generation = this.#transitionGeneration;
const call = this.#execute(name, arguments_, options, this.#transition);
@@ -535,7 +535,7 @@ export class BinarySession
async #execute(
name: Parameters[0],
arguments_: Readonly>,
- options: { readonly signal?: AbortSignal } | undefined,
+ options: Pick | undefined,
transition: Promise,
): Promise> {
const transitioned = await this.#waitForTransition(
diff --git a/src/application/binary/BinarySessionOpen.ts b/src/application/binary/BinarySessionOpen.ts
index 714bed804..8d810e671 100644
--- a/src/application/binary/BinarySessionOpen.ts
+++ b/src/application/binary/BinarySessionOpen.ts
@@ -1,4 +1,5 @@
import type { ExecutableFormatHint } from "../../domain/dosCom.js";
+import type { BinaryArchitecture } from "../../domain/binaryTargetTypes.js";
import type { AnalysisProviderSelector } from "../../contracts/providerSelection.js";
import type { AnalysisProfileCommitment } from "../../domain/analysisProfile.js";
import {
@@ -22,6 +23,8 @@ export interface BinarySessionOpenOptions {
readonly signal?: AbortSignal;
readonly targetKind?: BinaryTarget["kind"];
readonly formatHint?: ExecutableFormatHint;
+ readonly architecture?: BinaryArchitecture;
+ readonly entryPoint?: string;
readonly snapshot?: AnalysisSnapshot;
readonly providerId?: AnalysisProviderSelector;
}
@@ -72,6 +75,12 @@ export const resolveSessionOpen = async (
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
+ ...(options.architecture === undefined
+ ? {}
+ : { architecture: options.architecture }),
+ ...(options.entryPoint === undefined
+ ? {}
+ : { entryPoint: options.entryPoint }),
...(options.signal === undefined ? {} : { signal: options.signal }),
});
if (!parsed.ok) return parsed;
diff --git a/src/application/binary/BinarySessionPort.ts b/src/application/binary/BinarySessionPort.ts
index 166479a06..ee666f665 100644
--- a/src/application/binary/BinarySessionPort.ts
+++ b/src/application/binary/BinarySessionPort.ts
@@ -1,6 +1,9 @@
import type { InvestigationRecordPort } from "../investigation/InvestigationRecordPort.js";
import type { ExecutableFormatHint } from "../../domain/dosCom.js";
-import type { BinaryTarget } from "../../domain/binaryTargetTypes.js";
+import type {
+ BinaryArchitecture,
+ BinaryTarget,
+} from "../../domain/binaryTargetTypes.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import type { AnalysisSnapshot } from "../../domain/analysisSnapshot.js";
import type { AnalysisProfileCommitment } from "../../domain/analysisProfile.js";
@@ -44,6 +47,8 @@ export interface BinarySessionPort
readonly signal?: AbortSignal;
readonly targetKind?: BinaryTarget["kind"];
readonly formatHint?: ExecutableFormatHint;
+ readonly architecture?: BinaryArchitecture;
+ readonly entryPoint?: string;
readonly snapshot?: AnalysisSnapshot;
readonly providerId?: AnalysisProviderSelector;
},
diff --git a/src/application/binary/BinarySessionStatus.ts b/src/application/binary/BinarySessionStatus.ts
index 4c5fc34bb..9048c6de6 100644
--- a/src/application/binary/BinarySessionStatus.ts
+++ b/src/application/binary/BinarySessionStatus.ts
@@ -1,4 +1,5 @@
import type { BinaryTarget } from "../../domain/binaryTargetTypes.js";
+import { binaryTargetSummary } from "./BinaryTargetSummary.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import type { ProviderOperationHealth } from "../../domain/providerOperationHealth.js";
import type {
@@ -92,11 +93,7 @@ export const binarySessionStatus = ({
: {
open: true,
...common,
- path: target.path,
- sha256: target.sha256,
- format: target.format,
- kind: target.kind,
- architecture: target.architecture ?? null,
+ ...binaryTargetSummary(target),
};
};
diff --git a/src/application/binary/BinaryTargetSummary.ts b/src/application/binary/BinaryTargetSummary.ts
new file mode 100644
index 000000000..83d721283
--- /dev/null
+++ b/src/application/binary/BinaryTargetSummary.ts
@@ -0,0 +1,11 @@
+import type { BinaryTarget } from "../../domain/binaryTargetTypes.js";
+
+/** Preserve the admitted target interpretation in public lifecycle results. */
+export const binaryTargetSummary = (target: BinaryTarget) => ({
+ path: target.path,
+ format: target.format,
+ kind: target.kind,
+ sha256: target.sha256,
+ architecture: target.architecture ?? null,
+ ...(target.format === "raw-binary" ? { entry_point: target.entryPoint } : {}),
+});
diff --git a/src/application/native/EnhancedNativeInvestigation.test.ts b/src/application/native/EnhancedNativeInvestigation.test.ts
index 89756fcd2..087b5981f 100644
--- a/src/application/native/EnhancedNativeInvestigation.test.ts
+++ b/src/application/native/EnhancedNativeInvestigation.test.ts
@@ -246,6 +246,40 @@ describe("native UI action trace", () => {
});
});
+describe("native UI action selector origin", () => {
+ it("marks provider-reported function addresses as derived and the action seed as caller-supplied", async () => {
+ const inner = testAnalysis({
+ procedure_address: () => execution("procedure_address", "0x1000"),
+ });
+ const recorded: { operation: string; origin: unknown }[] = [];
+
+ const result = await new EnhancedTools({
+ execute: async (operation, parameters, options) => {
+ recorded.push({ operation, origin: options?.selectorOrigin });
+ return inner.execute(operation, parameters);
+ },
+ }).execute("trace_native_ui_action", { action: "0x1000" });
+
+ expect(result.ok, "the trace completes").toBe(true);
+ expect(
+ recorded
+ .filter(({ operation }) => operation === "procedure_address")
+ .map(({ origin }) => origin),
+ "the caller's action seed carries no provider origin",
+ ).toEqual([undefined]);
+ const probes = recorded.filter(
+ ({ operation }) =>
+ operation === "procedure_references" ||
+ operation === "procedure_callees",
+ );
+ expect(probes.length, "relationships were probed").toBeGreaterThan(0);
+ expect(
+ probes.every(({ origin }) => origin === "provider"),
+ "every relationship probe uses a provider-reported address",
+ ).toBe(true);
+ });
+});
+
describe("bounded native UI tracing", () => {
it("continues handler traversal from its own depth when another UI branch is deeper", async () => {
const deepGraph = {
diff --git a/src/application/native/NativeCallRoutes.ts b/src/application/native/NativeCallRoutes.ts
index bb819d742..fe77f61e9 100644
--- a/src/application/native/NativeCallRoutes.ts
+++ b/src/application/native/NativeCallRoutes.ts
@@ -1,5 +1,8 @@
import { z } from "zod";
-import type { AnalysisOperationPort } from "../AnalysisProvider.js";
+import type {
+ AnalysisOperationPort,
+ ExecutionOptions,
+} from "../AnalysisProvider.js";
import {
parseRelatedAddresses,
referenceKindSchema,
@@ -26,8 +29,12 @@ export const readNativeCallRoutes = async (
analysis: AnalysisOperationPort,
procedure: string,
signal?: AbortSignal,
+ selectorOrigin?: ExecutionOptions["selectorOrigin"],
) => {
- const options = signal === undefined ? {} : { signal };
+ const options = {
+ ...(signal === undefined ? {} : { signal }),
+ ...(selectorOrigin === undefined ? {} : { selectorOrigin }),
+ };
const execution = await analysis.execute(
"procedure_references",
{ procedure, direction: "outgoing" },
diff --git a/src/application/native/NativeUiActionTrace.ts b/src/application/native/NativeUiActionTrace.ts
index 9b975b32c..141b31bc0 100644
--- a/src/application/native/NativeUiActionTrace.ts
+++ b/src/application/native/NativeUiActionTrace.ts
@@ -411,6 +411,7 @@ const addDirectCallees = async (input: {
input.analysis,
current.address,
input.signal,
+ "provider",
);
examined += 1;
if (!execution.ok) {
diff --git a/src/application/native/NativeValueTrace.test.ts b/src/application/native/NativeValueTrace.test.ts
index bea7675ba..cdc663d54 100644
--- a/src/application/native/NativeValueTrace.test.ts
+++ b/src/application/native/NativeValueTrace.test.ts
@@ -529,3 +529,32 @@ describe("bounded native value dependency composition", () => {
});
});
});
+
+describe("native value trace selector origin", () => {
+ it("marks only the initial procedure as caller-supplied", async () => {
+ const analyzed: { procedure: unknown; origin: unknown }[] = [];
+
+ const result = await traceNativeValues(
+ {
+ execute: async (operation, parameters, options) => {
+ if (operation === "analyze_function")
+ analyzed.push({
+ procedure: parameters.procedure,
+ origin: options?.selectorOrigin,
+ });
+ return analysis.execute(operation, parameters, options);
+ },
+ },
+ { procedure: "0x1000" },
+ );
+
+ expect(result.ok, "the trace completes").toBe(true);
+ expect(
+ analyzed,
+ "the caller's procedure is unmarked and the discovered callee is provider-derived",
+ ).toEqual([
+ { procedure: "0x1000", origin: undefined },
+ { procedure: "0x2000", origin: "provider" },
+ ]);
+ });
+});
diff --git a/src/application/native/NativeValueTrace.ts b/src/application/native/NativeValueTrace.ts
index 3bf7b56db..71c602396 100644
--- a/src/application/native/NativeValueTrace.ts
+++ b/src/application/native/NativeValueTrace.ts
@@ -57,7 +57,10 @@ export const traceNativeValues = async (
const execution = await analysis.execute(
"analyze_function",
{ procedure: next.procedure },
- signal === undefined ? {} : { signal },
+ {
+ ...(signal === undefined ? {} : { signal }),
+ ...(next.depth > 0 ? { selectorOrigin: "provider" as const } : {}),
+ },
);
decompilations++;
if (!execution.ok) {
diff --git a/src/artifacts/ZipArtifactReader.ts b/src/artifacts/ZipArtifactReader.ts
index 2c74030b9..bd3fd93e5 100644
--- a/src/artifacts/ZipArtifactReader.ts
+++ b/src/artifacts/ZipArtifactReader.ts
@@ -147,22 +147,23 @@ export class ZipArtifactReader implements ArtifactReader {
}
async *entries(signal?: AbortSignal): AsyncIterable {
- const filenames = new Set();
+ let index = 0;
for await (const entry of this.#reader.getEntriesGenerator()) {
abortIfNeeded(signal);
- // Each enumeration can replay valid entries, but a second record with
- // the same name must not replace an already emitted source identity.
- if (filenames.has(entry.filename))
+ // ZIP member identity is its directory occurrence, not its filename.
+ // Logical path uniqueness belongs to the artifact inventory boundary.
+ const metadata = projectZipEntry(entry, index++);
+ const stored = this.#entries.get(metadata.adapterKey);
+ if (stored !== undefined && !sameArtifactEntry(metadata, stored.metadata))
throw new ArtifactReaderFailure(
- "path",
- `Artifact path collision: ${entry.filename}`,
+ "integrity",
+ `ZIP member identity changed during enumeration: ${entry.filename}`,
);
- filenames.add(entry.filename);
- const metadata = projectZipEntry(entry);
- this.#entries.set(entry.filename, {
- source: entry,
- metadata: copyArtifactEntry(metadata),
- });
+ if (stored === undefined)
+ this.#entries.set(metadata.adapterKey, {
+ source: entry,
+ metadata: copyArtifactEntry(metadata),
+ });
yield metadata;
}
}
@@ -203,7 +204,7 @@ export class ZipArtifactReader implements ArtifactReader {
}
}
-const projectZipEntry = (entry: Entry): ArtifactEntry => {
+const projectZipEntry = (entry: Entry, index: number): ArtifactEntry => {
const symlink = isSymlink(entry);
return {
path: entry.filename,
@@ -216,7 +217,7 @@ const projectZipEntry = (entry: Entry): ArtifactEntry => {
declaredSha256: null,
unpacked: false,
limitations: symlink ? ["Archive symlink target was not read."] : [],
- adapterKey: entry.filename,
+ adapterKey: `zip-entry:${index}`,
};
};
diff --git a/src/cli/coreBinaryCommands.ts b/src/cli/coreBinaryCommands.ts
index cf4a08236..6a117dada 100644
--- a/src/cli/coreBinaryCommands.ts
+++ b/src/cli/coreBinaryCommands.ts
@@ -8,9 +8,8 @@ import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import type { Logger } from "pino";
import {
- directAnalysisOptions,
- formatSelectionOption,
- providerSelectionOption,
+ directAnalysisOptionsFromCli,
+ nativeOpenOptionFields,
} from "./options.js";
import type { CliInstance } from "./types.js";
import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
@@ -43,8 +42,7 @@ const registerOverviewCommands = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
});
cli.command(CLI_COMMANDS.analyze, {
description: "Get an overview of an app",
@@ -75,12 +73,7 @@ const registerOverviewCommands = (
args.path,
"binary_overview",
{},
- directAnalysisOptions(
- logger,
- options.snapshot,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
);
},
@@ -97,12 +90,7 @@ const registerOverviewCommands = (
args.path,
"binary_overview",
{},
- directAnalysisOptions(
- logger,
- options.snapshot,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -136,8 +124,7 @@ const registerDecompileCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "decompile", () =>
@@ -152,12 +139,7 @@ const registerDecompileCommand = (
"procedure_pseudo_code",
),
},
- directAnalysisOptions(
- logger,
- options.snapshot,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -168,13 +150,17 @@ const routesToJavaScriptAnalysis = async (
path: string,
options: {
readonly snapshot?: string | undefined;
- readonly "target-format"?: "dos-com" | undefined;
+ readonly "target-format"?: "dos-com" | "raw-binary" | undefined;
+ readonly architecture?: string | undefined;
+ readonly "entry-point"?: string | undefined;
readonly provider?: string | undefined;
},
): Promise =>
options.provider === undefined &&
options.snapshot === undefined &&
options["target-format"] === undefined &&
+ options.architecture === undefined &&
+ options["entry-point"] === undefined &&
(await isJavaScriptApplicationPath(path));
const isJavaScriptApplicationPath = async (path: string): Promise => {
@@ -215,8 +201,7 @@ const registerXrefsCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "xrefs", () =>
@@ -231,12 +216,7 @@ const registerXrefsCommand = (
"xrefs",
),
},
- directAnalysisOptions(
- logger,
- options.snapshot,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -270,8 +250,7 @@ const registerTraceCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "trace", () =>
@@ -287,12 +266,7 @@ const registerTraceCommand = (
),
case_sensitive: options.caseSensitive,
},
- directAnalysisOptions(
- logger,
- options.snapshot,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -326,8 +300,7 @@ const registerFunctionCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "function", () =>
@@ -342,12 +315,7 @@ const registerFunctionCommand = (
"analyze_function",
),
},
- directAnalysisOptions(
- logger,
- options.snapshot,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -381,8 +349,7 @@ const registerInstructionsCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.instructions, () =>
@@ -397,12 +364,7 @@ const registerInstructionsCommand = (
"read_function_instructions",
),
},
- directAnalysisOptions(
- logger,
- options.snapshot,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -448,8 +410,7 @@ const registerSearchCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "search", () =>
@@ -468,12 +429,7 @@ const registerSearchCommand = (
mode: options.mode,
case_sensitive: options.caseSensitive,
},
- directAnalysisOptions(
- logger,
- options.snapshot,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
diff --git a/src/cli/coreNativeCommands.ts b/src/cli/coreNativeCommands.ts
index 77ded7347..016eedbc0 100644
--- a/src/cli/coreNativeCommands.ts
+++ b/src/cli/coreNativeCommands.ts
@@ -5,9 +5,8 @@ import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import type { Logger } from "pino";
import {
- directAnalysisOptions,
- formatSelectionOption,
- providerSelectionOption,
+ directAnalysisOptionsFromCli,
+ nativeOpenOptionFields,
} from "./options.js";
import type { CliInstance } from "./types.js";
@@ -23,8 +22,7 @@ export const registerCoreNativeCommands = (
"Verify loaded native bytes, source mappings, relocations and entry",
args: z.object({ path: z.string().describe("Local executable path") }),
options: z.object({
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.inspectNativeLoadImage, () =>
@@ -32,12 +30,7 @@ export const registerCoreNativeCommands = (
args.path,
"inspect_native_load_image",
{},
- directAnalysisOptions(
- logger,
- undefined,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -54,8 +47,7 @@ export const registerCoreNativeCommands = (
.min(1)
.default(256)
.describe("Requested byte count"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.readBytes, () =>
@@ -63,12 +55,7 @@ export const registerCoreNativeCommands = (
args.path,
"read_bytes",
{ address: args.address, length: options.length },
- directAnalysisOptions(
- logger,
- undefined,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -79,8 +66,7 @@ export const registerCoreNativeCommands = (
address: z.string().describe("Exact provider memory address"),
}),
options: z.object({
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.addressToFileOffset, () =>
@@ -88,12 +74,7 @@ export const registerCoreNativeCommands = (
args.path,
"address_to_file_offset",
{ address: args.address },
- directAnalysisOptions(
- logger,
- undefined,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -154,8 +135,7 @@ export const registerCoreNativeCommands = (
.max(5000)
.default(1000)
.describe("Maximum nodes on this page"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.traceNativeValues, () =>
@@ -172,12 +152,7 @@ export const registerCoreNativeCommands = (
offset: options.offset,
limit: options.limit,
},
- directAnalysisOptions(
- logger,
- undefined,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -189,8 +164,7 @@ export const registerCoreNativeCommands = (
options: z.object({
type: z.string().optional().describe("Exact database type category path"),
address: z.string().optional().describe("Exact native address"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.inspectNativeDataType, () =>
@@ -203,12 +177,7 @@ export const registerCoreNativeCommands = (
? {}
: { address: options.address }),
},
- directAnalysisOptions(
- logger,
- undefined,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -226,8 +195,7 @@ export const registerCoreNativeCommands = (
address: z.string().describe("Exact native address"),
}),
options: z.object({
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, command, () =>
@@ -235,12 +203,7 @@ export const registerCoreNativeCommands = (
args.path,
operation,
{ address: args.address },
- directAnalysisOptions(
- logger,
- undefined,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -273,8 +236,7 @@ const registerNativeDispatchMetadataCommand = (
.min(1)
.optional()
.describe("Load or update the local analysis snapshot"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: async ({ args, options }) =>
logCliCommand(logger, "inspect-native-dispatch-metadata", () =>
@@ -282,12 +244,7 @@ const registerNativeDispatchMetadataCommand = (
args.path,
"inspect_native_dispatch_metadata",
{ max_records: options.maxRecords },
- directAnalysisOptions(
- logger,
- options.snapshot,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -332,8 +289,7 @@ const registerNativeUiActionCommand = (
.max(5_000)
.default(500)
.describe("Maximum returned graph edges"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: async ({ args, options }) =>
logCliCommand(logger, "trace-native-ui-action", () =>
@@ -346,12 +302,7 @@ const registerNativeUiActionCommand = (
max_nodes: options.maxNodes,
max_edges: options.maxEdges,
},
- directAnalysisOptions(
- logger,
- undefined,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -374,8 +325,7 @@ const registerNativeApiCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "inspect-native-api", () =>
@@ -383,12 +333,7 @@ const registerNativeApiCommand = (
args.path,
"inspect_native_api",
{ procedure: args.address },
- directAnalysisOptions(
- logger,
- options.snapshot,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -417,8 +362,7 @@ const registerAnnotationCommand = (
.string()
.optional()
.describe("Inline entry comment; empty text clears it"),
- "target-format": formatSelectionOption,
- provider: providerSelectionOption,
+ ...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.annotateNativeFunction, () =>
@@ -435,12 +379,7 @@ const registerAnnotationCommand = (
? {}
: { inline_comment: options["inline-comment"] }),
},
- directAnalysisOptions(
- logger,
- undefined,
- options.provider,
- options["target-format"],
- ),
+ directAnalysisOptionsFromCli(logger, options),
),
),
});
diff --git a/src/cli/options.ts b/src/cli/options.ts
index 22f63ab9c..e96414707 100644
--- a/src/cli/options.ts
+++ b/src/cli/options.ts
@@ -2,6 +2,11 @@ import {
executableFormatHintSchema,
type ExecutableFormatHint,
} from "../domain/dosCom.js";
+import type { BinaryArchitecture } from "../domain/binaryTargetTypes.js";
+import {
+ binaryArchitectureSchema,
+ rawBinaryEntryPointSchema,
+} from "../domain/rawBinary.js";
import { analysisProviderSelectorSchema } from "../contracts/providerSelection.js";
import type { AnalysisProviderSelector } from "../contracts/providerSelection.js";
import type { Logger } from "pino";
@@ -15,16 +20,65 @@ export const providerSelectionOption = analysisProviderSelectorSchema
/** Explicit interpretation for headerless native executable formats. */
export const formatSelectionOption = executableFormatHintSchema
.optional()
- .describe("Explicit headerless DOS COM interpretation");
+ .describe(
+ "Explicit headerless interpretation (dos-com or raw-binary); omission preserves header-based detection",
+ );
+
+export const architectureSelectionOption = binaryArchitectureSchema
+ .optional()
+ .describe(
+ "Caller-supplied CPU family; required with --target-format raw-binary",
+ );
+
+export const entryPointSelectionOption = rawBinaryEntryPointSchema
+ .optional()
+ .describe(
+ "Caller-supplied load and entry address (0xhex); required with --target-format raw-binary",
+ );
+
+/** Shared CLI flags that bind a native target interpretation. */
+export const nativeOpenOptionFields = {
+ "target-format": formatSelectionOption,
+ architecture: architectureSelectionOption,
+ "entry-point": entryPointSelectionOption,
+ provider: providerSelectionOption,
+};
+
+/** Native CLI flags consumed when opening a target for one-shot analysis. */
+export interface NativeOpenCliFlags {
+ readonly snapshot?: string | undefined;
+ readonly provider?: AnalysisProviderSelector | undefined;
+ readonly "target-format"?: ExecutableFormatHint | undefined;
+ readonly architecture?: BinaryArchitecture | undefined;
+ readonly "entry-point"?: string | undefined;
+}
export const directAnalysisOptions = (
logger: Logger,
snapshotPath: string | undefined,
providerId: AnalysisProviderSelector | undefined,
formatHint?: ExecutableFormatHint,
+ architecture?: BinaryArchitecture,
+ entryPoint?: string,
) => ({
logger,
snapshotPath,
...(formatHint === undefined ? {} : { formatHint }),
+ ...(architecture === undefined ? {} : { architecture }),
+ ...(entryPoint === undefined ? {} : { entryPoint }),
...(providerId === undefined ? {} : { providerId }),
});
+
+/** Map native CLI flags onto the shared one-shot analysis options. */
+export const directAnalysisOptionsFromCli = (
+ logger: Logger,
+ options: NativeOpenCliFlags,
+) =>
+ directAnalysisOptions(
+ logger,
+ options.snapshot,
+ options.provider,
+ options["target-format"],
+ options.architecture,
+ options["entry-point"],
+ );
diff --git a/src/contracts/sessionLifecycleInputs.test.ts b/src/contracts/sessionLifecycleInputs.test.ts
new file mode 100644
index 000000000..34014b70b
--- /dev/null
+++ b/src/contracts/sessionLifecycleInputs.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+
+import { openBinaryInputSchema } from "./sessionLifecycleInputs.js";
+
+describe("open_binary raw-binary input contract", () => {
+ it("accepts header detection without architecture", () => {
+ expect(
+ openBinaryInputSchema.safeParse({ path: "/tmp/fixture.bin" }).success,
+ ).toBe(true);
+ expect(
+ openBinaryInputSchema.safeParse({
+ path: "/tmp/legacy.com",
+ format: "dos-com",
+ }).success,
+ ).toBe(true);
+ });
+ it("accepts raw-binary with architecture and entry", () => {
+ expect(
+ openBinaryInputSchema.safeParse({
+ path: "/tmp/ecu.bin",
+ format: "raw-binary",
+ architecture: "arm",
+ entry_point: "0x8000000",
+ }).success,
+ ).toBe(true);
+ });
+ it("rejects raw-binary without architecture or entry", () => {
+ const parsed = openBinaryInputSchema.safeParse({
+ path: "/tmp/ecu.bin",
+ format: "raw-binary",
+ });
+ expect(parsed.success).toBe(false);
+ expect(
+ openBinaryInputSchema.safeParse({
+ path: "/tmp/ecu.bin",
+ format: "raw-binary",
+ architecture: "arm",
+ }).success,
+ ).toBe(false);
+ });
+ it("rejects architecture without format=raw-binary", () => {
+ expect(
+ openBinaryInputSchema.safeParse({
+ path: "/tmp/ecu.bin",
+ architecture: "arm",
+ entry_point: "0x8000000",
+ }).success,
+ ).toBe(false);
+ });
+});
diff --git a/src/contracts/sessionLifecycleInputs.ts b/src/contracts/sessionLifecycleInputs.ts
index ca11b03a0..775da39cd 100644
--- a/src/contracts/sessionLifecycleInputs.ts
+++ b/src/contracts/sessionLifecycleInputs.ts
@@ -1,6 +1,11 @@
import { isAbsolute } from "node:path";
import { executableFormatHintSchema } from "../domain/dosCom.js";
import { localPathStringSchema } from "../domain/localPath.js";
+import {
+ binaryArchitectureSchema,
+ rawBinaryEntryPointSchema,
+ rawBinarySelectionError,
+} from "../domain/rawBinary.js";
import { z } from "zod";
import { analysisProviderSelectorSchema } from "./providerSelection.js";
@@ -25,16 +30,51 @@ const binaryTargetPathSchema = localPathStringSchema
);
/** Input contract for opening a target with an optional staged snapshot. */
-export const openBinaryInputSchema = z.strictObject({
- path: binaryTargetPathSchema,
- format: executableFormatHintSchema
- .optional()
- .describe(
- "Explicit headerless DOS COM interpretation; omission preserves header-based detection",
- ),
- provider_id: analysisProviderSelectorSchema.optional(),
- snapshot_path: snapshotPathSchema.optional(),
-});
+export const openBinaryInputSchema = z
+ .strictObject({
+ path: binaryTargetPathSchema,
+ format: executableFormatHintSchema
+ .optional()
+ .describe(
+ "Explicit headerless interpretation: dos-com or raw-binary. Omission preserves header-based detection.",
+ ),
+ architecture: binaryArchitectureSchema
+ .optional()
+ .describe(
+ "Caller-supplied CPU family. Required with format=raw-binary; rejected otherwise.",
+ ),
+ entry_point: rawBinaryEntryPointSchema
+ .optional()
+ .describe(
+ "Caller-supplied load and entry address (0xhex). File offset 0 is mapped here. Required with format=raw-binary; rejected otherwise.",
+ ),
+ provider_id: analysisProviderSelectorSchema.optional(),
+ snapshot_path: snapshotPathSchema.optional(),
+ })
+ .superRefine((value, context) => {
+ const pairing = rawBinarySelectionError({
+ ...(value.format === undefined ? {} : { format: value.format }),
+ ...(value.architecture === undefined
+ ? {}
+ : { architecture: value.architecture }),
+ ...(value.entry_point === undefined
+ ? {}
+ : { entryPoint: value.entry_point }),
+ });
+ if (pairing === undefined) return;
+ context.addIssue({
+ code: "custom",
+ path:
+ value.format === "raw-binary"
+ ? value.architecture === undefined
+ ? ["architecture"]
+ : ["entry_point"]
+ : value.architecture === undefined
+ ? ["entry_point"]
+ : ["architecture"],
+ message: pairing,
+ });
+ });
/** Input contract for closing a target after an optional atomic snapshot. */
export const closeBinaryInputSchema = z.strictObject({
diff --git a/src/contracts/sessionToolContracts.ts b/src/contracts/sessionToolContracts.ts
index e758335d7..b3ea2e318 100644
--- a/src/contracts/sessionToolContracts.ts
+++ b/src/contracts/sessionToolContracts.ts
@@ -69,7 +69,7 @@ export const exportEvidenceBundleInputSchema = z.strictObject({
export const SESSION_TOOL_CONTRACTS = [
session(
"open_binary",
- "Open a local executable, application bundle, archive, JavaScript, source map, plist, or analysis database after validation. format=dos-com explicitly interprets 1..65280 headerless bytes as a DOS COM analysis image; omission preserves header-based detection. provider_id selects one deep provider or deterministic auto selection; the binding remains stable until close or an explicit switch, with no failure fallback. Reopening the same target and profile retains its active database and metadata edits. An optional analysis snapshot is imported atomically and must match the binary identity, concrete provider, and canonical analysis profile exactly; importing into a session with metadata mutations requires closing and reopening it first.",
+ "Open a local executable, application bundle, archive, JavaScript, source map, plist, or analysis database after validation. format=dos-com explicitly interprets 1..65280 headerless bytes as a DOS COM analysis image. format=raw-binary interprets headerless bytes with a required architecture and entry_point; file offset 0 maps at that address. Omission preserves header-based detection. provider_id selects one deep provider or deterministic auto selection; the binding remains stable until close or an explicit switch, with no failure fallback. Reopening the same target and profile retains its active database and metadata edits. An optional analysis snapshot is imported atomically and must match the binary identity, concrete provider, and canonical analysis profile exactly; importing into a session with metadata mutations requires closing and reopening it first.",
openBinaryInputSchema,
),
session(
diff --git a/src/contracts/toolOutputSchemaGroups.ts b/src/contracts/toolOutputSchemaGroups.ts
index f9b4c0b3a..c87c0f09c 100644
--- a/src/contracts/toolOutputSchemaGroups.ts
+++ b/src/contracts/toolOutputSchemaGroups.ts
@@ -1,6 +1,10 @@
import { z } from "zod";
import { evidenceBundleSummarySchema } from "../domain/evidenceRecordSummary.js";
import { BINARY_ARCHITECTURES } from "../domain/binaryTargetTypes.js";
+import {
+ binaryArchitectureSchema,
+ rawBinaryEntryPointSchema,
+} from "../domain/rawBinary.js";
import { nativeFunctionAnnotationsSchema } from "../domain/native/nativeFunctionAnnotations.js";
import { nativeLoadImageSchema } from "../domain/native/nativeLoadImage.js";
import { nativeUiResultSchema } from "../domain/native/nativeUiObservation.js";
@@ -409,16 +413,33 @@ export const managedWorkflowOutputSchemas: Readonly<
),
};
+const lifecycleTargetFields = {
+ path: z.string(),
+ kind: targetKindSchema,
+ sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+ architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
+};
+const detectedLifecycleTargetSchema = z.object({
+ ...lifecycleTargetFields,
+ format: targetFormatSchema.exclude(["raw-binary"]),
+});
+const rawLifecycleTargetSchema = z.object({
+ ...lifecycleTargetFields,
+ format: z.literal("raw-binary"),
+ kind: z.literal("executable"),
+ architecture: binaryArchitectureSchema,
+ entry_point: rawBinaryEntryPointSchema.describe(
+ "Canonical caller-selected address where raw file offset 0 is mapped and execution is seeded.",
+ ),
+});
+
/** Exact structured-content schemas for target lifecycle operations. */
export const sessionOutputSchemas = {
open_binary: lifecycleResultOf(
- z.object({
- path: z.string(),
- format: targetFormatSchema,
- kind: targetKindSchema,
- sha256: z.string().regex(/^[a-f0-9]{64}$/u),
- architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
- }),
+ z.discriminatedUnion("format", [
+ detectedLifecycleTargetSchema,
+ rawLifecycleTargetSchema,
+ ]),
),
close_binary: lifecycleResultOf(
z.union([
@@ -448,19 +469,15 @@ export const sessionOutputSchemas = {
),
binary_session: lifecycleResultOf(
z.union([
- z.union([
- sessionProvider.extend({
- open: z.literal(false),
- }),
- sessionProvider.extend({
- open: z.literal(true),
- path: z.string(),
- format: targetFormatSchema,
- kind: targetKindSchema,
- sha256: z.string().regex(/^[a-f0-9]{64}$/u),
- architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
- }),
- ]),
+ sessionProvider.extend({ open: z.literal(false) }),
+ sessionProvider.extend({
+ open: z.literal(true),
+ ...detectedLifecycleTargetSchema.shape,
+ }),
+ sessionProvider.extend({
+ open: z.literal(true),
+ ...rawLifecycleTargetSchema.shape,
+ }),
]),
),
export_evidence_bundle: lifecycleResultOf(
diff --git a/src/contracts/toolOutputSchemaPrimitives.ts b/src/contracts/toolOutputSchemaPrimitives.ts
index 224245c37..1c4d449c8 100644
--- a/src/contracts/toolOutputSchemaPrimitives.ts
+++ b/src/contracts/toolOutputSchemaPrimitives.ts
@@ -56,6 +56,7 @@ export const targetFormatSchema = z.enum([
"pe",
"dos-mz",
"dos-com",
+ "raw-binary",
"zip",
"ipa",
"apk",
diff --git a/src/domain/analysisErrorPresentation.ts b/src/domain/analysisErrorPresentation.ts
index 07b226947..b0e81e54e 100644
--- a/src/domain/analysisErrorPresentation.ts
+++ b/src/domain/analysisErrorPresentation.ts
@@ -66,7 +66,7 @@ export const analysisErrorRemediationAction = (
if (error instanceof HopperRemoteError)
return error.diagnosticType === "invalid_request"
? "Correct the reported address, document, or arguments and retry."
- : "Review the Hopper diagnostic details; correct the request or retry if the failure was transient.";
+ : "Review the Hopper diagnostic details and correct the request or target; run `rea doctor` if the provider itself is failing. Repeating the unchanged request is not expected to succeed.";
if (error instanceof EvidenceReferenceError)
return "Use an exact Evidence reference retained by this session, supply the complete inline Evidence, re-run its producer, or import its Evidence bundle. close_binary clears retained records.";
if (
@@ -282,7 +282,7 @@ const hopperProcessMessage = (error: HopperProcessError): string => {
const standardErrorMessage = (tag: AnalysisErrorTag): string | undefined => {
if (UNREADABLE_OUTPUT_TAGS.has(tag))
- return "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.";
+ return "Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.";
if (UNSUPPORTED_PROVIDER_TAGS.has(tag))
return "This analysis is unavailable for the current target. Choose another analysis or target.";
if (CANCELLED_TAGS.has(tag))
@@ -290,7 +290,7 @@ const standardErrorMessage = (tag: AnalysisErrorTag): string | undefined => {
if (TIMEOUT_TAGS.has(tag))
return "Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.";
if (ADAPTER_FAILURE_TAGS.has(tag))
- return "Analysis could not complete. Retry once; if it continues, run `rea doctor`.";
+ return "Analysis could not complete. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.";
if (START_FAILURE_TAGS.has(tag))
return "Analysis could not start or stopped unexpectedly. Run `rea doctor`, then try again.";
return undefined;
diff --git a/src/domain/analysisErrorProjection.test.ts b/src/domain/analysisErrorProjection.test.ts
index 66fa06914..635d5c021 100644
--- a/src/domain/analysisErrorProjection.test.ts
+++ b/src/domain/analysisErrorProjection.test.ts
@@ -384,6 +384,38 @@ describe("analysis error projection: provider failures", () => {
});
});
+describe("analysis error projection: retry guidance", () => {
+ it.each([
+ [
+ "unreadable output",
+ new AnalysisOutputError("inspect_firmware_regions", "report missing"),
+ "unreadable_output",
+ ],
+ [
+ "adapter failure",
+ new ProviderAdapterError("firmware", "inspect_firmware_regions"),
+ "execution_failure",
+ ],
+ [
+ "Hopper remote failure",
+ new HopperRemoteError(7, "Hopper analysis failed", {
+ diagnosticType: "bridge_exception",
+ operation: "trace_feature",
+ }),
+ "execution_failure",
+ ],
+ ])(
+ "does not recommend an unchanged retry for non-retryable %s",
+ (_name, error, code) => {
+ const projected = projectAnalysisError(error);
+
+ expect(projected).toMatchObject({ code, retryable: false });
+ for (const text of [projected.message, projected.remediation.action])
+ expect(text).not.toMatch(/\bretry\b/iu);
+ },
+ );
+});
+
describe("analysis error projection: caller contract", () => {
it("preserves the reported output constraint without exposing its internal cause", () => {
const projected = projectAnalysisError(
diff --git a/src/domain/analysisSnapshot.test.ts b/src/domain/analysisSnapshot.test.ts
index 00f34684f..e2c1483c9 100644
--- a/src/domain/analysisSnapshot.test.ts
+++ b/src/domain/analysisSnapshot.test.ts
@@ -8,6 +8,7 @@ import {
snapshotBinding,
snapshotEvidenceForQuery,
snapshotTarget,
+ snapshotMatchesTarget,
} from "./analysisSnapshot.js";
import {
ANALYSIS_SNAPSHOT_PROFILE,
@@ -16,6 +17,7 @@ import {
} from "./analysisSnapshot.fixture.js";
import { createEvidence } from "./evidence.js";
import { createEvidenceBundle } from "./evidenceBundle.js";
+import type { BinaryTarget } from "./binaryTargetTypes.js";
const snapshotWithHistoricalEvidence = () => {
const target = snapshotTarget(ANALYSIS_SNAPSHOT_TARGET);
@@ -68,6 +70,54 @@ const snapshotWithHistoricalEvidence = () => {
};
describe("analysis snapshot contract", () => {
+ it("partitions raw snapshots and query identities by the canonical entry", () => {
+ const target: BinaryTarget = {
+ path: "/fixture/image.bin",
+ sha256: ANALYSIS_SNAPSHOT_TARGET.sha256,
+ kind: "executable",
+ format: "raw-binary",
+ architecture: "arm",
+ availableArchitectures: ["arm"],
+ entryPoint: "0x8000000",
+ entryPointSource: "0x08000000",
+ };
+ const snapshot = snapshotTarget(target);
+ const binding = snapshotBinding(ANALYSIS_SNAPSHOT_PROFILE);
+ const changed = {
+ ...target,
+ entryPoint: "0x9000000",
+ entryPointSource: "0x09000000",
+ };
+ expect(
+ snapshotMatchesTarget(snapshot, {
+ ...target,
+ entryPointSource: "0x8000000",
+ }),
+ ).toBe(true);
+ expect(snapshotMatchesTarget(snapshot, changed)).toBe(false);
+ expect(analysisQueryId(snapshot, binding, "list_procedures", {})).not.toBe(
+ analysisQueryId(snapshotTarget(changed), binding, "list_procedures", {}),
+ );
+ const parsed = analysisSnapshotSchema.parse({
+ target: snapshot,
+ binding,
+ entries: [],
+ workflow_entries: [],
+ evidence_bundle: createEvidenceBundle([]),
+ });
+ expect(parsed.target).toHaveProperty("entry_point", target.entryPoint);
+ const { entry_point: _entry, ...legacy } = {
+ ...snapshot,
+ entry_point: target.entryPoint,
+ };
+ expect(
+ analysisSnapshotSchema.safeParse({ ...parsed, target: legacy }).success,
+ ).toBe(false);
+ expect(snapshotTarget(ANALYSIS_SNAPSHOT_TARGET)).not.toHaveProperty(
+ "entry_point",
+ );
+ });
+
it("preserves DOS MZ target and subject formats with the x86 family", () => {
const target = {
path: ANALYSIS_SNAPSHOT_TARGET.path,
@@ -113,6 +163,37 @@ describe("analysis snapshot contract", () => {
expect(parsed.evidence_bundle.records[0]?.subject?.format).toBe("dos-mz");
});
+ it("rejects a snapshot subject path containing NUL", () => {
+ const binding = snapshotBinding(ANALYSIS_SNAPSHOT_PROFILE);
+ const entry = {
+ query_id: `query_${"0".repeat(64)}`,
+ operation: "analyze_function",
+ parameters: {},
+ execution: {
+ result: null,
+ raw_result: null,
+ provider: binding.provider,
+ limitations: [],
+ locations: [],
+ subject: {
+ path: "a\u0000b",
+ sha256: "a".repeat(64),
+ format: "elf" as const,
+ architecture: null,
+ },
+ },
+ };
+ expect(
+ analysisSnapshotSchema.safeParse({
+ target: snapshotTarget(ANALYSIS_SNAPSHOT_TARGET),
+ binding,
+ entries: [entry],
+ workflow_entries: [],
+ evidence_bundle: createEvidenceBundle([]),
+ }).success,
+ ).toBe(false);
+ });
+
it("accepts snapshots with more than ten thousand analysis entries", () => {
const binding = snapshotBinding(ANALYSIS_SNAPSHOT_PROFILE);
const entry = {
diff --git a/src/domain/analysisSnapshot.ts b/src/domain/analysisSnapshot.ts
index a60b70524..d6ca67e85 100644
--- a/src/domain/analysisSnapshot.ts
+++ b/src/domain/analysisSnapshot.ts
@@ -7,6 +7,7 @@ import {
compareUnicodeCodePoints,
compositeKey,
} from "./unicodeCodePointOrder.js";
+import { localPathStringSchema } from "./localPath.js";
import {
analysisProfileSchema,
@@ -39,6 +40,7 @@ import { digestSchema } from "./../domain/digests.js";
import { prefixedDigestSchema } from "./../domain/digests.js";
import { canonicalJsonDigestSteps } from "./canonicalJsonDigestSteps.js";
import { freezeJsonSnapshot } from "./immutableJson.js";
+import { rawBinaryEntryPointSchema } from "./rawBinary.js";
const architectureSchema = z.enum(BINARY_ARCHITECTURES);
const formatSchema = z.enum([
@@ -48,6 +50,7 @@ const formatSchema = z.enum([
"pe",
"dos-mz",
"dos-com",
+ "raw-binary",
"zip",
"ipa",
"apk",
@@ -65,7 +68,7 @@ const formatSchema = z.enum([
]);
const kindSchema = z.enum(["executable", "database", "archive", "artifact"]);
const subjectSchema = z.object({
- path: z.string().min(1),
+ path: localPathStringSchema,
sha256: digestSchema,
format: z.enum([
...formatSchema.options,
@@ -79,12 +82,22 @@ const subjectSchema = z.object({
]),
architecture: architectureSchema.nullable(),
});
-const targetSchema = z.object({
+const targetIdentitySchema = z.object({
sha256: digestSchema,
kind: kindSchema,
- format: formatSchema,
architecture: architectureSchema.nullable(),
});
+const targetSchema = z.discriminatedUnion("format", [
+ targetIdentitySchema.extend({
+ format: z.enum(
+ formatSchema.options.filter((format) => format !== "raw-binary"),
+ ),
+ }),
+ targetIdentitySchema.extend({
+ format: z.literal("raw-binary"),
+ entry_point: rawBinaryEntryPointSchema,
+ }),
+]);
const bindingSchema = z
.object({
provider: committedProviderSchema,
@@ -310,12 +323,16 @@ const canonicalJson = (value: unknown): string => {
/** Project a binary into the path-free identity used for cache invalidation. */
export const snapshotTarget = (
target: BinaryTarget,
-): AnalysisSnapshotTarget => ({
- sha256: target.sha256,
- kind: target.kind,
- format: target.format,
- architecture: target.architecture ?? null,
-});
+): AnalysisSnapshotTarget => {
+ const identity = {
+ sha256: target.sha256,
+ kind: target.kind,
+ architecture: target.architecture ?? null,
+ };
+ return target.format === "raw-binary"
+ ? { ...identity, format: target.format, entry_point: target.entryPoint }
+ : { ...identity, format: target.format };
+};
/** Build the immutable provider/profile binding used by a cached snapshot. */
export const snapshotBinding = (
@@ -334,7 +351,10 @@ export const snapshotMatchesTarget = (
snapshot.sha256 === target.sha256 &&
snapshot.kind === target.kind &&
snapshot.format === target.format &&
- snapshot.architecture === (target.architecture ?? null);
+ snapshot.architecture === (target.architecture ?? null) &&
+ (snapshot.format !== "raw-binary" ||
+ (target.format === "raw-binary" &&
+ snapshot.entry_point === target.entryPoint));
/** Compare a snapshot binding with the selected concrete analysis profile. */
export const snapshotMatchesProfile = (
diff --git a/src/domain/artifactGraph.ts b/src/domain/artifactGraph.ts
index 8b5d763eb..a3f301c09 100644
--- a/src/domain/artifactGraph.ts
+++ b/src/domain/artifactGraph.ts
@@ -50,6 +50,7 @@ const artifactFormatSchema = z.enum([
"pe",
"dos-mz",
"dos-com",
+ "raw-binary",
"hopper",
"analysis-database",
"ipa",
diff --git a/src/domain/binaryTargetTypes.ts b/src/domain/binaryTargetTypes.ts
index 9296109cd..5d7deba68 100644
--- a/src/domain/binaryTargetTypes.ts
+++ b/src/domain/binaryTargetTypes.ts
@@ -78,6 +78,13 @@ export type BinaryTarget =
readonly executableRole?: never;
readonly managed?: never;
})
+ | (ExecutableTarget & {
+ readonly format: "raw-binary";
+ readonly entryPoint: string;
+ readonly entryPointSource: string;
+ readonly executableRole?: never;
+ readonly managed?: never;
+ })
| (ExecutableTarget & {
readonly format: "pe";
/** Provider-neutral PE image role observed from COFF characteristics. */
diff --git a/src/domain/dosCom.ts b/src/domain/dosCom.ts
index 4139e14dc..1e6b0a747 100644
--- a/src/domain/dosCom.ts
+++ b/src/domain/dosCom.ts
@@ -1,8 +1,8 @@
import { z } from "zod";
import { err, ok, type Result } from "./result.js";
-/** Headerless DOS COM interpretation explicitly selected by the caller. */
-export const executableFormatHintSchema = z.literal("dos-com");
+/** Headerless executable interpretation explicitly selected by the caller. */
+export const executableFormatHintSchema = z.enum(["dos-com", "raw-binary"]);
/** Explicit executable interpretation for formats with no identifying header. */
export type ExecutableFormatHint = z.infer;
diff --git a/src/domain/evidence.test.ts b/src/domain/evidence.test.ts
index 9a129d7b6..fc2f19921 100644
--- a/src/domain/evidence.test.ts
+++ b/src/domain/evidence.test.ts
@@ -291,6 +291,22 @@ describe("analysis evidence identity", () => {
});
});
+it("rejects a subject local path containing NUL while admitting an empty path", () => {
+ const evidence = createEvidence(TARGET, PROVIDER, {
+ operation: "health",
+ parameters: {},
+ result: true,
+ });
+ expect(evidence.subject).not.toBeNull();
+ const withPath = (path: string) => ({
+ ...evidence,
+ subject: { ...evidence.subject, local_path: path },
+ });
+ expect(evidenceSchema.safeParse(withPath("/tmp/fixture")).success).toBe(true);
+ expect(evidenceSchema.safeParse(withPath("")).success).toBe(true);
+ expect(evidenceSchema.safeParse(withPath("a\u0000b")).success).toBe(false);
+});
+
it("binds an explicit unknown-subject reason into the semantic Evidence identity", () => {
const reason = "Caller excluded the observed digest.";
const observation = { operation: "health", parameters: {}, result: true };
diff --git a/src/domain/evidence.ts b/src/domain/evidence.ts
index 8aa6d4c65..8edb9c897 100644
--- a/src/domain/evidence.ts
+++ b/src/domain/evidence.ts
@@ -2,6 +2,7 @@ import { z } from "zod";
import { digestCanonicalValue } from "./canonicalDigest.js";
import { canonicalJsonDigestSteps } from "./canonicalJsonDigestSteps.js";
+import { nulFreeStringSchema } from "./localPath.js";
import {
analysisProfileSchema,
@@ -43,6 +44,7 @@ const subjectSchema = z.object({
"pe",
"dos-mz",
"dos-com",
+ "raw-binary",
"zip",
"ipa",
"apk",
@@ -65,7 +67,7 @@ const subjectSchema = z.object({
"entitlements",
]),
architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
- local_path: z.string(),
+ local_path: nulFreeStringSchema,
});
/** Source location attached to an evidence observation. */
/** Source-location schema shared by evidence-bearing persistence formats. */
diff --git a/src/domain/localPath.ts b/src/domain/localPath.ts
index d3d200189..789803a21 100644
--- a/src/domain/localPath.ts
+++ b/src/domain/localPath.ts
@@ -2,7 +2,9 @@ import { isAbsolute, relative, sep } from "node:path";
import { z } from "zod";
/**
- * Preserve selected filesystem names while rejecting OS-invalid NUL bytes.
+ * Reject OS-invalid NUL bytes in a local filesystem name. This is not a path
+ * shape check: an empty or relative value is admitted here and narrowed by the
+ * callers that need a nonempty or absolute path.
*
* The pattern spells NUL as `\x00` rather than `\u0000`. Both accept exactly the
* same strings. The hex form also avoids the short `\0` spelling rejected by
@@ -10,11 +12,13 @@ import { z } from "zod";
* one advertised pattern cannot compile. See `offsetDateTimeSchema` for the
* same hex-escape convention.
*/
-export const localPathStringSchema = z
+export const nulFreeStringSchema = z
.string()
- .min(1)
.regex(/^[^\x00]*$/u, "Local filesystem paths cannot contain NUL");
+/** A selected local filesystem path: nonempty and free of NUL bytes. */
+export const localPathStringSchema = nulFreeStringSchema.min(1);
+
/** Test lexical containment on the host platform; callers must resolve symlinks first. */
export const isPathWithinRoot = (root: string, path: string): boolean => {
const value = relative(root, path);
diff --git a/src/domain/native/nativeLoadImage.ts b/src/domain/native/nativeLoadImage.ts
index 568a0de25..6a3be4421 100644
--- a/src/domain/native/nativeLoadImage.ts
+++ b/src/domain/native/nativeLoadImage.ts
@@ -84,7 +84,7 @@ export const nativeLoadImageCheckSchema = z.strictObject({
});
/** Read-only native image verification; verified applies only to declared coverage. */
-export const nativeLoadImageSchema = z.discriminatedUnion("status", [
+export const nativeLoadImageSchema = z.union([
z.strictObject({
status: z.literal("unsupported"),
reason: z.string().min(1),
@@ -108,6 +108,23 @@ export const nativeLoadImageSchema = z.discriminatedUnion("status", [
checks: z.array(nativeLoadImageCheckSchema),
limitations: z.array(z.string().min(1)),
}),
+ z.strictObject({
+ status: z.enum(["verified", "mismatch"]),
+ format: z.literal("raw-binary"),
+ target_sha256: digest,
+ architecture: z.enum(["x86", "x86_64", "arm", "arm64"]),
+ language_id: z.string().min(1),
+ compiler_spec_id: z.string().min(1),
+ base_address: address,
+ file_bytes: integer.min(1),
+ entry: z.strictObject({
+ address: address,
+ file_offset: z.literal(0),
+ }),
+ observations: nativeLoadImageObservationSchema,
+ checks: z.array(nativeLoadImageCheckSchema),
+ limitations: z.array(z.string().min(1)),
+ }),
]);
/** Provider-neutral native load-image result. */
diff --git a/src/domain/rawBinary.test.ts b/src/domain/rawBinary.test.ts
new file mode 100644
index 000000000..ca4d7f0d6
--- /dev/null
+++ b/src/domain/rawBinary.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+
+import { executableFormatHintSchema } from "./dosCom.js";
+import {
+ admitRawBinary,
+ parseRawBinaryEntryPoint,
+ rawBinarySelectionError,
+ validateRawBinaryLength,
+} from "./rawBinary.js";
+
+describe("headerless format hints", () => {
+ it("admits dos-com and raw-binary names only", () => {
+ expect(executableFormatHintSchema.safeParse("dos-com").success).toBe(true);
+ expect(executableFormatHintSchema.safeParse("raw-binary").success).toBe(
+ true,
+ );
+ expect(executableFormatHintSchema.safeParse("raw").success).toBe(false);
+ });
+});
+
+describe("raw-binary entry addresses", () => {
+ it("canonicalizes equivalent hex spellings without dropping the source", () => {
+ const parsed = parseRawBinaryEntryPoint("0x08000000");
+ expect(parsed).toEqual({
+ ok: true,
+ value: {
+ source: "0x08000000",
+ canonical: "0x8000000",
+ value: 0x8000000n,
+ },
+ });
+ });
+ it.each(["8000000", "0x", "0xgg", "0X8000000", ""])(
+ "rejects malformed entry %s",
+ (value) => {
+ expect(parseRawBinaryEntryPoint(value).ok).toBe(false);
+ },
+ );
+});
+
+describe("raw-binary admission", () => {
+ it("admits a little-endian ARM image mapped at the caller entry", () => {
+ expect(
+ admitRawBinary({
+ architecture: "arm",
+ entryPoint: "0x8000000",
+ fileBytes: 4,
+ }),
+ ).toEqual({
+ ok: true,
+ value: {
+ architecture: "arm",
+ entryPoint: "0x8000000",
+ entryPointSource: "0x8000000",
+ },
+ });
+ });
+ it("rejects an empty file", () => {
+ expect(validateRawBinaryLength(0).ok).toBe(false);
+ expect(
+ admitRawBinary({
+ architecture: "x86",
+ entryPoint: "0x1000",
+ fileBytes: 0,
+ }).ok,
+ ).toBe(false);
+ });
+ it("rejects a 32-bit mapping that exceeds the architecture width", () => {
+ const result = admitRawBinary({
+ architecture: "arm",
+ entryPoint: "0xfffffffc",
+ fileBytes: 8,
+ });
+ expect(result.ok).toBe(false);
+ if (result.ok) throw new Error("expected overflow rejection");
+ expect(result.error).toContain("arm address width");
+ });
+ it("allows a 64-bit mapping that would overflow 32-bit ARM", () => {
+ expect(
+ admitRawBinary({
+ architecture: "arm64",
+ entryPoint: "0xfffffffc",
+ fileBytes: 8,
+ }).ok,
+ ).toBe(true);
+ });
+ it.each(["arm", "arm64"])(
+ "rejects unaligned %s entries before provider selection",
+ (architecture) => {
+ for (const entryPoint of ["0x8000001", "0x8000002", "0x8000003"]) {
+ expect(
+ admitRawBinary({ architecture, entryPoint, fileBytes: 4 }),
+ ).toEqual({
+ ok: false,
+ error: `raw-binary ${architecture} entry_point ${entryPoint} must be 4-byte aligned`,
+ });
+ }
+ },
+ );
+ it.each(["x86", "x86_64"])(
+ "admits byte-aligned %s entries",
+ (architecture) => {
+ const admitted = admitRawBinary({
+ architecture,
+ entryPoint: "0x1001",
+ fileBytes: 1,
+ });
+ if (!admitted.ok) throw new Error(admitted.error);
+ expect(admitted.value.entryPoint).toBe("0x1001");
+ },
+ );
+});
+
+describe("raw-binary selection pairing", () => {
+ it("requires architecture and entry with format=raw-binary", () => {
+ expect(rawBinarySelectionError({ format: "raw-binary" })).toBe(
+ "format=raw-binary requires architecture and entry_point",
+ );
+ expect(
+ rawBinarySelectionError({
+ format: "raw-binary",
+ architecture: "arm",
+ entryPoint: "0x8000000",
+ }),
+ ).toBeUndefined();
+ });
+ it("rejects architecture or entry without format=raw-binary", () => {
+ expect(
+ rawBinarySelectionError({ architecture: "arm", entryPoint: "0x1" }),
+ ).toBe("architecture and entry_point apply only with format=raw-binary");
+ expect(
+ rawBinarySelectionError({ format: "dos-com", architecture: "x86" }),
+ ).toBe("architecture and entry_point apply only with format=raw-binary");
+ });
+});
diff --git a/src/domain/rawBinary.ts b/src/domain/rawBinary.ts
new file mode 100644
index 000000000..a389bf7c3
--- /dev/null
+++ b/src/domain/rawBinary.ts
@@ -0,0 +1,123 @@
+import { z } from "zod";
+
+import type { BinaryArchitecture } from "./binaryTargetTypes.js";
+import type { ExecutableFormatHint } from "./dosCom.js";
+import { err, ok, type Result } from "./result.js";
+
+/** Caller-visible CPU families admitted for headerless raw binaries. */
+export const BINARY_ARCHITECTURES = [
+ "x86",
+ "x86_64",
+ "arm",
+ "arm64",
+] as const satisfies readonly BinaryArchitecture[];
+
+/** Provider-neutral CPU family for a caller-supplied raw-binary load. */
+export const binaryArchitectureSchema = z.enum(BINARY_ARCHITECTURES);
+
+const RAW_BINARY_ENTRY_POINT = /^0x[0-9A-Fa-f]{1,16}$/u;
+
+/** Hexadecimal load and entry address; file offset 0 is mapped here. */
+export const rawBinaryEntryPointSchema = z
+ .string()
+ .regex(RAW_BINARY_ENTRY_POINT, {
+ message: "entry_point must be a hexadecimal address of the form 0x…",
+ });
+
+/** Canonicalized caller-supplied raw-binary entry with the original spelling. */
+export interface CanonicalRawBinaryEntry {
+ readonly source: string;
+ readonly canonical: string;
+ readonly value: bigint;
+}
+
+/** Parse a caller-supplied hex entry while preserving the source spelling. */
+export const parseRawBinaryEntryPoint = (
+ value: string,
+): Result => {
+ if (!RAW_BINARY_ENTRY_POINT.test(value))
+ return err("entry_point must be a hexadecimal address of the form 0x…");
+ const parsed = BigInt(value);
+ return ok({
+ source: value,
+ canonical: `0x${parsed.toString(16)}`,
+ value: parsed,
+ });
+};
+
+/** Reject empty or non-integral file extents for a headerless image. */
+export const validateRawBinaryLength = (
+ length: number,
+): Result =>
+ Number.isSafeInteger(length) && length >= 1
+ ? ok(null)
+ : err("raw-binary requires at least one file byte");
+
+/** Admitted headerless load identity used by target resolution and profiles. */
+export interface RawBinaryAdmission {
+ readonly architecture: Exclude;
+ readonly entryPoint: string;
+ readonly entryPointSource: string;
+}
+
+const addressWidth = (architecture: BinaryArchitecture): bigint =>
+ architecture === "x86" || architecture === "arm"
+ ? 0xffffffffn
+ : 0xffffffffffffffffn;
+
+/** Validate architecture, entry, and that the mapped image fits the CPU width. */
+export const admitRawBinary = (input: {
+ readonly architecture: unknown;
+ readonly entryPoint: unknown;
+ readonly fileBytes: number;
+}): Result => {
+ const architecture = binaryArchitectureSchema.safeParse(input.architecture);
+ if (!architecture.success)
+ return err(
+ "raw-binary format requires architecture (x86, x86_64, arm, or arm64)",
+ );
+ if (typeof input.entryPoint !== "string")
+ return err(
+ "raw-binary format requires entry_point as a hexadecimal address of the form 0x…",
+ );
+ const entry = parseRawBinaryEntryPoint(input.entryPoint);
+ if (!entry.ok) return entry;
+ if (
+ (architecture.data === "arm" || architecture.data === "arm64") &&
+ entry.value.value % 4n !== 0n
+ )
+ return err(
+ `raw-binary ${architecture.data} entry_point ${entry.value.canonical} must be 4-byte aligned`,
+ );
+ const length = validateRawBinaryLength(input.fileBytes);
+ if (!length.ok) return length;
+ const last = entry.value.value + BigInt(input.fileBytes) - 1n;
+ const max = addressWidth(architecture.data);
+ if (entry.value.value > max || last > max)
+ return err(
+ `raw-binary mapping from ${entry.value.canonical} must fit in the ${architecture.data} address width`,
+ );
+ return ok({
+ architecture: architecture.data,
+ entryPoint: entry.value.canonical,
+ entryPointSource: entry.value.source,
+ });
+};
+
+/** Describe the format/architecture/entry pairing without performing I/O. */
+export const rawBinarySelectionError = (input: {
+ readonly format?: ExecutableFormatHint;
+ readonly architecture?: unknown;
+ readonly entryPoint?: unknown;
+}): string | undefined => {
+ const hasArchitecture = input.architecture !== undefined;
+ const hasEntry = input.entryPoint !== undefined;
+ if (input.format === "raw-binary") {
+ if (!hasArchitecture || !hasEntry)
+ return "format=raw-binary requires architecture and entry_point";
+ return undefined;
+ }
+ if (hasArchitecture || hasEntry)
+ return "architecture and entry_point apply only with format=raw-binary";
+ return undefined;
+};
diff --git a/src/generatedPackageMetadata.ts b/src/generatedPackageMetadata.ts
index b4795e7d8..00d5f109f 100644
--- a/src/generatedPackageMetadata.ts
+++ b/src/generatedPackageMetadata.ts
@@ -5,5 +5,5 @@ export const PACKAGE_METADATA = {
serverSdkVersion: "2.3.1",
clientSdkVersion: "2.3.1",
coreSdkVersion: "2.3.1",
- skillVersion: "38",
+ skillVersion: "39",
} as const;
diff --git a/src/ghidra/GhidraAnalysisProfile.ts b/src/ghidra/GhidraAnalysisProfile.ts
index a057ce4ba..259b89285 100644
--- a/src/ghidra/GhidraAnalysisProfile.ts
+++ b/src/ghidra/GhidraAnalysisProfile.ts
@@ -14,6 +14,7 @@ import type { AnalysisError } from "../domain/analysisErrorBase.js";
import { err, ok, type Result } from "../domain/result.js";
import type { GhidraInstallationInspection } from "./GhidraInstallation.js";
import { ghidraMipsProfileParameters } from "./GhidraMipsProfile.js";
+import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js";
import {
ghidraProcessorUnsupportedReason,
@@ -69,6 +70,57 @@ export const resolveGhidraAnalysisProfile = async (
: null;
if (pspExtension !== null && !pspExtension.ok) return pspExtension;
const provider = { ...identity, version: installation.providerVersion };
+ if (target.format === "raw-binary") {
+ if (languageOverride !== undefined)
+ return Promise.resolve(
+ err(
+ new AnalysisUnsupportedTargetError(
+ "resolve_analysis_profile",
+ target.path,
+ "REA_GHIDRA_LANGUAGE_ID cannot override the admitted raw-binary import.",
+ ),
+ ),
+ );
+ const language = ghidraRawBinaryLanguage(target.architecture);
+ return Promise.resolve(
+ ok({
+ profile: createAnalysisProfile(provider, {
+ target_kind: target.kind,
+ target_format: target.format,
+ architecture: target.architecture,
+ available_architectures: [...target.availableArchitectures].sort(),
+ import_mode: "ephemeral-source-immutable",
+ annotation_policy: "atomic-function-entry-metadata-v1",
+ load_image_observations: "source-mappings-entry-context-v2",
+ function_body_evidence: "complete-inclusive-ranges-v1",
+ function_references: "complete-body-and-entry-reference-manager-v2",
+ string_inventory_evidence: "defined-data-coverage-v1",
+ location_resolution: "explicit-address-exact-entry-symbol-first-v3",
+ instruction_flow_evidence: "decoded-return-pcode-v1",
+ instruction_references: "exact-address-incoming-v1",
+ function_boundary_observations: "ghidra-terminal-call-limitations-v1",
+ no_return_repair:
+ installation.platform === "win32"
+ ? "disabled-windows-p0"
+ : "returning-imports-decoded-return-v2",
+ process_launch:
+ installation.platform === "win32"
+ ? "official-headless-script-v1"
+ : "inspected-jvm-launch-support-v1",
+ load_image_evidence: "independent-raw-mapping-context-v2",
+ jump_table_evidence: "typed-case-default-blocks-v1",
+ decompiler_jump_loads: true,
+ loader: "BinaryLoader",
+ language_id: language.languageId,
+ compiler_spec_id: language.compilerSpecId,
+ language_selection: "caller-supplied-v1",
+ entry_point: target.entryPoint,
+ entry_seed: "external-entry-and-function-before-analysis-v1",
+ analyzer_preset: "ghidra-default",
+ }),
+ }),
+ );
+ }
const dosMz = target.format === "dos-mz";
const dosCom = target.format === "dos-com";
const dos = dosMz || dosCom;
diff --git a/src/ghidra/GhidraClient.ts b/src/ghidra/GhidraClient.ts
index ad35b3569..f2ccd381d 100644
--- a/src/ghidra/GhidraClient.ts
+++ b/src/ghidra/GhidraClient.ts
@@ -1,5 +1,8 @@
-import { randomBytes, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import type { Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
import type { Socket } from "node:net";
+import type { ProgressReporter } from "../application/ProgressReporter.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import type { JsonValue } from "../domain/jsonValue.js";
@@ -42,11 +45,12 @@ import {
type GhidraSessionInfo,
} from "./GhidraSessionValues.js";
import { createGhidraTargetSnapshot } from "./GhidraTargetSnapshot.js";
-import { readFile } from "node:fs/promises";
+import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
import {
openRegularFile,
RegularFileChangedError,
+ RegularFileAdmissionFailure,
sameRegularFileState,
} from "../filesystem/RegularFile.js";
import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
@@ -162,7 +166,12 @@ export class GhidraClient {
}
/** Launch Ghidra once and require its exact post-analysis handshake. */
- start(signal?: AbortSignal): Promise {
+ start(
+ signal?: AbortSignal,
+ progress?: ProgressReporter,
+ ): Promise {
+ if (progress !== undefined)
+ return this.#reportStartupWait(this.start(signal), signal, progress);
if (this.#closePromise !== undefined)
return this.#closePromise.then(
() => this.start(signal),
@@ -216,6 +225,41 @@ export class GhidraClient {
return started;
}
+ async #reportStartupWait(
+ started: Promise,
+ signal: AbortSignal | undefined,
+ progress: ProgressReporter,
+ ): Promise {
+ const startedAt = performance.now();
+ let active = true;
+ let reporting = false;
+ const timer = setInterval(() => {
+ if (!active || reporting || signal?.aborted) return;
+ reporting = true;
+ void Promise.resolve()
+ .then(() => {
+ if (!active || signal?.aborted) return;
+ return progress.report({
+ phase: "ghidra_startup",
+ completed: 0,
+ total: null,
+ message: `Waiting for Ghidra startup (${String(Math.floor((performance.now() - startedAt) / 1000))}s elapsed); import, auto-analysis and bridge readiness may still be pending`,
+ });
+ })
+ // Notification failure does not release the owned startup process.
+ .catch(() => {})
+ .finally(() => {
+ reporting = false;
+ });
+ }, 10_000);
+ try {
+ return await started;
+ } finally {
+ active = false;
+ clearInterval(timer);
+ }
+ }
+
/** Revalidate live bridge, provider, run, and profile metadata. */
async ping(
options: GhidraRequestOptions = {},
@@ -231,9 +275,12 @@ export class GhidraClient {
async callTool(
operation: GhidraOperation,
parameters: Readonly>,
- options: { readonly signal?: AbortSignal } = {},
+ options: {
+ readonly signal?: AbortSignal;
+ readonly progress?: ProgressReporter;
+ } = {},
): Promise> {
- const started = await this.start(options.signal);
+ const started = await this.start(options.signal, options.progress);
if (!started.ok) return started;
return this.#requestQueue.run(
operation,
@@ -242,12 +289,66 @@ export class GhidraClient {
);
}
- /** Read the private immutable source for independent import verification. */
- async readTargetSnapshot(
+ /** Read the private immutable source for format parsers that require captured bytes. */
+ readTargetSnapshot(
maximumBytes?: number,
signal?: AbortSignal,
): Promise> {
- if (this.#snapshotPath === undefined)
+ return this.#withTargetSnapshot(async (handle, initial, path) => {
+ if (
+ maximumBytes !== undefined &&
+ (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0)
+ )
+ throw new RangeError("Snapshot byte limit must be a safe integer");
+ if (maximumBytes !== undefined && initial.size > maximumBytes)
+ return {
+ kind: "over-capacity",
+ sourceBytesAtLeast: initial.size,
+ maximumBytes,
+ };
+ const bytes = await readBoundedFileBytes(
+ handle,
+ maximumBytes ?? initial.size,
+ signal,
+ initial.size,
+ );
+ if (bytes === undefined || bytes.length !== initial.size)
+ throw new RegularFileChangedError(path);
+ return { kind: "captured", bytes };
+ }, signal);
+ }
+
+ /** Measure the complete snapshot identity without retaining its bytes in memory. */
+ hashTargetSnapshot(
+ signal?: AbortSignal,
+ ): Promise<
+ Result<
+ { readonly sha256: string; readonly bytes: number },
+ GhidraSessionError
+ >
+ > {
+ return this.#withTargetSnapshot(async (handle, initial, path) => {
+ const hash = createHash("sha256");
+ let bytes = 0;
+ for await (const chunk of readFileHandleChunks(handle, {
+ end: initial.size,
+ signal,
+ })) {
+ bytes += chunk.length;
+ if (bytes > initial.size) throw new RegularFileChangedError(path);
+ hash.update(chunk);
+ }
+ if (bytes !== initial.size) throw new RegularFileChangedError(path);
+ return { sha256: hash.digest("hex"), bytes };
+ }, signal);
+ }
+
+ async #withTargetSnapshot(
+ read: (handle: FileHandle, initial: Stats, path: string) => Promise,
+ signal?: AbortSignal,
+ ): Promise> {
+ const path = this.#snapshotPath;
+ if (path === undefined)
return err(
this.#failure(
"protocol",
@@ -255,77 +356,42 @@ export class GhidraClient {
),
);
try {
- if (maximumBytes !== undefined) {
- signal?.throwIfAborted();
- if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0)
- throw new RangeError("Snapshot byte limit must be a safe integer");
- const handle = await openRegularFile(this.#snapshotPath, {
- symlinks: "reject",
- });
- const owner = new OwnedFileHandle(handle);
- this.#snapshotOwners.add(owner);
- let result: GhidraTargetSnapshot;
- let readFailure: unknown;
- try {
- const metadata = await handle.stat();
- signal?.throwIfAborted();
- if (metadata.size > maximumBytes)
- result = {
- kind: "over-capacity",
- sourceBytesAtLeast: metadata.size,
- maximumBytes,
- };
- else {
- const bytes = await readBoundedFileBytes(
- handle,
- maximumBytes,
- signal,
- metadata.size,
- );
- signal?.throwIfAborted();
- const after = await handle.stat();
- if (
- bytes !== undefined &&
- bytes.length === metadata.size &&
- sameRegularFileState(metadata, after)
- ) {
- result = { kind: "captured", bytes };
- } else if (
- bytes === undefined &&
- after.isFile() &&
- after.size > maximumBytes
- ) {
- result = {
- kind: "over-capacity",
- sourceBytesAtLeast: after.size,
- maximumBytes,
- };
- } else {
- throw new RegularFileChangedError(this.#snapshotPath);
- }
- }
- } catch (cause: unknown) {
- readFailure = cause;
- }
- try {
- await owner.close();
- this.#snapshotOwners.delete(owner);
- } catch (closeFailure: unknown) {
- throw new AggregateError(
- readFailure === undefined
- ? [closeFailure]
- : [readFailure, closeFailure],
- "Ghidra target snapshot read or descriptor cleanup failed",
- );
- }
- if (readFailure !== undefined) throw readFailure;
- return ok(result!);
- }
- return ok({
- kind: "captured",
- bytes: await readFile(this.#snapshotPath),
+ const handle = await openRegularFile(path, {
+ symlinks: "reject",
+ signal,
});
+ const owner = new OwnedFileHandle(handle);
+ this.#snapshotOwners.add(owner);
+ let result: Result;
+ try {
+ const initial = await handle.stat();
+ signal?.throwIfAborted();
+ if (!Number.isSafeInteger(initial.size) || initial.size < 0)
+ throw new RangeError("Snapshot size must be a safe integer");
+ const value = await read(handle, initial, path);
+ signal?.throwIfAborted();
+ const after = await handle.stat();
+ signal?.throwIfAborted();
+ if (!sameRegularFileState(initial, after))
+ throw new RegularFileChangedError(path);
+ result = ok(value);
+ } catch (cause: unknown) {
+ result = err(cause);
+ }
+ try {
+ await owner.close();
+ this.#snapshotOwners.delete(owner);
+ } catch (closeFailure: unknown) {
+ throw new AggregateError(
+ result.ok ? [closeFailure] : [result.error, closeFailure],
+ "Ghidra target snapshot read or descriptor cleanup failed",
+ );
+ }
+ if (!result.ok) throw result.error;
+ return result;
} catch (cause: unknown) {
+ if (cause instanceof RegularFileAdmissionFailure)
+ this.#snapshotOwners.add(cause.owner);
return err(
this.#failure(
signal?.aborted === true ? "cancelled" : "protocol",
diff --git a/src/ghidra/GhidraLauncher.ts b/src/ghidra/GhidraLauncher.ts
index e203030e5..a6b459d83 100644
--- a/src/ghidra/GhidraLauncher.ts
+++ b/src/ghidra/GhidraLauncher.ts
@@ -101,6 +101,11 @@ export interface GhidraHeadlessLauncherOptions {
/** Select the admitted 16-bit real-mode MZ import instead of auto-detection. */
readonly dosMz?: true;
readonly dosCom?: true;
+ readonly rawBinary?: {
+ readonly languageId: string;
+ readonly compilerSpecId: string;
+ readonly baseAddr: string;
+ };
/** Explicit import language committed by the analysis profile. */
readonly languageOverride?: GhidraLanguageOverride;
/** Caller seeds committed by the analysis profile, applied before analysis. */
@@ -201,6 +206,9 @@ export class GhidraHeadlessLauncher implements GhidraLauncher {
...(this.options.dosMz === undefined
? {}
: { dosMz: this.options.dosMz }),
+ ...(this.options.rawBinary === undefined
+ ? {}
+ : { rawBinary: this.options.rawBinary }),
...(this.options.languageOverride === undefined
? {}
: { languageOverride: this.options.languageOverride }),
@@ -411,6 +419,11 @@ export interface GhidraHeadlessArgumentOptions {
readonly psp?: true;
readonly dosMz?: true;
readonly dosCom?: true;
+ readonly rawBinary?: {
+ readonly languageId: string;
+ readonly compilerSpecId: string;
+ readonly baseAddr: string;
+ };
readonly languageOverride?: GhidraLanguageOverride;
/** Canonical seed snapshot passed to the pre-analysis seed script. */
readonly seedPath?: string;
@@ -426,6 +439,7 @@ export const ghidraHeadlessArguments = (
(options.platform ?? process.platform) === "win32" ? win32 : posix;
const bridgeDirectory = scriptPath.dirname(options.bridgeScriptPath);
const override = options.languageOverride;
+ const rawBinary = options.rawBinary;
if (
options.psp === true &&
(options.dosMz === true ||
@@ -435,6 +449,10 @@ export const ghidraHeadlessArguments = (
throw new Error(
"A PSP ELF import cannot be combined with DOS or a generic Ghidra language override.",
);
+ if (options.psp === true && rawBinary !== undefined)
+ throw new Error(
+ "A PSP ELF import cannot be combined with a raw-binary import.",
+ );
if (
override !== undefined &&
(options.dosMz === true || options.dosCom === true)
@@ -442,6 +460,17 @@ export const ghidraHeadlessArguments = (
throw new Error(
"A Ghidra language override cannot be combined with a DOS import.",
);
+ if (override !== undefined && rawBinary !== undefined)
+ throw new Error(
+ "A Ghidra language override cannot be combined with a raw-binary import.",
+ );
+ if (
+ rawBinary !== undefined &&
+ (options.dosMz === true || options.dosCom === true)
+ )
+ throw new Error(
+ "A raw-binary import cannot be combined with a DOS import.",
+ );
return [
options.projectRoot,
"rea-project",
@@ -467,24 +496,35 @@ export const ghidraHeadlessArguments = (
"-cspec",
"default",
]
- : options.psp === true
- ? [
- "-loader",
- "PspElfLoader",
- "-processor",
- "Allegrex:LE:32:default",
- "-cspec",
- "default",
- ]
- : override !== undefined
+ : rawBinary === undefined
+ ? options.psp === true
? [
+ "-loader",
+ "PspElfLoader",
"-processor",
- override.languageId,
- ...(override.compilerSpecId === undefined
- ? []
- : ["-cspec", override.compilerSpecId]),
+ "Allegrex:LE:32:default",
+ "-cspec",
+ "default",
]
- : []),
+ : override !== undefined
+ ? [
+ "-processor",
+ override.languageId,
+ ...(override.compilerSpecId === undefined
+ ? []
+ : ["-cspec", override.compilerSpecId]),
+ ]
+ : []
+ : [
+ "-loader",
+ "BinaryLoader",
+ "-loader-baseAddr",
+ rawBinary.baseAddr,
+ "-processor",
+ rawBinary.languageId,
+ "-cspec",
+ rawBinary.compilerSpecId,
+ ]),
"-readOnly",
"-deleteProject",
"-log",
@@ -499,6 +539,14 @@ export const ghidraHeadlessArguments = (
scriptPath.join(bridgeDirectory, "ReaGhidraPrepareCom.java"),
]
: []),
+ ...(rawBinary === undefined
+ ? []
+ : [
+ "-preScript",
+ scriptPath.join(bridgeDirectory, "ReaGhidraPrepareRaw.java"),
+ rawBinary.languageId,
+ rawBinary.baseAddr,
+ ]),
// Seeds follow any loader preparation and precede default auto-analysis.
...(options.seedPath === undefined
? []
diff --git a/src/ghidra/GhidraLoadImageAttest.ts b/src/ghidra/GhidraLoadImageAttest.ts
index 5034cec43..b61cd4c3b 100644
--- a/src/ghidra/GhidraLoadImageAttest.ts
+++ b/src/ghidra/GhidraLoadImageAttest.ts
@@ -12,17 +12,15 @@ import { err, ok, type Result } from "../domain/result.js";
import {
attestGhidraDosComLoadImage,
attestGhidraDosLoadImage,
+ attestGhidraRawBinaryLoadImage,
} from "./GhidraLoadImageValues.js";
import type { NativeAotPeResult } from "../domain/native/nativeAotPe.js";
-import type { GhidraTargetSnapshot } from "./GhidraClient.js";
+import type { GhidraClient } from "./GhidraClient.js";
import type { GhidraSessionError } from "./GhidraSessionError.js";
-type LoadImageSnapshotClient = {
- readonly readTargetSnapshot?: (
- maximumBytes?: number,
- signal?: AbortSignal,
- ) => Promise>;
-};
+type LoadImageSnapshotClient = Partial<
+ Pick
+>;
type NativeLoadImageAttestationInput = {
readonly target: BinaryTarget;
@@ -37,7 +35,7 @@ type NativeLoadImageAttestationInput = {
const isSignalAborted = (signal: AbortSignal | undefined): boolean =>
signal?.aborted === true;
-/** Independently verify measured load-image observations for admitted DOS targets. */
+/** Independently verify measured load-image observations for admitted DOS and raw-binary targets. */
export const attestGhidraNativeLoadImage = async (
input: NativeLoadImageAttestationInput,
): Promise> => {
@@ -71,7 +69,7 @@ export const attestGhidraNativeLoadImage = async (
nativeLoadImageSchema.parse({
status: "unsupported",
reason:
- "Independent load-image verification currently supports DOS MZ and explicit DOS COM targets only.",
+ "Independent load-image verification currently supports DOS MZ, explicit DOS COM, and caller-supplied raw-binary targets only.",
observations: {
...observations,
metadata_recovery: [
@@ -98,13 +96,17 @@ export const attestGhidraNativeLoadImage = async (
);
}
}
- if (target.format !== "dos-mz" && target.format !== "dos-com") {
+ if (
+ target.format !== "dos-mz" &&
+ target.format !== "dos-com" &&
+ target.format !== "raw-binary"
+ ) {
return ok(
jsonValueSchema.parse(
nativeLoadImageSchema.parse({
status: "unsupported",
reason:
- "Independent load-image verification currently supports DOS MZ and explicit DOS COM targets only.",
+ "Independent load-image verification currently supports DOS MZ, explicit DOS COM, and caller-supplied raw-binary targets only.",
observations,
limitations: [
"Other formats expose measured mappings and source identities; no format-specific verification was performed.",
@@ -113,6 +115,33 @@ export const attestGhidraNativeLoadImage = async (
),
);
}
+ if (target.format === "raw-binary") {
+ if (client.hashTargetSnapshot === undefined)
+ return err(
+ new ProviderAdapterError("ghidra", operation, {
+ diagnostics: {
+ reason:
+ "The Ghidra client does not expose its immutable target snapshot identity for independent raw-binary load-image verification.",
+ },
+ }),
+ );
+ const snapshot = await client.hashTargetSnapshot(signal);
+ if (!snapshot.ok) return err(mapSessionError(snapshot.error));
+ if (isSignalAborted(signal))
+ return err(new AnalysisCancelledError(operation));
+ const attested = attestGhidraRawBinaryLoadImage(
+ snapshot.value,
+ target,
+ observations,
+ );
+ return attested.ok
+ ? ok(jsonValueSchema.parse(attested.value))
+ : err(
+ new ProviderAdapterError("ghidra", operation, {
+ diagnostics: { reason: attested.error },
+ }),
+ );
+ }
if (client.readTargetSnapshot === undefined)
return err(
new ProviderAdapterError("ghidra", operation, {
@@ -122,14 +151,14 @@ export const attestGhidraNativeLoadImage = async (
},
}),
);
- const snapshot = await client.readTargetSnapshot();
+ const snapshot = await client.readTargetSnapshot(undefined, signal);
if (!snapshot.ok) return err(mapSessionError(snapshot.error));
if (snapshot.value.kind !== "captured")
return err(
new ProviderAdapterError("ghidra", operation, {
diagnostics: {
reason:
- "The uncapped DOS load-image snapshot was unexpectedly not captured.",
+ "The uncapped load-image snapshot was unexpectedly not captured.",
},
}),
);
diff --git a/src/ghidra/GhidraLoadImageValues.ts b/src/ghidra/GhidraLoadImageValues.ts
index b8aec0a3d..1c80bb635 100644
--- a/src/ghidra/GhidraLoadImageValues.ts
+++ b/src/ghidra/GhidraLoadImageValues.ts
@@ -7,8 +7,10 @@ import {
} from "../domain/native/nativeLoadImage.js";
import { parseDosMzHeader, type DosMzHeader } from "../domain/dosMz.js";
import type { JsonValue } from "../domain/jsonValue.js";
+import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import { validateDosComLength } from "../domain/dosCom.js";
import { err, ok, type Result } from "../domain/result.js";
+import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js";
const sha256 = (bytes: Buffer): string =>
createHash("sha256").update(bytes).digest("hex");
@@ -325,3 +327,111 @@ export const attestGhidraDosComLoadImage = (
}),
);
};
+
+const hexAddress = (value: bigint): string => `0x${value.toString(16)}`;
+
+/** Verify a caller-supplied raw-binary mapping against measured Ghidra import facts. */
+export const attestGhidraRawBinaryLoadImage = (
+ snapshot: { readonly sha256: string; readonly bytes: number },
+ target: Extract,
+ observations: NativeLoadImageObservation,
+): Result => {
+ if (snapshot.sha256 !== target.sha256)
+ return err(
+ "Ghidra raw-binary snapshot digest does not match the admitted target",
+ );
+ const language = ghidraRawBinaryLanguage(target.architecture);
+ const base = BigInt(target.entryPoint);
+ const last = hexAddress(base + BigInt(snapshot.bytes) - 1n);
+ const checks: NativeLoadImageCheck[] = [];
+ const check = (
+ name: string,
+ expected: JsonValue,
+ observed: JsonValue,
+ fileOffset: number | null = null,
+ location: string | null = null,
+ ): void => {
+ checks.push({
+ name,
+ matched: JSON.stringify(expected) === JSON.stringify(observed),
+ expected,
+ observed,
+ file_offset: fileOffset,
+ address: location,
+ });
+ };
+ const source = observations.source_files[0];
+ const mapping = observations.mappings[0];
+ check("executable_format", "Raw Binary", observations.executable_format);
+ check("language_id", language.languageId, observations.language_id);
+ check(
+ "compiler_spec_id",
+ language.compilerSpecId,
+ observations.compiler_spec_id,
+ );
+ // BinaryLoader's block base is independent of the Program image base.
+ check("image_base", "0x0", observations.image_base);
+ check("source_file_count", 1, observations.source_files.length);
+ check("source_file_size", snapshot.bytes, source?.size ?? null);
+ check("original_file_sha256", target.sha256, source?.original_sha256 ?? null);
+ check("modified_file_sha256", target.sha256, source?.modified_sha256 ?? null);
+ check("mapping_count", 1, observations.mappings.length);
+ check(
+ "mapping.file_offset",
+ 0,
+ mapping?.file_offset ?? null,
+ 0,
+ mapping?.start ?? null,
+ );
+ check(
+ "mapping.start",
+ target.entryPoint,
+ mapping?.start ?? null,
+ 0,
+ mapping?.start ?? null,
+ );
+ check("mapping.end", last, mapping?.end ?? null, 0, mapping?.end ?? null);
+ check(
+ "mapping.length",
+ snapshot.bytes,
+ mapping?.length ?? null,
+ 0,
+ mapping?.start ?? null,
+ );
+ check(
+ "mapping.sha256",
+ snapshot.sha256,
+ mapping?.sha256 ?? null,
+ 0,
+ mapping?.start ?? null,
+ );
+ check(
+ "entry_point",
+ target.entryPoint,
+ observations.entry_points.find((entry) => entry === target.entryPoint) ??
+ null,
+ );
+ check("relocation_records", [], observations.relocations);
+ return ok(
+ nativeLoadImageSchema.parse({
+ status: checks.every((item) => item.matched) ? "verified" : "mismatch",
+ format: "raw-binary",
+ target_sha256: target.sha256,
+ architecture: target.architecture,
+ language_id: language.languageId,
+ compiler_spec_id: language.compilerSpecId,
+ base_address: target.entryPoint,
+ file_bytes: snapshot.bytes,
+ entry: { address: target.entryPoint, file_offset: 0 },
+ observations,
+ checks,
+ limitations: [
+ "Raw binary is a headerless interpretation explicitly selected by the caller, not format identification from file bytes.",
+ "Verification covers complete original/modified source identity, mapped file bytes, the caller-supplied entry, and the bound little-endian Ghidra language. File offset 0 is mapped at the entry address.",
+ "Ghidra may report additional language-defined external entries outside the mapped image. They are preserved as observations; verification requires the caller-supplied entry and does not attest other entries.",
+ "Reset vectors, memory-mapped I/O, big-endian and Thumb-only variants, and runtime boot behavior are not modeled or verified. No original executable bytes are changed.",
+ "Mapping ends are inclusive; a mismatching digest identifies its source range, not the first differing byte.",
+ ],
+ }),
+ );
+};
diff --git a/src/ghidra/GhidraProvider.behavior.test.ts b/src/ghidra/GhidraProvider.behavior.test.ts
index 759d5f559..b0b8fbd87 100644
--- a/src/ghidra/GhidraProvider.behavior.test.ts
+++ b/src/ghidra/GhidraProvider.behavior.test.ts
@@ -10,6 +10,7 @@ import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
import { describe, expect, it } from "vitest";
import { fixtureDosLoadImage } from "./GhidraLoadImage.fixture.js";
+import { fixtureRawBinaryLoadImage } from "./GhidraRawBinaryLoadImage.fixture.js";
import {
nativeAotPeDigest,
nativeAotPeFixture,
@@ -177,6 +178,50 @@ describe("Ghidra provider", () => {
});
});
+describe("Ghidra raw-binary profile", () => {
+ it("commits BinaryLoader language and caller-supplied entry", async () => {
+ const ghidra = provider();
+ const target: BinaryTarget = {
+ path: "/tmp/ecu.bin",
+ sha256: "a".repeat(64),
+ kind: "executable",
+ format: "raw-binary",
+ architecture: "arm",
+ availableArchitectures: ["arm"],
+ entryPoint: "0x8000000",
+ entryPointSource: "0x08000000",
+ };
+ expect(ghidra.inspectTargetSupport(target).status).toBe("supported");
+ const resolved = await ghidra.resolveAnalysisProfile(target);
+ expect(resolved.ok && resolved.value).toMatchObject({
+ profile: {
+ parameters: {
+ target_format: "raw-binary",
+ architecture: "arm",
+ loader: "BinaryLoader",
+ language_id: "ARM:LE:32:v7",
+ compiler_spec_id: "default",
+ language_selection: "caller-supplied-v1",
+ entry_point: "0x8000000",
+ },
+ },
+ });
+ const shifted = await ghidra.resolveAnalysisProfile({
+ ...target,
+ entryPoint: "0x8001000",
+ entryPointSource: "0x8001000",
+ });
+ expect(resolved.ok && shifted.ok).toBe(true);
+ if (!resolved.ok || !shifted.ok || resolved.value.profile === null)
+ throw new Error("expected raw-binary profiles");
+ expect(shifted.value.profile?.digest).not.toBe(
+ resolved.value.profile.digest,
+ );
+ const windows = provider({ ...installationHost(), platform: "win32" });
+ expect(windows.inspectTargetSupport(target).status).toBe("unsupported");
+ });
+});
+
describe("Ghidra Mach-O slice support", () => {
it("refuses universal targets whose selected slice cannot be enforced", () => {
const ghidra = provider();
@@ -718,6 +763,88 @@ describe("Ghidra result projection", () => {
});
describe("Ghidra measured load-image projection", () => {
+ it.each(["verified", "changed-snapshot", "cancelled"] as const)(
+ "streams raw snapshot identity and preserves %s outcomes",
+ async (state) => {
+ const fixture = fixtureRawBinaryLoadImage();
+ const controller = new AbortController();
+ const signals: (AbortSignal | undefined)[] = [];
+ const ghidra = provider(installationHost(), () => ({
+ start: () => Promise.resolve(ok(sessionInfo())),
+ callTool: (operation) => {
+ if (operation !== "inspect_native_load_image")
+ throw new Error(`unexpected operation ${operation}`);
+ return Promise.resolve(
+ ok(jsonValueSchema.parse(fixture.observation)),
+ );
+ },
+ readTargetSnapshot: () => {
+ throw new Error(
+ "raw verification must not capture the complete file",
+ );
+ },
+ hashTargetSnapshot: (signal) => {
+ signals.push(signal);
+ if (state === "cancelled") {
+ controller.abort();
+ return Promise.resolve(
+ err(
+ new GhidraSessionError(
+ "cancelled",
+ "Snapshot hashing cancelled",
+ ),
+ ),
+ );
+ }
+ return Promise.resolve(
+ ok({
+ ...fixture.snapshot,
+ ...(state === "changed-snapshot"
+ ? { sha256: "f".repeat(64) }
+ : {}),
+ }),
+ );
+ },
+ close: () => Promise.resolve(ok(null)),
+ }));
+ const resolved = await ghidra.resolveAnalysisProfile(fixture.target);
+ if (!resolved.ok) throw resolved.error;
+ if (resolved.value.profile === null)
+ throw new Error("expected raw profile");
+ const client = ghidra.createClient(
+ fixture.target,
+ resolved.value.profile,
+ );
+ try {
+ const result = await client.execute(
+ "inspect_native_load_image",
+ {},
+ { signal: controller.signal },
+ );
+ expect(signals).toEqual([controller.signal]);
+ if (state === "verified") {
+ if (!result.ok) throw result.error;
+ expect(result.value.result).toMatchObject({
+ status: "verified",
+ observations: fixture.observation,
+ });
+ } else {
+ expect(result).toMatchObject({
+ ok: false,
+ error: {
+ _tag:
+ state === "cancelled"
+ ? "AnalysisCancelledError"
+ : "ProviderAdapterError",
+ },
+ });
+ }
+ } finally {
+ await client.close();
+ }
+ },
+ );
+
it.each([
"verified",
"mismatch",
diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.ts
index dd172cd77..2c37cfd24 100644
--- a/src/ghidra/GhidraProviderClient.ts
+++ b/src/ghidra/GhidraProviderClient.ts
@@ -87,12 +87,18 @@ import {
windowsNativeAuthorityUnavailableReason,
hasWindowsNativeAuthority,
} from "../process/WindowsAuthority.js";
+import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js";
/** Production seam for exercising provider projection without a real process. */
export type GhidraProviderClientFactory = (
options: GhidraClientOptions,
) => Pick &
- Partial>;
+ Partial<
+ Pick<
+ GhidraClient,
+ "runtimeLineage" | "readTargetSnapshot" | "hashTargetSnapshot"
+ >
+ >;
type GhidraProviderClientInstance = ReturnType;
@@ -440,6 +446,10 @@ export const createGhidraProviderClient = (input: {
let extensionFailure: AnalysisError | undefined;
// Replaced by the reported outcome once the session handshake is checked.
const seedLimitations: string[] = [...ghidraSeedLimitations(seeds)];
+ const rawLanguage =
+ target.format === "raw-binary"
+ ? ghidraRawBinaryLanguage(target.architecture)
+ : undefined;
const targetLimitations = [
...(target.format === "dos-mz"
? [
@@ -447,6 +457,13 @@ export const createGhidraProviderClient = (input: {
"Static DOS analysis does not emulate BIOS, DOS interrupts, device ports, or self-modifying unpacking code. Packed targets require a separately identified unpacked artifact for original-program analysis; appended overlays are not the initialized load module.",
]
: []),
+ ...(target.format === "raw-binary"
+ ? [
+ "Headerless raw-binary analysis uses the caller-supplied architecture and entry address; file offset 0 is mapped at that address. Headers are not discovered from file bytes.",
+ "Little-endian generic Ghidra languages are used for x86, x86_64, arm, and arm64. Big-endian, Thumb-only, Cortex-M, and other processor variants are unsupported in this increment.",
+ "Static analysis does not emulate reset vectors, memory-mapped I/O, or firmware boot sequences.",
+ ]
+ : []),
...(target.kind === "executable" && target.architecture === "mips"
? (target.mips.limitations ?? [])
: []),
@@ -474,6 +491,15 @@ export const createGhidraProviderClient = (input: {
: {}),
...(target.format === "dos-mz" ? { dosMz: true } : {}),
...(target.format === "dos-com" ? { dosCom: true } : {}),
+ ...(rawLanguage === undefined || target.format !== "raw-binary"
+ ? {}
+ : {
+ rawBinary: {
+ languageId: rawLanguage.languageId,
+ compilerSpecId: rawLanguage.compilerSpecId,
+ baseAddr: target.entryPoint,
+ },
+ }),
...(languageOverride === undefined ? {} : { languageOverride }),
...(seeds === undefined ? {} : { analysisSeeds: seeds }),
platform: installation.platform,
@@ -495,13 +521,18 @@ export const createGhidraProviderClient = (input: {
expectedLanguageId: "x86:LE:16:Real Mode",
expectedCompilerSpecId: "default",
}
- : languageOverride === undefined
- ? {}
+ : rawLanguage === undefined
+ ? languageOverride === undefined
+ ? {}
+ : {
+ expectedLanguageId: languageOverride.languageId,
+ ...(languageOverride.compilerSpecId === undefined
+ ? {}
+ : { expectedCompilerSpecId: languageOverride.compilerSpecId }),
+ }
: {
- expectedLanguageId: languageOverride.languageId,
- ...(languageOverride.compilerSpecId === undefined
- ? {}
- : { expectedCompilerSpecId: languageOverride.compilerSpecId }),
+ expectedLanguageId: rawLanguage.languageId,
+ expectedCompilerSpecId: rawLanguage.compilerSpecId,
}),
...(psp
? {
@@ -573,7 +604,7 @@ export const createGhidraProviderClient = (input: {
),
);
if (operation === "health") {
- const started = await client.start(options?.signal);
+ const started = await client.start(options?.signal, options?.progress);
if (!started.ok)
return err(
projectSessionError(
@@ -596,7 +627,7 @@ export const createGhidraProviderClient = (input: {
: parseGhidraInventoryInput(operation, parameters);
if (!input.ok) return input;
if (extensions.length > 0 || seeds !== undefined) {
- const started = await client.start(options?.signal);
+ const started = await client.start(options?.signal, options?.progress);
if (!started.ok)
return err(
projectSessionError(
@@ -608,11 +639,12 @@ export const createGhidraProviderClient = (input: {
const failed = await checkExtensions(operation, started.value);
if (failed !== undefined) return err(failed);
}
- const called = await client.callTool(
- operation,
- input.value,
- options?.signal === undefined ? {} : { signal: options.signal },
- );
+ const called = await client.callTool(operation, input.value, {
+ ...(options?.signal === undefined ? {} : { signal: options.signal }),
+ ...(options?.progress === undefined
+ ? {}
+ : { progress: options.progress }),
+ });
if (!called.ok)
return err(
projectSessionError(
@@ -637,7 +669,10 @@ export const createGhidraProviderClient = (input: {
const address = input.value.address;
if (typeof address === "string") {
if (target.format === "pe" && nativeAotOwner !== undefined) {
- const started = await client.start(options?.signal);
+ const started = await client.start(
+ options?.signal,
+ options?.progress,
+ );
if (!started.ok)
return err(
projectSessionError(
diff --git a/src/ghidra/GhidraRawBinaryLanguage.ts b/src/ghidra/GhidraRawBinaryLanguage.ts
new file mode 100644
index 000000000..d63592e76
--- /dev/null
+++ b/src/ghidra/GhidraRawBinaryLanguage.ts
@@ -0,0 +1,26 @@
+import type { BinaryArchitecture } from "../domain/binaryTargetTypes.js";
+
+/** Bound Ghidra language for a caller-supplied raw-binary architecture. */
+export interface GhidraRawBinaryLanguage {
+ readonly languageId: string;
+ readonly compilerSpecId: "default";
+}
+
+/**
+ * Map the four caller-visible CPU families to little-endian generic Ghidra
+ * languages. Big-endian, Thumb-only, and Cortex-M variants are out of scope.
+ */
+export const ghidraRawBinaryLanguage = (
+ architecture: Exclude,
+): GhidraRawBinaryLanguage => {
+ switch (architecture) {
+ case "x86":
+ return { languageId: "x86:LE:32:default", compilerSpecId: "default" };
+ case "x86_64":
+ return { languageId: "x86:LE:64:default", compilerSpecId: "default" };
+ case "arm":
+ return { languageId: "ARM:LE:32:v7", compilerSpecId: "default" };
+ case "arm64":
+ return { languageId: "AARCH64:LE:64:v8A", compilerSpecId: "default" };
+ }
+};
diff --git a/src/ghidra/GhidraRawBinaryLoadImage.fixture.ts b/src/ghidra/GhidraRawBinaryLoadImage.fixture.ts
new file mode 100644
index 000000000..c25859263
--- /dev/null
+++ b/src/ghidra/GhidraRawBinaryLoadImage.fixture.ts
@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+
+import type { NativeLoadImageObservation } from "../domain/native/nativeLoadImage.js";
+import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
+
+const hash = (bytes: Buffer): string =>
+ createHash("sha256").update(bytes).digest("hex");
+
+export const fixtureRawBinaryLoadImage = (): {
+ snapshot: { sha256: string; bytes: number };
+ target: Extract;
+ observation: NativeLoadImageObservation;
+} => {
+ const bytes = Buffer.from("1eff2fe1", "hex");
+ const digest = hash(bytes);
+ return {
+ snapshot: { sha256: digest, bytes: bytes.length },
+ target: {
+ path: "/tmp/ecu.bin",
+ sha256: digest,
+ kind: "executable",
+ format: "raw-binary",
+ architecture: "arm",
+ availableArchitectures: ["arm"],
+ entryPoint: "0x8000000",
+ entryPointSource: "0x08000000",
+ },
+ observation: {
+ executable_format: "Raw Binary",
+ language_id: "ARM:LE:32:v7",
+ compiler_spec_id: "default",
+ image_base: "0x0",
+ default_address_space: "ram",
+ source_files: [
+ {
+ name: "ecu.bin",
+ size: bytes.length,
+ original_sha256: digest,
+ modified_sha256: digest,
+ },
+ ],
+ mappings: [
+ {
+ block: "ram",
+ start: "0x8000000",
+ end: "0x8000003",
+ address_space: "ram",
+ initialized: true,
+ loaded: true,
+ overlay: false,
+ length: bytes.length,
+ source_file_index: 0,
+ file_offset: 0,
+ sha256: digest,
+ },
+ ],
+ relocations: [],
+ entry_points: ["0x8000000"],
+ entry_context: [],
+ },
+ };
+};
diff --git a/src/ghidra/GhidraRawBinaryLoadImage.test.ts b/src/ghidra/GhidraRawBinaryLoadImage.test.ts
new file mode 100644
index 000000000..a20fd9642
--- /dev/null
+++ b/src/ghidra/GhidraRawBinaryLoadImage.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+
+import { attestGhidraRawBinaryLoadImage } from "./GhidraLoadImageValues.js";
+import { fixtureRawBinaryLoadImage } from "./GhidraRawBinaryLoadImage.fixture.js";
+import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js";
+
+describe("raw-binary Ghidra language binding", () => {
+ it("maps the four admitted families to little-endian generic languages", () => {
+ expect(ghidraRawBinaryLanguage("x86")).toEqual({
+ languageId: "x86:LE:32:default",
+ compilerSpecId: "default",
+ });
+ expect(ghidraRawBinaryLanguage("x86_64")).toEqual({
+ languageId: "x86:LE:64:default",
+ compilerSpecId: "default",
+ });
+ expect(ghidraRawBinaryLanguage("arm")).toEqual({
+ languageId: "ARM:LE:32:v7",
+ compilerSpecId: "default",
+ });
+ expect(ghidraRawBinaryLanguage("arm64")).toEqual({
+ languageId: "AARCH64:LE:64:v8A",
+ compilerSpecId: "default",
+ });
+ });
+});
+
+describe("raw-binary independent load-image checks", () => {
+ it("verifies mapped bytes at the caller-supplied entry", () => {
+ const f = fixtureRawBinaryLoadImage();
+ const result = attestGhidraRawBinaryLoadImage(
+ f.snapshot,
+ f.target,
+ f.observation,
+ );
+ expect(result).toMatchObject({
+ ok: true,
+ value: {
+ status: "verified",
+ format: "raw-binary",
+ architecture: "arm",
+ language_id: "ARM:LE:32:v7",
+ base_address: "0x8000000",
+ file_bytes: 4,
+ entry: { address: "0x8000000", file_offset: 0 },
+ },
+ });
+ });
+ it("retains mismatch evidence for a drifted language", () => {
+ const f = fixtureRawBinaryLoadImage();
+ f.observation.language_id = "x86:LE:32:default";
+ const result = attestGhidraRawBinaryLoadImage(
+ f.snapshot,
+ f.target,
+ f.observation,
+ );
+ expect(result).toMatchObject({
+ ok: true,
+ value: { status: "mismatch", observations: f.observation },
+ });
+ });
+ it("preserves additional language entries while requiring the caller entry", () => {
+ const f = fixtureRawBinaryLoadImage();
+ f.observation.entry_points = ["0x0", f.target.entryPoint, "0xffff0000"];
+ expect(
+ attestGhidraRawBinaryLoadImage(f.snapshot, f.target, f.observation),
+ ).toMatchObject({
+ ok: true,
+ value: { status: "verified", observations: f.observation },
+ });
+ f.observation.entry_points = ["0x0", "0xffff0000"];
+ expect(
+ attestGhidraRawBinaryLoadImage(f.snapshot, f.target, f.observation),
+ ).toMatchObject({
+ ok: true,
+ value: {
+ status: "mismatch",
+ checks: expect.arrayContaining([
+ expect.objectContaining({
+ name: "entry_point",
+ matched: false,
+ observed: null,
+ }),
+ ]),
+ },
+ });
+ });
+ it("rejects stale snapshot identity", () => {
+ const f = fixtureRawBinaryLoadImage();
+ expect(
+ attestGhidraRawBinaryLoadImage(
+ f.snapshot,
+ { ...f.target, sha256: "f".repeat(64) },
+ f.observation,
+ ).ok,
+ ).toBe(false);
+ });
+});
diff --git a/src/hopper/HopperAnalysisProfile.ts b/src/hopper/HopperAnalysisProfile.ts
index 9c1f40a1a..9dfef9e07 100644
--- a/src/hopper/HopperAnalysisProfile.ts
+++ b/src/hopper/HopperAnalysisProfile.ts
@@ -140,6 +140,7 @@ export const hopperLoaderArgsForTarget = (
return ok(["-l", "WinPE", flag]);
case "dos-mz":
case "dos-com":
+ case "raw-binary":
return err(
new ProviderAdapterError("hopper", "resolve_analysis_profile"),
);
diff --git a/src/hopper/HopperProvider.test.ts b/src/hopper/HopperProvider.test.ts
index 3265b26c5..94715034c 100644
--- a/src/hopper/HopperProvider.test.ts
+++ b/src/hopper/HopperProvider.test.ts
@@ -5,6 +5,27 @@ import { silentLogger } from "../logger.js";
import { HopperProvider } from "./HopperProvider.js";
describe("Hopper provider capabilities", () => {
+ it("declines headerless raw-binary targets with a Ghidra-directed reason", () => {
+ const config = parseConfig({});
+ if (!config.ok) throw new Error("expected valid configuration");
+ const provider = new HopperProvider(config.value, silentLogger, {});
+ expect(
+ provider.inspectTargetSupport({
+ path: "/tmp/ecu.bin",
+ sha256: "a".repeat(64),
+ kind: "executable",
+ format: "raw-binary",
+ architecture: "arm",
+ availableArchitectures: ["arm"],
+ entryPoint: "0x8000000",
+ entryPointSource: "0x8000000",
+ }),
+ ).toMatchObject({
+ status: "unsupported",
+ code: "target_format_unsupported",
+ reason: expect.stringContaining("Ghidra"),
+ });
+ });
it("declines DOS MZ targets with a provider-specific support reason", () => {
const config = parseConfig({});
if (!config.ok) throw new Error("expected valid configuration");
diff --git a/src/hopper/HopperProvider.ts b/src/hopper/HopperProvider.ts
index e0cd543bf..d8b2dafa6 100644
--- a/src/hopper/HopperProvider.ts
+++ b/src/hopper/HopperProvider.ts
@@ -123,6 +123,14 @@ export class HopperProvider implements AnalysisProviderCandidate {
reason: "REA's Hopper adapter does not admit MIPS targets.",
diagnostics,
};
+ if (target.format === "raw-binary")
+ return {
+ status: "unsupported",
+ code: "target_format_unsupported",
+ reason:
+ "Headerless raw-binary analysis requires the Ghidra adapter with a caller-supplied architecture and entry point.",
+ diagnostics,
+ };
if (target.format === "dos-mz" || target.format === "dos-com")
return {
status: "unsupported",
diff --git a/src/ida/IdaOperationFailures.test.ts b/src/ida/IdaOperationFailures.test.ts
index 25b2bab8a..e863266d0 100644
--- a/src/ida/IdaOperationFailures.test.ts
+++ b/src/ida/IdaOperationFailures.test.ts
@@ -5,6 +5,9 @@ import {
RecordingIdaMcp,
} from "../../tests/fixtures/idaMcp.js";
import type { JsonValue } from "../domain/jsonValue.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { decodeIdaToolResult } from "./IdaMcpConnection.js";
import type { AnalysisOperation } from "../application/AnalysisProvider.js";
import { IdaSessionClient } from "./IdaSessionClient.js";
@@ -96,3 +99,290 @@ describe("headless IDA operation failures", () => {
},
);
});
+
+const lookup = (query: string, fn: JsonValue, error: string | null) => [
+ { query, fn, error },
+];
+const knownFunction = { addr: "0x1000", name: "main", size: "0x20" };
+
+const missingProcedureFixture = async (
+ answer: (query: string) => JsonValue | undefined,
+) => {
+ const { root, target } = await createIdaTarget();
+ roots.push(root);
+ const producer = new RecordingIdaMcp(target, "headless");
+ producer.overrideCall = (name, args) => {
+ if (name !== "lookup_funcs") return undefined;
+ const queries = args.queries;
+ const query = Array.isArray(queries) ? String(queries[0]) : "";
+ return answer(query);
+ };
+ const client = new IdaSessionClient(
+ {
+ command: "fixture",
+ args: [],
+ env: {},
+ mode: "headless",
+ timeoutMs: 1000,
+ workspaceRoot: root,
+ },
+ target,
+ producer,
+ );
+ return client;
+};
+
+describe("headless IDA procedure lookup failures", () => {
+ it.each([
+ ["Not found", "procedure_pseudo_code", "main"],
+ ["Not found", "procedure_address", "main"],
+ ["Not found", "analyze_function", "main"],
+ ["Not a function", "procedure_pseudo_code", "main"],
+ ["Not a function", "read_function_instructions", "main"],
+ ["Not a function", "procedure_pseudo_code", "0x1000"],
+ ["Not found", "procedure_assembly", "_missing"],
+ ["Not found", "procedure_pseudo_code", "main\nsecond line"],
+ ] as const)(
+ "reports the upstream %s answer for %s of %s as an invalid request naming the procedure",
+ async (upstream, operation, procedure) => {
+ const client = await missingProcedureFixture((query) =>
+ lookup(query, null, upstream),
+ );
+ try {
+ const result = await client.execute(operation, { procedure });
+
+ if (result.ok) throw new Error("expected invalid input");
+ expect(result.error._tag, "the caller's procedure is the fault").toBe(
+ "AnalysisInputError",
+ );
+ const projected = projectAnalysisError(result.error);
+ expect(projected.code, "the public code is invalid_request").toBe(
+ "invalid_request",
+ );
+ expect(projected.category, "the category is invalid_input").toBe(
+ "invalid_input",
+ );
+ expect(projected.retryable, "the caller can correct and retry").toBe(
+ true,
+ );
+ expect(
+ projected.details,
+ "the operation and exactly one issue that names the procedure in its message",
+ ).toEqual({
+ operation,
+ issues: [
+ {
+ path: [],
+ reason: "invalid_value",
+ message: `IDA could not resolve procedure ${JSON.stringify(procedure)}: ${upstream}.`,
+ },
+ ],
+ });
+ if (!(result.error instanceof AnalysisInputError))
+ throw new Error("expected an AnalysisInputError");
+ expect(
+ result.error.issues.map(({ message }) => message ?? "").join(""),
+ "a control character in the query is carried JSON-escaped, never raw",
+ ).not.toContain("\n");
+ expect(
+ (result.error.cause as Error | undefined)?.message,
+ "the upstream text stays on the retained cause",
+ ).toContain(upstream);
+ expect(
+ JSON.stringify(projected).toLowerCase(),
+ "no retry or doctor advice for a caller mistake",
+ ).not.toMatch(/doctor|retry once/u);
+ } finally {
+ expect((await client.close()).ok).toBe(true);
+ }
+ },
+ );
+
+ it.each([
+ ["an upstream exception text", lookup("main", null, "Database is closed")],
+ ["a function with an error", lookup("main", knownFunction, "Not found")],
+ ["neither a function nor an error", lookup("main", null, null)],
+ [
+ "a near-miss spelling of the not-found text",
+ lookup("main", null, "not found"),
+ ],
+ [
+ "an exception text that merely contains the not-found text",
+ lookup("main", null, "Database lookup failed: Not found"),
+ ],
+ ["a padded not-found text", lookup("main", null, " Not found ")],
+ ["an empty error", lookup("main", null, "")],
+ ["a whitespace-only error", lookup("main", null, " ")],
+ ["an answer for a different query", lookup("helper", null, "Not found")],
+ ])("keeps %s as unreadable output", async (_label, answer) => {
+ const client = await missingProcedureFixture(() => answer);
+ try {
+ const result = await client.execute("procedure_pseudo_code", {
+ procedure: "main",
+ });
+
+ if (result.ok) throw new Error("expected unreadable output");
+ expect(result.error._tag, "a producer fault, not caller input").toBe(
+ "AnalysisProtocolError",
+ );
+ expect(
+ projectAnalysisError(result.error).code,
+ "unknown beats a wrong fact about the caller's input",
+ ).toBe("unreadable_output");
+ } finally {
+ expect((await client.close()).ok).toBe(true);
+ }
+ });
+
+ it("keeps an unresolvable callee reported by IDA itself as unreadable output", async () => {
+ const { root, target } = await createIdaTarget();
+ roots.push(root);
+ const producer = new RecordingIdaMcp(target, "headless");
+ producer.overrideCall = (name, args) => {
+ if (name === "callees")
+ return [
+ {
+ callees: [{ addr: "0x2000", name: "sub_2000", type: "internal" }],
+ more: false,
+ },
+ ];
+ if (name !== "lookup_funcs") return undefined;
+ const queries = args.queries;
+ const query = Array.isArray(queries) ? String(queries[0]) : "";
+ return query === "0x2000"
+ ? lookup(query, null, "Not a function")
+ : lookup(query, knownFunction, null);
+ };
+ const client = new IdaSessionClient(
+ {
+ command: "fixture",
+ args: [],
+ env: {},
+ mode: "headless",
+ timeoutMs: 1000,
+ workspaceRoot: root,
+ },
+ target,
+ producer,
+ );
+ try {
+ const result = await client.execute("procedure_callees", {
+ procedure: "main",
+ });
+
+ if (result.ok) throw new Error("expected unreadable output");
+ expect(
+ projectAnalysisError(result.error).code,
+ "an address IDA itself reported is not the caller's mistake",
+ ).toBe("unreadable_output");
+ } finally {
+ expect((await client.close()).ok).toBe(true);
+ }
+ });
+});
+
+describe("provider-derived procedure selectors", () => {
+ it.each(["Not found", "Not a function"])(
+ "reports a derived selector answered %s as a producer fault",
+ async (upstream) => {
+ const client = await missingProcedureFixture((query) =>
+ lookup(query, null, upstream),
+ );
+ try {
+ const result = await client.execute(
+ "procedure_callees",
+ { procedure: "0x2000" },
+ { selectorOrigin: "provider" },
+ );
+
+ if (result.ok) throw new Error("expected a producer fault");
+ expect(result.error._tag, "not the caller's mistake").toBe(
+ "AnalysisProtocolError",
+ );
+ expect(
+ projectAnalysisError(result.error).code,
+ "projected as on main",
+ ).toBe("unreadable_output");
+ } finally {
+ expect((await client.close()).ok).toBe(true);
+ }
+ },
+ );
+});
+
+describe("attached IDA procedure lookup failures", () => {
+ it("leaves a failed legacy lookup as unreadable output", async () => {
+ const { root, target } = await createIdaTarget();
+ roots.push(root);
+ const producer = new RecordingIdaMcp(target, "attached");
+ producer.overrideCall = (name) =>
+ name === "get_function_by_name" ? null : undefined;
+ const client = new IdaSessionClient(
+ {
+ command: "fixture",
+ args: [],
+ env: {},
+ mode: "attached",
+ timeoutMs: 1000,
+ workspaceRoot: root,
+ },
+ target,
+ producer,
+ );
+ try {
+ const result = await client.execute("procedure_pseudo_code", {
+ procedure: "main",
+ });
+
+ if (result.ok) throw new Error("expected unreadable output");
+ expect(
+ projectAnalysisError(result.error).code,
+ "the legacy profile keeps its pre-existing classification",
+ ).toBe("unreadable_output");
+ } finally {
+ expect((await client.close()).ok).toBe(true);
+ }
+ });
+
+ it("leaves an MCP error reply for an unknown legacy name as unreadable output", async () => {
+ const { root, target } = await createIdaTarget();
+ roots.push(root);
+ const producer = new RecordingIdaMcp(target, "attached");
+ producer.beforeCall = async (name) => {
+ if (name === "get_function_by_name")
+ decodeIdaToolResult({
+ content: [{ type: "text", text: "Function not found: main" }],
+ isError: true,
+ });
+ };
+ const client = new IdaSessionClient(
+ {
+ command: "fixture",
+ args: [],
+ env: {},
+ mode: "attached",
+ timeoutMs: 1000,
+ workspaceRoot: root,
+ },
+ target,
+ producer,
+ );
+ try {
+ const result = await client.execute("procedure_pseudo_code", {
+ procedure: "main",
+ });
+
+ if (result.ok) throw new Error("expected unreadable output");
+ expect(
+ result.error._tag,
+ "a producer error reply, not caller input",
+ ).toBe("AnalysisProtocolError");
+ expect(
+ projectAnalysisError(result.error).code,
+ "the legacy profile keeps its existing classification",
+ ).toBe("unreadable_output");
+ } finally {
+ expect((await client.close()).ok).toBe(true);
+ }
+ });
+});
diff --git a/src/ida/IdaOperationRunner.ts b/src/ida/IdaOperationRunner.ts
index 553053a31..51de0352f 100644
--- a/src/ida/IdaOperationRunner.ts
+++ b/src/ida/IdaOperationRunner.ts
@@ -51,6 +51,11 @@ const identity = (fn: IdaFunction) => ({
classification: null,
body: unknownBody,
});
+/** The only lookup answers upstream reports for a name or address that is not a function. */
+const MISSING_PROCEDURE_ANSWERS: ReadonlySet = new Set([
+ "Not found",
+ "Not a function",
+]);
const lines = (asm: IdaDisassembly) =>
asm.lines.map(({ address, instruction }) => `${address}: ${instruction}`);
@@ -64,6 +69,7 @@ export class IdaOperationRunner {
private readonly protocol: "legacy" | "modern",
private readonly database?: string,
private readonly signal?: AbortSignal,
+ private readonly selectorOrigin?: "provider",
) {}
async call(
@@ -106,11 +112,42 @@ export class IdaOperationRunner {
return result;
}
- async resolve(query: string): Promise {
+ /**
+ * Resolves a procedure. When `requestedBy` names the caller's operation, an
+ * upstream "not found" or "not a function" answer is reported as invalid
+ * input; every other failed lookup stays a producer fault. `run()` passes
+ * `requestedBy` only for caller-supplied selectors. Provider-derived
+ * selectors, such as the addresses composed workflows revisit, and the
+ * callee resolution inside `relationships()` pass none, because those
+ * addresses were reported by IDA itself.
+ */
+ async resolve(query: string, requestedBy?: string): Promise {
if (this.protocol === "modern") {
const item = modernLookupSchema.parse(
await this.call("lookup_funcs", { queries: [query] }),
)[0];
+ if (
+ requestedBy !== undefined &&
+ item?.query === query &&
+ item.fn === null &&
+ item.error !== null &&
+ MISSING_PROCEDURE_ANSWERS.has(item.error)
+ )
+ throw new AnalysisInputError(
+ requestedBy,
+ {
+ cause: new AnalysisProtocolError(
+ `IDA function lookup failed for ${query}: ${item.error}`,
+ ),
+ },
+ [
+ {
+ path: [],
+ reason: "invalid_value",
+ message: `IDA could not resolve procedure ${JSON.stringify(query)}: ${item.error}.`,
+ },
+ ],
+ );
if (item?.fn == null || item.error !== null)
throw new AnalysisProtocolError(
`IDA function lookup failed for ${query}: ${item?.error ?? "missing function"}`,
@@ -351,6 +388,7 @@ export class IdaOperationRunner {
}
const fn = await this.resolve(
z.string().min(1).parse(parameters.procedure),
+ this.selectorOrigin === "provider" ? undefined : operation,
);
this.locations.push({ kind: "address", address: fn.address });
switch (operation) {
diff --git a/src/ida/IdaProvider.test.ts b/src/ida/IdaProvider.test.ts
new file mode 100644
index 000000000..ccf67c5b4
--- /dev/null
+++ b/src/ida/IdaProvider.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+
+import { parseConfig } from "../config/parseConfig.js";
+import { IdaProvider } from "./IdaProvider.js";
+
+describe("IDA provider target support", () => {
+ it("declines headerless raw-binary targets", () => {
+ const config = parseConfig({});
+ if (!config.ok) throw new Error("expected valid configuration");
+ const provider = new IdaProvider(config.value, {});
+ expect(
+ provider.inspectTargetSupport({
+ path: "/tmp/ecu.bin",
+ sha256: "a".repeat(64),
+ kind: "executable",
+ format: "raw-binary",
+ architecture: "arm",
+ availableArchitectures: ["arm"],
+ entryPoint: "0x8000000",
+ entryPointSource: "0x8000000",
+ }),
+ ).toMatchObject({
+ status: "unsupported",
+ code: "target_format_unsupported",
+ reason: expect.stringContaining("Ghidra"),
+ });
+ });
+});
diff --git a/src/ida/IdaProvider.ts b/src/ida/IdaProvider.ts
index 691a666c2..7fefce825 100644
--- a/src/ida/IdaProvider.ts
+++ b/src/ida/IdaProvider.ts
@@ -109,15 +109,23 @@ export class IdaProvider implements AnalysisProviderCandidate {
"REA's IDA adapter has no verified MIPS lane. Select a supported Ghidra profile instead.",
diagnostics,
};
- return target.kind === "executable"
- ? { status: "supported", code: null, reason: null, diagnostics }
- : {
- status: "unsupported",
- code: "target_kind_unsupported",
- reason:
- "IDA MCP integration admits executable inputs, not analysis databases. Select the original input binary.",
- diagnostics,
- };
+ if (target.kind !== "executable")
+ return {
+ status: "unsupported",
+ code: "target_kind_unsupported",
+ reason:
+ "IDA MCP integration admits executable inputs, not analysis databases. Select the original input binary.",
+ diagnostics,
+ };
+ if (target.format === "raw-binary")
+ return {
+ status: "unsupported",
+ code: "target_format_unsupported",
+ reason:
+ "IDA does not admit headerless raw binaries. Open the target with Ghidra and supply architecture and entry_point.",
+ diagnostics,
+ };
+ return { status: "supported", code: null, reason: null, diagnostics };
}
async resolveAnalysisProfile(
_target: BinaryTarget,
diff --git a/src/ida/IdaSessionClient.ts b/src/ida/IdaSessionClient.ts
index 48920a725..8de42a67d 100644
--- a/src/ida/IdaSessionClient.ts
+++ b/src/ida/IdaSessionClient.ts
@@ -192,12 +192,7 @@ export class IdaSessionClient implements AnalysisClient {
throw new AnalysisProtocolError(
"IDA operation changed after validation.",
);
- const runner = new IdaOperationRunner(
- this.connection,
- this.config.mode === "attached" ? "legacy" : "modern",
- this.#database,
- options?.signal,
- );
+ const runner = this.#runner(options);
const result = await runner.run(operation, parameters);
if (wasCancelled(options))
return err(new AnalysisCancelledError(operation));
@@ -227,6 +222,16 @@ export class IdaSessionClient implements AnalysisClient {
}
}
+ #runner(options: ExecutionOptions | undefined): IdaOperationRunner {
+ return new IdaOperationRunner(
+ this.connection,
+ this.config.mode === "attached" ? "legacy" : "modern",
+ this.#database,
+ options?.signal,
+ options?.selectorOrigin,
+ );
+ }
+
#health(metadata: JsonValue) {
return ok(
createAnalysisExecution(
diff --git a/src/server/mcpProgress.ts b/src/server/mcpProgress.ts
index 0cbe0a194..a3fd4fde0 100644
--- a/src/server/mcpProgress.ts
+++ b/src/server/mcpProgress.ts
@@ -22,8 +22,10 @@ export const mcpProgressReporter = (
method: "notifications/progress",
params: {
progressToken: token,
- progress: update.completed,
- ...(update.total === null ? {} : { total: update.total }),
+ // Status phases can repeat their work count while waiting. The
+ // protocol requires every notification to advance; count emitted
+ // observations without inventing a total amount of analysis work.
+ progress: update.sequence,
message: `${update.phase}: ${update.message}`,
},
});
diff --git a/src/server/registerSessionTools.ts b/src/server/registerSessionTools.ts
index 7b7e5ebb5..1c4b89a54 100644
--- a/src/server/registerSessionTools.ts
+++ b/src/server/registerSessionTools.ts
@@ -12,6 +12,7 @@ import { ProcessCaptureResourceScope } from "../process/capture/ProcessCaptureLi
import { ProcessCaptureError } from "../process/capture/ProcessCaptureError.js";
import { toolContract } from "../contracts/toolContracts.js";
import type { AnalysisSnapshot } from "../domain/analysisSnapshot.js";
+import { binaryTargetSummary } from "../application/binary/BinaryTargetSummary.js";
import { UnknownRegistryError } from "../domain/unknownRegistryError.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import type { Evidence } from "../domain/evidence.js";
@@ -203,6 +204,12 @@ const registerOpenLifecycleTool = ({
session.open(input.path, {
signal: context.mcpReq.signal,
...(input.format === undefined ? {} : { formatHint: input.format }),
+ ...(input.architecture === undefined
+ ? {}
+ : { architecture: input.architecture }),
+ ...(input.entry_point === undefined
+ ? {}
+ : { entryPoint: input.entry_point }),
...(input.provider_id === undefined
? {}
: { providerId: input.provider_id }),
@@ -213,13 +220,7 @@ const registerOpenLifecycleTool = ({
? server.delivery.toCallToolResult(
{
ok: true,
- value: {
- path: opened.value.path,
- format: opened.value.format,
- kind: opened.value.kind,
- sha256: opened.value.sha256,
- architecture: opened.value.architecture ?? null,
- },
+ value: binaryTargetSummary(opened.value),
},
openContract,
)
diff --git a/src/server/runDerivedOperation.test.ts b/src/server/runDerivedOperation.test.ts
index f2404279a..5fc511f47 100644
--- a/src/server/runDerivedOperation.test.ts
+++ b/src/server/runDerivedOperation.test.ts
@@ -67,8 +67,10 @@ describe("derived MCP operation boundary", () => {
);
expect(result).toEqual({ ok: true, value: "complete" });
- expect(notifications.map(({ params }) => params?.progress)).toEqual([0, 2]);
- expect(notifications.every(({ params }) => params?.total === 2)).toBe(true);
+ expect(notifications.map(({ params }) => params?.progress)).toEqual([1, 2]);
+ expect(
+ notifications.every(({ params }) => params?.total === undefined),
+ ).toBe(true);
});
it("projects synchronous computation failures into a typed result", async () => {
diff --git a/tests/boundary/android/jadxConfiguration.test.ts b/tests/boundary/android/jadxConfiguration.test.ts
index 57beee669..3ebba3271 100644
--- a/tests/boundary/android/jadxConfiguration.test.ts
+++ b/tests/boundary/android/jadxConfiguration.test.ts
@@ -86,6 +86,40 @@ it("accepts a full JDK and canonicalizes the selected JAR", async () => {
});
});
+it("admits engine classes past repeated ZIP resource filenames", async () => {
+ const root = await createTestTempDirectory("rea-jadx-duplicate-resource-");
+ const jar = join(root, "engine.jar");
+ const javaHome = await createFakeJdk(root);
+ await writeOrderedZip(jar, [
+ "META-INF/LICENSE.txt",
+ "META-INF/LICENCE.txt",
+ "com/atxx/jhmcp/JadxSession.class",
+ "com/atxx/jhmcp/SessionHolder.class",
+ "jadx/api/JadxDecompiler.class",
+ "com/google/gson/Gson.class",
+ "io/modelcontextprotocol/kotlin/sdk/server/Server.class",
+ ]);
+ const bytes = await readFile(jar);
+ const original = Buffer.from("META-INF/LICENCE.txt");
+ let renamed = 0;
+ for (
+ let offset = bytes.indexOf(original);
+ offset >= 0;
+ offset = bytes.indexOf(original, offset + original.length)
+ ) {
+ bytes.write("META-INF/LICENSE.txt", offset);
+ renamed++;
+ }
+ expect(renamed).toBe(2);
+ await writeFile(jar, bytes);
+ await expect(
+ resolveConfiguration(
+ { REA_JADX_MCP_JAR: jar, JAVA_HOME: javaHome },
+ "inspect_android_package",
+ ),
+ ).resolves.toMatchObject({ jar: await realpath(jar) });
+});
+
it("configures heap and visible processors independently without forcing either", async () => {
const root = await createTestTempDirectory("rea-jadx-config-");
const jar = join(root, "engine.jar");
diff --git a/tests/boundary/cli/clientProfileLifecycle.test.ts b/tests/boundary/cli/clientProfileLifecycle.test.ts
index 286d04357..531e6378a 100644
--- a/tests/boundary/cli/clientProfileLifecycle.test.ts
+++ b/tests/boundary/cli/clientProfileLifecycle.test.ts
@@ -1,4 +1,12 @@
-import { access, readFile, writeFile } from "node:fs/promises";
+import {
+ access,
+ lstat,
+ mkdir,
+ readFile,
+ realpath,
+ symlink,
+ writeFile,
+} from "node:fs/promises";
import { join } from "node:path";
import { expect } from "vitest";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
@@ -78,6 +86,54 @@ const groups = [
],
},
];
+
+cliTest(
+ "uninstall purge retains unrelated data behind a managed-root symlink",
+ async ({ cli }) => {
+ const root = await createTestTempDirectory("rea-uninstall-root-link-");
+ const home = join(root, "home");
+ const unrelated = join(root, "unrelated-application");
+ await mkdir(home);
+ for (const name of ["cache", "state"]) {
+ await mkdir(join(unrelated, name), { recursive: true });
+ await writeFile(join(unrelated, name, "keep.txt"), `unrelated ${name}`);
+ }
+ const managedRoot = join(home, ".rea");
+ await symlink(
+ unrelated,
+ managedRoot,
+ process.platform === "win32" ? "junction" : "dir",
+ );
+
+ const result = await cli.run({
+ arguments: ["uninstall", "--purge-data", "--json"],
+ cwd: home,
+ environment: {
+ HOME: home,
+ USERPROFILE: home,
+ XDG_CONFIG_HOME: join(root, "xdg-config"),
+ XDG_CACHE_HOME: join(root, "xdg-cache"),
+ },
+ timeoutMs: 20_000,
+ });
+
+ expect(result.exitCode, result.stderr).toBe(0);
+ expect.soft(result.json).toMatchObject({
+ status: "complete",
+ items: expect.arrayContaining([
+ expect.objectContaining({ name: "cache", status: "retained" }),
+ expect.objectContaining({ name: "state", status: "retained" }),
+ ]),
+ });
+ expect((await lstat(managedRoot)).isSymbolicLink()).toBe(true);
+ expect(await realpath(managedRoot)).toBe(await realpath(unrelated));
+ for (const name of ["cache", "state"])
+ await expect
+ .soft(readFile(join(unrelated, name, "keep.txt"), "utf8"))
+ .resolves.toBe(`unrelated ${name}`);
+ },
+);
+
for (const group of groups) {
cliTest(
`${group.name} lifecycle follows the selected roots`,
diff --git a/tests/boundary/cli/rawBinaryCli.test.ts b/tests/boundary/cli/rawBinaryCli.test.ts
new file mode 100644
index 000000000..b16d296ce
--- /dev/null
+++ b/tests/boundary/cli/rawBinaryCli.test.ts
@@ -0,0 +1,103 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { expect } from "vitest";
+
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { cliTest } from "../../support/cli/cliFixture.js";
+
+cliTest(
+ "rejects a headerless image until architecture and entry are supplied",
+ async ({ cli }) => {
+ const root = await createTestTempDirectory("rea-raw-cli-");
+ const path = join(root, "ecu.bin");
+ await writeFile(path, Buffer.from("1eff2fe1", "hex"));
+ const before = await cli.run({
+ arguments: ["inspect", path, "--json"],
+ environment: {
+ HOME: root,
+ XDG_CONFIG_HOME: root,
+ XDG_CACHE_HOME: root,
+ },
+ });
+ expect(before.exitCode).not.toBe(0);
+ expect(JSON.stringify(before.json)).not.toContain("raw-binary");
+ const missing = await cli.run({
+ arguments: ["inspect", path, "--target-format", "raw-binary", "--json"],
+ environment: {
+ HOME: root,
+ XDG_CONFIG_HOME: root,
+ XDG_CACHE_HOME: root,
+ },
+ });
+ expect(missing.exitCode).toBe(1);
+ expect(missing.json).toMatchObject({
+ code: "target_unavailable",
+ details: { reason: expect.stringContaining("architecture") },
+ });
+ },
+);
+
+cliTest(
+ "rejects an unaligned AArch64 entry before provider startup",
+ async ({ cli }) => {
+ const root = await createTestTempDirectory("rea-raw-cli-alignment-");
+ const path = join(root, "image.bin");
+ await writeFile(path, Buffer.from("c0035fd6", "hex"));
+ const result = await cli.run({
+ arguments: [
+ "inspect",
+ path,
+ "--target-format",
+ "raw-binary",
+ "--architecture",
+ "arm64",
+ "--entry-point",
+ "0x8000001",
+ "--provider",
+ "ghidra",
+ "--json",
+ ],
+ environment: { HOME: root, XDG_CONFIG_HOME: root, XDG_CACHE_HOME: root },
+ });
+ expect(result.exitCode).toBe(1);
+ expect(result.json).toMatchObject({
+ code: "target_unavailable",
+ details: { reason: expect.stringContaining("must be 4-byte aligned") },
+ });
+ },
+);
+
+cliTest(
+ "stops Hopper from claiming a caller-supplied raw-binary image",
+ async ({ cli }) => {
+ const root = await createTestTempDirectory("rea-raw-cli-hopper-");
+ const path = join(root, "ecu.bin");
+ await writeFile(path, Buffer.from("1eff2fe1", "hex"));
+ const result = await cli.run({
+ arguments: [
+ "inspect",
+ path,
+ "--target-format",
+ "raw-binary",
+ "--architecture",
+ "arm",
+ "--entry-point",
+ "0x8000000",
+ "--provider",
+ "hopper",
+ "--json",
+ ],
+ environment: {
+ HOME: root,
+ XDG_CONFIG_HOME: root,
+ XDG_CACHE_HOME: root,
+ },
+ });
+ expect(result.exitCode).toBe(1);
+ expect(JSON.stringify(result.json)).toMatch(/Hopper|ghidra|Ghidra|hopper/i);
+ expect(JSON.stringify(result.json)).not.toMatch(
+ /unsupported binary format/i,
+ );
+ },
+);
diff --git a/tests/boundary/filesystem/artifactZipIntegrity.test.ts b/tests/boundary/filesystem/artifactZipIntegrity.test.ts
index 3bbb13f49..b2b8b179f 100644
--- a/tests/boundary/filesystem/artifactZipIntegrity.test.ts
+++ b/tests/boundary/filesystem/artifactZipIntegrity.test.ts
@@ -77,7 +77,7 @@ it("binds ZIP opens to the emitted entry metadata", async () => {
}
});
-it("rejects duplicate ZIP names before replacing an emitted entry", async () => {
+it("retains duplicate ZIP members without replacing their source identities", async () => {
const root = await createTestTempDirectory("rea-zip-duplicate-identity-");
const path = join(root, "duplicates.zip");
const writer = new ZipWriter(new Uint8ArrayWriter());
@@ -106,11 +106,20 @@ it("rejects duplicate ZIP names before replacing an emitted entry", async () =>
const iterator = reader.entries()[Symbol.asyncIterator]();
const first = await iterator.next();
if (first.done) throw new Error("Expected the first ZIP member");
- await expect(iterator.next()).rejects.toMatchObject({ reason: "path" });
- const stream = await reader.open({ ...first.value });
- const chunks: Buffer[] = [];
- for await (const chunk of stream) chunks.push(Buffer.from(chunk));
- expect(Buffer.concat(chunks).toString()).toBe("first bytes\n");
+ const second = await iterator.next();
+ if (second.done) throw new Error("Expected the second ZIP member");
+ expect(first.value.path).toBe(second.value.path);
+ expect(first.value.adapterKey).not.toBe(second.value.adapterKey);
+ expect((await iterator.next()).done).toBe(true);
+ for (const [entry, expected] of [
+ [first.value, "first bytes\n"],
+ [second.value, "later bytes\n"],
+ ] as const) {
+ const chunks: Buffer[] = [];
+ for await (const chunk of await reader.open({ ...entry }))
+ chunks.push(Buffer.from(chunk));
+ expect(Buffer.concat(chunks).toString()).toBe(expected);
+ }
} finally {
await reader.close();
}
diff --git a/tests/boundary/filesystem/clientLifecycle.test.ts b/tests/boundary/filesystem/clientLifecycle.test.ts
index ae814c885..9b3e8f5b9 100644
--- a/tests/boundary/filesystem/clientLifecycle.test.ts
+++ b/tests/boundary/filesystem/clientLifecycle.test.ts
@@ -1341,6 +1341,146 @@ describe("Codex configuration comments", () => {
});
});
+describe("managed data purge root validation", () => {
+ it.each(["existing", "dangling"] as const)(
+ "retains cache and state when the managed-root symlink is %s",
+ async (targetState) => {
+ const root = await createTestTempDirectory("rea-uninstall-data-root-");
+ roots.push(root);
+ const home = join(root, "home");
+ const outside = join(root, "unrelated-application");
+ await mkdir(home);
+ if (targetState === "existing")
+ for (const name of ["cache", "state"]) {
+ await mkdir(join(outside, name), { recursive: true });
+ await writeFile(join(outside, name, "keep.txt"), "unrelated data");
+ }
+ const managedRoot = join(home, ".rea");
+ await symlink(
+ outside,
+ managedRoot,
+ process.platform === "win32" ? "junction" : "dir",
+ );
+
+ const result = await runUninstall(
+ true,
+ systemUninstallHost(home, undefined, {}),
+ );
+
+ expect(result.status).toBe("complete");
+ expect((await lstat(managedRoot)).isSymbolicLink()).toBe(true);
+ for (const name of ["cache", "state"])
+ expect(result.items).toContainEqual(
+ expect.objectContaining({ name, status: "retained" }),
+ );
+ if (targetState === "existing")
+ for (const name of ["cache", "state"])
+ expect(await readFile(join(outside, name, "keep.txt"), "utf8")).toBe(
+ "unrelated data",
+ );
+ else
+ await expect(lstat(outside)).rejects.toMatchObject({ code: "ENOENT" });
+ },
+ );
+
+ it("retains a managed data root that is not a directory", async () => {
+ const home = await createTestTempDirectory("rea-uninstall-data-file-");
+ roots.push(home);
+ const managedRoot = join(home, ".rea");
+ await writeFile(managedRoot, "unrelated file");
+
+ const result = await runUninstall(
+ true,
+ systemUninstallHost(home, undefined, {}),
+ );
+
+ expect(result.status).toBe("complete");
+ for (const name of ["cache", "state"])
+ expect(result.items).toContainEqual(
+ expect.objectContaining({ name, status: "retained" }),
+ );
+ expect(await readFile(managedRoot, "utf8")).toBe("unrelated file");
+ });
+
+ it("purges ordinary managed data through a legitimate home directory link", async () => {
+ const root = await createTestTempDirectory("rea-uninstall-home-link-");
+ roots.push(root);
+ const home = join(root, "actual-home");
+ const linkedHome = join(root, "linked-home");
+ const managedRoot = join(home, ".rea");
+ for (const name of ["cache", "state"]) {
+ await mkdir(join(managedRoot, name), { recursive: true });
+ await writeFile(join(managedRoot, name, "data.txt"), "managed data");
+ }
+ await writeFile(join(managedRoot, "keep.txt"), "other data");
+ await symlink(
+ home,
+ linkedHome,
+ process.platform === "win32" ? "junction" : "dir",
+ );
+
+ const result = await runUninstall(
+ true,
+ systemUninstallHost(linkedHome, undefined, {}),
+ );
+
+ expect(result.status).toBe("complete");
+ for (const name of ["cache", "state"]) {
+ expect(result.items).toContainEqual(
+ expect.objectContaining({ name, status: "removed" }),
+ );
+ await expect(lstat(join(managedRoot, name))).rejects.toMatchObject({
+ code: "ENOENT",
+ });
+ }
+ expect((await lstat(linkedHome)).isSymbolicLink()).toBe(true);
+ expect(await readFile(join(managedRoot, "keep.txt"), "utf8")).toBe(
+ "other data",
+ );
+ });
+
+ it("reports root inspection failure without removing managed data", async () => {
+ const home = await createTestTempDirectory("rea-uninstall-data-denied-");
+ roots.push(home);
+ const managedRoot = join(home, ".rea");
+ for (const name of ["cache", "state"]) {
+ await mkdir(join(managedRoot, name), { recursive: true });
+ await writeFile(join(managedRoot, name, "keep.txt"), "managed data");
+ }
+ const remove = vi.fn(testFileSystem.remove);
+ const result = await runUninstall(
+ true,
+ systemUninstallHost(
+ home,
+ {
+ ...testFileSystem,
+ stat: (path) =>
+ path === managedRoot
+ ? Promise.reject(
+ Object.assign(new Error("root inspection denied"), {
+ code: "EACCES",
+ }),
+ )
+ : lstat(path),
+ remove,
+ },
+ {},
+ ),
+ );
+
+ expect(result.status).toBe("failed");
+ expect(remove).not.toHaveBeenCalled();
+ for (const name of ["cache", "state"]) {
+ expect(result.items).toContainEqual(
+ expect.objectContaining({ name, status: "failed" }),
+ );
+ expect(await readFile(join(managedRoot, name, "keep.txt"), "utf8")).toBe(
+ "managed data",
+ );
+ }
+ });
+});
+
describe("client configuration filesystem removal", () => {
it("uninstalls only owned entries and refuses purge symlinks", async () => {
const home = await createTestTempDirectory("rea-uninstall-");
diff --git a/tests/boundary/filesystem/rawBinaryTarget.test.ts b/tests/boundary/filesystem/rawBinaryTarget.test.ts
new file mode 100644
index 000000000..5fd171d20
--- /dev/null
+++ b/tests/boundary/filesystem/rawBinaryTarget.test.ts
@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { parseBinaryTarget } from "../../../src/application/BinaryTargetResolver.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+
+describe("raw-binary admission", () => {
+ it("requires explicit architecture and entry even with a misleading suffix", async () => {
+ const directory = await createTestTempDirectory("rea-raw-target-");
+ const path = join(directory, "fixture.js");
+ const bytes = Buffer.from("1eff2fe1", "hex");
+ await writeFile(path, bytes);
+ const target = await parseBinaryTarget(path, {
+ cwd: directory,
+ hostArchitecture: "arm64",
+ formatHint: "raw-binary",
+ architecture: "arm",
+ entryPoint: "0x08000000",
+ });
+ expect(target).toMatchObject({
+ ok: true,
+ value: {
+ path,
+ format: "raw-binary",
+ kind: "executable",
+ architecture: "arm",
+ availableArchitectures: ["arm"],
+ entryPoint: "0x8000000",
+ entryPointSource: "0x08000000",
+ sha256: createHash("sha256").update(bytes).digest("hex"),
+ },
+ });
+ expect(await readFile(path)).toEqual(bytes);
+ const detected = await parseBinaryTarget(path);
+ expect(detected.ok && detected.value.format).not.toBe("raw-binary");
+ });
+ it("rejects raw-binary without architecture and entry", async () => {
+ const directory = await createTestTempDirectory("rea-raw-missing-");
+ const path = join(directory, "fixture.bin");
+ await writeFile(path, Buffer.from("c3", "hex"));
+ expect(
+ await parseBinaryTarget(path, {
+ cwd: directory,
+ hostArchitecture: "x64",
+ formatHint: "raw-binary",
+ }),
+ ).toMatchObject({
+ ok: false,
+ error: {
+ _tag: "BinaryTargetError",
+ reason: expect.stringContaining("architecture"),
+ },
+ });
+ });
+ it("rejects architecture without format=raw-binary", async () => {
+ const directory = await createTestTempDirectory("rea-raw-unpaired-");
+ const path = join(directory, "fixture.bin");
+ await writeFile(path, Buffer.from("c3", "hex"));
+ expect(
+ await parseBinaryTarget(path, {
+ cwd: directory,
+ hostArchitecture: "x64",
+ architecture: "arm",
+ entryPoint: "0x8000000",
+ }),
+ ).toMatchObject({
+ ok: false,
+ error: {
+ _tag: "BinaryTargetError",
+ reason: expect.stringContaining("format=raw-binary"),
+ },
+ });
+ });
+ it("rejects an empty image", async () => {
+ const directory = await createTestTempDirectory("rea-raw-empty-");
+ const path = join(directory, "fixture.bin");
+ await writeFile(path, Buffer.alloc(0));
+ expect(
+ await parseBinaryTarget(path, {
+ cwd: directory,
+ hostArchitecture: "x64",
+ formatHint: "raw-binary",
+ architecture: "x86",
+ entryPoint: "0x1000",
+ }),
+ ).toMatchObject({ ok: false, error: { _tag: "BinaryTargetError" } });
+ });
+ it("rejects a contradictory target kind", async () => {
+ const directory = await createTestTempDirectory("rea-raw-kind-");
+ const path = join(directory, "fixture.bin");
+ await writeFile(path, Buffer.from("c3", "hex"));
+ expect(
+ await parseBinaryTarget(path, {
+ cwd: directory,
+ hostArchitecture: "x64",
+ targetKind: "database",
+ formatHint: "raw-binary",
+ architecture: "x86",
+ entryPoint: "0x1000",
+ }),
+ ).toMatchObject({ ok: false, error: { _tag: "BinaryTargetError" } });
+ });
+});
diff --git a/tests/boundary/mcp/electronMcp.test.ts b/tests/boundary/mcp/electronMcp.test.ts
index 39bdc3ef7..3fe41b1ca 100644
--- a/tests/boundary/mcp/electronMcp.test.ts
+++ b/tests/boundary/mcp/electronMcp.test.ts
@@ -415,8 +415,11 @@ it("exposes the target-free static JavaScript application workflow", async () =>
);
expect(analyzed.isError).not.toBe(true);
- expect(progress[0]).toBe(0);
- expect(progress.at(-1)).toBe(1);
+ expect(progress[0]).toBe(1);
+ expect(progress.at(-1)).toBeGreaterThan(1);
+ progress.forEach((value, index) => {
+ expect(value).toBeGreaterThan(progress[index - 1] ?? 0);
+ });
const projected = z
.object({
evidence_id: z.string(),
diff --git a/tests/boundary/mcp/enhancedTools.03-returns-typed-graph-failures-and.test.ts b/tests/boundary/mcp/enhancedTools.03-returns-typed-graph-failures-and.test.ts
index 035689b58..511dec47c 100644
--- a/tests/boundary/mcp/enhancedTools.03-returns-typed-graph-failures-and.test.ts
+++ b/tests/boundary/mcp/enhancedTools.03-returns-typed-graph-failures-and.test.ts
@@ -44,7 +44,7 @@ describe("enhanced MCP tools", () => {
error: {
category: "execution_failure",
message:
- "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",
+ "Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",
},
},
],
diff --git a/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts b/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts
index 1792221ac..5ed8e9c52 100644
--- a/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts
+++ b/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts
@@ -96,11 +96,11 @@ describe("enhanced MCP tools", () => {
category: "execution_failure",
details: { operation: "decompile", reason: "failed" },
message:
- "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",
+ "Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",
retryable: false,
remediation: {
action:
- "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",
+ "Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.",
},
},
},
diff --git a/tests/boundary/mcp/progressMcp.test.ts b/tests/boundary/mcp/progressMcp.test.ts
index 31c537a92..6c95b291a 100644
--- a/tests/boundary/mcp/progressMcp.test.ts
+++ b/tests/boundary/mcp/progressMcp.test.ts
@@ -1,4 +1,5 @@
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { setTimeout as delay } from "node:timers/promises";
import { describe, expect, it } from "vitest";
import type { AnalysisOperationPort } from "../../../src/application/AnalysisProvider.js";
@@ -8,29 +9,52 @@ import { createServer } from "../../../src/server/createServer.js";
import { observed } from "../../fixtures/analysisExecution.js";
describe("ordinary MCP progress and cancellation", () => {
- it("emits bounded progress for a normal tool request", async () => {
+ it("advances MCP progress when provider waiting does not advance completed work", async () => {
const analysis: AnalysisOperationPort = {
- execute: () => Promise.resolve(observed("0x1000")),
+ execute: async (_operation, _parameters, options) => {
+ for (const message of ["import pending", "analysis pending"]) {
+ await delay(120);
+ await options?.progress?.report({
+ phase: "ghidra_startup",
+ completed: 0,
+ total: null,
+ message,
+ });
+ }
+ return observed("0x1000");
+ },
};
const server = createServer({ kind: "fixed", analysis });
const client = new Client({ name: "progress-test", version: "1" });
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
- const progress: number[] = [];
+ const progress: {
+ progress: number;
+ total?: number | undefined;
+ message?: string | undefined;
+ }[] = [];
try {
await server.connect(serverTransport);
await client.connect(clientTransport);
const result = await client.callTool(
{ name: "current_address", arguments: {} },
- { onprogress: (update) => progress.push(update.progress) },
+ { onprogress: (update) => progress.push(update) },
);
expect(result.isError).not.toBe(true);
- expect(progress[0]).toBe(0);
- expect(progress.at(-1)).toBe(1);
- progress.forEach((value, index) => {
- expect(value).toBeGreaterThanOrEqual(progress[index - 1] ?? 0);
- expect(value).toBeLessThanOrEqual(1);
+ expect(progress[0]?.progress).toBe(1);
+ expect(progress.map((update) => update.message)).toEqual(
+ expect.arrayContaining([
+ "ghidra_startup: import pending",
+ "ghidra_startup: analysis pending",
+ ]),
+ );
+ expect(progress.at(-1)?.message).toContain("completed");
+ progress.forEach((update, index) => {
+ expect(update.progress).toBeGreaterThan(
+ progress[index - 1]?.progress ?? 0,
+ );
+ expect(update.total).toBeUndefined();
});
} finally {
await Promise.allSettled([client.close(), server.close()]);
diff --git a/tests/boundary/mcp/rawBinaryMcp.test.ts b/tests/boundary/mcp/rawBinaryMcp.test.ts
new file mode 100644
index 000000000..c1d2029c2
--- /dev/null
+++ b/tests/boundary/mcp/rawBinaryMcp.test.ts
@@ -0,0 +1,219 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { expect, it, onTestFinished } from "vitest";
+import { z } from "zod";
+
+import { createServer } from "../../../src/server/createServer.js";
+import { toolContract } from "../../../src/contracts/toolContracts.js";
+import type { AnalysisProvider } from "../../../src/application/AnalysisProvider.js";
+import { createAnalysisProfile } from "../../../src/domain/analysisProfile.js";
+import { ok } from "../../../src/domain/result.js";
+import { observed } from "../../fixtures/analysisExecution.js";
+import {
+ createCacheProvider,
+ createTestBinarySession,
+} from "../../fixtures/binarySession.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { silentLogger } from "../../../src/logger.js";
+import type { CallToolResult } from "@modelcontextprotocol/server";
+
+const connect = async (
+ provider: AnalysisProvider = createCacheProvider([]),
+) => {
+ const session = createTestBinarySession(provider);
+ const server = createServer(
+ { kind: "session", session },
+ { logger: silentLogger },
+ );
+ const client = new Client({ name: "raw-binary-mcp", version: "1" });
+ onTestFinished(async () => {
+ await client.close();
+ await server.close();
+ await session.close();
+ });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+ return { client, session };
+};
+
+const structured = (result: CallToolResult): Record => {
+ if (
+ typeof result.structuredContent !== "object" ||
+ result.structuredContent === null
+ )
+ throw new Error("missing structured result");
+ return z.record(z.string(), z.unknown()).parse(result.structuredContent);
+};
+
+it("opens a headerless image when architecture and entry are supplied", async () => {
+ const root = await createTestTempDirectory("rea-raw-mcp-");
+ const path = join(root, "ecu.bin");
+ await writeFile(path, Buffer.from("1eff2fe1", "hex"));
+ const { client } = await connect();
+ const opened = await client.callTool({
+ name: "open_binary",
+ arguments: {
+ path,
+ format: "raw-binary",
+ architecture: "arm",
+ entry_point: "0x08000000",
+ },
+ });
+ expect(opened.isError).not.toBe(true);
+ expect(structured(opened).result).toMatchObject({
+ path,
+ format: "raw-binary",
+ kind: "executable",
+ architecture: "arm",
+ entry_point: "0x8000000",
+ });
+});
+
+it("rejects an unaligned AArch64 entry before selecting or starting a provider", async () => {
+ const root = await createTestTempDirectory("rea-raw-mcp-alignment-");
+ const path = join(root, "image.bin");
+ await writeFile(path, Buffer.from("c0035fd6", "hex"));
+ const { client, session } = await connect({
+ ...createCacheProvider([]),
+ resolveAnalysisProfile: () => {
+ throw new Error("unaligned input must not select a provider");
+ },
+ createClient: () => {
+ throw new Error("unaligned input must not launch a provider");
+ },
+ });
+ const opened = await client.callTool({
+ name: "open_binary",
+ arguments: {
+ path,
+ format: "raw-binary",
+ architecture: "arm64",
+ entry_point: "0x8000001",
+ },
+ });
+ expect(opened.isError).toBe(true);
+ expect(JSON.stringify(opened.content)).toContain("must be 4-byte aligned");
+ expect(session.activeTarget()).toBeUndefined();
+});
+
+it("rejects raw-binary open requests that omit architecture", async () => {
+ const root = await createTestTempDirectory("rea-raw-mcp-missing-");
+ const path = join(root, "ecu.bin");
+ await writeFile(path, Buffer.from("1eff2fe1", "hex"));
+ const { client } = await connect();
+ const opened = await client.callTool({
+ name: "open_binary",
+ arguments: { path, format: "raw-binary" },
+ });
+ expect(opened.isError).toBe(true);
+});
+
+it("reuses a canonical raw entry and replaces the session when the entry changes", async () => {
+ const root = await createTestTempDirectory("rea-raw-mcp-reopen-");
+ const path = join(root, "ecu.bin");
+ await writeFile(path, Buffer.from("1eff2fe1", "hex"));
+ const fixture = createCacheProvider([]);
+ const resolved: string[] = [];
+ const created: string[] = [];
+ const closed: string[] = [];
+ const { client, session } = await connect({
+ ...fixture,
+ resolveAnalysisProfile: (target) => {
+ if (target.format !== "raw-binary")
+ throw new Error("expected raw binary");
+ resolved.push(target.entryPoint);
+ return Promise.resolve(
+ ok({
+ profile: createAnalysisProfile(
+ { ...fixture.identity(), version: "1" },
+ {
+ entry_point: target.entryPoint,
+ },
+ ),
+ }),
+ );
+ },
+ createClient: (target) => {
+ if (target.format !== "raw-binary")
+ throw new Error("expected raw binary");
+ created.push(target.entryPoint);
+ return {
+ execute: (operation) => {
+ if (operation !== "health" && operation !== "address_name")
+ throw new Error(`unexpected fixture operation: ${operation}`);
+ return Promise.resolve(observed(target.entryPoint));
+ },
+ close: () => {
+ closed.push(target.entryPoint);
+ return Promise.resolve(ok(null));
+ },
+ };
+ },
+ });
+ const tools = (await client.listTools()).tools;
+ const validateLifecycle = (
+ name: "open_binary" | "binary_session",
+ response: CallToolResult,
+ ) => {
+ const tool = tools.find((candidate) => candidate.name === name);
+ if (tool?.outputSchema === undefined)
+ throw new Error(`missing ${name} output schema`);
+ const schema = z.record(z.string(), z.unknown()).parse(tool.outputSchema);
+ const validate = new Ajv2020({
+ strict: false,
+ validateFormats: false,
+ }).compile(schema);
+ expect(
+ validate(response.structuredContent),
+ JSON.stringify(validate.errors),
+ ).toBe(true);
+ const parsed = toolContract(name).outputSchema.parse(
+ response.structuredContent,
+ );
+ const target = z.record(z.string(), z.unknown()).parse(parsed.result);
+ const { entry_point: _entry, ...missingEntry } = target;
+ expect(validate({ ...structured(response), result: missingEntry })).toBe(
+ false,
+ );
+ return target;
+ };
+ for (const entryPoint of ["0x08000000", "0x8000000", "0x09000000"]) {
+ const opened = await client.callTool({
+ name: "open_binary",
+ arguments: {
+ path,
+ format: "raw-binary",
+ architecture: "arm",
+ entry_point: entryPoint,
+ },
+ });
+ expect(opened.isError, JSON.stringify(opened)).not.toBe(true);
+ const canonical = `0x${BigInt(entryPoint).toString(16)}`;
+ expect(validateLifecycle("open_binary", opened).entry_point).toBe(
+ canonical,
+ );
+ const status = await client.callTool({
+ name: "binary_session",
+ arguments: {},
+ });
+ expect(status.isError, JSON.stringify(status)).not.toBe(true);
+ expect(validateLifecycle("binary_session", status).entry_point).toBe(
+ canonical,
+ );
+ const result = await client.callTool({
+ name: "address_name",
+ arguments: { address: entryPoint },
+ });
+ expect(result.isError, JSON.stringify(result)).not.toBe(true);
+ expect(structured(result).normalized_result).toBe(canonical);
+ }
+ expect(session.analysisProfile()?.parameters.entry_point).toBe("0x9000000");
+ expect(resolved).toEqual(["0x8000000", "0x9000000"]);
+ expect(created).toEqual(["0x8000000", "0x9000000"]);
+ expect(closed).toEqual(["0x8000000"]);
+});
diff --git a/tests/boundary/providers/ghidra/ghidraClient.test.ts b/tests/boundary/providers/ghidra/ghidraClient.test.ts
index 0e84f1769..5b04f6c47 100644
--- a/tests/boundary/providers/ghidra/ghidraClient.test.ts
+++ b/tests/boundary/providers/ghidra/ghidraClient.test.ts
@@ -8,9 +8,11 @@ import { fileURLToPath } from "node:url";
import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";
import pino from "pino";
import type { Logger } from "pino";
+import type { ProgressUpdate } from "../../../../src/application/ProgressReporter.js";
import { ok } from "../../../../src/domain/result.js";
import { GhidraClient } from "../../../../src/ghidra/GhidraClient.js";
+import { OwnedFileHandle } from "../../../../src/filesystem/OwnedFileHandle.js";
import { GHIDRA_PROCESS_DIAGNOSTIC_BYTES } from "../../../../src/ghidra/GhidraDiagnostics.js";
import { GhidraHeadlessLauncher } from "../../../../src/ghidra/GhidraLauncher.js";
import type { GhidraDiagnostic } from "../../../../src/ghidra/GhidraClientTypes.js";
@@ -121,12 +123,14 @@ const clientFor = (
readonly transport?: GhidraTransportKind;
readonly runId?: string;
readonly logger?: Logger;
+ readonly targetPath?: string;
+ readonly targetSha256?: string;
} = {},
): GhidraClient => {
const client = new GhidraClient({
launcher,
- targetPath: fixturePath,
- targetSha256: TARGET_SHA256,
+ targetPath: options.targetPath ?? fixturePath,
+ targetSha256: options.targetSha256 ?? TARGET_SHA256,
transport: options.transport ?? HOST_TRANSPORT,
providerVersion: PROVIDER_VERSION,
profileDigest: PROFILE_DIGEST,
@@ -146,7 +150,156 @@ afterEach(async () => {
await Promise.all(clients.splice(0).map((client) => client.close()));
});
+it("reports unknown startup work and stops notifications when cancellation releases the process", async () => {
+ vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });
+ const launcher = new FixtureLauncher("silent");
+ const client = clientFor(launcher, { startupTimeoutMs: 30_000 });
+ const controller = new AbortController();
+ const updates: ProgressUpdate[] = [];
+ const started = client.start(controller.signal, {
+ report: async (update) => {
+ updates.push(update);
+ controller.abort();
+ },
+ });
+ const child = await launcher.started;
+ await vi.advanceTimersByTimeAsync(10_000);
+ expect(await started).toMatchObject({
+ ok: false,
+ error: { kind: "cancelled" },
+ });
+ expect(updates).toEqual([
+ expect.objectContaining({
+ phase: "ghidra_startup",
+ completed: 0,
+ total: null,
+ message: expect.stringContaining("Waiting for Ghidra startup"),
+ }),
+ ]);
+ await client.close();
+ await expect(waitForChildExit(child, 5_000)).resolves.toBe(true);
+ await expect(access(launcher.runtimeRoots[0] ?? "")).rejects.toMatchObject({
+ code: "ENOENT",
+ });
+ await vi.advanceTimersByTimeAsync(30_000);
+ expect(updates).toHaveLength(1);
+});
+
+it("keeps one shared startup despite a failed progress sink and stops reports after readiness", async () => {
+ vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });
+ const launcher = new FixtureLauncher();
+ let releaseLaunch: (() => void) | undefined;
+ let markLaunchPending: (() => void) | undefined;
+ const launchPending = new Promise((resolve) => {
+ markLaunchPending = resolve;
+ });
+ const launchGate = new Promise((resolve) => {
+ releaseLaunch = resolve;
+ });
+ const client = clientFor(
+ {
+ async launch(session) {
+ markLaunchPending?.();
+ await launchGate;
+ return launcher.launch(session);
+ },
+ },
+ { startupTimeoutMs: 30_000 },
+ );
+ let reports = 0;
+ const started = client.start(undefined, {
+ report: async () => {
+ reports += 1;
+ throw new Error("notification unavailable");
+ },
+ });
+ const concurrent = client.start();
+ await launchPending;
+ await vi.advanceTimersByTimeAsync(10_000);
+ expect(reports).toBe(1);
+ releaseLaunch?.();
+ await expect(started).resolves.toMatchObject({ ok: true });
+ await expect(concurrent).resolves.toMatchObject({ ok: true });
+ expect(launcher.processes).toHaveLength(1);
+ await vi.advanceTimersByTimeAsync(30_000);
+ expect(reports).toBe(1);
+});
+
describe("GhidraClient captured source snapshot", () => {
+ it("retains a snapshot descriptor whose close failed until session cleanup succeeds", async () => {
+ const client = clientFor(new FixtureLauncher());
+ const started = await client.start();
+ if (!started.ok) throw started.error;
+ const close = vi
+ .spyOn(OwnedFileHandle.prototype, "close")
+ .mockRejectedValueOnce(new Error("snapshot descriptor close failed"));
+ try {
+ await expect(client.hashTargetSnapshot()).resolves.toMatchObject({
+ ok: false,
+ error: { kind: "protocol" },
+ });
+ const owner = close.mock.contexts[0];
+ expect(owner).toBeInstanceOf(OwnedFileHandle);
+ const closed = await client.close();
+ if (!closed.ok) throw closed.error;
+ expect(
+ close.mock.contexts.filter((context) => context === owner),
+ ).toHaveLength(2);
+ } finally {
+ close.mockRestore();
+ }
+ });
+
+ it("hashes complete private snapshots with bounded chunks and abortable reads", async () => {
+ const root = await createTestTempDirectory("rea-ghidra-hash-");
+ const source = join(root, "firmware.bin");
+ const bytes = Buffer.alloc(512 * 1024 + 3, 0xa5);
+ const sha256 = createHash("sha256").update(bytes).digest("hex");
+ await writeFile(source, bytes);
+ const client = clientFor(new FixtureLauncher(), {
+ targetPath: source,
+ targetSha256: sha256,
+ });
+ await expect(client.hashTargetSnapshot()).resolves.toMatchObject({
+ ok: false,
+ error: { kind: "protocol" },
+ });
+ const started = await client.start();
+ if (!started.ok) throw started.error;
+ // Observe the admitted private snapshot even if the original path changes.
+ await writeFile(source, "changed original");
+ const allocate = Buffer.allocUnsafe;
+ const allocations = vi.spyOn(Buffer, "allocUnsafe");
+ try {
+ const identity = await client.hashTargetSnapshot();
+ if (!identity.ok) throw identity.error;
+ expect(identity.value).toEqual({ sha256, bytes: bytes.length });
+ expect(allocations.mock.calls.length).toBeGreaterThan(1);
+ expect(
+ Math.max(...allocations.mock.calls.map(([size]) => size)),
+ ).toBeLessThan(bytes.length);
+ const controller = new AbortController();
+ allocations.mockImplementationOnce((size) => {
+ controller.abort();
+ return allocate(size);
+ });
+ await expect(
+ client.hashTargetSnapshot(controller.signal),
+ ).resolves.toMatchObject({ ok: false, error: { kind: "cancelled" } });
+ } finally {
+ allocations.mockRestore();
+ }
+ await expect(client.hashTargetSnapshot()).resolves.toMatchObject({
+ ok: true,
+ value: { sha256, bytes: bytes.length },
+ });
+ await client.close();
+ await expect(client.hashTargetSnapshot()).resolves.toMatchObject({
+ ok: false,
+ error: { kind: "protocol" },
+ });
+ });
+
it("exposes the immutable import snapshot only during the live session", async () => {
const client = clientFor(new FixtureLauncher());
await expect(client.readTargetSnapshot()).resolves.toMatchObject({
diff --git a/tests/boundary/providers/ghidra/ghidraLauncher.test.ts b/tests/boundary/providers/ghidra/ghidraLauncher.test.ts
index 1811b3108..89d8d5baa 100644
--- a/tests/boundary/providers/ghidra/ghidraLauncher.test.ts
+++ b/tests/boundary/providers/ghidra/ghidraLauncher.test.ts
@@ -113,6 +113,39 @@ describe("Ghidra COM loader", () => {
});
});
+describe("Ghidra raw-binary loader", () => {
+ it("loads caller-supplied architecture and entry before auto-analysis", () => {
+ const arguments_ = ghidraHeadlessArguments({
+ projectRoot: "/tmp/project",
+ targetPath: "/tmp/ecu.bin",
+ bridgeScriptPath: "/package/bridge/ReaGhidraBridge.java",
+ descriptorPath: "/tmp/session.json",
+ ghidraLogPath: "/tmp/ghidra.log",
+ scriptLogPath: "/tmp/script.log",
+ rawBinary: {
+ languageId: "ARM:LE:32:v7",
+ compilerSpecId: "default",
+ baseAddr: "0x8000000",
+ },
+ });
+ expectOptions(arguments_, [
+ ["-loader", "BinaryLoader"],
+ ["-loader-baseAddr", "0x8000000"],
+ ["-processor", "ARM:LE:32:v7"],
+ ["-cspec", "default"],
+ ]);
+ const prepare = arguments_.indexOf("-preScript");
+ expect(arguments_[prepare + 1]).toBe(
+ join("/package/bridge", "ReaGhidraPrepareRaw.java"),
+ );
+ expect(arguments_[prepare + 2]).toBe("ARM:LE:32:v7");
+ expect(arguments_[prepare + 3]).toBe("0x8000000");
+ expect(prepare).toBeLessThan(arguments_.indexOf("-postScript"));
+ expect(arguments_).toContain("-readOnly");
+ expect(arguments_).toContain("-deleteProject");
+ });
+});
+
describe("Ghidra headless launcher", () => {
it("forces the admitted real-mode language and loader for DOS MZ", () => {
const arguments_ = ghidraHeadlessArguments({
@@ -208,6 +241,20 @@ describe("Ghidra configured import language and seeds", () => {
).toThrow(/cannot be combined with a DOS import/u);
});
+ it("never combines a configured language with a raw-binary import", () => {
+ expect(() =>
+ ghidraHeadlessArguments({
+ ...base,
+ languageOverride: { languageId: "x86:LE:32:default" },
+ rawBinary: {
+ languageId: "ARM:LE:32:v7",
+ compilerSpecId: "default",
+ baseAddr: "0x8000000",
+ },
+ }),
+ ).toThrow(/cannot be combined with a raw-binary import/u);
+ });
+
it.each(["darwin", "win32"] as const)(
"applies seeds after loader preparation and before analysis scripts on %s",
(platform) => {
diff --git a/tests/boundary/providers/hopper/hopperAnalysisProfile.test.ts b/tests/boundary/providers/hopper/hopperAnalysisProfile.test.ts
index fd2a9c0db..a8f121e61 100644
--- a/tests/boundary/providers/hopper/hopperAnalysisProfile.test.ts
+++ b/tests/boundary/providers/hopper/hopperAnalysisProfile.test.ts
@@ -31,6 +31,27 @@ describe("Hopper analysis profiles", () => {
});
});
+ it("does not map caller-supplied raw binaries onto a Hopper loader", () => {
+ expect(
+ hopperLoaderArgsForTarget({
+ path: "/tmp/ecu.bin",
+ sha256: "a".repeat(64),
+ kind: "executable",
+ format: "raw-binary",
+ architecture: "arm",
+ availableArchitectures: ["arm"],
+ entryPoint: "0x8000000",
+ entryPointSource: "0x8000000",
+ }),
+ ).toMatchObject({
+ ok: false,
+ error: {
+ _tag: "ProviderAdapterError",
+ operation: "resolve_analysis_profile",
+ },
+ });
+ });
+
it.each([
[target("elf", "x86_64"), ["-l", "ELF", "--intel-64"]],
[target("pe", "x86"), ["-l", "WinPE", "--intel-32"]],
diff --git a/tests/boundary/providers/ida/selectorProvenance.test.ts b/tests/boundary/providers/ida/selectorProvenance.test.ts
new file mode 100644
index 000000000..e18a1d3af
--- /dev/null
+++ b/tests/boundary/providers/ida/selectorProvenance.test.ts
@@ -0,0 +1,131 @@
+import { rm } from "node:fs/promises";
+import { afterEach, describe, expect, it } from "vitest";
+import { EnhancedTools } from "../../../../src/application/EnhancedTools.js";
+import { IdaSessionClient } from "../../../../src/ida/IdaSessionClient.js";
+import type { JsonValue } from "../../../../src/domain/jsonValue.js";
+import { createIdaTarget, RecordingIdaMcp } from "../../../fixtures/idaMcp.js";
+
+const roots: string[] = [];
+afterEach(async () => {
+ for (const root of roots.splice(0))
+ await rm(root, { recursive: true, force: true });
+});
+
+const entry = { addr: "0x1000", name: "main", size: "0x20" };
+
+/** Headless session where `main` resolves, its external callee 0x2000 is not a function, and `nosuch` is unknown. */
+const session = async () => {
+ const { root, target } = await createIdaTarget();
+ roots.push(root);
+ const producer = new RecordingIdaMcp(target, "headless");
+ producer.overrideCall = (name, args): JsonValue | undefined => {
+ if (name !== "lookup_funcs") return undefined;
+ const queries = args.queries;
+ const query = Array.isArray(queries) ? String(queries[0]) : "";
+ if (query === "main" || query === "0x1000")
+ return [{ query, fn: entry, error: null }];
+ return [
+ {
+ query,
+ fn: null,
+ error: query === "nosuch" ? "Not found" : "Not a function",
+ },
+ ];
+ };
+ const client = new IdaSessionClient(
+ {
+ command: "fixture",
+ args: [],
+ env: {},
+ mode: "headless",
+ timeoutMs: 1000,
+ workspaceRoot: root,
+ },
+ target,
+ producer,
+ );
+ return { client, tools: new EnhancedTools(client) };
+};
+
+describe("provider-derived selectors in IDA composed workflows", () => {
+ it("records an external callee IDA cannot resolve as a producer fault in the call graph", async () => {
+ const { client, tools } = await session();
+ try {
+ const result = await tools.execute("get_call_graph", { address: "main" });
+
+ if (!result.ok) throw result.error;
+ expect(
+ result.value,
+ "the resolved root stays ok and only the derived node carries the producer fault",
+ ).toMatchObject({
+ "0": [{ address: "0x1000", status: "ok" }],
+ "1": [
+ {
+ address: "0x2000",
+ status: "error",
+ error: { code: "unreadable_output" },
+ },
+ ],
+ });
+ } finally {
+ expect((await client.close()).ok).toBe(true);
+ }
+ });
+
+ it("records the same node as a producer fault in the call path", async () => {
+ const { client, tools } = await session();
+ try {
+ const result = await tools.execute("trace_call_path", { start: "main" });
+
+ if (!result.ok) throw result.error;
+ expect(
+ result.value,
+ "the failure belongs to the derived address and is not blamed on the caller",
+ ).toMatchObject({
+ failures: [{ address: "0x2000", error: { code: "unreadable_output" } }],
+ });
+ } finally {
+ expect((await client.close()).ok).toBe(true);
+ }
+ });
+
+ it("keeps the caller's own unknown selector an invalid request in each workflow", async () => {
+ const { client, tools } = await session();
+ try {
+ const graph = await tools.execute("get_call_graph", {
+ address: "nosuch",
+ });
+ const trace = await tools.execute("trace_call_path", { start: "nosuch" });
+ const batch = await tools.execute("batch_decompile", {
+ addresses: ["nosuch"],
+ });
+
+ if (graph.ok || trace.ok) throw new Error("expected invalid requests");
+ expect(graph.error._tag, "graph start is caller input").toBe(
+ "AnalysisInputError",
+ );
+ expect(trace.error._tag, "trace start is caller input").toBe(
+ "AnalysisInputError",
+ );
+ if (!batch.ok) throw batch.error;
+ expect(
+ batch.value,
+ "the unresolved batch item and its fallback retry are both caller input",
+ ).toMatchObject({
+ items: [
+ {
+ address: "nosuch",
+ procedure: {
+ status: "unknown",
+ error: { code: "invalid_request" },
+ },
+ status: "error",
+ error: { code: "invalid_request" },
+ },
+ ],
+ });
+ } finally {
+ expect((await client.close()).ok).toBe(true);
+ }
+ });
+});
diff --git a/tests/composition/analysis-sessions/binarySession.test.ts b/tests/composition/analysis-sessions/binarySession.test.ts
index c0563e06b..aa809b6fb 100644
--- a/tests/composition/analysis-sessions/binarySession.test.ts
+++ b/tests/composition/analysis-sessions/binarySession.test.ts
@@ -1114,3 +1114,41 @@ describe("no replacement start", () => {
expect(session.status()).toMatchObject({ open: false });
});
});
+
+describe("selector origin forwarding", () => {
+ it("forwards the per-call selector origin to the provider client on both execution paths", async () => {
+ const [first] = await createBinarySessionTargets();
+ const seen: unknown[] = [];
+ const session = createTestBinarySession(() => ({
+ execute: (_operation, _parameters, options) => {
+ seen.push(options?.selectorOrigin);
+ return Promise.resolve(ok(null));
+ },
+ close: () => Promise.resolve(resultOk(null)),
+ }));
+ expect((await session.open(first)).ok, "the target opens").toBe(true);
+ seen.length = 0;
+
+ await session.execute(
+ "address_name",
+ { address: "0x1000" },
+ { selectorOrigin: "provider" },
+ );
+ await session.withAdmittedAnalysis(
+ "binary_overview",
+ undefined,
+ (analysis) =>
+ analysis.execute(
+ "address_name",
+ { address: "0x2000" },
+ { selectorOrigin: "provider" },
+ ),
+ );
+ await session.execute("address_name", { address: "0x3000" });
+
+ expect(
+ seen,
+ "direct and admitted calls forward the origin; an unmarked call carries none",
+ ).toEqual(["provider", "provider", undefined]);
+ });
+});
diff --git a/tests/conformance/android/ReaJadxMetadataRegression.java b/tests/conformance/android/ReaJadxMetadataRegression.java
index 852bee5fd..a0cbd9364 100644
--- a/tests/conformance/android/ReaJadxMetadataRegression.java
+++ b/tests/conformance/android/ReaJadxMetadataRegression.java
@@ -1,11 +1,16 @@
import com.atxx.jhmcp.*;
+import com.android.tools.smali.smali.Smali;
+import com.android.tools.smali.smali.SmaliOptions;
import com.google.gson.*;
import io.modelcontextprotocol.kotlin.sdk.types.CallToolResult;
import io.modelcontextprotocol.kotlin.sdk.types.TextContent;
import jadx.api.*;
import jadx.core.dex.nodes.*;
import java.lang.reflect.*;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.*;
import java.util.*;
+import java.util.zip.*;
import kotlin.coroutines.EmptyCoroutineContext;
import kotlinx.coroutines.BuildersKt;
@@ -37,6 +42,86 @@ public class ReaJadxMetadataRegression {
return value;
}
+ private static Path initializerFixture(String sources, String output) throws Exception {
+ Path directory = Path.of(output);
+ SmaliOptions options = new SmaliOptions();
+ options.apiLevel = 28;
+ options.jobs = 1;
+ options.outputDexFile = directory.resolve("initializers.dex").toString();
+ require(Smali.assemble(options, List.of(
+ Path.of(sources, "InitializationPolicy.smali").toString(),
+ Path.of(sources, "MixedInitialization.smali").toString())), "Initializer fixture assembly failed");
+ Path apk = directory.resolve("initializers.apk");
+ try (ZipOutputStream zip = new ZipOutputStream(Files.newOutputStream(apk))) {
+ zip.putNextEntry(new ZipEntry("classes.dex"));
+ Files.copy(Path.of(options.outputDexFile), zip);
+ zip.closeEntry();
+ }
+ return apk;
+ }
+
+ private static JsonObject methodArguments(String className, String methodName) {
+ JsonObject value = arguments(className);
+ value.addProperty("method_name", methodName);
+ value.addProperty("overload_index", 0);
+ return value;
+ }
+
+ private static void verifyInitializers(SessionHolder holder, SessionConfig config,
+ Constructor> constructor, Method handle, Path apk) throws Exception {
+ BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+ (scope, continuation) -> holder.unload(continuation));
+ BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+ (scope, continuation) -> holder.load(apk.toString(), config, continuation));
+ Object bridge = constructor.newInstance(holder);
+ String[] classNames = { "fixture.InitializationPolicy", "fixture.MixedInitialization" };
+ String[][] witnesses = {
+ { "declared-policy", "->singletonList", "->POLICY:Ljava/util/List;" },
+ { "field-value", "->LABEL:Ljava/lang/String;", "->touch()V" }
+ };
+ for (int index = 0; index < classNames.length; index++) {
+ JsonObject summary = call(handle, bridge, "get_class_summary", arguments(classNames[index]));
+ JsonObject input = methodArguments(classNames[index], "");
+ JsonObject body = call(handle, bridge, "get_method_body", input);
+ String text = body.get("body").getAsString();
+ for (String witness : witnesses[index]) require(text.contains(witness), "Missing initializer instruction: " + witness);
+ require(body.get("mode").getAsString().equals("smali"), "Static initializer must preserve DEX instructions");
+ require(body.get("fell_back").getAsBoolean(), "Disassembly fallback was not reported");
+ require(body.getAsJsonArray("markers").contains(new JsonPrimitive("static_initializer_disassembly")),
+ "Static initializer representation reason was not reported");
+ require(text.contains(".method static constructor ()V") && text.contains(".end method"),
+ "Initializer method boundaries missing");
+ require(body.get("overload_index").getAsInt() == 0 && body.get("overload_count").getAsInt() == 1,
+ "Initializer identity changed");
+ require(body.equals(call(handle, bridge, "get_method_body", input)), "Repeated initializer body changed");
+ require(summary.equals(call(handle, bridge, "get_class_summary", arguments(classNames[index]))),
+ "Frozen initializer metadata changed after source generation");
+ }
+ for (String name : List.of("missing", "originalNative")) {
+ JsonObject body = call(handle, bridge, "get_method_body", methodArguments(classNames[0], name));
+ String text = body.get("body").getAsString();
+ require(body.get("mode").getAsString().equals("java") && !text.contains("{") && !text.contains(".method"),
+ "Executable body was fabricated for " + name + ": " + text);
+ }
+ JsonObject ordinary = call(handle, bridge, "get_method_body", methodArguments(classNames[1], "touch"));
+ require(ordinary.get("mode").getAsString().equals("java") && ordinary.get("body").getAsString().contains("COUNT"),
+ "Ordinary executable method no longer produces Java");
+
+ SessionConfig bounded = new SessionConfig(96, 0, 90000L, 1, List.of(), List.of(), 64, ResourceMode.FULL);
+ BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+ (scope, continuation) -> holder.unload(continuation));
+ BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+ (scope, continuation) -> holder.load(apk.toString(), bounded, continuation));
+ JsonObject partial = call(handle, constructor.newInstance(holder), "get_method_body",
+ methodArguments(classNames[0], ""));
+ require(partial.get("mode").getAsString().equals("smali")
+ && partial.get("body").getAsString().contains("[truncated: exceeds 96 bytes, total "),
+ "Static initializer ignored the source byte limit or omitted its truncation marker");
+ String prefix = partial.get("body").getAsString().split("\n\n\\.\\.\\. \\[truncated:", 2)[0];
+ require(prefix.getBytes(StandardCharsets.UTF_8).length <= 96, "Initializer text exceeded its byte limit");
+ System.out.println("INITIALIZER_REGRESSION_PASS folded=2 bounded=true");
+ }
+
public static void main(String[] args) throws Exception {
SessionConfig config = new SessionConfig(1048576, 0, 90000L, 1, List.of(), List.of(), 64, ResourceMode.FULL);
SessionHolder holder = new SessionHolder(config);
@@ -89,6 +174,7 @@ public class ReaJadxMetadataRegression {
"Frozen summary changed after code generation");
require(apiSummary.equals(call(handle, bridge, "get_class_summary", apiArgs)), "Unrelated frozen summary changed");
System.out.println("METADATA_REGRESSION_PASS classes=" + states.size() + " overloads=" + signatures.size());
+ verifyInitializers(holder, config, constructor, handle, initializerFixture(args[1], args[2]));
} finally {
BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
(scope, continuation) -> holder.unload(continuation));
diff --git a/tests/fixtures/android/static-initializers/InitializationPolicy.smali b/tests/fixtures/android/static-initializers/InitializationPolicy.smali
new file mode 100644
index 000000000..9ad130d61
--- /dev/null
+++ b/tests/fixtures/android/static-initializers/InitializationPolicy.smali
@@ -0,0 +1,25 @@
+.class public abstract Lfixture/InitializationPolicy;
+.super Ljava/lang/Object;
+
+.field public static final POLICY:Ljava/util/List;
+
+.method static constructor ()V
+ .registers 1
+ const-string v0, "declared-policy"
+ invoke-static {v0}, Ljava/util/Collections;->singletonList(Ljava/lang/Object;)Ljava/util/List;
+ move-result-object v0
+ sput-object v0, Lfixture/InitializationPolicy;->POLICY:Ljava/util/List;
+ return-void
+.end method
+
+.method public constructor ()V
+ .registers 1
+ invoke-direct {p0}, Ljava/lang/Object;->()V
+ return-void
+.end method
+
+.method public abstract missing()V
+.end method
+
+.method public native originalNative()V
+.end method
diff --git a/tests/fixtures/android/static-initializers/MixedInitialization.smali b/tests/fixtures/android/static-initializers/MixedInitialization.smali
new file mode 100644
index 000000000..f06cd8703
--- /dev/null
+++ b/tests/fixtures/android/static-initializers/MixedInitialization.smali
@@ -0,0 +1,21 @@
+.class public Lfixture/MixedInitialization;
+.super Ljava/lang/Object;
+
+.field public static final LABEL:Ljava/lang/String;
+.field public static COUNT:I
+
+.method static constructor ()V
+ .registers 1
+ const-string v0, "field-value"
+ sput-object v0, Lfixture/MixedInitialization;->LABEL:Ljava/lang/String;
+ invoke-static {}, Lfixture/MixedInitialization;->touch()V
+ return-void
+.end method
+
+.method public static touch()V
+ .registers 1
+ sget v0, Lfixture/MixedInitialization;->COUNT:I
+ add-int/lit8 v0, v0, 0x1
+ sput v0, Lfixture/MixedInitialization;->COUNT:I
+ return-void
+.end method
diff --git a/tests/fixtures/hopperBridgeReconnectProbe.py b/tests/fixtures/hopperBridgeReconnectProbe.py
index 1ba4bebea..ff462519d 100644
--- a/tests/fixtures/hopperBridgeReconnectProbe.py
+++ b/tests/fixtures/hopperBridgeReconnectProbe.py
@@ -45,11 +45,21 @@ def probe(path, socket_path, mode):
assert time.monotonic() < deadline, failures
time.sleep(0.005)
- def connect():
- client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
- client.settimeout(2)
- client.connect(socket_path)
- return client, client.makefile("rwb")
+ def connect(wait_until_listening=False):
+ deadline = time.monotonic() + 2 if wait_until_listening else None
+ while True:
+ client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+ client.settimeout(2)
+ try:
+ client.connect(socket_path)
+ except OSError as error:
+ client.close()
+ if (not isinstance(error, ConnectionRefusedError)
+ or deadline is None or time.monotonic() >= deadline):
+ raise
+ time.sleep(0.005)
+ else:
+ return client, client.makefile("rwb")
def send(file, method, token="owned-token", params=None):
file.write((json.dumps({"id": 1, "method": method, "token": token, "params": params or {}}) + "\n").encode())
@@ -63,7 +73,8 @@ def probe(path, socket_path, mode):
if "event" not in value:
return value
- client, file = connect()
+ # bind() creates the socket path before listen() makes it connectable.
+ client, file = connect(wait_until_listening=True)
send(file, "health", "foreign-token" if mode == "unauthorized" else "owned-token")
if mode == "lost-reply":
assert entered.wait(2)