Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(elf): inspect PT_NOTE and SHT_NOTE tables (#4837)
Matt Van Horn2edf3b23c146
diff --git a/.agents/skills/reverse-engineer-anything/SKILL.md b/.agents/skills/reverse-engineer-anything/SKILL.mdindex f27a38db4..c9203a252 100644--- a/.agents/skills/reverse-engineer-anything/SKILL.md+++ b/.agents/skills/reverse-engineer-anything/SKILL.md@@ -219,6 +219,12 @@ explicit path or endpoint and do not need it.delivery requires `--evidence_output`.See the[Rust binary guide](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md).+- ELF note tables: `inspect_elf_notes` with the explicit local ELF32/ELF64+ file. This built-in target-free inspection requires no disassembler. Preserve+ PT_NOTE and SHT_NOTE ranges, owners, types, descriptor SHA-256, and GNU+ build-id or ABI-tag fields. A missing table is observed absence of those+ declarations, not proof the image never carried notes. See the+ [ELF notes guide](https://github.com/morluto/rea/blob/main/docs/elf-notes.md).- Explicit local SQLite database snapshot: `inspect_sqlite_database`. Inspectwith Node.js 24.x >=24.15 or 26+ providing native SQLite limits. Read schemadiff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.mdindex 9566ad11e..b31021e6b 100644--- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md+++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md@@ -96,6 +96,17 @@ dependencies. An omitted package kind stays null. A rustc commit hash isinferred from a read-only `/rustc/<40-hex>/` path and does not by itselfidentify the compiler. See [Rust binaries](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md).+## ELF note tables++Use `inspect_elf_notes` for an explicit local ELF32/ELF64 image when the+question concerns PT_NOTE/SHT_NOTE owners, GNU build-id, or GNU ABI-tag+fields. No `open_binary` or target execution is required. The CLI equivalent+is `inspect-elf-notes PATH`. Preserve artifact SHA-256, table file ranges,+descriptor hashes, and original owner spellings. A missing table is observed+absence of those declarations, not proof the image never carried notes in+another container. See+[ELF note tables](https://github.com/morluto/rea/blob/main/docs/elf-notes.md).+## SQLite snapshotsUse `inspect_sqlite_database` with an explicit local database snapshot for itsdiff --git a/README.md b/README.mdindex b0d470e45..0a8cd4992 100644--- a/README.md+++ b/README.md@@ -191,6 +191,7 @@ Additional tools and host support depend on the target:| IL2CPP metadata | Unity global-metadata.dat assembly images, type and method names and index ranges | Built-in static decoding of versions 24, 27, 29, 31 and 39; no Unity required || Godot PCK | Archive inventory and extraction, original header/directory facts and selected content identities | Built-in static formats 2, 3 and 4; no Godot required || Rust binaries | Embedded cargo-auditable crate names, versions, sources and dependency edges | Built-in static ELF/PE/thin Mach-O inspection; [Rust binaries](docs/rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](docs/elf-notes.md) || WASM artifact | Validation, sections, exact import/export WAT forms and decoded WAT | Caller-supplied WABT 1.0.42; `inspect_wasm_artifact` || EVM bytecode | Dispatch selectors, byte offsets, inferred arguments and mutability | Local raw/hex carrier on Linux x64; [offline EVM guide](docs/evm-bytecode.md) || SQLite databases | Tables, columns, indexes, views, triggers and selected ordinary-table rows | Local database/WAL snapshot; Node.js 24.x >=24.15 or 26+ with native SQLite limits |diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 86d825c13..e043d56db 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -32,6 +32,7 @@ export default defineConfig({{ text: "IL2CPP metadata", link: "/il2cpp-metadata" },{ text: "Model artifacts", link: "/model-artifacts" },{ text: "Rust dependencies", link: "/rust-binaries" },+ { text: "ELF notes", link: "/elf-notes" },{text: "JavaScript and Electron",link: "/javascript-artifact-reconstruction",diff --git a/docs/cli.md b/docs/cli.mdindex b263b323d..60496ebe4 100644--- a/docs/cli.md+++ b/docs/cli.md@@ -155,6 +155,16 @@ dependency edges, and the section's file range. A missing `.dep-v0` section isnull metadata, not proof that the binary has no dependencies. See[Rust binaries](rust-binaries.md).+Inspect ELF PT_NOTE and SHT_NOTE tables without executing the image:++```bash+rea inspect-elf-notes /absolute/path/to/program --json+```++The workflow reports note owners, types, descriptor hashes, and GNU build-id+or ABI-tag fields when those descriptors match. A missing note table is+observed absence of those declarations. See [ELF note tables](elf-notes.md).+Configure [Hopper or Ghidra](installation.md#hopper), the[IDA adapter](ida-provider.md), or [Kuna](kuna-provider.md) before analyzing anative target. Substitutediff --git a/docs/elf-notes.md b/docs/elf-notes.mdnew file mode 100644index 000000000..2627e4149--- /dev/null+++ b/docs/elf-notes.md@@ -0,0 +1,53 @@+# ELF note tables++`inspect_elf_notes` / `inspect-elf-notes` answers whether one selected local+ELF32/ELF64 image declares `PT_NOTE` program headers or `SHT_NOTE` sections,+which note owners and types those tables store, and which GNU build-id or+ABI-tag fields those notes carry. It reads the file without executing it and+does not require a disassembler, debug package, or package catalog.++```bash+rea inspect-elf-notes /absolute/path/to/program --json+```++The CLI resolves relative paths against the caller's working directory. MCP+requires an absolute filesystem path and preserves that exact selection:++```json+{+ "name": "inspect_elf_notes",+ "arguments": { "path": "/artifacts/program" }+}+```++## Observations++The inline Evidence result contains the artifact path, SHA-256, and byte length.+`tables` lists each declared note program header or section, including the+section name when a string table is present. Each `entries[]` item reports owner,+type, descriptor SHA-256, and a hex preview for descriptors of 64 bytes or less.++For GNU notes, `gnu.build_id_hex`, `gnu.abi_tag`, or `gnu.gold_version` are+filled when the descriptor matches that type. Other owners keep `gnu` null.++`PT_NOTE` and `SHT_NOTE` are examined independently. The same file range may+appear twice when both tables declare it.++A missing table list is observed absence of those declarations. It is not proof+the image never carried notes in another container or overlay.++## Limits and failures++The selected file is limited to 64 MiB by default (512 MiB maximum). At most+32 note entries are examined by default across every table. Retained note+names, section names, and GNU descriptor text share that file's byte budget,+and repeated table ranges count again. Each descriptor range is hashed once,+and each GNU version's trailing NUL run is scanned once; neither walk may+exceed that byte ceiling. Malformed ELF headers, truncated header+tables, declared note tables that extend past the file, and truncated+note entries fail without partial success. ELF extended+numbering (`PN_XNUM`, including a section count stored when `e_shnum` is 0) is+unsupported.++This workflow does not execute the image or verify GNU build-id uniqueness+against package catalogs.diff --git a/docs/index.md b/docs/index.mdindex 070b8aad5..0980ad312 100644--- a/docs/index.md+++ b/docs/index.md@@ -50,7 +50,7 @@ For runtime instrumentation, see the [Frida guide](./frida-instrumentation.md).| Task | Guides || --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || Identify a desktop installation | [Runtime candidates, evidence and follow-up files](desktop-applications.md) |-| Inspect native functions, references, or types | [Native binaries](native-investigation.md), [Go metadata](go-binaries.md), [Rust dependencies](rust-binaries.md), [offline ELF layout](binary-diagnostics.md), [recorded crashes](recorded-crashes.md) |+| Inspect native functions, references, or types | [Native binaries](native-investigation.md), [Go metadata](go-binaries.md), [Rust dependencies](rust-binaries.md), [ELF notes](elf-notes.md), [offline ELF layout](binary-diagnostics.md), [recorded crashes](recorded-crashes.md) || Select a native provider or import format | [Ghidra semantics](ghidra-provider.md), [Windows](windows-ghidra-p0.md), [DOS](ghidra-dos.md), [raw bytes](raw-binary.md), [MIPS](ghidra-mips.md), [PSP](ghidra-psp.md), [NativeAOT](ghidra-nativeaot.md), [IDA](ida-provider.md), [Kuna](kuna-provider.md), [JEB](jeb-analysis.md) || Analyze JavaScript or Electron artifacts | [Static analysis](javascript-artifact-reconstruction.md), [tracing and comparisons](javascript-application-workflows.md), [application graph](javascript-application-graph.md), [source recovery](javascript-recovery.md) || Compare static JavaScript with runtime observations | [Runtime attribution](javascript-runtime-observation.md), [reconciliation](javascript-runtime-reconciliation.md), [Electron observation](electron-observation.md), [Electron fuses](electron-fuses.md) |diff --git a/docs/readme/README_ar.md b/docs/readme/README_ar.mdindex 435ed3e7b..bc489aff6 100644--- a/docs/readme/README_ar.md+++ b/docs/readme/README_ar.md@@ -145,6 +145,7 @@ npx rea-agents@latest setup| بنية ELF دون تشغيل | الأقسام والمقاطع والرموز ومعلومات إعادة التموضع الأصلية، وآليات الحماية المحتملة المستدلّ عليها بالفحص الثابت | pwntools يوفّره المستدعي على Linux x64؛ [تشخيص الملفات الثنائية](../binary-diagnostics.md) || شيفرة EVM البايتية | محددات التوجيه، وإزاحات البايتات، والمعاملات المستنتجة، وقابلية تغيير الحالة | مدخل محلي يحمل بايتات خامًا أو تمثيلًا سداسيًا عشريًا على Linux x64؛ [دليل EVM دون تشغيل](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || أعطال Linux المسجّلة | سجلات note الخام، ومسجّلات المعالج/الإشارات لكل خيط مسجّل، وترشيحات اختيارية لخرائط الذاكرة | pwntools يوفّره المستدعي على Linux x64؛ GDB/pwndbg اختياريان؛ [الأعطال المسجّلة](../recorded-crashes.md) || تثبيتات سطح المكتب | عائلات وقت التشغيل، والملفات الداعمة، وعلامات المكونات، والخطوات التالية | فحص محدود للملفات والترويسات;[تطبيقات سطح المكتب](../desktop-applications.md) || JavaScript / Electron | الوحدات، وعمليات الاستيراد، وخرائط المصدر، والمسارات، وIPC، وعلاقات إضافات الشيفرة الأصلية | Node.js وnpm؛ [تحليل التطبيقات](../javascript-application-workflows.md) |diff --git a/docs/readme/README_de.md b/docs/readme/README_de.mdindex 5fddd80ff..cb5c7aaf1 100644--- a/docs/readme/README_de.md+++ b/docs/readme/README_de.md@@ -145,6 +145,7 @@ REA benötigt Node.js 22.x (>=22.19), 24.x (>=24.11) oder 26+ sowie npm. Zusätz| Offline-ELF-Struktur | Sektionen, Segmente, ursprüngliche Symbole/Relokationen und mögliche Schutzmaßnahmen aus statischer Analyse | Vom Aufrufer bereitgestelltes pwntools unter Linux x64; [Binärdiagnostik](../binary-diagnostics.md) || EVM-Bytecode | Dispatch-Selektoren, Byte-Offsets, abgeleitete Argumente und Veränderbarkeit des Zustands | Lokale Eingabe mit Rohbytes oder Hexdarstellung unter Linux x64; [Offline-EVM-Leitfaden](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || Aufgezeichnete Linux-Abstürze | Unverarbeitete Note-Einträge, Register/Signale aller aufgezeichneten Threads und optionale Zuordnungskandidaten | Vom Aufrufer bereitgestelltes pwntools unter Linux x64; optional GDB/pwndbg; [aufgezeichnete Abstürze](../recorded-crashes.md) || Desktop-Installationen | Laufzeitkandidaten, Quelldateien, Komponenten und nächste Schritte | Begrenzte Verzeichnis- und Headerprüfung;[Desktop-Anwendungen](../desktop-applications.md) || JavaScript / Electron | Module, Imports, Source Maps, Routen, IPC und Beziehungen zu nativen Add-ons | Node.js und npm; [Anwendungsanalyse](../javascript-application-workflows.md) |diff --git a/docs/readme/README_el.md b/docs/readme/README_el.mdindex 93ef1517d..330504ace 100644--- a/docs/readme/README_el.md+++ b/docs/readme/README_el.md@@ -149,6 +149,7 @@ npx rea-agents@latest setup| Δομή ELF χωρίς εκτέλεση | Ενότητες, τμήματα, αρχικά σύμβολα/εγγραφές μετεγκατάστασης και ενδείξεις πιθανών μέτρων προστασίας από στατική ανάλυση | pwntools που παρέχει ο χρήστης σε Linux x64· [διαγνωστικά δυαδικών αρχείων](../binary-diagnostics.md) || Δυαδικά αρχεία Go | Ενσωματωμένη έκδοση μεταγλωττιστή, modules, αντικαταστάσεις και ρυθμίσεις μεταγλώττισης | Ενσωματωμένη στατική εξέταση ELF/PE/thin Mach-O· δεν απαιτείται εγκατάσταση του Go || Δυαδικά αρχεία Rust | Ενσωματωμένα ονόματα, εκδόσεις, πηγές και σχέσεις εξάρτησης των crates από το cargo-auditable | Ενσωματωμένη στατική εξέταση ELF/PE/thin Mach-O· [δυαδικά αρχεία Rust](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || Αρχείο WASM | Έλεγχο εγκυρότητας, ενότητες, ακριβείς μορφές εισαγωγών/εξαγωγών σε WAT και αποκωδικοποιημένο WAT | WABT 1.0.42 που παρέχει ο χρήστης· `inspect_wasm_artifact` || Bytecode EVM | Selectors επιλογής συνάρτησης, μετατοπίσεις σε bytes, εκτιμώμενα ορίσματα και δυνατότητα μεταβολής της κατάστασης | Τοπική είσοδος σε ακατέργαστα bytes ή δεκαεξαδική μορφή σε Linux x64· [οδηγός EVM χωρίς εκτέλεση](../evm-bytecode.md) || Βάσεις δεδομένων SQLite | Πίνακες, στήλες, ευρετήρια, όψεις, triggers και επιλεγμένες γραμμές κανονικών πινάκων | Τοπικό στιγμιότυπο βάσης δεδομένων/WAL· Node.js 24.x >=24.15 ή 26+ με εγγενή όρια SQLite |diff --git a/docs/readme/README_es.md b/docs/readme/README_es.mdindex 02dc7cda3..f21d11224 100644--- a/docs/readme/README_es.md+++ b/docs/readme/README_es.md@@ -145,6 +145,7 @@ REA requiere Node.js 22.x (>=22.19), 24.x (>=24.11) o 26+, además de npm. Las h| Estructura ELF sin ejecutar | Secciones, segmentos, símbolos/reubicaciones originales y posibles medidas de mitigación detectadas mediante análisis estático | pwntools proporcionado por quien llama, en Linux x64; [diagnóstico de binarios](../binary-diagnostics.md) || Bytecode EVM | Selectores de despacho, desplazamientos en bytes, argumentos inferidos y mutabilidad | Entrada local con bytes sin procesar o representación hexadecimal, en Linux x64; [guía de EVM sin ejecutar](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || Fallos de Linux registrados | Registros note sin procesar, registros/señales de cada hilo registrado y posibles correspondencias de memoria opcionales | pwntools proporcionado por quien llama, en Linux x64; GDB/pwndbg opcionales; [fallos registrados](../recorded-crashes.md) || Instalaciones de escritorio | Posibles entornos de ejecución, archivos de evidencia, componentes y siguientes pasos | Inspección acotada de directorios y cabeceras;[Aplicaciones de escritorio](../desktop-applications.md) || JavaScript / Electron | Módulos, importaciones, mapas de código fuente, rutas, IPC y relaciones con complementos nativos | Node.js y npm; [análisis de aplicaciones](../javascript-application-workflows.md) |diff --git a/docs/readme/README_fa.md b/docs/readme/README_fa.mdindex 37a3355d9..a0b4ea0c3 100644--- a/docs/readme/README_fa.md+++ b/docs/readme/README_fa.md@@ -137,6 +137,7 @@ REA به Node.js 22.x (>=22.19)، 24.x (>=24.11) یا 26+، بههمراه np| ساختار ELF آفلاین | بخشها، سگمنتها، نمادها و relocationهای اصلی و گزینههای احتمالی کاهش آسیبپذیری ایستا | pwntools تأمینشده توسط فراخواننده روی Linux x64؛ [تشخیص باینری](../binary-diagnostics.md) || بایتکد EVM | selectorهای dispatch، offsetهای بایتی، آرگومانهای استنباطشده و قابلیت تغییر وضعیت | دادهٔ خام/hex محلی روی Linux x64؛ [راهنمای EVM آفلاین](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || کرشهای ثبتشدهٔ لینوکس | یادداشتهای خام، رجیسترها/سیگنالهای تمام threadهای ثبتشده و گزینههای احتمالی نگاشت | pwntools تأمینشده توسط فراخواننده روی Linux x64؛ GDB/pwndbg اختیاری؛ [کرشهای ثبتشده](../recorded-crashes.md) || نصبهای دسکتاپ | نامزدهای زمان اجرا، فایلهای شاهد، نشانههای مؤلفهها و مراحل بعدی | بررسی محدود پوشهها و سرآیندها;[برنامههای دسکتاپ](../desktop-applications.md) || JavaScript / Electron | ماژولها، importها، source mapها، مسیرها، IPC و ارتباط افزونههای بومی | Node.js و npm؛ [تحلیل برنامه](../javascript-application-workflows.md) |diff --git a/docs/readme/README_fr.md b/docs/readme/README_fr.mdindex 40083bd48..b5b001179 100644--- a/docs/readme/README_fr.md+++ b/docs/readme/README_fr.md@@ -149,6 +149,7 @@ REA nécessite Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, ainsi que npm. Les| 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](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.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](../recorded-crashes.md) || Installations de bureau | Environnements candidats, fichiers justificatifs, composants et étapes suivantes | Inspection bornée des répertoires et en-têtes;[Applications de bureau](../desktop-applications.md) || JavaScript / Electron | Modules, imports, source maps, routes, IPC et relations avec les modules natifs | Node.js et npm ; [analyse d'applications](../javascript-application-workflows.md) |diff --git a/docs/readme/README_id.md b/docs/readme/README_id.mdindex b8906ba2b..d06eb7d25 100644--- a/docs/readme/README_id.md+++ b/docs/readme/README_id.md@@ -152,6 +152,7 @@ Alat tambahan dan dukungan sistem host bergantung pada target yang dianalisis:| 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](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.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](../recorded-crashes.md) || Instalasi desktop | Kandidat runtime, berkas pendukung, penanda komponen, dan langkah berikutnya | Pemeriksaan direktori dan header terbatas;[Aplikasi desktop](../desktop-applications.md) || JavaScript / Electron | Modul, impor, source map, rute, IPC, dan hubungan add-on native | Node.js dan npm; [analisis aplikasi](../javascript-application-workflows.md) |diff --git a/docs/readme/README_it.md b/docs/readme/README_it.mdindex 6831919be..7d746d434 100644--- a/docs/readme/README_it.md+++ b/docs/readme/README_it.md@@ -149,6 +149,7 @@ REA richiede Node.js 22.x (>=22.19), 24.x (>=24.11) o 26+, oltre a npm. Strument| 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](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.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](../recorded-crashes.md) || Installazioni desktop | Runtime candidati, file di supporto, componenti e passi successivi | Ispezione limitata di directory e intestazioni;[Applicazioni desktop](../desktop-applications.md) || JavaScript / Electron | Moduli, import, source map, route, IPC e relazioni con add-on nativi | Node.js e npm; [analisi delle applicazioni](../javascript-application-workflows.md) |diff --git a/docs/readme/README_ja.md b/docs/readme/README_ja.mdindex 325287fa4..8764cec73 100644--- a/docs/readme/README_ja.md+++ b/docs/readme/README_ja.md@@ -145,6 +145,7 @@ REA には Node.js 22.x(>=22.19)、24.x(>=24.11)、または 26+ と npm| オフライン ELF レイアウト | セクション、セグメント、元のシンボル/再配置情報、静的解析によるセキュリティ対策の候補 | Linux x64 で利用者が用意する pwntools;[バイナリ診断](../binary-diagnostics.md) || EVM バイトコード | ディスパッチセレクター、バイトオフセット、推定された引数と状態変更の可否 | Linux x64 上のローカルの生バイト/16 進数の入力ファイル;[オフライン EVM ガイド](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || 記録済みの Linux クラッシュ | 生の note レコード、記録された全スレッドのレジスター/シグナル、任意のマッピング候補 | Linux x64 で利用者が用意する pwntools;GDB/pwndbg は任意;[記録済みクラッシュ](../recorded-crashes.md) || デスクトップのインストール先 | ランタイム候補、根拠ファイル、コンポーネントの目印、次の調査手順 | 上限付きのディレクトリ・ヘッダー検査;[デスクトップアプリ](../desktop-applications.md) || JavaScript / Electron | モジュール、インポート、ソースマップ、ルート、IPC、ネイティブアドオンの関係 | Node.js と npm;[アプリケーション分析](../javascript-application-workflows.md) |diff --git a/docs/readme/README_ko.md b/docs/readme/README_ko.mdindex 462fd08e2..2a75886fc 100644--- a/docs/readme/README_ko.md+++ b/docs/readme/README_ko.md@@ -153,6 +153,7 @@ REA에는 Node.js 22.x(>=22.19), 24.x(>=24.11) 또는 26+와 npm이 필요합니| 오프라인 ELF 레이아웃 | 섹션, 세그먼트, 원본 심볼/재배치 정보, 정적 분석으로 얻은 보안 완화 기법 후보 | Linux x64에서 호출자가 제공하는 pwntools; [바이너리 진단](../binary-diagnostics.md) || Go 바이너리 | 내장된 컴파일러 버전, 모듈, `replace` 지시어, 빌드 설정 | REA 내장 ELF/PE/thin Mach-O 정적 검사; Go 설치 불필요 || Rust 바이너리 | cargo-auditable이 내장한 크레이트 이름, 버전, 소스, 의존성 관계 | REA 내장 ELF/PE/thin Mach-O 정적 검사; [Rust 바이너리](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || WASM 아티팩트 | 유효성 검사, 섹션, import/export의 정확한 WAT 형식, 디코딩된 WAT | 호출자 제공 WABT 1.0.42; `inspect_wasm_artifact` || EVM 바이트코드 | 디스패치 선택자, 바이트 오프셋, 추론한 인자와 상태 변경 가능 여부 | Linux x64의 로컬 원시 바이트/16진수 입력 파일; [오프라인 EVM 가이드](../evm-bytecode.md) || SQLite 데이터베이스 | 테이블, 열, 인덱스, 뷰, 트리거, 선택한 일반 테이블의 행 | 로컬 데이터베이스/WAL 스냅샷; Node.js 24.15 이상의 24.x 또는 26 이상(네이티브 SQLite 한도 적용) |diff --git a/docs/readme/README_ml.md b/docs/readme/README_ml.mdindex 6dd281e90..c0b756dcc 100644--- a/docs/readme/README_ml.md+++ b/docs/readme/README_ml.md@@ -151,6 +151,7 @@ REA-യ്ക്ക് Node.js 22.x (>=22.19), 24.x (>=24.11), അല്ലെ| Offline ELF layout | Sections, segments, യഥാർത്ഥ symbols/relocations, static mitigation candidates | Linux x64-ൽ caller നൽകുന്ന pwntools; [binary diagnostics](../binary-diagnostics.md) || Go binaries | ഉൾച്ചേർത്ത compiler version, modules, replacements, build settings | Built-in static ELF/PE/thin Mach-O പരിശോധന; Go installation ആവശ്യമില്ല || Rust binaries | ഉൾച്ചേർത്ത cargo-auditable crate പേരുകൾ, versions, sources, dependency edges | Built-in static ELF/PE/thin Mach-O പരിശോധന; [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || WASM artifact | Validation, sections, കൃത്യമായ import/export WAT രൂപങ്ങൾ, decoded WAT | Caller നൽകുന്ന WABT 1.0.42; `inspect_wasm_artifact` || EVM bytecode | Dispatch selectors, byte offsets, അനുമാനിച്ച arguments, mutability | Linux x64-ൽ local raw/hex carrier; [offline EVM guide](../evm-bytecode.md) || SQLite databases | Tables, columns, indexes, views, triggers, തിരഞ്ഞെടുത്ത സാധാരണ table rows | Local database/WAL snapshot; native SQLite പരിമിതികളോടെ Node.js 24.x >=24.15 അല്ലെങ്കിൽ 26+ |diff --git a/docs/readme/README_pl.md b/docs/readme/README_pl.mdindex 1ae828eb1..d7a10010b 100644--- a/docs/readme/README_pl.md+++ b/docs/readme/README_pl.md@@ -145,6 +145,7 @@ REA wymaga Node.js 22.x (>=22.19), 24.x (>=24.11) lub 26+ oraz npm. Dodatkowe na| Układ pliku ELF w trybie offline | Sekcje, segmenty, oryginalne symbole/relokacje i potencjalne mechanizmy zabezpieczeń wskazane przez analizę statyczną | pwntools dostarczone przez użytkownika w systemie Linux x64; [diagnostyka plików binarnych](../binary-diagnostics.md) || Kod bajtowy EVM | Selektory wywołań, przesunięcia bajtowe, wywnioskowane argumenty i mutowalność | Lokalny plik z surowymi bajtami lub zapisem szesnastkowym w systemie Linux x64; [przewodnik EVM offline](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || Zarejestrowane awarie systemu Linux | Surowe rekordy note, rejestry/sygnały każdego zarejestrowanego wątku i opcjonalni kandydaci na mapowania | pwntools dostarczone przez użytkownika w systemie Linux x64; opcjonalnie GDB/pwndbg; [zarejestrowane awarie](../recorded-crashes.md) || Instalacje desktopowe | Kandydaci środowisk uruchomieniowych, pliki źródłowe dowodów, komponenty i dalsze kroki | Ograniczona inspekcja katalogów i nagłówków;[Aplikacje desktopowe](../desktop-applications.md) || JavaScript / Electron | Moduły, importy, mapy źródeł, trasy, IPC i powiązania z natywnymi dodatkami | Node.js i npm; [analiza aplikacji](../javascript-application-workflows.md) |diff --git a/docs/readme/README_pt-BR.md b/docs/readme/README_pt-BR.mdindex 139028136..3a1558406 100644--- a/docs/readme/README_pt-BR.md+++ b/docs/readme/README_pt-BR.md@@ -145,6 +145,7 @@ O REA requer Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, além do npm. As fer| Estrutura ELF sem execução | Seções, segmentos, símbolos/relocações originais e possíveis mecanismos de mitigação identificados por análise estática | pwntools fornecido pelo chamador no Linux x64; [diagnóstico de binários](../binary-diagnostics.md) || Bytecode EVM | Seletores de despacho, offsets de bytes, argumentos inferidos e mutabilidade | Entrada local com bytes brutos ou representação hexadecimal no Linux x64; [guia de EVM sem execução](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || Falhas do Linux registradas | Registros note brutos, registradores/sinais de cada thread registrada e candidatos opcionais a mapeamentos | pwntools fornecido pelo chamador no Linux x64; GDB/pwndbg opcionais; [falhas registradas](../recorded-crashes.md) || Instalações desktop | Ambientes candidatos, arquivos de evidência, componentes e próximos passos | Inspeção limitada de diretórios e cabeçalhos;[Aplicações desktop](../desktop-applications.md) || JavaScript / Electron | Módulos, importações, source maps, rotas, IPC e relações com complementos nativos | Node.js e npm; [análise de aplicativos](../javascript-application-workflows.md) |diff --git a/docs/readme/README_ru.md b/docs/readme/README_ru.mdindex 42234a8c0..65935f2d5 100644--- a/docs/readme/README_ru.md+++ b/docs/readme/README_ru.md@@ -145,6 +145,7 @@ REA требует Node.js 22.x (>=22.19), 24.x (>=24.11) или 26+, а так| Структура ELF без запуска | Секции, сегменты, исходные символы/релокации и возможные механизмы защиты по данным статического анализа | pwntools, предоставленный вызывающей стороной, в Linux x64; [диагностика бинарных файлов](../binary-diagnostics.md) || Байт-код EVM | Селекторы диспетчеризации, смещения байтов, предполагаемые аргументы и изменяемость состояния | Локальные необработанные байты или шестнадцатеричное представление в Linux x64; [руководство по EVM без запуска](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || Записанные сбои Linux | Необработанные записи note, регистры/сигналы каждого записанного потока и необязательные кандидаты сопоставления с памятью | pwntools, предоставленный вызывающей стороной, в Linux x64; необязательные GDB/pwndbg; [записанные сбои](../recorded-crashes.md) || Установленные настольные приложения | Возможные среды выполнения, файлы с доказательствами, компоненты и дальнейшие шаги | Ограниченная проверка каталогов и заголовков;[Настольные приложения](../desktop-applications.md) || JavaScript / Electron | Модули, импорты, карты исходного кода, маршруты, IPC и связи с нативными дополнениями | Node.js и npm; [анализ приложений](../javascript-application-workflows.md) |diff --git a/docs/readme/README_th.md b/docs/readme/README_th.mdindex f8203910e..4e3838a7d 100644--- a/docs/readme/README_th.md+++ b/docs/readme/README_th.md@@ -145,6 +145,7 @@ REA ต้องใช้ Node.js 22.x (>=22.19), 24.x (>=24.11) หรือ 26| โครงสร้าง ELF แบบออฟไลน์ | เซกชัน เซกเมนต์ สัญลักษณ์/รีโลเคชันต้นฉบับ และตัวเลือกกลไกป้องกันที่พบจากการวิเคราะห์แบบสถิต | pwntools ที่ผู้ใช้จัดเตรียมบน Linux x64; [การวินิจฉัยไบนารี](../binary-diagnostics.md) || ไบต์โค้ด EVM | ตัวเลือกฟังก์ชันสำหรับการเรียก ออฟเซ็ตไบต์ อาร์กิวเมนต์และความสามารถในการเปลี่ยนสถานะที่อนุมานได้ | ไฟล์บนเครื่องที่มีไบต์ดิบหรือข้อมูลเลขฐานสิบหกบน Linux x64; [คู่มือ EVM แบบออฟไลน์](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || ข้อมูลการแครชของ Linux ที่บันทึกไว้ | ระเบียน note ดิบ รีจิสเตอร์/สัญญาณของทุกเธรดที่บันทึกไว้ และตัวเลือกการแมปเพิ่มเติม | pwntools ที่ผู้ใช้จัดเตรียมบน Linux x64; เลือกใช้ GDB/pwndbg เพิ่มเติมได้; [การแครชที่บันทึกไว้](../recorded-crashes.md) || ไดเรกทอรีติดตั้งแอปเดสก์ท็อป | รันไทม์ที่เป็นไปได้ ไฟล์หลักฐาน ตัวบ่งชี้ส่วนประกอบ และขั้นตอนถัดไป | ตรวจสอบไดเรกทอรีและส่วนหัวโดยจำกัดขอบเขต;[แอปเดสก์ท็อป](../desktop-applications.md) || JavaScript / Electron | โมดูล การนำเข้า ซอร์สแมป เส้นทาง IPC และความสัมพันธ์กับส่วนเสริมเนทีฟ | Node.js และ npm; [การวิเคราะห์แอปพลิเคชัน](../javascript-application-workflows.md) |diff --git a/docs/readme/README_tr.md b/docs/readme/README_tr.mdindex 675827925..f55ccf71f 100644--- a/docs/readme/README_tr.md+++ b/docs/readme/README_tr.md@@ -147,6 +147,7 @@ REA; Node.js 22.x (>=22.19), 24.x (>=24.11) veya 26+ ve npm gerektirir. Ek araç| Çevrimdışı ELF yapısı | Bölümler, segmentler, özgün semboller/yeniden konumlandırmalar ve statik analizden olası güvenlik önlemleri | Linux x64 üzerinde çağıranın sağladığı pwntools; [ikili dosya tanılama](../binary-diagnostics.md) || Go ikili dosyaları | Gömülü compiler sürümü, modüller, replacement'lar ve build ayarları | Yerleşik statik ELF/PE/thin Mach-O incelemesi; Go kurulumu gerekmez || Rust ikili dosyaları | Gömülü cargo-auditable crate adları, sürümleri, kaynakları ve bağımlılık ilişkileri | Yerleşik statik ELF/PE/thin Mach-O incelemesi; [Rust ikili dosyaları](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || WASM artefaktı | Doğrulama, bölümler, tam import/export WAT biçimleri ve decode edilmiş WAT | Çağıranın sağladığı WABT 1.0.42; `inspect_wasm_artifact` || EVM bayt kodu | Yönlendirme seçicileri, bayt ofsetleri, çıkarımla belirlenen argümanlar ve durum değiştirilebilirliği | Linux x64 üzerinde yerel ham bayt/onaltılık girdi; [çevrimdışı EVM rehberi](../evm-bytecode.md) || SQLite veritabanları | Tablolar, sütunlar, index'ler, view'lar, trigger'lar ve seçilen sıradan tablo satırları | Yerel database/WAL snapshot'ı; native SQLite sınırlarıyla Node.js 24.x >=24.15 veya 26+ |diff --git a/docs/readme/README_uk.md b/docs/readme/README_uk.mdindex 59c29dbe1..56a3fd884 100644--- a/docs/readme/README_uk.md+++ b/docs/readme/README_uk.md@@ -145,6 +145,7 @@ REA потребує Node.js 22.x (>=22.19), 24.x (>=24.11) або 26+, а та| Структура ELF без запуску | Секції, сегменти, початкові символи/релокації та можливі захисні механізми за даними статичного аналізу | pwntools, наданий стороною, що викликає інструмент, у Linux x64; [діагностика бінарних файлів](../binary-diagnostics.md) || Байт-код EVM | Селектори диспетчеризації, зміщення байтів, виведені припущення про аргументи та змінюваність стану | Локальні необроблені байти або шістнадцяткове представлення у Linux x64; [посібник EVM без запуску](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || Записані аварійні завершення в Linux | Необроблені записи note, регістри/сигнали кожного записаного потоку й необов'язкові кандидати зіставлення пам'яті | pwntools, наданий стороною, що викликає інструмент, у Linux x64; необов'язкові GDB/pwndbg; [записані аварійні завершення](../recorded-crashes.md) || Встановлені настільні програми | Можливі середовища виконання, файли доказів, компоненти та наступні кроки | Обмежена перевірка каталогів і заголовків;[Настільні програми](../desktop-applications.md) || JavaScript / Electron | Модулі, імпорти, карти вихідного коду, маршрути, IPC і зв'язки з нативними доповненнями | Node.js і npm; [аналіз застосунків](../javascript-application-workflows.md) |diff --git a/docs/readme/README_vi.md b/docs/readme/README_vi.mdindex 72f66b8bd..a528d4f0e 100644--- a/docs/readme/README_vi.md+++ b/docs/readme/README_vi.md@@ -145,6 +145,7 @@ REA yêu cầu Node.js 22.x (>=22.19), 24.x (>=24.11) hoặc 26+, cùng với np| Bố cục ELF ngoại tuyến | Các section, segment, ký hiệu/thông tin tái định vị gốc và các biện pháp giảm thiểu có thể có từ phân tích tĩnh | pwntools do bên gọi cung cấp trên Linux x64; [chẩn đoán tệp nhị phân](../binary-diagnostics.md) || Bytecode EVM | Bộ chọn điều phối, độ lệch byte, tham số suy luận và khả năng thay đổi trạng thái | Đầu vào cục bộ chứa byte thô hoặc dạng thập lục phân trên Linux x64; [hướng dẫn EVM ngoại tuyến](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || Sự cố Linux đã ghi lại | Bản ghi note thô, thanh ghi/tín hiệu của mọi luồng được ghi lại và các ứng viên ánh xạ tùy chọn | pwntools do bên gọi cung cấp trên Linux x64; GDB/pwndbg tùy chọn; [sự cố đã ghi lại](../recorded-crashes.md) || Thư mục cài đặt ứng dụng máy tính | Các runtime có khả năng được dùng, tệp bằng chứng, dấu hiệu thành phần và bước tiếp theo | Kiểm tra thư mục và phần đầu tệp có giới hạn;[Ứng dụng máy tính](../desktop-applications.md) || JavaScript / Electron | Mô-đun, các khai báo import, source map, tuyến, IPC và quan hệ với tiện ích mở rộng mã máy | Node.js và npm; [phân tích ứng dụng](../javascript-application-workflows.md) |diff --git a/docs/readme/README_zh-TW.md b/docs/readme/README_zh-TW.mdindex 777dc0d58..cd2048bb9 100644--- a/docs/readme/README_zh-TW.md+++ b/docs/readme/README_zh-TW.md@@ -149,6 +149,7 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。| WASM 工件 | 驗證、節、精確的匯入/匯出 WAT 形式及解碼後的 WAT | 呼叫方提供的 WABT 1.0.42;`inspect_wasm_artifact` || EVM 位元組碼 | 分派選擇器、位元組偏移、推斷的參數和狀態可變性 | Linux x64 上的本地原始位元組/十六進位輸入載體;[離線 EVM 指南](../evm-bytecode.md) || Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) || 已記錄的 Linux 崩潰 | 原始 note 記錄、每個已記錄執行緒的暫存器/訊號及可選的對映候選項 | Linux x64 上由呼叫方提供的 pwntools;可選的 GDB/pwndbg;[已記錄崩潰](../recorded-crashes.md) || 桌面安裝目錄 | 執行階段候選、支持檔案、元件標記與後續操作 | 有界的目錄與檔頭檢查;[桌面應用](../desktop-applications.md) || JavaScript / Electron | 模組、匯入、source map、路由、IPC 和原生附加元件關係 | Node.js 和 npm;[應用分析](../javascript-application-workflows.md) |diff --git a/docs/readme/README_zh.md b/docs/readme/README_zh.mdindex e7fe365fb..b5f7a09bf 100644--- a/docs/readme/README_zh.md+++ b/docs/readme/README_zh.md@@ -141,32 +141,33 @@ npx rea-agents@latest setupREA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。额外工具和主机支持取决于分析目标:-| 目标 | REA 返回的内容 | 要求与指南 |-| --------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |-| 原生二进制文件 | 伪代码、汇编、字符串、符号、调用和引用 | Hopper、Ghidra 或 IDA;[原生分析](../native-investigation.md) |-| 离线 ELF 布局 | 节、段、原始符号/重定位信息及静态防护机制候选项 | Linux x64 上由调用方提供的 pwntools;[二进制诊断](../binary-diagnostics.md) |-| Go 二进制文件 | 内嵌编译器版本、模块、替换项和构建设置 | 内置静态 ELF/PE/thin Mach-O 检查;无需安装 Go |-| WASM 工件 | 验证、节、精确的导入/导出 WAT 形式及解码后的 WAT | 调用方提供的 WABT 1.0.42;`inspect_wasm_artifact` |-| EVM 字节码 | 分派选择器、字节偏移、推断的参数和状态可变性 | Linux x64 上的本地原始字节/十六进制输入载体;[离线 EVM 指南](../evm-bytecode.md) |-| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |-| 已记录的 Linux 崩溃 | 原始 note 记录、每个已记录线程的寄存器/信号及可选的映射候选项 | Linux x64 上由调用方提供的 pwntools;可选的 GDB/pwndbg;[已记录崩溃](../recorded-crashes.md) |-| 桌面安装目录 | 运行时候选、支持文件、组件标记和后续操作 | 有界的目录与文件头检查;[桌面应用](../desktop-applications.md) |-| JavaScript / Electron | 模块、导入、source map、路由、IPC 和原生扩展关系 | Node.js 和 npm;[应用分析](../javascript-application-workflows.md) |-| 网站 | 页面结构、脚本、网络观察结果和按请求获取的截图 | Chrome 系浏览器;[浏览器分析](../browser-observation.md) |-| 已保存的网络捕获 | 请求、响应、可访问的载荷和来源位置 | HAR;原生 mitmproxy 捕获需要 Linux 上的 mitmdump;[捕获指南](../web-network-captures.md) |-| 数据包捕获 | 端点、DNS、TLS SNI、协议分布和 HTTP 请求 | 调用方提供的 tshark 和 capinfos;[pcap 指南](../pcap-analysis.md) |-| .NET 程序集 | 元数据、CIL 指令、声明的原生依赖和构建对比 | 静态检查;[托管代码指南](../managed-code-analysis.md) |-| PyInstaller | CArchive, PYZ, Python bytecode | Static inspection; [Python packaged applications](../python-packaged-applications.md) |-| Android APK | 清单声明、类、反编译的方法和引用 | Linux/macOS/Windows x64 上的无界面 JADX 和完整 JDK;[Android 指南](../android-analysis.md) |-| Android 设备 | 设备、软件包、进程、日志、转储、屏幕截图以及 APK/文件传输 | 调用方提供的 adb(模拟器或实体设备);[ADB 指南](../adb-device-analysis.md) |-| JEB 项目 | 引擎支持的项目单元、工件摘要和类型/方法的伪代码 | 由调用方启动、提供 MCP 的 JEB 客户端,通过 REA_JEB_MCP_URL 选择;[JEB 指南](../jeb-analysis.md) |-| Android 资源 | 解码后的清单、字符串表、语言区域和版本信息 | 调用方提供的 Apktool 启动器;[资源指南](../apktool-resource-analysis.md) |-| Flutter 应用 | Dart 快照哈希、按 ABI 的库摘要及引擎构建溯源 | 无(静态 APK 解析);[Flutter 指南](../flutter-analysis.md) |-| 固件 | 区域、提取结果和转交原生分析的内容 | Linux 上的 Binwalk / Unblob;[固件指南](../firmware-analysis.md) |-| 抓包文件 | 指定字段、重复值、过滤条件与解码规则 | Linux: TShark 4.x + prlimit; [抓包分析指南](../packet-captures.md) |-| 录制的逻辑信号 | 解码注释、样本范围和诊断信息 | Linux: sigrok-cli 0.7.2 + prlimit; [信号记录指南](../signal-recordings.md) |-| 软件包与资源 | 文件清单、摘要、plist、Apple bundle 结构和提取的资源 | [制品与 JavaScript 指南](../javascript-artifact-reconstruction.md)、[Apple 应用](../apple-application-analysis.md) |-| 进程行为 | 终端输出、交互、退出和文件系统观察结果,以及运行对比 | 支持原生 PTY 的 Linux/macOS;[进程捕获](../process-capture.md) |+| 目标 | REA 返回的内容 | 要求与指南 |+| --------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |+| 原生二进制文件 | 伪代码、汇编、字符串、符号、调用和引用 | Hopper、Ghidra 或 IDA;[原生分析](../native-investigation.md) |+| 离线 ELF 布局 | 节、段、原始符号/重定位信息及静态防护机制候选项 | Linux x64 上由调用方提供的 pwntools;[二进制诊断](../binary-diagnostics.md) |+| Go 二进制文件 | 内嵌编译器版本、模块、替换项和构建设置 | 内置静态 ELF/PE/thin Mach-O 检查;无需安装 Go |+| WASM 工件 | 验证、节、精确的导入/导出 WAT 形式及解码后的 WAT | 调用方提供的 WABT 1.0.42;`inspect_wasm_artifact` |+| EVM 字节码 | 分派选择器、字节偏移、推断的参数和状态可变性 | Linux x64 上的本地原始字节/十六进制输入载体;[离线 EVM 指南](../evm-bytecode.md) |+| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |+| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |+| 已记录的 Linux 崩溃 | 原始 note 记录、每个已记录线程的寄存器/信号及可选的映射候选项 | Linux x64 上由调用方提供的 pwntools;可选的 GDB/pwndbg;[已记录崩溃](../recorded-crashes.md) |+| 桌面安装目录 | 运行时候选、支持文件、组件标记和后续操作 | 有界的目录与文件头检查;[桌面应用](../desktop-applications.md) |+| JavaScript / Electron | 模块、导入、source map、路由、IPC 和原生扩展关系 | Node.js 和 npm;[应用分析](../javascript-application-workflows.md) |+| 网站 | 页面结构、脚本、网络观察结果和按请求获取的截图 | Chrome 系浏览器;[浏览器分析](../browser-observation.md) |+| 已保存的网络捕获 | 请求、响应、可访问的载荷和来源位置 | HAR;原生 mitmproxy 捕获需要 Linux 上的 mitmdump;[捕获指南](../web-network-captures.md) |+| 数据包捕获 | 端点、DNS、TLS SNI、协议分布和 HTTP 请求 | 调用方提供的 tshark 和 capinfos;[pcap 指南](../pcap-analysis.md) |+| .NET 程序集 | 元数据、CIL 指令、声明的原生依赖和构建对比 | 静态检查;[托管代码指南](../managed-code-analysis.md) |+| PyInstaller | CArchive, PYZ, Python bytecode | Static inspection; [Python packaged applications](../python-packaged-applications.md) |+| Android APK | 清单声明、类、反编译的方法和引用 | Linux/macOS/Windows x64 上的无界面 JADX 和完整 JDK;[Android 指南](../android-analysis.md) |+| Android 设备 | 设备、软件包、进程、日志、转储、屏幕截图以及 APK/文件传输 | 调用方提供的 adb(模拟器或实体设备);[ADB 指南](../adb-device-analysis.md) |+| JEB 项目 | 引擎支持的项目单元、工件摘要和类型/方法的伪代码 | 由调用方启动、提供 MCP 的 JEB 客户端,通过 REA_JEB_MCP_URL 选择;[JEB 指南](../jeb-analysis.md) |+| Android 资源 | 解码后的清单、字符串表、语言区域和版本信息 | 调用方提供的 Apktool 启动器;[资源指南](../apktool-resource-analysis.md) |+| Flutter 应用 | Dart 快照哈希、按 ABI 的库摘要及引擎构建溯源 | 无(静态 APK 解析);[Flutter 指南](../flutter-analysis.md) |+| 固件 | 区域、提取结果和转交原生分析的内容 | Linux 上的 Binwalk / Unblob;[固件指南](../firmware-analysis.md) |+| 抓包文件 | 指定字段、重复值、过滤条件与解码规则 | Linux: TShark 4.x + prlimit; [抓包分析指南](../packet-captures.md) |+| 录制的逻辑信号 | 解码注释、样本范围和诊断信息 | Linux: sigrok-cli 0.7.2 + prlimit; [信号记录指南](../signal-recordings.md) |+| 软件包与资源 | 文件清单、摘要、plist、Apple bundle 结构和提取的资源 | [制品与 JavaScript 指南](../javascript-artifact-reconstruction.md)、[Apple 应用](../apple-application-analysis.md) |+| 进程行为 | 终端输出、交互、退出和文件系统观察结果,以及运行对比 | 支持原生 PTY 的 Linux/macOS;[进程捕获](../process-capture.md) |静态 JavaScript 和 .NET 检查读取提供的文件,不运行应用。运行时捕获会以你的用户权限运行目标或与之交互;各运行时指南说明了具体影响。diff --git a/scripts/lib/catalog-builders.mjs b/scripts/lib/catalog-builders.mjsindex 2ac0bb989..31557cea7 100644--- a/scripts/lib/catalog-builders.mjs+++ b/scripts/lib/catalog-builders.mjs@@ -250,6 +250,13 @@ export const providerCatalog = (sources) => {({ name }) => name === "inspect_pe_resources",),},+ {+ identity: sources.artifactProviders.ELF_NOTES_PROVIDER,+ contracts:+ sources.binaryDiagnosticsContracts.BINARY_DIAGNOSTICS_TOOL_CONTRACTS.filter(+ ({ name }) => name === "inspect_elf_notes",+ ),+ },{identity: sources.artifactProviders.BYTE_ENTROPY_PROVIDER,contracts:diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.tsindex cd3394ddd..bbcd1a953 100644--- a/src/application/CapabilityInventory.ts+++ b/src/application/CapabilityInventory.ts@@ -500,6 +500,8 @@ const workflowAvailabilityFor = ({};if (name === "inspect_pe_resources")return { reason: "available", remediation: null };+ if (name === "inspect_elf_notes")+ return { reason: "available", remediation: null };if (name === "inspect_evm_interface") {if (policy.evmInterfaceEnabled !== true)return {diff --git a/src/application/InvestigationProviders.ts b/src/application/InvestigationProviders.tsindex 00fcd5642..3ad47a962 100644--- a/src/application/InvestigationProviders.ts+++ b/src/application/InvestigationProviders.ts@@ -48,6 +48,13 @@ export const PE_RESOURCES_PROVIDER = Object.freeze({version: "1",} as const);+/** Provider identity for portable, execution-free ELF note-table decoding. */+export const ELF_NOTES_PROVIDER = Object.freeze({+ id: "rea-elf-notes",+ name: "REA ELF note parser",+ version: "1",+} as const);+/** Provider identity for execution-free Shannon byte-entropy profiling. */export const BYTE_ENTROPY_PROVIDER = Object.freeze({id: "byte-entropy",diff --git a/src/application/binaryDiagnostics/ElfNotesPort.ts b/src/application/binaryDiagnostics/ElfNotesPort.tsnew file mode 100644index 000000000..ad3c5a373--- /dev/null+++ b/src/application/binaryDiagnostics/ElfNotesPort.ts@@ -0,0 +1,20 @@+import type {+ ExecutionOptions,+ ProviderIdentity,+} from "../AnalysisProvider.js";+import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import type {+ InspectElfNotesInput,+ ElfNotes,+} from "../../domain/native/elfNotes.js";+import type { Result } from "../../domain/result.js";++/** Stable read and ELF note-table decoding, independent of a disassembler session. */+export interface ElfNotesPort {+ readonly identity: ProviderIdentity;+ close?(): Promise<void>;+ inspect(+ input: InspectElfNotesInput,+ options?: ExecutionOptions,+ ): Promise<Result<ElfNotes, AnalysisError>>;+}diff --git a/src/application/binaryDiagnostics/ElfNotesService.test.ts b/src/application/binaryDiagnostics/ElfNotesService.test.tsnew file mode 100644index 000000000..7f2fa63f9--- /dev/null+++ b/src/application/binaryDiagnostics/ElfNotesService.test.ts@@ -0,0 +1,79 @@+import { expect, it } from "vitest";+import { ElfNotesService } from "./ElfNotesService.js";+import { ELF_NOTES_PROVIDER } from "../InvestigationProviders.js";+import type { ElfNotes } from "../../domain/native/elfNotes.js";+import { ok } from "../../domain/result.js";+import {+ AnalysisCancelledError,+ AnalysisInputError,+} from "../../domain/analysisErrorCore.js";++const identity = ELF_NOTES_PROVIDER;+const report: ElfNotes = {+ artifact: {+ path: "/artifacts/app",+ sha256: "a".repeat(64),+ bytes: 512,+ },+ format: "elf64",+ byte_order: "little",+ machine: 62,+ type: 3,+ type_name: "shared",+ tables: [],+ entries: [],+ coverage: { status: "complete", examined_tables: 0, examined_entries: 0 },+ limitations: ["No PT_NOTE program header or SHT_NOTE section was declared."],+};++it("rejects a relative path and extra arguments before reading", async () => {+ let calls = 0;+ const service = new ElfNotesService({+ identity,+ inspect: () => {+ calls += 1;+ return Promise.resolve(ok(report));+ },+ });+ const relative = await service.inspect({ path: "app" });+ const extra = await service.inspect({+ path: report.artifact.path,+ extra: true,+ });+ expect(relative.ok).toBe(false);+ expect(extra.ok).toBe(false);+ if (!relative.ok) expect(relative.error).toBeInstanceOf(AnalysisInputError);+ if (!extra.ok) expect(extra.error).toBeInstanceOf(AnalysisInputError);+ expect(calls).toBe(0);+});++it("records the selected ELF and an absent note table", async () => {+ const result = await new ElfNotesService({+ identity,+ inspect: () => Promise.resolve(ok(report)),+ }).inspect({ path: report.artifact.path });+ expect(result.ok).toBe(true);+ if (!result.ok) throw result.error;+ expect(result.value).toMatchObject({+ confidence: "observed",+ subject: { format: "elf", architecture: "x86_64" },+ normalized_result: report,+ });+});++it("discards an observation if the caller cancels while the provider completes", async () => {+ const controller = new AbortController();+ const service = new ElfNotesService({+ identity,+ inspect: () => {+ controller.abort();+ return Promise.resolve(ok(report));+ },+ });+ const result = await service.inspect(+ { path: report.artifact.path },+ { signal: controller.signal },+ );+ expect(result.ok).toBe(false);+ if (!result.ok) expect(result.error).toBeInstanceOf(AnalysisCancelledError);+});diff --git a/src/application/binaryDiagnostics/ElfNotesService.ts b/src/application/binaryDiagnostics/ElfNotesService.tsnew file mode 100644index 000000000..e34f4effb--- /dev/null+++ b/src/application/binaryDiagnostics/ElfNotesService.ts@@ -0,0 +1,127 @@+import { isAbsolute } from "node:path";+import type { ExecutionOptions } from "../AnalysisProvider.js";+import type { ElfNotesPort } from "./ElfNotesPort.js";+import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import {+ AnalysisCancelledError,+ AnalysisInputError,+ AnalysisOutputError,+} from "../../domain/analysisErrorCore.js";+import { createEvidence, type Evidence } from "../../domain/evidence.js";+import {+ inspectElfNotesInputSchema,+ elfNotesSchema,+ type ElfNotes,+} from "../../domain/native/elfNotes.js";+import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";+import { BINARY_ARCHITECTURES } from "../../domain/binaryTargetTypes.js";+import { elfArchitecture } from "../../domain/elfFixedHeader.js";+import { err, type Result } from "../../domain/result.js";+import { completeProviderEvidence } from "../ProviderOperationExecution.js";++const OPERATION = "inspect_elf_notes";++/** Shared caller validation, output parsing and Evidence provenance for CLI/MCP. */+export class ElfNotesService {+ constructor(readonly provider: ElfNotesPort) {}++ close(): Promise<void> {+ return this.provider.close?.() ?? Promise.resolve();+ }++ async inspect(+ rawInput: unknown,+ options?: ExecutionOptions,+ ): Promise<Result<Evidence, AnalysisError>> {+ if (options?.signal?.aborted)+ return err(new AnalysisCancelledError(OPERATION));+ const input = inspectElfNotesInputSchema.safeParse(rawInput);+ if (!input.success)+ return err(+ analysisInputErrorFromIssues(OPERATION, input.error.issues, rawInput, {+ cause: input.error,+ }),+ );+ if (!isAbsolute(input.data.path))+ return err(+ new AnalysisInputError(OPERATION, undefined, [+ {+ path: ["path"],+ reason: "invalid_format",+ message: "Expected an absolute filesystem path on this host.",+ },+ ]),+ );+ const result = await this.provider.inspect(input.data, options);+ if (!result.ok) return result;+ const report = elfNotesSchema.safeParse(result.value);+ if (+ !report.success ||+ report.data.artifact.path !== input.data.path ||+ !validReport(+ report.data,+ input.data.max_entries,+ input.data.max_file_bytes,+ )+ )+ return err(+ new AnalysisOutputError(+ OPERATION,+ "ELF note provider returned malformed output or changed artifact identity.",+ ),+ );+ const value = report.data;+ const architecture = BINARY_ARCHITECTURES.find(+ (supported) => supported === elfArchitecture(value.machine),+ );+ const locations = [+ { kind: "artifact-path" as const, path: value.artifact.path },+ ...value.tables.map((table) => ({+ kind: "file-offset-range" as const,+ start: table.location.offset,+ end: table.location.offset + table.location.bytes,+ })),+ ];+ return completeProviderEvidence(+ createEvidence(+ {+ path: value.artifact.path,+ format: "elf",+ sha256: value.artifact.sha256,+ ...(architecture === undefined ? {} : { architecture }),+ },+ this.provider.identity,+ {+ operation: OPERATION,+ parameters: input.data,+ result: value,+ confidence: "observed",+ limitations: value.limitations,+ locations,+ },+ ),+ options?.signal,+ );+ }+}++const validReport = (+ report: ElfNotes,+ maxEntries: number,+ maxBytes: number,+): boolean => {+ const inside = ({ offset, bytes }: { offset: number; bytes: number }) =>+ offset <= report.artifact.bytes - bytes;+ if (+ report.artifact.bytes > maxBytes ||+ report.coverage.examined_entries > maxEntries ||+ report.entries.length > maxEntries+ )+ return false;+ return (+ report.tables.every((table) => inside(table.location)) &&+ report.entries.every(+ (entry) => inside(entry.location) && inside(entry.descriptor.location),+ )+ );+};diff --git a/src/cli/binaryDiagnosticsCommands.ts b/src/cli/binaryDiagnosticsCommands.tsindex 7b1eb9173..9e125c22d 100644--- a/src/cli/binaryDiagnosticsCommands.ts+++ b/src/cli/binaryDiagnosticsCommands.ts@@ -4,6 +4,7 @@ import {createByteEntropyService,createRecordedCrashService,createBinaryLayoutService,+ createElfNotesService,createPeResourcesService,} from "../composition/binaryDiagnostics.js";import { CLI_COMMANDS } from "../cliCommandNames.js";@@ -14,6 +15,7 @@ import { withCommandCancellation } from "./commandCancellation.js";import { inspectBinaryLayoutInputSchema } from "../domain/native/binaryLayout.js";import { inspectRecordedCrashInputSchema } from "../domain/native/recordedCrash.js";import { inspectPeResourcesInputSchema } from "../domain/native/peResources.js";+import { inspectElfNotesInputSchema } from "../domain/native/elfNotes.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";import { finishAnalysisCommand } from "./finishAnalysisCommand.js";import { absoluteCallerPath } from "../filesystem/callerPath.js";@@ -24,6 +26,39 @@ export const registerBinaryDiagnosticsCommands = (logger: Logger,environment: Readonly<NodeJS.ProcessEnv>,): void => {+ cli.command(CLI_COMMANDS.inspectElfNotes, {+ description:+ "Inspect ELF PT_NOTE and SHT_NOTE identities without executing the image",+ args: z.object({ path: z.string().describe("Local ELF32/ELF64 image") }),+ options: z.object({+ maxFileBytes: inspectElfNotesInputSchema.shape.max_file_bytes,+ maxEntries: inspectElfNotesInputSchema.shape.max_entries,+ }),+ run: ({ args, options }) =>+ withCommandCancellation(async (signal) => {+ const elf = createElfNotesService();+ return await logCliCommand(+ logger,+ CLI_COMMANDS.inspectElfNotes,+ async () =>+ finishAnalysisCommand(+ () =>+ elf.inspect(+ {+ path: absoluteCallerPath(args.path),+ max_file_bytes: options.maxFileBytes,+ max_entries: options.maxEntries,+ },+ { signal },+ ),+ elf,+ "rea-elf-notes",+ "inspect_elf_notes",+ signal,+ ),+ );+ }),+ });const entropy = createByteEntropyService();cli.command(CLI_COMMANDS.inspectByteEntropy, {description:diff --git a/src/cliCommandNames.ts b/src/cliCommandNames.tsindex 27eeca5bd..45b847f37 100644--- a/src/cliCommandNames.ts+++ b/src/cliCommandNames.ts@@ -66,6 +66,7 @@ export const CLI_COMMANDS = Object.freeze({inspectGpuCodeObjects: "inspect-gpu-code-objects",inspectRustBinary: "inspect-rust-binary",inspectPeResources: "inspect-pe-resources",+ inspectElfNotes: "inspect-elf-notes",inspectAnalysisView: "inspect-analysis-view",listFridaDevices: "list-frida-devices",listFridaProcesses: "list-frida-processes",diff --git a/src/composition/binaryDiagnostics.ts b/src/composition/binaryDiagnostics.tsindex 4d9cfc69c..e17ed4e22 100644--- a/src/composition/binaryDiagnostics.ts+++ b/src/composition/binaryDiagnostics.ts@@ -5,12 +5,18 @@ import { BinaryLayoutService } from "../application/binaryDiagnostics/BinaryLayoimport { PwntoolsLayoutProvider } from "../native/pwntools/PwntoolsLayoutProvider.js";import { PeResourcesService } from "../application/binaryDiagnostics/PeResourcesService.js";import { PeResourcesProvider } from "../native/pe/PeResourcesProvider.js";+import { ElfNotesService } from "../application/binaryDiagnostics/ElfNotesService.js";+import { ElfNotesProvider } from "../native/elf/ElfNotesProvider.js";import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";/** Portable PE inspection with no engine, installation or target acquisition. */export const createPeResourcesService = (): PeResourcesService =>new PeResourcesService(new PeResourcesProvider());+/** Portable ELF note-table inspection with no engine or package catalog. */+export const createElfNotesService = (): ElfNotesService =>+ new ElfNotesService(new ElfNotesProvider());+/** Compose the offline adapter without import-time I/O or dependency acquisition. */export const createBinaryLayoutService = (environment: Readonly<NodeJS.ProcessEnv> = process.env,diff --git a/src/contracts/native/binaryDiagnosticsToolContracts.ts b/src/contracts/native/binaryDiagnosticsToolContracts.tsindex 0e31d8ef3..9c63f3aa5 100644--- a/src/contracts/native/binaryDiagnosticsToolContracts.ts+++ b/src/contracts/native/binaryDiagnosticsToolContracts.ts@@ -21,6 +21,10 @@ import {inspectPeResourcesInputSchema,peResourcesSchema,} from "../../domain/native/peResources.js";+import {+ inspectElfNotesInputSchema,+ elfNotesSchema,+} from "../../domain/native/elfNotes.js";/** Caller-selected delivery of completed binary layout Evidence. */export const inspectBinaryLayoutRequestSchema =@@ -36,6 +40,21 @@ export const inspectByteEntropyRequestSchema = publicInputStrictObject(/** Offline binary diagnostics are independent of macOS process/UI providers. */export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [+ {+ name: "inspect_elf_notes",+ ...toolContractMetadata("inspect_elf_notes"),+ kind: "native-provider",+ description:+ "Inspect one explicit local ELF32/ELF64 image's PT_NOTE program headers and SHT_NOTE sections without executing it or opening a disassembler. Returns note-table file ranges, owners, types, descriptor SHA-256 and hex previews, plus GNU build-id, ABI-tag and gold-version fields when those descriptors match. A missing table is observed absence of those declarations, not proof the image never carried notes in another container. Reads a stable regular file; malformed ELF headers, truncated notes and exhausted budgets return no partial success. Portable on supported Node hosts; no debug package or catalog is required.",+ inputSchema: inspectElfNotesInputSchema,+ outputSchema: evidenceResultOf(elfNotesSchema),+ examples: [+ {+ title: "Inspect ELF GNU build-id and ABI-tag notes",+ input: { path: "/artifacts/program" },+ },+ ],+ },{name: "inspect_byte_entropy",...toolContractMetadata("inspect_byte_entropy"),diff --git a/src/contracts/toolEffects.test.ts b/src/contracts/toolEffects.test.tsindex 0403a6d96..8c448d908 100644--- a/src/contracts/toolEffects.test.ts+++ b/src/contracts/toolEffects.test.ts@@ -27,6 +27,7 @@ const EXECUTION_WORDING_EXCEPTIONS: Readonly<Record<string, string>> = {resolve_native_call_targets: "states that it does not execute code",inspect_byte_entropy: "states that it profiles the file without execution",inspect_pe_resources: "states that it does not execute the image",+ inspect_elf_notes: "states that it does not execute the image",inspect_desktop_application:"states that directory triage performs no target execution",inspect_go_binary: "reads embedded metadata without executing the target",diff --git a/src/contracts/toolEffects.ts b/src/contracts/toolEffects.tsindex 24d8e2989..8a855a285 100644--- a/src/contracts/toolEffects.ts+++ b/src/contracts/toolEffects.ts@@ -253,6 +253,7 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {}),inspect_byte_entropy: evidence,inspect_pe_resources: evidence,+ inspect_elf_notes: evidence,inspect_analysis_view: evidence,inspect_firmware_regions: effects({mutatesSession: true,diff --git a/src/domain/artifactOperationError.ts b/src/domain/artifactOperationError.tsindex e16e76770..a4dce9a6f 100644--- a/src/domain/artifactOperationError.ts+++ b/src/domain/artifactOperationError.ts@@ -26,6 +26,7 @@ export class ArtifactOperationError extends AnalysisError {| "inspect_artifact"| "inspect_desktop_application"| "inspect_pe_resources"+ | "inspect_elf_notes"| "extract_artifact"| "decode_interface_builder"| "inspect_asset_catalog"diff --git a/src/domain/elfFixedHeader.ts b/src/domain/elfFixedHeader.tsindex 38ae7c01d..030d7952c 100644--- a/src/domain/elfFixedHeader.ts+++ b/src/domain/elfFixedHeader.ts@@ -70,7 +70,7 @@ export const readElfFixedHeader = (});};-const elfArchitecture = (+export const elfArchitecture = (machine: number,): Exclude<BinaryArchitecture, RawOnlyArchitecture> | undefined => {switch (machine) {diff --git a/src/domain/native/elfNotes.test.ts b/src/domain/native/elfNotes.test.tsnew file mode 100644index 000000000..9aa98f45d--- /dev/null+++ b/src/domain/native/elfNotes.test.ts@@ -0,0 +1,47 @@+import { expect, it } from "vitest";+import {+ elfObjectTypeName,+ gnuNoteTypeName,+ inspectElfNotesInputSchema,+ elfNotesSchema,+} from "./elfNotes.js";++it("maps ELF object and GNU note types without inventing unknown names", () => {+ expect(elfObjectTypeName(1)).toBe("relocatable");+ expect(elfObjectTypeName(2)).toBe("executable");+ expect(elfObjectTypeName(3)).toBe("shared");+ expect(elfObjectTypeName(4)).toBe("core");+ expect(elfObjectTypeName(99)).toBe("unknown");+ expect(gnuNoteTypeName(1)).toBe("gnu_abi_tag");+ expect(gnuNoteTypeName(3)).toBe("gnu_build_id");+ expect(gnuNoteTypeName(99)).toBe("unknown");+});++it("rejects extra caller arguments and admits an empty note inventory", () => {+ expect(+ inspectElfNotesInputSchema.safeParse({+ path: "/artifacts/app",+ extra: true,+ }).success,+ ).toBe(false);+ const report = elfNotesSchema.parse({+ artifact: {+ path: "/artifacts/app",+ sha256: "a".repeat(64),+ bytes: 512,+ },+ format: "elf64",+ byte_order: "little",+ machine: 62,+ type: 3,+ type_name: "shared",+ tables: [],+ entries: [],+ coverage: { status: "complete", examined_tables: 0, examined_entries: 0 },+ limitations: [+ "No PT_NOTE program header or SHT_NOTE section was declared.",+ ],+ });+ expect(report.tables).toEqual([]);+ expect(report.entries).toEqual([]);+});diff --git a/src/domain/native/elfNotes.ts b/src/domain/native/elfNotes.tsnew file mode 100644index 000000000..b6d60974d--- /dev/null+++ b/src/domain/native/elfNotes.ts@@ -0,0 +1,161 @@+import { z } from "zod";++import { digestSchema } from "../digests.js";+import { localPathStringSchema } from "../localPath.js";++const uint = z.number().int().min(0).max(0xffffffff);+const range = z.strictObject({ offset: uint, bytes: uint });++/** Hard ceiling on the caller-selected input read budget. */+export const MAX_INSPECT_ELF_NOTE_FILE_BYTES = 536870912;+/** Hard ceiling on decoded note entries across every declared table. */+export const MAX_INSPECT_ELF_NOTE_ENTRIES = 256;++export const ELF_NOTE_TYPE_NAMES = [+ "gnu_abi_tag",+ "gnu_hwcap",+ "gnu_build_id",+ "gnu_gold_version",+ "gnu_property",+ "unknown",+] as const;+export type ElfNoteTypeName = (typeof ELF_NOTE_TYPE_NAMES)[number];++export const ELF_OBJECT_TYPE_NAMES = [+ "relocatable",+ "executable",+ "shared",+ "core",+ "unknown",+] as const;+export type ElfObjectTypeName = (typeof ELF_OBJECT_TYPE_NAMES)[number];++/** Map e_type without inventing names for unknown object kinds. */+export const elfObjectTypeName = (type: number): ElfObjectTypeName => {+ switch (type) {+ case 1:+ return "relocatable";+ case 2:+ return "executable";+ case 3:+ return "shared";+ case 4:+ return "core";+ default:+ return "unknown";+ }+};++/** Map GNU n_type when the owner is GNU; other owners stay unknown. */+export const gnuNoteTypeName = (type: number): ElfNoteTypeName => {+ switch (type) {+ case 1:+ return "gnu_abi_tag";+ case 2:+ return "gnu_hwcap";+ case 3:+ return "gnu_build_id";+ case 4:+ return "gnu_gold_version";+ case 5:+ return "gnu_property";+ default:+ return "unknown";+ }+};++/** Complete bounded inspection of ELF PT_NOTE and SHT_NOTE tables. */+export const inspectElfNotesInputSchema = z.strictObject({+ path: localPathStringSchema.describe(+ "Absolute filesystem path to an ELF image",+ ),+ max_file_bytes: z+ .number()+ .int()+ .min(64)+ .max(MAX_INSPECT_ELF_NOTE_FILE_BYTES)+ .default(67108864)+ .describe("Maximum stable artifact bytes to read (default 64 MiB)"),+ max_entries: z+ .number()+ .int()+ .min(1)+ .max(MAX_INSPECT_ELF_NOTE_ENTRIES)+ .default(32)+ .describe(+ "Maximum note entries to examine across every table; exceeding the budget fails without partial success",+ ),+});++const gnuAbiTagSchema = z.strictObject({+ os: uint,+ os_name: z.string().nullable(),+ major: uint,+ minor: uint,+ subminor: uint,+});++const noteEntrySchema = z.strictObject({+ index: uint,+ table_kind: z.enum(["program", "section"]),+ table_index: uint,+ location: range,+ namesz: uint,+ descsz: uint,+ type: uint,+ type_name: z.enum(ELF_NOTE_TYPE_NAMES),+ owner: z.string(),+ owner_bytes_hex: z.string().regex(/^[0-9a-f]*$/),+ descriptor: z.strictObject({+ location: range,+ bytes: uint,+ sha256: digestSchema,+ hex: z+ .string()+ .regex(/^[0-9a-f]*$/)+ .nullable(),+ }),+ gnu: z+ .strictObject({+ build_id_hex: z+ .string()+ .regex(/^[0-9a-f]*$/)+ .nullable(),+ abi_tag: gnuAbiTagSchema.nullable(),+ gold_version: z.string().nullable(),+ })+ .nullable(),+});++/** Observed ELF note tables; absence is an empty list, not proof notes never existed. */+export const elfNotesSchema = z.strictObject({+ artifact: z.strictObject({+ path: z.string().min(1),+ sha256: digestSchema,+ bytes: uint,+ }),+ format: z.enum(["elf32", "elf64"]),+ byte_order: z.enum(["little", "big"]),+ machine: uint,+ type: uint,+ type_name: z.enum(ELF_OBJECT_TYPE_NAMES),+ tables: z.array(+ z.strictObject({+ kind: z.enum(["program", "section"]),+ index: uint,+ name: z.string().nullable(),+ location: range,+ alignment: uint,+ }),+ ),+ entries: z.array(noteEntrySchema),+ coverage: z.strictObject({+ status: z.literal("complete"),+ examined_tables: uint,+ examined_entries: uint,+ }),+ limitations: z.array(z.string()),+});++export type ElfNotes = z.infer<typeof elfNotesSchema>;+export type InspectElfNotesInput = z.infer<typeof inspectElfNotesInputSchema>;diff --git a/src/native/elf/ElfNoteParser.test.ts b/src/native/elf/ElfNoteParser.test.tsnew file mode 100644index 000000000..730fae623--- /dev/null+++ b/src/native/elf/ElfNoteParser.test.ts@@ -0,0 +1,406 @@+import { createHash } from "node:crypto";+import { readFileSync } from "node:fs";+import { expect, it } from "vitest";+import { inspectElfNotesInputSchema } from "../../domain/native/elfNotes.js";+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";+import {+ elfNote,+ elfNoteFixture,+ elfNoteTablePastEnd,+ gnuAbiTagNote,+ gnuBuildIdNote,+ gnuPropertyNote,+} from "./ElfNotes.fixture.js";+import { parseElfNotes } from "./ElfNoteParser.js";++const defaults = inspectElfNotesInputSchema.parse({+ path: "/artifacts/app",+});++const parse = (bytes: Buffer, input: typeof defaults = defaults) =>+ parseElfNotes(+ bytes,+ {+ path: input.path,+ sha256: createHash("sha256").update(bytes).digest("hex"),+ bytes: bytes.length,+ },+ input,+ );++const elf64 = (+ fields: {+ readonly phoff?: number;+ readonly shoff?: number;+ readonly phnum?: number;+ readonly shnum?: number;+ readonly phentsize?: number;+ readonly shentsize?: number;+ },+ tail?: Buffer,+): Buffer => {+ const header = Buffer.alloc(64);+ header.write("\x7fELF", 0, "latin1");+ header[4] = 2;+ header[5] = 1;+ header[6] = 1;+ header.writeUInt16LE(2, 16);+ header.writeUInt16LE(62, 18);+ header.writeUInt32LE(1, 20);+ header.writeBigUInt64LE(BigInt(fields.phoff ?? 0), 32);+ header.writeBigUInt64LE(BigInt(fields.shoff ?? 0), 40);+ header.writeUInt16LE(64, 52);+ header.writeUInt16LE(fields.phentsize ?? 56, 54);+ header.writeUInt16LE(fields.phnum ?? 0, 56);+ header.writeUInt16LE(fields.shentsize ?? 64, 58);+ header.writeUInt16LE(fields.shnum ?? 0, 60);+ return tail === undefined ? header : Buffer.concat([header, tail]);+};++it("reads GNU build-id and ABI-tag notes from ELF32 and ELF64", () => {+ for (const bits of [32, 64] as const) {+ const bytes = elfNoteFixture({ bits, ownership: "program" });+ const report = parse(bytes);+ expect(report.format).toBe(bits === 64 ? "elf64" : "elf32");+ expect(report.byte_order).toBe("little");+ expect(report.tables).toHaveLength(1);+ expect(report.tables[0]?.kind).toBe("program");+ const buildId = report.entries.find(+ (entry) => entry.type_name === "gnu_build_id",+ );+ const abi = report.entries.find(+ (entry) => entry.type_name === "gnu_abi_tag",+ );+ expect(buildId?.gnu?.build_id_hex).toBe(+ "0123456789abcdef0123456789abcdef01234567",+ );+ expect(abi?.gnu?.abi_tag).toMatchObject({+ os: 0,+ os_name: "linux",+ major: 3,+ minor: 2,+ subminor: 0,+ });+ }+});++it("reads the same notes from an SHT_NOTE section including its name", () => {+ const report = parse(elfNoteFixture({ ownership: "section" }));+ expect(report.tables).toEqual([+ expect.objectContaining({+ kind: "section",+ name: ".note.gnu.build-id",+ }),+ ]);+ expect(+ report.entries.some((entry) => entry.type_name === "gnu_build_id"),+ ).toBe(true);+});++it("reports independent PT_NOTE and SHT_NOTE declarations of the same bytes", () => {+ const report = parse(elfNoteFixture({ ownership: "both" }));+ expect(report.tables.map((table) => table.kind).sort()).toEqual([+ "program",+ "section",+ ]);+ expect(+ report.entries.filter((entry) => entry.type_name === "gnu_build_id"),+ ).toHaveLength(2);+});++it("reports missing note tables without claiming notes never existed", () => {+ const report = parse(elfNoteFixture({ ownership: "none" }));+ expect(report.tables).toEqual([]);+ expect(report.entries).toEqual([]);+ expect(report.limitations[0]).toMatch(/No PT_NOTE/u);+});++it("fails a truncated note payload without partial success", () => {+ const notes = gnuBuildIdNote();+ notes.writeUInt32LE(64, 0);+ const bytes = elfNoteFixture({ ownership: "program", notes });+ expect(() => parse(bytes)).toThrow(ArtifactReaderFailure);+});++it("keeps non-GNU owners as unknown types with descriptor hashes", () => {+ const payload = Buffer.from("hello");+ const notes = elfNote("CORE", 1, payload);+ const report = parse(elfNoteFixture({ ownership: "program", notes }));+ expect(report.entries[0]).toMatchObject({+ owner: "CORE",+ type_name: "unknown",+ gnu: null,+ });+ expect(report.entries[0]?.descriptor.sha256).toBe(+ createHash("sha256").update(payload).digest("hex"),+ );+});++it("reads a big-endian ELF32 GNU build-id", () => {+ const notes = gnuBuildIdNote(undefined, false);+ const report = parse(+ elfNoteFixture({+ bits: 32,+ little: false,+ machine: 20,+ ownership: "program",+ notes,+ }),+ );+ expect(report.byte_order).toBe("big");+ expect(report.machine).toBe(20);+ expect(report.entries[0]?.gnu?.build_id_hex).toBe(+ "0123456789abcdef0123456789abcdef01234567",+ );+});++it("reads an 8-aligned GNU property note from a PT_NOTE program header", () => {+ const notes = gnuPropertyNote();+ expect(notes.length).toBe(48);+ const report = parse(+ elfNoteFixture({ ownership: "program", notes, alignment: 8 }),+ );+ expect(report.tables).toEqual([+ expect.objectContaining({ kind: "program", alignment: 8 }),+ ]);+ expect(report.entries).toHaveLength(1);+ expect(report.entries[0]).toMatchObject({+ owner: "GNU",+ type: 5,+ type_name: "gnu_property",+ namesz: 4,+ descsz: 32,+ });+ expect(report.entries[0]?.descriptor.location.offset).toBe(+ (report.entries[0]?.location.offset ?? 0) + 16,+ );+});++it("reads an 8-aligned GNU property note from an SHT_NOTE section", () => {+ const report = parse(+ elfNoteFixture({+ ownership: "section",+ notes: gnuPropertyNote(),+ alignment: 8,+ sectionName: ".note.gnu.property",+ }),+ );+ expect(report.tables).toEqual([+ expect.objectContaining({+ kind: "section",+ name: ".note.gnu.property",+ alignment: 8,+ }),+ ]);+ expect(report.entries[0]?.type_name).toBe("gnu_property");+ expect(report.entries[0]?.descriptor.bytes).toBe(32);+});++it.each([0, 1] as const)(+ "treats declared note alignment %i as 4-byte padding",+ (alignment) => {+ const report = parse(elfNoteFixture({ ownership: "program", alignment }));+ expect(report.tables[0]?.alignment).toBe(4);+ expect(+ report.entries.some((entry) => entry.type_name === "gnu_build_id"),+ ).toBe(true);+ expect(+ report.entries.some((entry) => entry.type_name === "gnu_abi_tag"),+ ).toBe(true);+ },+);++const hostElf = [+ "/bin/ls",+ "/usr/bin/ls",+ "/usr/bin/env",+].reduce<Buffer | null>((found, path) => {+ if (found) return found;+ try {+ const bytes = readFileSync(path);+ if (+ bytes.length > 64 &&+ bytes[0] === 0x7f &&+ bytes[1] === 0x45 &&+ bytes[2] === 0x4c &&+ bytes[3] === 0x46+ )+ return bytes;+ } catch {+ return found;+ }+ return found;+}, null);++it.skipIf(hostElf === null)(+ "parses a host ELF without requiring it to contain notes",+ () => {+ const report = parse(hostElf!);+ expect(report.coverage.status).toBe("complete");+ const buildId = report.entries.find(+ (entry) => entry.type_name === "gnu_build_id",+ );+ const abi = report.entries.find(+ (entry) => entry.type_name === "gnu_abi_tag",+ );+ if (buildId !== undefined)+ expect(buildId.gnu?.build_id_hex).toMatch(/^[0-9a-f]+$/u);+ if (abi !== undefined)+ expect(abi.gnu?.abi_tag).toMatchObject({+ os: expect.any(Number),+ major: expect.any(Number),+ minor: expect.any(Number),+ subminor: expect.any(Number),+ });+ },+);++const unterminatedNoteSections = (+ sections: number,+ nameBytes: number,+): Buffer => {+ const shnum = sections + 2;+ const tableOffset = 64 + shnum * 64;+ const shdr = (type: number, offset = 0, size = 0): Buffer => {+ const header = Buffer.alloc(64);+ header.writeUInt32LE(type, 4);+ header.writeBigUInt64LE(BigInt(offset), 24);+ header.writeBigUInt64LE(BigInt(size), 32);+ return header;+ };+ const image = Buffer.concat([+ elf64({ shoff: 64, shnum }),+ shdr(0),+ shdr(3, tableOffset, nameBytes),+ ...Array.from({ length: sections }, () => shdr(7, tableOffset)),+ Buffer.alloc(nameBytes, 0x41),+ ]);+ image.writeUInt16LE(1, 62);+ return image;+};++it("bounds repeated scans of an unterminated section name", () => {+ expect(parse(unterminatedNoteSections(1, 64)).tables[0]?.name).toBeNull();+ expect(() => parse(unterminatedNoteSections(3, 400))).toThrow(/byte budget/u);+});++it("rejects note text that repeats beyond the shared byte budget", () => {+ const notes = elfNote("A".repeat(40), 1, Buffer.alloc(0));+ const once = elfNoteFixture({ ownership: "program", notes });+ const twice = elfNoteFixture({ ownership: "both", notes });+ const input = inspectElfNotesInputSchema.parse({+ path: defaults.path,+ max_file_bytes: 200,+ });+ expect(parse(once, input).entries).toHaveLength(1);+ expect(() => parse(twice, input)).toThrow(ArtifactReaderFailure);+ expect(() => parse(twice, input)).toThrow(/byte budget/u);+});++it("rejects program and section header tables that do not fit", () => {+ expect(() =>+ parse(elf64({ phoff: 64, phnum: 1 }, Buffer.from([1, 0, 0, 0]))),+ ).toThrow(/leaves the artifact/u);+ expect(() =>+ parse(+ elf64({ shoff: 64, shnum: 1, shentsize: 64 }, Buffer.from([0, 0, 0, 0])),+ ),+ ).toThrow(/leaves the artifact/u);+});++it("rejects an extended section count stored in section zero", () => {+ expect(() => parse(elf64({ shoff: 64, shnum: 0 }))).toThrow(+ /extended numbering/u,+ );+});++const repeatedNotes = (count: number, notes: Buffer): Buffer => {+ const headers = Buffer.alloc(56 * count);+ const offset = 64 + headers.length;+ for (let index = 0; index < count; index += 1) {+ const at = index * 56;+ headers.writeUInt32LE(4, at);+ headers.writeBigUInt64LE(BigInt(offset), at + 8);+ headers.writeBigUInt64LE(BigInt(notes.length), at + 32);+ headers.writeBigUInt64LE(4n, at + 48);+ }+ return Buffer.concat([elf64({ phoff: 64, phnum: count }), headers, notes]);+};++it("reuses one descriptor hash and GNU NUL scan across note headers", () => {+ const payload = Buffer.alloc(400);+ const hashed = parse(repeatedNotes(6, elfNote("X", 1, payload)));+ expect(hashed.entries).toHaveLength(6);+ expect(+ new Set(hashed.entries.map((entry) => entry.descriptor.sha256)).size,+ ).toBe(1);+ const gold = parse(repeatedNotes(6, elfNote("GNU", 4, payload)));+ expect(gold.entries).toHaveLength(6);+ expect(gold.entries.every((entry) => entry.gnu?.gold_version === "")).toBe(+ true,+ );+ const distinct = Buffer.concat([+ elfNote("X", 1, payload),+ elfNote("X", 1, Buffer.alloc(400, 1)),+ ]);+ expect(() =>+ parse(+ elfNoteFixture({ ownership: "program", notes: distinct }),+ inspectElfNotesInputSchema.parse({+ path: defaults.path,+ max_file_bytes: payload.length + 160,+ }),+ ),+ ).toThrow(/byte budget/u);+});++it("decodes a GNU gold version by scanning trailing NULs", () => {+ const trailing = elfNote("GNU", 4, Buffer.from("gold\0\0x\0", "latin1"));+ expect(+ parse(elfNoteFixture({ ownership: "program", notes: trailing })).entries[0]+ ?.gnu?.gold_version,+ ).toBe("gold\0\0x");+ const descriptor = Buffer.concat([Buffer.alloc(131_072), Buffer.from("x")]);+ const started = Date.now();+ const report = parse(+ elfNoteFixture({+ ownership: "program",+ notes: elfNote("GNU", 4, descriptor),+ }),+ );+ expect(Date.now() - started).toBeLessThan(1_000);+ expect(report.entries[0]?.gnu?.gold_version).toBe(`${"\0".repeat(131_072)}x`);+});++it("rejects a declared note table that extends past the file", () => {+ const truncated = elfNoteTablePastEnd();+ expect(truncated.length).toBe(137);+ expect(() => parse(truncated)).toThrow(ArtifactReaderFailure);+ expect(() => parse(truncated)).toThrow(/leaves the artifact/u);+ const present = Buffer.concat([truncated, Buffer.alloc(3)]);+ expect(parse(present).entries).toHaveLength(1);+ expect(parse(present).tables[0]?.location).toEqual({+ offset: 120,+ bytes: 20,+ });+});++it("fails when the entry budget is exhausted", () => {+ const notes = Buffer.concat([+ gnuBuildIdNote(),+ gnuAbiTagNote(),+ elfNote("GNU", 4, Buffer.from("gold")),+ ]);+ const bytes = elfNoteFixture({ ownership: "program", notes });+ expect(() =>+ parseElfNotes(+ bytes,+ {+ path: defaults.path,+ sha256: createHash("sha256").update(bytes).digest("hex"),+ bytes: bytes.length,+ },+ inspectElfNotesInputSchema.parse({ path: defaults.path, max_entries: 1 }),+ ),+ ).toThrow(ArtifactReaderFailure);+});diff --git a/src/native/elf/ElfNoteParser.ts b/src/native/elf/ElfNoteParser.tsnew file mode 100644index 000000000..80474c552--- /dev/null+++ b/src/native/elf/ElfNoteParser.ts@@ -0,0 +1,455 @@+import { createHash } from "node:crypto";+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";+import { readElfFixedHeader } from "../../domain/elfFixedHeader.js";+import type {+ ElfNotes,+ InspectElfNotesInput,+} from "../../domain/native/elfNotes.js";+import {+ elfObjectTypeName,+ gnuNoteTypeName,+} from "../../domain/native/elfNotes.js";++const PT_NOTE = 4;+const SHT_NOTE = 7;+const SHT_STRTAB = 3;+const HEX_DESCRIPTOR_LIMIT = 64;++interface TextBudget {+ readonly limit: number;+ used: number;+ hashed: number;+ scanned: number;+ readonly hashes: Map<string, string>;+ readonly scans: Map<string, number>;+}++const fail = (message: string): never => {+ throw new ArtifactReaderFailure("format", message);+};++const chargeText = (+ budget: TextBudget,+ bytes: number,+ field: "used" | "hashed" | "scanned" = "used",+): void => {+ if (+ !Number.isSafeInteger(bytes) ||+ bytes < 0 ||+ bytes > budget.limit - budget[field]+ )+ throw new ArtifactReaderFailure(+ "limit",+ `ELF note text exceeds the ${String(budget.limit)}-byte budget.`,+ { boundary: "memory" },+ );+ budget[field] += bytes;+};++const sha256 = (bytes: Buffer): string =>+ createHash("sha256").update(bytes).digest("hex");++const alignTo = (value: number, alignment: number): number => {+ if (alignment <= 1) return value;+ return Math.ceil(value / alignment) * alignment;+};++const GNU_OS_NAMES: Readonly<Record<number, string>> = {+ 0: "linux",+ 1: "hurd",+ 2: "solaris",+ 3: "freebsd",+ 4: "netbsd",+ 5: "syllable",+ 6: "nacl",+};++const LIMITATIONS = [+ "This workflow does not execute the image, resolve runtime notes, or verify GNU build-id uniqueness against package catalogs.",+ "PT_NOTE and SHT_NOTE are examined independently; the same file range may appear twice when both tables declare it.",+] as const;++const ABSENT_LIMITATIONS = [+ "No PT_NOTE program header or SHT_NOTE section was declared. That is not proof the image never carried notes in another container or overlay.",+ "This workflow does not execute the image, resolve runtime notes, or verify GNU build-id uniqueness against package catalogs.",+] as const;++class ElfReader {+ constructor(+ readonly bytes: Buffer,+ readonly little: boolean,+ readonly bits: 32 | 64,+ ) {}++ u16(offset: number): number {+ this.require(offset, 2);+ return this.little+ ? this.bytes.readUInt16LE(offset)+ : this.bytes.readUInt16BE(offset);+ }++ u32(offset: number): number {+ this.require(offset, 4);+ return this.little+ ? this.bytes.readUInt32LE(offset)+ : this.bytes.readUInt32BE(offset);+ }++ word(offset: number): number {+ const width = this.bits === 64 ? 8 : 4;+ this.require(offset, width);+ if (this.bits === 32) return this.u32(offset);+ const value = this.little+ ? this.bytes.readBigUInt64LE(offset)+ : this.bytes.readBigUInt64BE(offset);+ if (value > BigInt(Number.MAX_SAFE_INTEGER))+ fail("ELF offset or size exceeds a safe integer.");+ return Number(value);+ }++ require(offset: number, length: number): void {+ if (+ !Number.isSafeInteger(offset) ||+ !Number.isSafeInteger(length) ||+ offset < 0 ||+ length < 0 ||+ offset > this.bytes.length - length+ )+ fail(+ `ELF range ${String(offset)} + ${String(length)} leaves the artifact.`,+ );+ }++ slice(offset: number, length: number): Buffer {+ this.require(offset, length);+ return this.bytes.subarray(offset, offset + length);+ }++ cString(table: Buffer, offset: number, text: TextBudget): string | null {+ if (offset < 0 || offset >= table.length) return null;+ const affordable = text.limit - text.used;+ const available = table.length - offset;+ const scanned = Math.min(available, affordable + 1);+ const end = table.subarray(offset, offset + scanned).indexOf(0);+ if (end < 0) {+ chargeText(text, scanned);+ return null;+ }+ chargeText(text, end);+ return table.subarray(offset, offset + end).toString("latin1");+ }+}++/** Note name/descriptor padding follows the containing table's p_align or+ * sh_addralign: 8 stays 8; 0, 1, 4, and other values pad as 4, matching+ * readelf/binutils. */+const noteAlignment = (declared: number): number => (declared === 8 ? 8 : 4);++interface ParsedNote {+ readonly location: { offset: number; bytes: number };+ readonly namesz: number;+ readonly descsz: number;+ readonly type: number;+ readonly owner: string;+ readonly owner_bytes_hex: string;+ readonly descriptor: Buffer;+ readonly descriptor_offset: number;+}++const parseNoteStream = (+ reader: ElfReader,+ offset: number,+ size: number,+ alignment: number,+ maxEntries: number,+ examined: { count: number },+ text: TextBudget,+): ParsedNote[] => {+ // Alignment padding is not read when a note's aligned size equals the+ // declared table. Require the whole table first so a short file is invalid+ // input instead of a provider result the service rejects.+ reader.require(offset, size);+ const notes: ParsedNote[] = [];+ let at = 0;+ while (at + 12 <= size) {+ examined.count += 1;+ if (examined.count > maxEntries)+ throw new ArtifactReaderFailure(+ "limit",+ `ELF note tables exceed the ${String(maxEntries)}-entry budget.`,+ { boundary: "capacity" },+ );+ const header = offset + at;+ const namesz = reader.u32(header);+ const descsz = reader.u32(header + 4);+ const type = reader.u32(header + 8);+ // Align offsets from the start of this note. Independently rounding+ // namesz/descsz disagrees with binutils when alignment is 8 because the+ // 12-byte note header is not 8-aligned (GNU property namesz=4 then starts+ // its descriptor at 16, not 20).+ const descRel = alignTo(12 + namesz, alignment);+ const nextRel = alignTo(descRel + descsz, alignment);+ const next = at + nextRel;+ if (next > size) fail("ELF note entry exceeds its table.");+ if (next <= at) fail("ELF note alignment did not advance.");+ const nameBytes = reader.slice(header + 12, namesz);+ const descriptor = reader.slice(header + descRel, descsz);+ const ownerEnd = nameBytes.indexOf(0);+ const ownerBytes = ownerEnd < 0 ? namesz : ownerEnd;+ chargeText(text, ownerBytes + namesz * 2);+ notes.push({+ location: { offset: header, bytes: next - at },+ namesz,+ descsz,+ type,+ owner:+ ownerEnd < 0+ ? nameBytes.toString("latin1")+ : nameBytes.subarray(0, ownerEnd).toString("latin1"),+ owner_bytes_hex: nameBytes.toString("hex"),+ descriptor,+ descriptor_offset: header + descRel,+ });+ at = next;+ }+ if (+ at < size &&+ reader.slice(offset + at, size - at).some((byte) => byte !== 0)+ )+ fail("ELF note table has trailing non-zero bytes.");+ return notes;+};++const decodeGnu = (+ owner: string,+ type: number,+ descriptor: Buffer,+ little: boolean,+ text: TextBudget,+): ElfNotes["entries"][number]["gnu"] => {+ if (owner !== "GNU") return null;+ if (type === 3 && descriptor.length > 0) {+ chargeText(text, descriptor.length * 2);+ return {+ build_id_hex: descriptor.toString("hex"),+ abi_tag: null,+ gold_version: null,+ };+ }+ if (type === 1 && descriptor.length === 16) {+ const read = (offset: number) =>+ little+ ? descriptor.readUInt32LE(offset)+ : descriptor.readUInt32BE(offset);+ const os = read(0);+ return {+ build_id_hex: null,+ abi_tag: {+ os,+ os_name: GNU_OS_NAMES[os] ?? null,+ major: read(4),+ minor: read(8),+ subminor: read(12),+ },+ gold_version: null,+ };+ }+ if (type === 4) {+ const range = `${String(descriptor.byteOffset)}:${String(descriptor.length)}`;+ let end = text.scans.get(range);+ if (end === undefined) {+ chargeText(text, descriptor.length, "scanned");+ end = descriptor.length;+ while (end > 0 && descriptor[end - 1] === 0) end -= 1;+ text.scans.set(range, end);+ }+ chargeText(text, end);+ return {+ build_id_hex: null,+ abi_tag: null,+ gold_version: descriptor.toString("latin1", 0, end),+ };+ }+ return {+ build_id_hex: null,+ abi_tag: null,+ gold_version: null,+ };+};++/** Decode PT_NOTE and SHT_NOTE tables from one in-memory ELF image. */+export const parseElfNotes = (+ bytes: Buffer,+ artifact: ElfNotes["artifact"],+ input: InspectElfNotesInput,+): ElfNotes => {+ const fixed = readElfFixedHeader(bytes);+ if (!fixed.ok) return fail(fixed.error);+ const header = fixed.value;+ const reader = new ElfReader(+ bytes,+ header.byteOrder === "little",+ header.elfClass,+ );+ const wide = header.elfClass === 64;+ const type = reader.u16(16);+ const phoff = reader.word(wide ? 32 : 28);+ const shoff = reader.word(wide ? 40 : 32);+ const phentsize = reader.u16(wide ? 54 : 42);+ const phnum = reader.u16(wide ? 56 : 44);+ const shentsize = reader.u16(wide ? 58 : 46);+ const shnum = reader.u16(wide ? 60 : 48);+ const shstrndx = reader.u16(wide ? 62 : 50);+ if (+ phnum === 0xffff ||+ shnum === 0xffff ||+ shstrndx === 0xffff ||+ (shoff !== 0 && shnum === 0)+ )+ return fail("ELF extended numbering is unsupported.");+ if (phnum !== 0) {+ if (phentsize < (wide ? 56 : 32))+ return fail("ELF program header width is invalid.");+ reader.require(phoff, phnum * phentsize);+ }+ if (shnum !== 0) {+ if (shentsize < (wide ? 64 : 40))+ return fail("ELF section header width is invalid.");+ reader.require(shoff, shnum * shentsize);+ }+ const text: TextBudget = {+ limit: Math.min(bytes.length, input.max_file_bytes),+ used: 0,+ hashed: 0,+ scanned: 0,+ hashes: new Map(),+ scans: new Map(),+ };+ let shstrtab: Buffer | null = null;+ if (shnum !== 0 && shstrndx !== 0) {+ if (shstrndx >= shnum)+ return fail("ELF section name index is out of range.");+ const namesHeader = shoff + shstrndx * shentsize;+ if (reader.u32(namesHeader + 4) !== SHT_STRTAB)+ return fail("ELF section name table is not a string table.");+ const strOff = reader.word(namesHeader + (wide ? 24 : 16));+ const strSize = reader.word(namesHeader + (wide ? 32 : 20));+ shstrtab = reader.slice(strOff, strSize);+ }+ const tables: ElfNotes["tables"] = [];+ const parsed: ReturnType<typeof toEntry>[] = [];+ const examined = { count: 0 };+ if (phnum !== 0) {+ if (phoff < header.headerSize)+ return fail("ELF program header table overlaps the native header.");+ for (let index = 0; index < phnum; index += 1) {+ const at = phoff + index * phentsize;+ if (reader.u32(at) !== PT_NOTE) continue;+ const fileOffset = reader.word(at + (wide ? 8 : 4));+ const fileSize = reader.word(at + (wide ? 32 : 16));+ const alignment = noteAlignment(reader.word(at + (wide ? 48 : 28)));+ tables.push({+ kind: "program",+ index,+ name: null,+ location: { offset: fileOffset, bytes: fileSize },+ alignment,+ });+ for (const note of parseNoteStream(+ reader,+ fileOffset,+ fileSize,+ alignment,+ input.max_entries,+ examined,+ text,+ ))+ parsed.push(toEntry(note, "program", index, reader.little, text));+ }+ }+ if (shnum !== 0) {+ if (shoff < header.headerSize)+ return fail("ELF section header table overlaps the native header.");+ for (let index = 0; index < shnum; index += 1) {+ const at = shoff + index * shentsize;+ if (reader.u32(at + 4) !== SHT_NOTE) continue;+ const nameOffset = reader.u32(at);+ const fileOffset = reader.word(at + (wide ? 24 : 16));+ const fileSize = reader.word(at + (wide ? 32 : 20));+ const alignment = noteAlignment(reader.word(at + (wide ? 48 : 32)));+ tables.push({+ kind: "section",+ index,+ name:+ shstrtab === null ? null : reader.cString(shstrtab, nameOffset, text),+ location: { offset: fileOffset, bytes: fileSize },+ alignment,+ });+ for (const note of parseNoteStream(+ reader,+ fileOffset,+ fileSize,+ alignment,+ input.max_entries,+ examined,+ text,+ ))+ parsed.push(toEntry(note, "section", index, reader.little, text));+ }+ }+ const absent = tables.length === 0;+ return {+ artifact,+ format: wide ? "elf64" : "elf32",+ byte_order: reader.little ? "little" : "big",+ machine: header.machine,+ type,+ type_name: elfObjectTypeName(type),+ tables,+ entries: parsed.map((entry, index) => ({ ...entry, index })),+ coverage: {+ status: "complete",+ examined_tables: tables.length,+ examined_entries: examined.count,+ },+ limitations: [...(absent ? ABSENT_LIMITATIONS : LIMITATIONS)],+ };+};++const toEntry = (+ note: ParsedNote,+ tableKind: "program" | "section",+ tableIndex: number,+ little: boolean,+ text: TextBudget,+): Omit<ElfNotes["entries"][number], "index"> => {+ const gnuOwner = note.owner === "GNU";+ const range = `${String(note.descriptor_offset)}:${String(note.descsz)}`;+ let digest = text.hashes.get(range);+ if (digest === undefined) {+ chargeText(text, note.descriptor.length, "hashed");+ digest = sha256(note.descriptor);+ text.hashes.set(range, digest);+ }+ return {+ table_kind: tableKind,+ table_index: tableIndex,+ location: note.location,+ namesz: note.namesz,+ descsz: note.descsz,+ type: note.type,+ type_name: gnuOwner ? gnuNoteTypeName(note.type) : "unknown",+ owner: note.owner,+ owner_bytes_hex: note.owner_bytes_hex,+ descriptor: {+ location: { offset: note.descriptor_offset, bytes: note.descsz },+ bytes: note.descsz,+ sha256: digest,+ hex:+ note.descsz <= HEX_DESCRIPTOR_LIMIT+ ? note.descriptor.toString("hex")+ : null,+ },+ gnu: decodeGnu(note.owner, note.type, note.descriptor, little, text),+ };+};diff --git a/src/native/elf/ElfNotes.fixture.ts b/src/native/elf/ElfNotes.fixture.tsnew file mode 100644index 000000000..a7ac80380--- /dev/null+++ b/src/native/elf/ElfNotes.fixture.ts@@ -0,0 +1,239 @@+const concat = (...parts: Buffer[]): Buffer => Buffer.concat(parts);++const alignTo = (value: number, alignment: number): number =>+ Math.ceil(value / alignment) * alignment;++/** Effective namesz/descsz padding: 8 stays 8; 0, 1, 4, and other values use 4. */+const notePadding = (declared: number): number => (declared === 8 ? 8 : 4);++const writeWord = (+ bytes: Buffer,+ offset: number,+ value: number,+ bits: 32 | 64,+ little: boolean,+): void => {+ if (bits === 64) {+ if (little) bytes.writeBigUInt64LE(BigInt(value), offset);+ else bytes.writeBigUInt64BE(BigInt(value), offset);+ return;+ }+ if (little) bytes.writeUInt32LE(value, offset);+ else bytes.writeUInt32BE(value, offset);+};++const write16 = (+ bytes: Buffer,+ offset: number,+ value: number,+ little: boolean,+): void => {+ if (little) bytes.writeUInt16LE(value, offset);+ else bytes.writeUInt16BE(value, offset);+};++const write32 = (+ bytes: Buffer,+ offset: number,+ value: number,+ little: boolean,+): void => {+ if (little) bytes.writeUInt32LE(value, offset);+ else bytes.writeUInt32BE(value, offset);+};++/** Encode one ELF note, padding name/descriptor to the table alignment. */+export const elfNote = (+ owner: string,+ type: number,+ descriptor: Buffer,+ little = true,+ alignment = 4,+): Buffer => {+ const name = Buffer.from(`${owner}\0`, "latin1");+ const pad = notePadding(alignment);+ const descOff = alignTo(12 + name.length, pad);+ const bytes = Buffer.alloc(alignTo(descOff + descriptor.length, pad));+ write32(bytes, 0, name.length, little);+ write32(bytes, 4, descriptor.length, little);+ write32(bytes, 8, type, little);+ name.copy(bytes, 12);+ descriptor.copy(bytes, descOff);+ return bytes;+};++/** GNU NT_GNU_BUILD_ID note with a 20-byte descriptor. */+export const gnuBuildIdNote = (+ hex = "0123456789abcdef0123456789abcdef01234567",+ little = true,+): Buffer => elfNote("GNU", 3, Buffer.from(hex, "hex"), little);++/** GNU NT_GNU_ABI_TAG note: Linux 3.2.0. */+export const gnuAbiTagNote = (little = true): Buffer => {+ const descriptor = Buffer.alloc(16);+ write32(descriptor, 0, 0, little);+ write32(descriptor, 4, 3, little);+ write32(descriptor, 8, 2, little);+ write32(descriptor, 12, 0, little);+ return elfNote("GNU", 1, descriptor, little);+};++/** GNU NT_GNU_PROPERTY_TYPE_0 note with 8-byte table padding. */+export const gnuPropertyNote = (little = true): Buffer => {+ const descriptor = Buffer.alloc(32);+ write32(descriptor, 0, 0xc0000002, little);+ write32(descriptor, 4, 4, little);+ write32(descriptor, 8, 3, little);+ write32(descriptor, 16, 0xc0008002, little);+ write32(descriptor, 20, 4, little);+ write32(descriptor, 24, 1, little);+ return elfNote("GNU", 5, descriptor, little, 8);+};++export interface ElfNoteImageOptions {+ readonly bits?: 32 | 64;+ readonly little?: boolean;+ readonly notes?: Buffer;+ readonly ownership?: "program" | "section" | "both" | "none";+ readonly machine?: number;+ readonly type?: number;+ readonly alignment?: number;+ readonly sectionName?: string;+}++/** Minimal ELF32/ELF64 image declaring PT_NOTE and/or SHT_NOTE. */+export const elfNoteFixture = (options: ElfNoteImageOptions = {}): Buffer => {+ const bits = options.bits ?? 64;+ const little = options.little ?? true;+ const ownership = options.ownership ?? "both";+ const notes =+ options.notes ??+ concat(gnuBuildIdNote(undefined, little), gnuAbiTagNote(little));+ const declaredAlign = options.alignment ?? 4;+ const pad = notePadding(declaredAlign);+ const header = bits === 64 ? 64 : 52;+ const phent = bits === 64 ? 56 : 32;+ const shent = bits === 64 ? 64 : 40;+ const program = ownership === "program" || ownership === "both";+ const section = ownership === "section" || ownership === "both";+ const phnum = program ? 1 : 0;+ const sectionName = options.sectionName ?? ".note.gnu.build-id";+ const shstrtab = Buffer.from(`\0${sectionName}\0.shstrtab\0`, "latin1");+ const shnum = section ? 3 : 0;+ const phoff = header;+ const shoff = phoff + phnum * phent;+ const noteOff = alignTo(shoff + shnum * shent, pad);+ const strOff = noteOff + notes.length;+ const bytes = Buffer.alloc(strOff + (section ? shstrtab.length : 0));+ bytes.writeUInt32LE(0x464c457f, 0);+ bytes[4] = bits === 64 ? 2 : 1;+ bytes[5] = little ? 1 : 2;+ bytes[6] = 1;+ write16(bytes, 0x10, options.type ?? 3, little);+ write16(bytes, 0x12, options.machine ?? 62, little);+ write32(bytes, 0x14, 1, little);+ write16(bytes, bits === 64 ? 0x34 : 0x28, header, little);+ writeWord(+ bytes,+ bits === 64 ? 0x20 : 0x1c,+ phnum === 0 ? 0 : phoff,+ bits,+ little,+ );+ write16(bytes, bits === 64 ? 0x36 : 0x2a, phent, little);+ write16(bytes, bits === 64 ? 0x38 : 0x2c, phnum, little);+ writeWord(+ bytes,+ bits === 64 ? 0x28 : 0x20,+ shnum === 0 ? 0 : shoff,+ bits,+ little,+ );+ write16(bytes, bits === 64 ? 0x3a : 0x2e, shent, little);+ write16(bytes, bits === 64 ? 0x3c : 0x30, shnum, little);+ write16(bytes, bits === 64 ? 0x3e : 0x32, section ? 2 : 0, little);+ if (program) {+ const ph = phoff;+ write32(bytes, ph, 4, little);+ if (bits === 64) {+ write32(bytes, ph + 4, 4, little);+ writeWord(bytes, ph + 8, noteOff, bits, little);+ writeWord(bytes, ph + 32, notes.length, bits, little);+ writeWord(bytes, ph + 40, notes.length, bits, little);+ writeWord(bytes, ph + 48, declaredAlign, bits, little);+ } else {+ writeWord(bytes, ph + 4, noteOff, bits, little);+ writeWord(bytes, ph + 16, notes.length, bits, little);+ writeWord(bytes, ph + 20, notes.length, bits, little);+ write32(bytes, ph + 24, 4, little);+ writeWord(bytes, ph + 28, declaredAlign, bits, little);+ }+ }+ if (section) {+ const noteName = 1;+ const strName = `${sectionName}\0`.length + 1;+ const noteSh = shoff + shent;+ const strSh = shoff + 2 * shent;+ write32(bytes, noteSh, noteName, little);+ write32(bytes, noteSh + 4, 7, little);+ writeWord(bytes, noteSh + (bits === 64 ? 24 : 16), noteOff, bits, little);+ writeWord(+ bytes,+ noteSh + (bits === 64 ? 32 : 20),+ notes.length,+ bits,+ little,+ );+ writeWord(+ bytes,+ noteSh + (bits === 64 ? 48 : 32),+ declaredAlign,+ bits,+ little,+ );+ write32(bytes, strSh, strName, little);+ write32(bytes, strSh + 4, 3, little);+ writeWord(bytes, strSh + (bits === 64 ? 24 : 16), strOff, bits, little);+ writeWord(+ bytes,+ strSh + (bits === 64 ? 32 : 20),+ shstrtab.length,+ bits,+ little,+ );+ shstrtab.copy(bytes, strOff);+ }+ notes.copy(bytes, noteOff);+ return bytes;+};++/**+ * ELF64 whose only PT_NOTE declares 20 bytes. The file holds the 12-byte+ * header, 4-byte name, and 1-byte descriptor; the 3 alignment bytes are absent.+ */+export const elfNoteTablePastEnd = (): Buffer => {+ const note = Buffer.alloc(17);+ write32(note, 0, 4, true);+ write32(note, 4, 1, true);+ write32(note, 8, 1, true);+ note.write("GNU\0", 12, "latin1");+ note[16] = 0x2a;+ const header = Buffer.alloc(64);+ header.writeUInt32LE(0x464c457f, 0);+ header[4] = 2;+ header[5] = 1;+ header[6] = 1;+ write16(header, 0x10, 3, true);+ write16(header, 0x12, 62, true);+ write32(header, 0x14, 1, true);+ write16(header, 0x34, 64, true);+ writeWord(header, 0x20, 64, 64, true);+ write16(header, 0x36, 56, true);+ write16(header, 0x38, 1, true);+ const program = Buffer.alloc(56);+ write32(program, 0, 4, true);+ writeWord(program, 8, 120, 64, true);+ writeWord(program, 32, 20, 64, true);+ writeWord(program, 48, 4, 64, true);+ return concat(header, program, note);+};diff --git a/src/native/elf/ElfNotesProvider.test.ts b/src/native/elf/ElfNotesProvider.test.tsnew file mode 100644index 000000000..22a733bc8--- /dev/null+++ b/src/native/elf/ElfNotesProvider.test.ts@@ -0,0 +1,91 @@+import { writeFile } from "node:fs/promises";+import { join } from "node:path";+import { describe, expect, it } from "vitest";+import { ElfNotesService } from "../../application/binaryDiagnostics/ElfNotesService.js";+import {+ AnalysisInputError,+ AnalysisResourceConstraintError,+} from "../../domain/analysisErrorCore.js";+import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";+import { createTestTempDirectory } from "../../../tests/fixtures/temporaryDirectory.js";+import {+ elfNote,+ elfNoteFixture,+ elfNoteTablePastEnd,+} from "./ElfNotes.fixture.js";+import { ElfNotesProvider } from "./ElfNotesProvider.js";++const inspect = async (+ path: string,+ input: { readonly max_file_bytes?: number } = {},+) => {+ const service = new ElfNotesService(new ElfNotesProvider());+ try {+ return await service.inspect({ path, ...input });+ } finally {+ await service.close();+ }+};++describe("ELF note provider failures", () => {+ it("reports a note table past the end of the file as invalid input", async () => {+ const root = await createTestTempDirectory("rea-elf-note-past-end-");+ const path = join(root, "program");+ await writeFile(path, elfNoteTablePastEnd());+ const result = await inspect(path);+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected invalid input");+ expect(result.error).toBeInstanceOf(AnalysisInputError);+ expect(result.error).toMatchObject({+ _tag: "AnalysisInputError",+ issues: [+ {+ path: ["path"],+ reason: "invalid_format",+ message: expect.stringContaining("leaves the artifact"),+ },+ ],+ });+ });++ it("names the note text budget instead of host memory", async () => {+ const root = await createTestTempDirectory("rea-elf-note-text-budget-");+ const path = join(root, "program");+ await writeFile(+ path,+ elfNoteFixture({+ ownership: "program",+ notes: elfNote("GNU", 3, Buffer.alloc(4096, 1)),+ }),+ );+ const result = await inspect(path);+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected a text budget refusal");+ const error = result.error as AnalysisResourceConstraintError;+ expect(error.resource).toBe("memory");+ expect(error.message).toMatch(/byte budget/u);+ const projected = projectAnalysisError(error);+ expect(projected.retryable).toBe(false);+ expect(projected.remediation.action).toContain(+ "ELF note text, hash, and scan budget",+ );+ expect(projected.remediation.action).toMatch(/admitted image length/u);+ expect(projected.remediation.action).toMatch(/do not raise it/u);+ expect(projected.remediation.action).not.toMatch(/available host memory/u);+ });++ it("keeps a caller file-size budget distinct from host memory", async () => {+ const root = await createTestTempDirectory("rea-elf-note-file-budget-");+ const path = join(root, "program");+ await writeFile(path, elfNoteFixture({ ownership: "program" }));+ const result = await inspect(path, { max_file_bytes: 64 });+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected a file-size refusal");+ const error = result.error as AnalysisResourceConstraintError;+ expect(error.resource).toBe("file-size");+ const projected = projectAnalysisError(error);+ expect(projected.retryable).toBe(false);+ expect(projected.remediation.action).toContain("max_file_bytes");+ expect(projected.remediation.action).not.toMatch(/available host memory/u);+ });+});diff --git a/src/native/elf/ElfNotesProvider.ts b/src/native/elf/ElfNotesProvider.tsnew file mode 100644index 000000000..06c25408f--- /dev/null+++ b/src/native/elf/ElfNotesProvider.ts@@ -0,0 +1,207 @@+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";+import {+ ArtifactFileCleanupFailure,+ bindArtifactFileCleanup,+ artifactFileCancellationCause,+} from "../../artifacts/ArtifactFileOperation.js";+import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";+import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";+import type { ElfNotesPort } from "../../application/binaryDiagnostics/ElfNotesPort.js";+import type { ExecutionOptions } from "../../application/AnalysisProvider.js";+import { ArtifactOperationError } from "../../domain/artifactOperationError.js";+import {+ AnalysisAccessDeniedError,+ AnalysisArtifactChangedError,+ AnalysisCancelledError,+ AnalysisInputError,+ AnalysisResourceConstraintError,+} from "../../domain/analysisErrorCore.js";+import { fixedAllowanceOptions } from "../../domain/fixedAllowanceRemediation.js";+import {+ MAX_INSPECT_ELF_NOTE_ENTRIES,+ MAX_INSPECT_ELF_NOTE_FILE_BYTES,+ type InspectElfNotesInput,+} from "../../domain/native/elfNotes.js";+import { err, ok } from "../../domain/result.js";+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";+import { ELF_NOTES_PROVIDER } from "../../application/InvestigationProviders.js";+import { parseElfNotes } from "./ElfNoteParser.js";++const OPERATION = "inspect_elf_notes";++/** Portable parser over one bounded, identity-checked regular file. */+export class ElfNotesProvider implements ElfNotesPort {+ readonly identity = ELF_NOTES_PROVIDER;+ readonly #resources = new ArtifactResourceScope();++ async close(): Promise<void> {+ try {+ await this.#resources.close();+ } catch (cause: unknown) {+ if (+ !(cause instanceof ArtifactReaderFailure) ||+ cause.cleanup === undefined+ )+ throw cause;+ const error = new ProviderCleanupError(+ ELF_NOTES_PROVIDER.id,+ cause.cleanup.resources,+ { reason: cause.cleanup.reason },+ { cause, operation: OPERATION },+ );+ bindArtifactFileCleanup(cause, error);+ throw error;+ }+ }++ async inspect(input: InspectElfNotesInput, options?: ExecutionOptions) {+ try {+ return await this.#resources.run(async () => {+ const snapshot = await readStableArtifact(+ input.path,+ input.max_file_bytes,+ options?.signal,+ undefined,+ this.#resources,+ );+ return ok(+ parseElfNotes(+ snapshot.bytes,+ {+ path: input.path,+ sha256: snapshot.sha256,+ bytes: snapshot.bytes.length,+ },+ input,+ ),+ );+ });+ } catch (cause) {+ return err(elfNotesFailure(cause, input, options?.signal));+ }+ }+}++const NOTE_TEXT_BUDGET =+ "The ELF note text, hash, and scan budget tied to the admitted image length";++const inputBudgetRemediation = (+ boundary: "file-size" | "capacity",+ input: InspectElfNotesInput,+): string =>+ boundary === "file-size"+ ? input.max_file_bytes >= MAX_INSPECT_ELF_NOTE_FILE_BYTES+ ? `The image exceeds the ${String(MAX_INSPECT_ELF_NOTE_FILE_BYTES)}-byte input ceiling this operation accepts; select a smaller artifact.`+ : `Raise max_file_bytes above ${String(input.max_file_bytes)} bytes or select a smaller artifact; the limit is the caller-selected input read budget.`+ : input.max_entries >= MAX_INSPECT_ELF_NOTE_ENTRIES+ ? `The image exceeds the ${String(MAX_INSPECT_ELF_NOTE_ENTRIES)}-entry note-table ceiling this operation accepts; select a smaller artifact.`+ : `Raise max_entries above ${String(input.max_entries)} or select a smaller artifact; the limit is the caller-selected note entry budget.`;++const elfNotesFailurePrimary = (+ cause: unknown,+ input: InspectElfNotesInput,+) => {+ if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity")+ return new AnalysisArtifactChangedError(+ OPERATION,+ input.path,+ cause.message,+ {+ cause,+ },+ );+ if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled")+ return new AnalysisCancelledError(OPERATION, {+ cause: artifactFileCancellationCause(cause),+ });+ if (cause instanceof ArtifactReaderFailure) {+ if (cause.reason === "limit") {+ // Caller-selected read and entry budgets name the bound to raise.+ // The note text, hash, and scan ceiling equals the admitted image+ // length, so host memory cannot raise it.+ const noteTextBudget = cause.boundary === "memory";+ return new AnalysisResourceConstraintError(+ OPERATION,+ cause.boundary ?? "memory",+ cause.message,+ {+ max_file_bytes: input.max_file_bytes,+ max_entries: input.max_entries,+ },+ {+ cause,+ ...(cause.boundary === undefined+ ? {}+ : noteTextBudget+ ? fixedAllowanceOptions(NOTE_TEXT_BUDGET, "parser")+ : {+ retryable: false as const,+ remediationAction: inputBudgetRemediation(+ cause.boundary,+ input,+ ),+ }),+ },+ );+ }+ if (cause.reason === "path" || cause.reason === "format")+ return new AnalysisInputError(OPERATION, { cause }, [+ {+ path: ["path"],+ reason: "invalid_format",+ message: cause.message,+ },+ ]);+ }+ if (cause instanceof Error && "code" in cause) {+ if (cause.code === "EACCES" || cause.code === "EPERM")+ return new AnalysisAccessDeniedError(OPERATION, input.path, cause.code, {+ cause,+ });+ if (+ ["ENOENT", "ENOTDIR", "ELOOP", "ENAMETOOLONG"].includes(+ String(cause.code),+ )+ )+ return new AnalysisInputError(OPERATION, { cause }, [+ {+ path: ["path"],+ reason: "invalid_value",+ message: `Selected ELF image could not be read (${String(cause.code)}): ${input.path}.`,+ },+ ]);+ }+ return new ArtifactOperationError(+ OPERATION,+ cause instanceof ArtifactReaderFailure ? cause.reason : "io",+ undefined,+ cause instanceof Error ? cause.message : "ELF note inspection failed.",+ { cause },+ );+};++const elfNotesFailure = (+ cause: unknown,+ input: InspectElfNotesInput,+ signal: AbortSignal | undefined,+) => {+ const primary =+ cause instanceof ArtifactFileCleanupFailure &&+ cause.fileCleanupFailure.outcome.kind === "failed"+ ? elfNotesFailurePrimary(cause.fileCleanupFailure.outcome.cause, input)+ : cause instanceof ArtifactFileCleanupFailure && signal?.aborted+ ? new AnalysisCancelledError(OPERATION, { cause: signal.reason })+ : elfNotesFailurePrimary(cause, input);+ if (!(cause instanceof ArtifactReaderFailure) || cause.cleanup === undefined)+ return primary;+ const cleanup = new ProviderCleanupError(+ ELF_NOTES_PROVIDER.id,+ cause.cleanup.resources,+ { reason: cause.cleanup.reason },+ { operation: OPERATION, cause },+ );+ const error = analysisErrorWithCleanupFailure(primary, cleanup, OPERATION);+ bindArtifactFileCleanup(cause, error);+ return error;+};diff --git a/src/server/createServer.ts b/src/server/createServer.tsindex 67f7a4e0d..4d81d8234 100644--- a/src/server/createServer.ts+++ b/src/server/createServer.ts@@ -12,8 +12,13 @@ import { wasmArtifactModule } from "../composition/wasm.js";import { registerWasmTools } from "./registerWasmTools.js";import { snapshotEnvironment } from "../process/snapshotEnvironment.js";import { captureProviderEnvironment } from "./providerEnvironment.js";-import { createPeResourcesService } from "../composition/binaryDiagnostics.js";+import {+ createElfNotesService,+ createPeResourcesService,+} from "../composition/binaryDiagnostics.js";+import type { ElfNotesService } from "../application/binaryDiagnostics/ElfNotesService.js";import type { PeResourcesService } from "../application/binaryDiagnostics/PeResourcesService.js";+import { registerElfNotesTool } from "./registerElfNotesTool.js";import { registerPeResourcesTool } from "./registerPeResourcesTool.js";import type { EvmInterfaceService } from "../application/evm/EvmInterfaceService.js";import {@@ -350,6 +355,7 @@ export const createServer = (const il2cppMetadata =options.il2cppMetadata ?? createIl2cppMetadataService();const peResources = createPeResourcesService();+ const elfNotes = createElfNotesService();const electronFuses = options.electronFuses ?? createElectronFuseService();const webNetworkCapture =options.webNetworkCapture ?? createWebNetworkCaptureService(environment);@@ -451,6 +457,7 @@ export const createServer = (modelArtifact.close(),gpuCodeObjects.close(),peResources.close(),+ elfNotes.close(),electronFuses.close(),webNetworkCapture.close(),javascriptRecovery.close?.() ?? Promise.resolve(),@@ -514,6 +521,7 @@ export const createServer = (rustBinary,il2cppMetadata,peResources,+ elfNotes,electronFuses,webNetworkCapture,};@@ -745,6 +753,7 @@ const registerConfiguredAnalysisTools = (rustBinary,il2cppMetadata,peResources,+ elfNotes,webNetworkCapture,artifactResources,}: ServerToolContext,@@ -794,6 +803,13 @@ const registerConfiguredAnalysisTools = (recordEvidence,withAdmittedAnalysis,);+ registerElfNotesTool(+ server,+ elfNotes,+ toolLogger,+ recordEvidence,+ withAdmittedAnalysis,+ );registerGoTools(server,goBinary,@@ -927,6 +943,7 @@ interface ServerToolContext extends ReturnType<typeof createSessionRecorders> {readonly rustBinary: RustBinaryService;readonly il2cppMetadata: Il2cppMetadataService;readonly peResources: PeResourcesService;+ readonly elfNotes: ElfNotesService;readonly electronFuses: ElectronFuseService;readonly webNetworkCapture: WebNetworkCaptureService;readonly artifactResources: ArtifactResourceScope;diff --git a/src/server/registerElfNotesTool.ts b/src/server/registerElfNotesTool.tsnew file mode 100644index 000000000..c383ad295--- /dev/null+++ b/src/server/registerElfNotesTool.ts@@ -0,0 +1,31 @@+import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";+import type { ElfNotesService } from "../application/binaryDiagnostics/ElfNotesService.js";+import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";+import { toolContract } from "../contracts/toolContracts.js";+import type { Logger } from "pino";+import { createEvidenceToolHandler } from "./contractToolHandler.js";+import type { WithAdmittedAnalysis } from "./analysisAdmission.js";+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";++/** Register the explicit-file ELF note-table workflow and retain its complete Evidence. */+export const registerElfNotesTool = (+ server: EvidenceMcpServer,+ service: ElfNotesService,+ logger: Logger,+ recordEvidence?: EvidenceWriter["recordEvidence"],+ withAdmittedAnalysis?: WithAdmittedAnalysis,+): void => {+ const contract = toolContract("inspect_elf_notes");+ const handler = createEvidenceToolHandler(+ server,+ (input, options) => service.inspect(input, options),+ logger,+ recordEvidence,+ withAdmittedAnalysis,+ );+ server.registerTool(+ contract.name,+ toolRegistrationOptions(contract),+ handler(contract),+ );+};diff --git a/tests/acceptance/elfNotesCli.test.ts b/tests/acceptance/elfNotesCli.test.tsnew file mode 100644index 000000000..cc797ec2c--- /dev/null+++ b/tests/acceptance/elfNotesCli.test.ts@@ -0,0 +1,60 @@+import { writeFile } from "node:fs/promises";+import { join } from "node:path";+import { expect } from "vitest";+import { toolContract } from "../../src/contracts/toolContracts.js";+import { elfNoteFixture } from "../../src/native/elf/ElfNotes.fixture.js";+import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";+import { cliTest } from "../support/cli/cliFixture.js";++cliTest("reports a GNU build-id through the public CLI", async ({ cli }) => {+ const root = await createTestTempDirectory("rea-elf-notes-cli-");+ const path = join(root, "program");+ await writeFile(path, elfNoteFixture({ ownership: "program" }));+ const result = await cli.run({+ arguments: ["inspect-elf-notes", path, "--json"],+ });+ expect(result.exitCode, result.stderr).toBe(0);+ const evidence = toolContract("inspect_elf_notes").outputSchema.parse(+ result.json,+ );+ expect(+ evidence.normalized_result.entries.find(+ (entry) => entry.type_name === "gnu_build_id",+ )?.gnu?.build_id_hex,+ ).toBe("0123456789abcdef0123456789abcdef01234567");+});++cliTest(+ "resolves a relative ELF path against the working directory",+ async ({ cli }) => {+ const root = await createTestTempDirectory("rea-elf-notes-cli-rel-");+ await writeFile(+ join(root, "unsigned"),+ elfNoteFixture({ ownership: "none" }),+ );+ const result = await cli.run({+ arguments: ["inspect-elf-notes", "unsigned", "--json"],+ cwd: root,+ });+ expect(result.exitCode, result.stderr).toBe(0);+ const evidence = toolContract("inspect_elf_notes").outputSchema.parse(+ result.json,+ );+ expect(evidence.normalized_result.tables).toEqual([]);+ expect(evidence.subject?.local_path).toBe(join(root, "unsigned"));+ },+);++cliTest("reports a truncated ELF as invalid input", async ({ cli }) => {+ const root = await createTestTempDirectory("rea-elf-notes-cli-bad-");+ const path = join(root, "broken");+ await writeFile(path, Buffer.from("\x7fELF"));+ const result = await cli.run({+ arguments: ["inspect-elf-notes", path, "--json"],+ });+ expect(result.exitCode).toBe(1);+ expect(result.json).toMatchObject({+ code: "invalid_request",+ details: { operation: "inspect_elf_notes" },+ });+});diff --git a/tests/acceptance/tools/localToolContracts.test.ts b/tests/acceptance/tools/localToolContracts.test.tsindex 980638aa5..f0bb73c6c 100644--- a/tests/acceptance/tools/localToolContracts.test.ts+++ b/tests/acceptance/tools/localToolContracts.test.ts@@ -218,6 +218,7 @@ const pathRequests: readonly [string, Record<string, unknown>][] = [{ capture_path: nul, output_directory: "/tmp/exported-scripts" },],["inspect_pe_resources", { path: nul }],+ ["inspect_elf_notes", { path: nul }],["inspect_binary_layout", { path: nul }],["inspect_recorded_crash", { path: nul }],["inspect_wasm_artifact", { path: nul }],diff --git a/tests/boundary/filesystem/elfNotes.test.ts b/tests/boundary/filesystem/elfNotes.test.tsnew file mode 100644index 000000000..a3c431da4--- /dev/null+++ b/tests/boundary/filesystem/elfNotes.test.ts@@ -0,0 +1,56 @@+import { symlink, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { describe, expect, it } from "vitest";+import { createElfNotesService } from "../../../src/composition/binaryDiagnostics.js";+import { elfNoteFixture } from "../../../src/native/elf/ElfNotes.fixture.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";++describe("ELF note stable filesystem boundary", () => {+ it("reports non-file and malformed ELF selections as caller input errors", async () => {+ const root = await createTestTempDirectory("rea-elf-notes-files-");+ const path = join(root, "program");+ const alias = join(root, "alias");+ const malformed = join(root, "malformed");+ await writeFile(path, elfNoteFixture());+ await writeFile(malformed, Buffer.from("not an elf"));+ await symlink(path, alias);+ const service = createElfNotesService();+ for (const [candidate, reason] of [+ [root, "invalid_format"],+ [alias, "invalid_format"],+ [malformed, "invalid_format"],+ [join(root, "missing"), "invalid_value"],+ [join(path, "child"), "invalid_value"],+ ] as const) {+ const result = await service.inspect({ path: candidate });+ if (result.ok) throw new Error("Expected file acquisition failure");+ expect(result.error).toMatchObject({+ _tag: "AnalysisInputError",+ operation: "inspect_elf_notes",+ issues: [+ {+ path: ["path"],+ reason,+ message: expect.any(String),+ },+ ],+ });+ }+ });++ it("returns typed resource and cancellation failures", async () => {+ const root = await createTestTempDirectory("rea-elf-notes-budget-");+ const path = join(root, "program");+ await writeFile(path, elfNoteFixture());+ const service = createElfNotesService();+ const tooSmall = await service.inspect({ path, max_file_bytes: 64 });+ if (tooSmall.ok) throw new Error("Expected resource budget failure");+ expect(tooSmall.error._tag).toBe("AnalysisResourceConstraintError");+ const cancelled = await service.inspect(+ { path },+ { signal: AbortSignal.abort() },+ );+ if (cancelled.ok) throw new Error("Expected cancellation");+ expect(cancelled.error._tag).toBe("AnalysisCancelledError");+ });+});diff --git a/tests/boundary/mcp/elfNotesMcp.test.ts b/tests/boundary/mcp/elfNotesMcp.test.tsnew file mode 100644index 000000000..7bea4702c--- /dev/null+++ b/tests/boundary/mcp/elfNotesMcp.test.ts@@ -0,0 +1,70 @@+import { writeFile } from "node:fs/promises";+import { join } from "node:path";+import { expect } from "vitest";+import { toolContract } from "../../../src/contracts/toolContracts.js";+import { createServer } from "../../../src/server/createServer.js";+import { createTestBinarySession } from "../../fixtures/binarySession.js";+import { parseMcpToolError } from "../../fixtures/mcpToolError.js";+import { elfNoteFixture } from "../../../src/native/elf/ElfNotes.fixture.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { mcpTest, type TestMcp } from "../../support/mcp/mcpFixture.js";++const connect = async (mcp: TestMcp) => {+ const session = createTestBinarySession(() => {+ throw new Error("ELF note inspection must not start a deep provider");+ });+ const client = await mcp.connect(createServer({ kind: "session", session }));+ return { client, session };+};++mcpTest(+ "advertises inspect_elf_notes and reads a GNU build-id",+ async ({ mcp }) => {+ const { client, session } = await connect(mcp);+ try {+ const advertised = (await client.listTools()).tools.find(+ (tool) => tool.name === "inspect_elf_notes",+ );+ expect(advertised?.annotations).toMatchObject({+ readOnlyHint: false,+ idempotentHint: true,+ });+ const root = await createTestTempDirectory("rea-elf-notes-mcp-");+ const path = join(root, "program");+ await writeFile(path, elfNoteFixture({ bits: 32, ownership: "section" }));+ const response = await client.callTool({+ name: "inspect_elf_notes",+ arguments: { path },+ });+ expect(response.isError, JSON.stringify(response.content)).not.toBe(true);+ const evidence = toolContract("inspect_elf_notes").outputSchema.parse(+ response.structuredContent,+ );+ expect(evidence.normalized_result.format).toBe("elf32");+ expect(+ evidence.normalized_result.entries.find(+ (entry) => entry.type_name === "gnu_build_id",+ )?.gnu?.build_id_hex,+ ).toBe("0123456789abcdef0123456789abcdef01234567");+ } finally {+ await session.close();+ }+ },+);++mcpTest("requires an absolute path for inspect_elf_notes", async ({ mcp }) => {+ const { client, session } = await connect(mcp);+ try {+ const response = await client.callTool({+ name: "inspect_elf_notes",+ arguments: { path: "program" },+ });+ expect(response.isError).toBe(true);+ expect(parseMcpToolError(response).error).toMatchObject({+ code: "invalid_request",+ details: { operation: "inspect_elf_notes" },+ });+ } finally {+ await session.close();+ }+});