From 9bab55337ab10616be6929afddb08fb19fbb8ab7 Mon Sep 17 00:00:00 2001
From: N0zoM1z0 <161784452+N0zoM1z0@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:24:33 +0800
Subject: [PATCH] feat(ghidra): add atomic function annotation edits (#709)
* feat(ghidra): edit function annotations atomically
Return annotation readback and refreshed function analysis through CLI and MCP. Own each database transaction, invalidate caches and immutable snapshots, preserve executable bytes, and retain the Windows mutation boundary.
Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering)
* fix(ghidra): preserve qualified function annotation identity
Preserve namespaces during local name writes and match qualified readback to the refreshed dossier. Add a producer-shaped regression and verify a real namespaced C++ function through the CLI.
Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering)
* test(ghidra): align verification with annotation authority
Keep strict capability and profile checks while admitting the explicit session metadata operation. Verify packaged transport authority and atomic transaction commitments and preserve a read-only Windows expectation.
Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering)
---
AGENTS.md | 2 +-
README.md | 14 +--
README_ar.md | 2 +-
README_ja.md | 2 +-
README_ko.md | 2 +-
README_zh.md | 2 +-
bridge/ghidra/ReaGhidraBridge.java | 102 +++++++++++++++-
...rovider-selection-and-analysis-profiles.md | 6 +-
docs/ghidra-dos.md | 19 +++
docs/installation.md | 8 +-
docs/native-investigation.md | 6 +-
docs/product-catalog.json | 19 +--
docs/provider-evaluation.md | 17 +--
docs/roadmap.md | 4 +-
.../managed-conformance-manifest.json | 4 +-
scripts/verify-packaged-ghidra-windows.mjs | 5 +-
scripts/verify-packed-bridge.mjs | 6 +-
scripts/verify-real-ghidra-com.mjs | 89 ++++++++++++++
scripts/verify-real-ghidra-dos.mjs | 6 +-
scripts/verify-real-ghidra-windows.mjs | 16 ++-
skills/reverse-engineer-anything/SKILL.md | 4 +-
.../references/native-and-artifacts.md | 4 +
src/application/DirectAnalysis.ts | 1 +
src/cli/coreAnalysisCommands.ts | 49 ++++++++
src/cliCommandNames.ts | 1 +
src/contracts/officialToolContracts.ts | 6 +
src/contracts/toolContractExamples.ts | 5 +
src/contracts/toolEffects.ts | 6 +
src/contracts/toolOutputSchemaGroups.ts | 2 +
src/domain/nativeFunctionAnnotations.ts | 52 ++++++++
src/generatedMcpToolCatalog.ts | 2 +-
src/ghidra/GhidraAnalysisProfile.ts | 3 +-
src/ghidra/GhidraAnnotations.test.ts | 114 ++++++++++++++++++
src/ghidra/GhidraClient.ts | 4 +-
src/ghidra/GhidraFunctionValues.ts | 11 +-
src/ghidra/GhidraProvider.behavior.test.ts | 58 ++++++++-
src/ghidra/GhidraProvider.test.ts | 6 +-
src/ghidra/GhidraProvider.ts | 10 +-
src/ghidra/GhidraProviderCapabilities.ts | 20 ++-
src/ghidra/GhidraSessionValues.test.ts | 45 ++++++-
src/ghidra/GhidraSessionValues.ts | 18 +--
src/hopper/HopperProvider.ts | 1 +
src/server/registerOfficialTools.ts | 3 +
tests/boundary/cli/productCatalog.test.ts | 1 +
tests/boundary/mcp/ghidraEvidenceMcp.test.ts | 3 +-
tests/boundary/mcp/ghidraMcpHarness.ts | 2 +-
tests/boundary/mcp/officialTools.test.ts | 24 ++++
.../providers/ghidra/ghidraClient.test.ts | 8 +-
tests/fixtures/fakeGhidra.mjs | 8 +-
49 files changed, 730 insertions(+), 72 deletions(-)
create mode 100644 src/domain/nativeFunctionAnnotations.ts
create mode 100644 src/ghidra/GhidraAnnotations.test.ts
diff --git a/AGENTS.md b/AGENTS.md
index b73238f19..2ccbf8fd5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,7 +2,7 @@
## Product Direction
-REA exposes reverse-engineering tools through a CLI and MCP server. Hopper and the bring-your-own Ghidra adapter are operation-capable deep binary-analysis providers. Ghidra is supported on Linux x64 and macOS x64/arm64 with matching native decompiler tools, and has an experimental Windows x64 P0 boundary for approved native x86-64 PE applications; it supplies admitted read-only inventory and function-analysis operations but no GUI or mutation authority. Keep provider-specific code out of the domain and application layers.
+REA exposes reverse-engineering tools through a CLI and MCP server. Hopper and the bring-your-own Ghidra adapter are operation-capable deep binary-analysis providers. Ghidra is supported on Linux x64 and macOS x64/arm64 with matching native decompiler tools, and has an experimental Windows x64 P0 boundary for approved native x86-64 PE applications; on Linux and macOS it supplies inventory, function analysis, and atomic function annotation edits in an ephemeral database, without modifying executable bytes or controlling a GUI. Windows P0 has no mutation authority. Keep provider-specific code out of the domain and application layers.
Prioritize:
diff --git a/README.md b/README.md
index 9d75bc666..1dd1e86ae 100644
--- a/README.md
+++ b/README.md
@@ -149,7 +149,7 @@ Update either installation with `rea update`.
- Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+
- npm; REA does not require or install a particular npm version
-Native binary analysis requires [Hopper](https://www.hopperapp.com/) or [Ghidra](#ghidra-read-only-analysis-provider). Hopper is separate software with its own license; its demo supports analysis with vendor-defined limits. REA can use Ghidra that you have already installed.
+Native binary analysis requires [Hopper](https://www.hopperapp.com/) or [Ghidra](#ghidra-analysis-provider). Hopper is separate software with its own license; its demo supports analysis with vendor-defined limits. REA can use Ghidra that you have already installed.
Windows Ghidra support is experimental for native x86-64 PE applications on local NTFS. The package bundles native Job Object, private-DACL, and path-admission controls. See [Windows Ghidra P0](docs/windows-ghidra-p0.md) for prerequisites and verified scope.
@@ -184,7 +184,7 @@ Install the missing packages and rerun `rea setup`. The Linux demo needs Xvfb, P
REA defaults `HOPPER_LAUNCHER_PATH` to `/Applications/Hopper Disassembler.app/Contents/MacOS/hopper` on macOS and `/opt/hopper/bin/Hopper` on Linux. Explicit configuration always takes precedence.
-### Ghidra read-only analysis provider
+### Ghidra analysis provider
Already use Ghidra? REA can connect it to your agent on Linux x64 or macOS x64/arm64. It requires **Ghidra 12.1.4** and a **64-bit JDK 21**. On macOS, your Ghidra installation must also include the native decompiler for your architecture.
@@ -200,7 +200,7 @@ rea providers --json
Setup checks the installations and saves their paths in your selected agents' configuration after approval. Ghidra and Java must already be installed; REA does not download or change them.
-The adapter exposes **25 read-only operations** for functions, strings, symbols, assembly, decompilation, calls, references, instructions, and data types. These also support REA's overview, search, call-graph, and function-analysis workflows. Ghidra does not provide GUI controls or annotation changes through REA.
+The adapter exposes inventory, function, memory and load-image inspection, plus atomic function annotation edits on Linux and macOS. `annotate_native_function` edits names and entry comments in the session database and returns a refreshed function dossier; executable bytes stay unchanged. Ghidra does not provide GUI controls through REA.
REA analyzes a temporary copy of the target and removes the temporary project when the session closes. Results identify what Ghidra observed and what it could not resolve. Decompilation produces pseudocode rather than the original source.
@@ -307,7 +307,7 @@ See [native investigation](docs/native-investigation.md) for keyed archives, ins
| Tool family | Count | Examples |
| ------------------------- | ----: | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Native inspection | 40 | functions, pseudocode, assembly, strings, symbols, calls, references, annotations, byte reads, and file offsets |
+| Native inspection | 41 | functions, pseudocode, assembly, strings, symbols, calls, references, annotations, byte reads, and file offsets |
| Investigation workflows | 14 | app overviews, function dossiers, native APIs and dispatch, batch decompilation, feature traces, call paths, call graphs, Swift and Objective-C discovery |
| Native macOS utilities | 7 | Mach-O metadata, code signatures, plists, architectures, and Swift demangling without launching Hopper |
| Artifact graph | 5 | directory and package inventories, compiled Interface Builder files, Apple asset catalogs, and extraction |
@@ -453,7 +453,7 @@ flowchart LR
REA --> Session["Target-bound session router"]
Session --> Registry["Deep-provider registry
deterministic selection"]
Registry --> Hopper["Hopper provider"]
- Registry --> Ghidra["Ghidra provider
read-only inventory + function analysis"]
+ Registry --> Ghidra["Ghidra provider
inventory + function analysis + annotations"]
Hopper --> Runtime["Owned provider runtime
deadline + bounded diagnostics + cleanup"]
Ghidra --> Runtime
Session --> Native["Native macOS provider"]
@@ -522,7 +522,7 @@ Use `--provider`, or `provider_id` in MCP, to choose Hopper or Ghidra for a targ
With `auto`, REA selects the only available tool that supports the target. If both are available, specify one before opening the target. The session keeps that choice until you explicitly switch or close it; a failure never silently switches tools. Artifact-only analysis can work without a native analysis tool.
-Run `rea providers` and `rea capabilities` to check availability and supported operations. Ghidra exposes 25 read-only operations on supported Linux and macOS hosts. GUI controls and annotation changes require Hopper. Windows Ghidra P0 supports native x86-64 PE applications on local NTFS with bundled native controls.
+Run `rea providers` and `rea capabilities` to check availability and supported operations. Ghidra supports inspection and atomic function annotation edits on Linux and macOS. Its database edits are discarded on close; GUI controls require Hopper. Windows Ghidra P0 supports read-only analysis of native x86-64 PE applications on local NTFS with bundled native controls.
The session also reports active work and cleanup status. If a caller times out, the analysis tool may still be busy; `analysis_activity` reports that state. A `cleanup_incomplete` result identifies resources whose shutdown or removal could not be verified. See [provider selection and analysis profiles](docs/adr/0001-provider-selection-and-analysis-profiles.md) for session, cache, and process-tracking details.
@@ -628,7 +628,7 @@ No. Setup can install Hopper for you, but Hopper remains separate software with
Does REA install or include Ghidra or Java?
-No. REA connects to an existing Ghidra installation. Run setup after providing the Ghidra and Java paths shown in the [Ghidra section](#ghidra-read-only-analysis-provider).
+No. REA connects to an existing Ghidra installation. Run setup after providing the Ghidra and Java paths shown in the [Ghidra section](#ghidra-analysis-provider).
diff --git a/README_ar.md b/README_ar.md
index d415dda64..65dd7ba7f 100644
--- a/README_ar.md
+++ b/README_ar.md
@@ -204,7 +204,7 @@ rea setup
| عائلة الأدوات | العدد | الاستخدام |
| --------------------- | ----: | -------------------------------------------------------------------------------------- |
-| فحص الملفات التنفيذية | 40 | الدوال والشيفرة شبه المصدرية والتعليمات والسلاسل والرموز والمراجع والتعليقات |
+| فحص الملفات التنفيذية | 41 | الدوال والشيفرة شبه المصدرية والتعليمات والسلاسل والرموز والمراجع والتعليقات |
| التحليل المركب | 14 | النظرة العامة وتحليل الدوال وفك الترجمة الدفعي ومخطط الاستدعاء وفحص Swift وObjC |
| أدوات macOS الأصلية | 7 | بيانات Mach-O والتوقيعات وplist والمعماريات واستعادة أسماء Swift |
| الملفات والحزم | 5 | فحص الدلائل والحزم وInterface Builder وموارد Apple والاستخراج |
diff --git a/README_ja.md b/README_ja.md
index 0e9b3a35e..23b4a4f12 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -193,7 +193,7 @@ REA は手順 1〜5 のバイナリ解析を処理し、手順 6 はエージェ
| ツール分類 | 数 | 用途 |
| -------------------- | --: | --------------------------------------------------------------------------- |
-| バイナリ検査 | 40 | 関数、疑似コード、アセンブリ、文字列、シンボル、参照、注釈 |
+| バイナリ検査 | 41 | 関数、疑似コード、アセンブリ、文字列、シンボル、参照、注釈 |
| 組み合わせた解析 | 14 | 概要、関数解析、一括逆コンパイル、呼び出しグラフ、Swift と ObjC |
| macOS ネイティブ | 7 | Mach-O メタデータ、署名、plist、アーキテクチャ、Swift 名の復元 |
| ファイルとパッケージ | 5 | ディレクトリとパッケージ、Interface Builder、Apple リソース、抽出 |
diff --git a/README_ko.md b/README_ko.md
index 07aac2fc6..f6b10abd0 100644
--- a/README_ko.md
+++ b/README_ko.md
@@ -194,7 +194,7 @@ REA는 1–5단계의 바이너리 분석을 처리합니다. 6단계는 에이
| 도구 분류 | 수 | 용도 |
| ----------------- | --: | -------------------------------------------------------------------- |
-| 바이너리 검사 | 40 | 함수, 의사 코드, 어셈블리, 문자열, 심볼, 참조, 주석 |
+| 바이너리 검사 | 41 | 함수, 의사 코드, 어셈블리, 문자열, 심볼, 참조, 주석 |
| 결합 분석 | 14 | 개요, 함수 분석, 일괄 디컴파일, 호출 그래프, Swift와 ObjC 검사 |
| macOS 네이티브 | 7 | Mach-O 메타데이터, 서명, plist, 아키텍처, Swift 이름 복원 |
| 파일과 패키지 | 5 | 디렉터리와 패키지 검사, Interface Builder, Apple 리소스, 추출 |
diff --git a/README_zh.md b/README_zh.md
index 5cfdb8692..cb03593e5 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -193,7 +193,7 @@ REA 负责第 1–5 步中的二进制分析。第 6 步由智能体使用其常
| 工具类别 | 数量 | 用途 |
| ----------------- | ---: | --------------------------------------------------------- |
-| 二进制检查 | 40 | 函数、伪代码、汇编、字符串、符号、段、引用与注释 |
+| 二进制检查 | 41 | 函数、伪代码、汇编、字符串、符号、段、引用与注释 |
| 组合分析 | 14 | 概览、函数分析、批量反编译、调用图、Swift 与 ObjC 检查 |
| macOS 原生工具 | 7 | Mach-O 元数据、代码签名、plist、架构与 Swift 符号还原 |
| 制品检查 | 5 | 目录与软件包检查、Interface Builder、Apple 资源目录与提取 |
diff --git a/bridge/ghidra/ReaGhidraBridge.java b/bridge/ghidra/ReaGhidraBridge.java
index e6b9902d1..f13996938 100644
--- a/bridge/ghidra/ReaGhidraBridge.java
+++ b/bridge/ghidra/ReaGhidraBridge.java
@@ -117,6 +117,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
"params"
);
private static final String[] CAPABILITIES = {
+ "annotate_native_function",
"inspect_native_load_image",
"read_bytes",
"address_to_file_offset",
@@ -191,6 +192,9 @@ public final class ReaGhidraBridge extends HeadlessScript {
"Ghidra imported-byte digest does not match the admitted target"
);
}
+ // GhidraScript wraps run() in a transaction. End it before serving so
+ // each edit owns a real outer transaction and can roll back immediately.
+ end(true);
try {
initializeDecompiler();
serve(descriptor);
@@ -363,6 +367,11 @@ public final class ReaGhidraBridge extends HeadlessScript {
case "resolve_native_call_targets" -> resolveNativeCallTargets(request.params);
case "xrefs" -> xrefs(request.params);
case "analyze_function" -> analyzeFunction(request.params);
+ case "annotate_native_function" -> {
+ if (!descriptor.transport.equals("unix-socket"))
+ throw new RequestFailure("method_unavailable", "Windows P0 does not admit database mutation");
+ yield annotateNativeFunction(request.params);
+ }
default -> throw new RequestFailure(
"method_unavailable",
"Bridge method is unavailable"
@@ -395,10 +404,15 @@ public final class ReaGhidraBridge extends HeadlessScript {
result.addProperty("run_id", descriptor.runId);
result.addProperty("profile_digest", descriptor.profileDigest);
result.add("provider", provider);
- result.addProperty("read_only", true);
+ boolean readOnly = !descriptor.transport.equals("unix-socket");
+ result.addProperty("read_only", readOnly);
result.addProperty("analysis_complete", !timedOut);
result.addProperty("analysis_timed_out", timedOut);
- result.add("capabilities", GSON.toJsonTree(CAPABILITIES));
+ result.add("capabilities", GSON.toJsonTree(
+ java.util.Arrays.stream(CAPABILITIES)
+ .filter(value -> !readOnly || !value.equals("annotate_native_function"))
+ .toArray(String[]::new)
+ ));
result.add("target", target);
return result;
}
@@ -954,6 +968,90 @@ public final class ReaGhidraBridge extends HeadlessScript {
return result;
}
+ private void invalidateAnalysisCaches() {
+ nameInventory = null;
+ procedureInventory = null;
+ stringInventory = null;
+ if (decompiler != null) decompiler.flushCache();
+ }
+
+ private JsonObject annotationReadback(Function function) {
+ Address entry = function.getEntryPoint();
+ JsonObject value = new JsonObject();
+ value.addProperty("address", canonicalAddress(entry));
+ value.addProperty("name", procedureName(function));
+ value.addProperty("comment", currentProgram.getListing().getComment(CommentType.PRE, entry));
+ value.addProperty("inline_comment", currentProgram.getListing().getComment(CommentType.EOL, entry));
+ return value;
+ }
+
+ private JsonObject annotateNativeFunction(JsonObject params) throws Exception {
+ if (!Set.of("procedure", "name", "comment", "inline_comment").containsAll(params.keySet()))
+ throw new RequestFailure("invalid_request", "Unknown function annotation field");
+ if (!params.has("name") && !params.has("comment") && !params.has("inline_comment"))
+ throw new RequestFailure("invalid_request", "Supply at least one annotation change");
+ Function function = resolveProcedure(requireString(params, "procedure"));
+ Address entry = function.getEntryPoint();
+ if (function.isExternal() || !currentProgram.getMemory().contains(entry))
+ throw new RequestFailure("invalid_request", "Annotations require a local function entry: " + canonicalAddress(entry));
+ int transaction = currentProgram.startTransaction("REA function annotations");
+ boolean commit = false;
+ try {
+ // Validate edits through Ghidra's own setters, including name rules.
+ // A later invalid name must roll back earlier comment writes.
+ for (String field : List.of("comment", "inline_comment")) {
+ if (params.has(field)) {
+ String text = requireText(params, field);
+ CommentType type = field.equals("comment") ? CommentType.PRE : CommentType.EOL;
+ currentProgram.getListing().setComment(entry, type, text.isEmpty() ? null : text);
+ }
+ }
+ if (params.has("name"))
+ function.setName(requireString(params, "name"), SourceType.USER_DEFINED);
+ monitor.checkCancelled();
+ invalidateAnalysisCaches();
+ JsonObject readback = annotationReadback(function);
+ for (String field : List.of("name", "comment", "inline_comment")) {
+ if (!params.has(field)) continue;
+ String requested = requireText(params, field);
+ JsonElement measured = readback.get(field);
+ String expected = !field.equals("name") && requested.isEmpty() ? null : requested;
+ String observed = field.equals("name") ? function.getName() :
+ (measured.isJsonNull() ? null : measured.getAsString());
+ if (!java.util.Objects.equals(expected, observed))
+ throw new RequestFailure("annotation_readback_mismatch", "Annotation readback differs for " + field + " at " + canonicalAddress(entry));
+ }
+ JsonObject query = new JsonObject();
+ query.addProperty("procedure", canonicalAddress(entry));
+ JsonObject result = new JsonObject();
+ result.add("annotations", readback);
+ result.add("dossier", analyzeFunction(query));
+ JsonObject effects = new JsonObject();
+ effects.addProperty("scope", "session-analysis-database");
+ effects.addProperty("source_bytes_modified", false);
+ effects.addProperty("persists_after_close", false);
+ result.add("effects", effects);
+ monitor.checkCancelled();
+ commit = true;
+ return result;
+ }
+ catch (ghidra.util.exception.InvalidInputException | ghidra.util.exception.DuplicateNameException exception) {
+ throw new RequestFailure("invalid_function_name", "Invalid function name at " + canonicalAddress(entry) + ": " + safeMessage(exception));
+ }
+ finally {
+ currentProgram.endTransaction(transaction, commit);
+ // Rollback also invalidates inventory and decompiler views.
+ invalidateAnalysisCaches();
+ }
+ }
+
+ private static String requireText(JsonObject params, String field) {
+ JsonElement value = params.get(field);
+ if (value == null || !value.isJsonPrimitive() || !value.getAsJsonPrimitive().isString())
+ throw new RequestFailure("invalid_request", "Annotation " + field + " must be text");
+ return value.getAsString();
+ }
+
private JsonObject analyzeFunction(JsonObject params) throws Exception {
requireKeys(params, Set.of("procedure"));
Function function = resolveProcedure(requireString(params, "procedure"));
diff --git a/docs/adr/0001-provider-selection-and-analysis-profiles.md b/docs/adr/0001-provider-selection-and-analysis-profiles.md
index d918390d0..7d1fdfe8b 100644
--- a/docs/adr/0001-provider-selection-and-analysis-profiles.md
+++ b/docs/adr/0001-provider-selection-and-analysis-profiles.md
@@ -569,5 +569,7 @@ The first six implementation stages are shipped:
Future stages may deepen format and indirect-flow coverage, but must continue
to compare normalized semantics rather than provider-specific pseudocode or
-assembly text. Ghidra continues to omit GUI and mutation operations, so
-unsupported requests cannot route to an unverified implementation.
+assembly text. Linux and macOS now admit atomic function-name and entry-comment
+edits in the ephemeral database, with readback, rollback, and cache invalidation.
+Executable bytes remain unchanged. Windows P0 retains its read-only boundary;
+GUI and other unimplemented mutations remain unavailable.
diff --git a/docs/ghidra-dos.md b/docs/ghidra-dos.md
index 5c521daa4..a43e52408 100644
--- a/docs/ghidra-dos.md
+++ b/docs/ghidra-dos.md
@@ -167,3 +167,22 @@ executable fixtures, an emulator, or an existing analysis database.
Provider p-code representations can contain process-specific address-space selector
tokens. The lane preserves those reported values and compares stable dossier
observations rather than asserting cross-process identity of raw p-code.
+
+## Function annotations
+
+`annotate_native_function` changes the name and/or comments at one exact local function entry, verifies readback, and returns a refreshed dossier. This is useful when recording recovered DOS function roles; it does not claim original-source names. Name writes preserve the existing namespace; readback returns the fully qualified name used by function inventories. Regular comments map to Ghidra PRE comments and inline comments to EOL comments. Empty text clears a comment; omitted fields preserve it. The whole edit rolls back if a setter, readback or analysis fails.
+
+```json
+{
+ "procedure": "0x10100",
+ "name": "entry",
+ "comment": "Recovered startup role",
+ "inline_comment": "Inspect segment setup"
+}
+```
+
+```bash
+rea annotate-native-function /local/program.com 0x10100 --target-format dos-com --provider ghidra --name entry --comment 'Recovered startup role' --json
+```
+
+The CLI returns the updated analysis before closing its isolated session. MCP edits remain visible to later reads until `close_binary`. Original bytes remain unchanged, database edits are discarded on close, and immutable analysis snapshots are invalidated after edits. This operation does not save a Ghidra project, change ABI/types/body ranges, patch instructions, or emulate a DOS runtime. Windows P0 does not admit it.
diff --git a/docs/installation.md b/docs/installation.md
index d4a516669..3e3ec2c0c 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -224,9 +224,11 @@ operations and twelve function-analysis operations. These cover metadata,
decompilation, assembly, resolved calls, typed references, xrefs, function
dossiers, instructions, recovered data types, measured load mappings, loaded
memory bytes, and observed file offsets. Independent load-image attestation
-currently supports DOS MZ only; PE returns its measurements with that limitation.
-GUI controls and annotation
-changes require Hopper.
+supports DOS MZ and explicitly selected COM; PE returns its measurements with that limitation.
+On Linux and macOS, `annotate_native_function` also edits a function name and/or
+entry comments atomically and returns refreshed analysis. These session metadata
+edits leave executable bytes unchanged and are discarded on close. GUI controls
+require Hopper; Windows P0 remains read-only.
Windows P0 admits native x86-64 PE applications on fixed local NTFS volumes.
The npm package bundles native Job Object ownership, protected private runtime
diff --git a/docs/native-investigation.md b/docs/native-investigation.md
index 43627c33f..a8cd6ac92 100644
--- a/docs/native-investigation.md
+++ b/docs/native-investigation.md
@@ -150,8 +150,10 @@ the matching native decompiler. Experimental Windows x64 P0 admits native
x86-64 PE applications on local NTFS using bundled Job Object ownership,
protected runtime DACLs, and handle-based path admission. See [Windows Ghidra P0](windows-ghidra-p0.md) and
[issue #527](https://github.com/morluto/rea/issues/527).
-Ghidra has no GUI or mutation authority, and REA never falls back automatically
-to Hopper.
+On Linux and macOS, `annotate_native_function` atomically edits a function name
+and entry comments in the ephemeral database, returning refreshed analysis
+without changing executable bytes. Windows P0 remains read-only. Ghidra has no
+GUI authority, and REA never falls back automatically to Hopper.
- `npm run verify:ghidra`: host-native debug/stripped targets, native type layout,
instruction/call facts, value dependencies and process/project cleanup.
diff --git a/docs/product-catalog.json b/docs/product-catalog.json
index b2c226b5a..658557640 100644
--- a/docs/product-catalog.json
+++ b/docs/product-catalog.json
@@ -10,15 +10,16 @@
"skill_version": "24"
},
"tools": {
- "total": 117,
+ "total": 118,
"families": [
{
"id": "direct",
"surface": "official-proxy",
- "count": 40,
+ "count": 41,
"tools": [
"address_name",
"address_to_file_offset",
+ "annotate_native_function",
"comment",
"current_address",
"current_document",
@@ -210,6 +211,7 @@
"address_name",
"address_to_file_offset",
"analyze_function",
+ "annotate_native_function",
"inspect_native_data_type",
"inspect_native_instruction",
"inspect_native_load_image",
@@ -469,12 +471,13 @@
}
],
"cli": {
- "primary_count": 72,
+ "primary_count": 73,
"commands": [
"address-to-file-offset",
"analyze",
"analyze-javascript-application",
"analyze-web-bundle",
+ "annotate-native-function",
"build-reconstruction-obligation-ledger",
"capabilities",
"capture-browser-scenario",
@@ -553,15 +556,15 @@
},
"runtime_catalog": {
"counts": {
- "cli_commands": 72,
- "mcp_tools": 117,
+ "cli_commands": 73,
+ "mcp_tools": 118,
"mcp_prompts": 6
},
"digests": {
- "tools_sha256": "be74884c49199aa22146a94dfbf8c11dd0ae0b87c0896e32a10b9ff691fdd342",
+ "tools_sha256": "bbd9aacf7bb0bc54a8f8743491583482e1176252513d99780a309d0fddeb3df0",
"prompts_sha256": "4762db348821fec787a5b8c6423f2c48a71f6f0ec2afee97b16ad69030ec504b",
- "combined_sha256": "f63ae9b3480f206700cf334c54b3267aff8d0c3a7f4e782d8b5f7952cfdd5271",
- "providers_sha256": "c1a6849b2524347e6cf9e004a17ba1805f86114b2da72eb689a075afbbb1aada"
+ "combined_sha256": "b4f7e5860d90b029876b58fe7cd4a8041fef1f2add23440e37e90827d808e503",
+ "providers_sha256": "e094c361b60ec930a6062a1a90ee05536ce411541dba5b51ace7e2da2ba25af0"
}
}
}
diff --git a/docs/provider-evaluation.md b/docs/provider-evaluation.md
index ca4f80b6d..dbb59d3a3 100644
--- a/docs/provider-evaluation.md
+++ b/docs/provider-evaluation.md
@@ -9,7 +9,10 @@ operations after analysis completes. They cover inventories, search,
decompilation, assembly, function metadata, resolved calls, references, control
flow, instructions, and recovered types. Results identify the provider version,
analysis settings, target digest, and any unavailable or incomplete facts.
-Ghidra does not expose Hopper's GUI or annotation operations.
+On Linux and macOS, `annotate_native_function` additionally edits names and entry
+comments atomically, verifies readback, and returns refreshed function analysis.
+Changes live only in the session database and leave executable bytes unchanged.
+Ghidra does not expose GUI controls; Windows P0 remains read-only.
Windows x64 P0 supports native x86-64 PE applications on local NTFS with
bundled Job Object ownership, protected runtime DACLs, and handle-based path
@@ -152,12 +155,12 @@ only the generic process mechanisms.
## Shortlist
-| Provider | License / automation surface | What it brings | REA fit and blockers |
-| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [Ghidra](https://github.com/NationalSecurityAgency/ghidra) | Apache-2.0 source license; `analyzeHeadless`, Java APIs, and PyGhidra | Static analysis, multiple processors and formats, scripting, and project/database workflows | 25 read-only operations shipped on Linux/macOS with installation checks, temporary projects, a serial API queue, and real ELF/PE/Mach-O conformance. Experimental Windows x64 P0 supports native x86-64 PE on local NTFS with bundled native controls and ordinary-user CLI/MCP verification; GUI and mutation operations are unavailable. |
-| [Rizin](https://github.com/rizinorg/rizin) / [rz-pipe](https://github.com/rizinorg/rz-pipe) | Rizin repository contains LGPL-3.0 and GPL-3.0 components; `rizin`, `rz-bin`, and language bridges through `rzpipe` | Portable CLI analysis, disassembly/debugging, many architectures and file formats, JSON command output | Good candidate for a process-backed Linux provider and fast metadata fallback. License/component inventory must be preserved; command output needs version-pinned parsers and semantic conformance before evidence is trusted. |
-| [LIEF](https://github.com/lief-project/LIEF) | Apache-2.0; C++, Python, and other bindings | Deterministic parsing and modification of ELF, PE, Mach-O, COFF, and related executable formats; headers, sections, symbols, relocations, and functions | Best near-term complement, not a decompiler replacement. It can cover format metadata and artifact evidence without a long-lived analysis process; function semantics, pseudocode, CFG, and cross-reference parity remain out of scope unless separately demonstrated. |
-| [Binary Ninja](https://docs.binary.ninja/dev/index.html) | API/documentation components are MIT, while the analysis product is licensed by edition; commercial, Ultimate, or Headless license is required for headless automation | Python/Core/C++/Rust APIs, headless loading, IL layers, function analysis, plugins, and configurable analysis | Strong technical fit for a native provider, especially function dossiers. Commercial licensing, license-secret handling, native runtime packaging, and multithreaded lifecycle rules are material deployment blockers. |
+| Provider | License / automation surface | What it brings | REA fit and blockers |
+| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Ghidra](https://github.com/NationalSecurityAgency/ghidra) | Apache-2.0 source license; `analyzeHeadless`, Java APIs, and PyGhidra | Static analysis, multiple processors and formats, scripting, and project/database workflows | 25 read-only operations shipped on Linux/macOS with installation checks, temporary projects, a serial API queue, and real ELF/PE/Mach-O conformance. Experimental Windows x64 P0 supports native x86-64 PE on local NTFS with bundled native controls and ordinary-user CLI/MCP verification; Linux/macOS additionally support atomic session function annotations; Windows mutation and all Ghidra GUI operations are unavailable. |
+| [Rizin](https://github.com/rizinorg/rizin) / [rz-pipe](https://github.com/rizinorg/rz-pipe) | Rizin repository contains LGPL-3.0 and GPL-3.0 components; `rizin`, `rz-bin`, and language bridges through `rzpipe` | Portable CLI analysis, disassembly/debugging, many architectures and file formats, JSON command output | Good candidate for a process-backed Linux provider and fast metadata fallback. License/component inventory must be preserved; command output needs version-pinned parsers and semantic conformance before evidence is trusted. |
+| [LIEF](https://github.com/lief-project/LIEF) | Apache-2.0; C++, Python, and other bindings | Deterministic parsing and modification of ELF, PE, Mach-O, COFF, and related executable formats; headers, sections, symbols, relocations, and functions | Best near-term complement, not a decompiler replacement. It can cover format metadata and artifact evidence without a long-lived analysis process; function semantics, pseudocode, CFG, and cross-reference parity remain out of scope unless separately demonstrated. |
+| [Binary Ninja](https://docs.binary.ninja/dev/index.html) | API/documentation components are MIT, while the analysis product is licensed by edition; commercial, Ultimate, or Headless license is required for headless automation | Python/Core/C++/Rust APIs, headless loading, IL layers, function analysis, plugins, and configurable analysis | Strong technical fit for a native provider, especially function dossiers. Commercial licensing, license-secret handling, native runtime packaging, and multithreaded lifecycle rules are material deployment blockers. |
## Recommended order
diff --git a/docs/roadmap.md b/docs/roadmap.md
index daac7d8ee..77ca34678 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -48,7 +48,9 @@ GitHub Copilot CLI, Command Code, and VS Code using each client's configuration
Ghidra analysis supports Linux x64 and macOS x64/arm64 with Ghidra 12.1.4 and a
64-bit full JDK 21. macOS also requires the matching native decompiler. The
adapter exposes thirteen inventory operations and twelve function-analysis
-operations, for 25 read-only operations total. Approved setup saves verified
+operations, for 25 read-only operations total. Linux and macOS additionally support
+atomic function-name and entry-comment edits with refreshed analysis; metadata
+is discarded on close and executable bytes stay unchanged. Approved setup saves verified
installation paths in agent configurations without installing or changing
Ghidra or Java.
diff --git a/docs/verification/managed-conformance-manifest.json b/docs/verification/managed-conformance-manifest.json
index 57873f205..57c1ea486 100644
--- a/docs/verification/managed-conformance-manifest.json
+++ b/docs/verification/managed-conformance-manifest.json
@@ -1,5 +1,5 @@
{
- "manifest_id": "ecm_8d5469adca2b281028f4b94f0e82c8a104c988d97542a91b51d903e764d6c779",
+ "manifest_id": "ecm_125743de92b0cbb08a3cb11ee0d9305f60e5c4fb81152b8b748d348f91f99ee8",
"verifier": {
"id": "rea-managed-conformance",
"version": "1"
@@ -13,7 +13,7 @@
"skill_digests": [
{
"skill_id": "reverse-engineer-anything",
- "sha256": "73d1f6ba53bb3d3a115a5a5895dd21975494147b05f3360cc19d35437d060cd0"
+ "sha256": "26338313efd5c941e1f3e1f1d35e2605d47749f674c359458e76d5a470b0cbb1"
}
],
"claims": [
diff --git a/scripts/verify-packaged-ghidra-windows.mjs b/scripts/verify-packaged-ghidra-windows.mjs
index 7c3fa36c1..3df61d288 100644
--- a/scripts/verify-packaged-ghidra-windows.mjs
+++ b/scripts/verify-packaged-ghidra-windows.mjs
@@ -257,7 +257,10 @@ try {
pathToFileURL(join(packageRoot, "dist/ghidra/GhidraSessionValues.js"))
)
).GHIDRA_SESSION_CAPABILITIES.filter(
- (name) => name !== "ping" && name !== "shutdown",
+ (name) =>
+ name !== "ping" &&
+ name !== "shutdown" &&
+ name !== "annotate_native_function",
);
assert.ok(
expected.every((name) => report.mcpOperations.includes(name)),
diff --git a/scripts/verify-packed-bridge.mjs b/scripts/verify-packed-bridge.mjs
index 10b41389e..854772683 100644
--- a/scripts/verify-packed-bridge.mjs
+++ b/scripts/verify-packed-bridge.mjs
@@ -27,7 +27,11 @@ export async function verifyPackedBridge({
"extends HeadlessScript",
'request.method.equals("ping")',
'request.method.equals("shutdown")',
- 'result.addProperty("read_only", true)',
+ 'boolean readOnly = !descriptor.transport.equals("unix-socket")',
+ 'result.addProperty("read_only", readOnly)',
+ 'case "annotate_native_function"',
+ 'currentProgram.startTransaction("REA function annotations")',
+ "currentProgram.endTransaction(transaction, commit)",
"analysisTimeoutOccurred()",
])
if (!ghidraSource.includes(commitment))
diff --git a/scripts/verify-real-ghidra-com.mjs b/scripts/verify-real-ghidra-com.mjs
index a4dfd2569..455c0e735 100644
--- a/scripts/verify-real-ghidra-com.mjs
+++ b/scripts/verify-real-ghidra-com.mjs
@@ -173,6 +173,88 @@ try {
(await cli("address-to-file-offset", fixture.near)).normalized_result,
mapping,
);
+ const changes = {
+ procedure: fixture.entry,
+ name: "rea_entry",
+ comment: "Regular\nUnicode 註記",
+ inline_comment: "Inline finding",
+ };
+ // Prime provider inventories and the session snapshot before edits.
+ await call("list_names");
+ const updated = await call("annotate_native_function", changes);
+ assert.equal(updated.annotations.name, changes.name);
+ assert.equal(updated.annotations.comment, changes.comment);
+ assert.equal(updated.annotations.inline_comment, changes.inline_comment);
+ assert.equal(updated.dossier.procedure.name, changes.name);
+ assert.ok(updated.dossier.pseudocode.includes(changes.name));
+ assert.equal(
+ await call("procedure_address", { procedure: changes.name }),
+ fixture.entry,
+ );
+ assert.equal(
+ await call("address_name", { address: fixture.entry }),
+ changes.name,
+ );
+ assert.ok(
+ (await call("list_procedures")).some((p) => p.value === changes.name),
+ );
+ assert.ok((await call("list_names")).some((p) => p.value === changes.name));
+ assert.equal(
+ (await call("analyze_function", { procedure: fixture.entry })).procedure
+ .name,
+ changes.name,
+ );
+ const rejected = await client.callTool({
+ name: "annotate_native_function",
+ arguments: {
+ procedure: fixture.entry,
+ comment: "MUST ROLL BACK",
+ name: "invalid name\n",
+ },
+ });
+ assert.equal(
+ rejected.isError,
+ true,
+ "Ghidra accepted an invalid function name",
+ );
+ const retained = await call("annotate_native_function", {
+ procedure: fixture.entry,
+ name: changes.name,
+ });
+ assert.equal(
+ retained.annotations.comment,
+ changes.comment,
+ "Failed edit leaked its earlier comment write",
+ );
+ assert.equal(retained.annotations.inline_comment, changes.inline_comment);
+ assert.equal(retained.dossier.procedure.name, changes.name);
+ const cleared = await call("annotate_native_function", {
+ procedure: fixture.entry,
+ comment: "",
+ inline_comment: "",
+ });
+ assert.equal(cleared.annotations.comment, null);
+ assert.equal(cleared.annotations.inline_comment, null);
+ assert.ok(!cleared.dossier.comments.some((c) => c.address === fixture.entry));
+ assert.equal(
+ (
+ await call("read_bytes", {
+ address: fixture.entry,
+ length: fixture.bytes.length,
+ })
+ ).bytes_hex,
+ fixture.bytes.toString("hex"),
+ );
+ assert.equal((await call("inspect_native_load_image")).status, "verified");
+ const cliAnnotated = await cli("annotate-native-function", fixture.entry, [
+ "--name",
+ changes.name,
+ "--comment",
+ changes.comment,
+ "--inline-comment",
+ changes.inline_comment,
+ ]);
+ assert.deepEqual(cliAnnotated.normalized_result, updated);
if (captureDirectory !== undefined)
await writeFile(
join(captureDirectory, "image.json"),
@@ -204,6 +286,13 @@ try {
partial_read_bytes: 2,
},
functions: { entry: true, near: true, pseudocode_nonempty: true },
+ annotations: {
+ atomic_rollback: true,
+ fresh_inventories: true,
+ fresh_decompiler: true,
+ clear_comments: true,
+ cli_mcp_parity: true,
+ },
original_unchanged: true,
limitations: image.limitations,
};
diff --git a/scripts/verify-real-ghidra-dos.mjs b/scripts/verify-real-ghidra-dos.mjs
index fd98a1a5e..70319fdcd 100644
--- a/scripts/verify-real-ghidra-dos.mjs
+++ b/scripts/verify-real-ghidra-dos.mjs
@@ -498,7 +498,11 @@ function assertProfile(profile) {
);
assert.equal(profile.provider.id, "ghidra");
assert.equal(profile.parameters.target_format, "dos-mz");
- assert.equal(profile.parameters.import_mode, "ephemeral-read-only");
+ assert.equal(profile.parameters.import_mode, "ephemeral-source-immutable");
+ assert.equal(
+ profile.parameters.annotation_policy,
+ "atomic-function-entry-metadata-v1",
+ );
assert.equal(profile.parameters.loader, "MzLoader");
assert.equal(profile.parameters.language_id, "x86:LE:16:Real Mode");
assert.equal(profile.parameters.compiler_spec_id, "default");
diff --git a/scripts/verify-real-ghidra-windows.mjs b/scripts/verify-real-ghidra-windows.mjs
index 08f05cffb..8dd9f6b53 100644
--- a/scripts/verify-real-ghidra-windows.mjs
+++ b/scripts/verify-real-ghidra-windows.mjs
@@ -22,16 +22,26 @@ import {
} from "../dist/ghidra/GhidraInstallation.js";
import { GhidraHeadlessLauncher } from "../dist/ghidra/GhidraLauncher.js";
import { GHIDRA_PROVIDER_IDENTITY } from "../dist/ghidra/GhidraProvider.js";
-import { GHIDRA_SESSION_CAPABILITIES as SESSION_CAPABILITIES } from "../dist/ghidra/GhidraSessionValues.js";
+import { windowsP0Capabilities } from "../dist/ghidra/GhidraProviderCapabilities.js";
+import { GHIDRA_SESSION_CAPABILITIES } from "../dist/ghidra/GhidraSessionValues.js";
import { parseBinaryTarget } from "../dist/application/BinaryTargetResolver.js";
import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";
const verifierRun = createVerifierRun();
+const SESSION_CAPABILITIES = GHIDRA_SESSION_CAPABILITIES.filter(
+ (name) => name !== "annotate_native_function",
+);
if (process.platform !== "win32" || process.arch !== "x64")
throw new Error(
"The real Windows Ghidra verifier requires a Windows x64 host",
);
+if (
+ windowsP0Capabilities().some(
+ ({ available, effects }) => available && effects.mutatesArtifact,
+ )
+)
+ throw new Error("Windows Ghidra must not advertise database mutation");
const installDir = process.env.GHIDRA_INSTALL_DIR;
if (installDir === undefined || !isAbsolute(installDir))
throw new Error(
@@ -185,7 +195,9 @@ try {
const expected = [
...GHIDRA_INVENTORY_OPERATIONS,
- ...GHIDRA_FUNCTION_OPERATIONS,
+ ...GHIDRA_FUNCTION_OPERATIONS.filter(
+ (name) => name !== "annotate_native_function",
+ ),
];
if (
observed.size !== expected.length ||
diff --git a/skills/reverse-engineer-anything/SKILL.md b/skills/reverse-engineer-anything/SKILL.md
index 7f278ec50..7e51beb20 100644
--- a/skills/reverse-engineer-anything/SKILL.md
+++ b/skills/reverse-engineer-anything/SKILL.md
@@ -3,8 +3,8 @@ name: reverse-engineer-anything
description: Reverse engineer native, managed, Electron/JavaScript, packaged, and browser applications with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
metadata:
version: "24"
- tool_count: 117
- catalog_digest: "f63ae9b3480f206700cf334c54b3267aff8d0c3a7f4e782d8b5f7952cfdd5271"
+ tool_count: 118
+ catalog_digest: "b4f7e5860d90b029876b58fe7cd4a8041fef1f2add23440e37e90827d808e503"
---
# REA
diff --git a/skills/reverse-engineer-anything/references/native-and-artifacts.md b/skills/reverse-engineer-anything/references/native-and-artifacts.md
index feacc671f..27ab9fc06 100644
--- a/skills/reverse-engineer-anything/references/native-and-artifacts.md
+++ b/skills/reverse-engineer-anything/references/native-and-artifacts.md
@@ -60,3 +60,7 @@ For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI
`--target-format dos-com`). Inspect the load image before trusting function
analysis: the entry is `0x10100`, file offset zero, with imposed real-mode segment
context. PSP/stack/device state remains unmodeled. See [DOS guide](../../../docs/ghidra-dos.md).
+
+### Function annotations in Ghidra
+
+Use `annotate_native_function` for one function name and/or entry comments, with at least one explicit change. Review its annotation readback and refreshed dossier inline. Changes are atomic and session-scoped; empty comments clear them, omitted fields preserve them. Later MCP calls observe edits until close. CLI `annotate-native-function` returns the updated analysis before discarding the session. Original executable bytes are unchanged; edits invalidate immutable snapshots. Windows P0 does not admit database mutations.
diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.ts
index b5a57c934..eb04765ea 100644
--- a/src/application/DirectAnalysis.ts
+++ b/src/application/DirectAnalysis.ts
@@ -43,6 +43,7 @@ export {
} from "./DirectAnalysisStatus.js";
type DirectAnalysisTool =
+ | "annotate_native_function"
| "inspect_native_load_image"
| "read_bytes"
| "address_to_file_offset"
diff --git a/src/cli/coreAnalysisCommands.ts b/src/cli/coreAnalysisCommands.ts
index 0c6bf4b75..0fe296dc9 100644
--- a/src/cli/coreAnalysisCommands.ts
+++ b/src/cli/coreAnalysisCommands.ts
@@ -19,6 +19,7 @@ export const registerCoreAnalysisCommands = (
logger: Logger,
): void => {
registerCoreCommands(cli, logger);
+ registerAnnotationCommand(cli, logger);
cli.command(CLI_COMMANDS.inspectNativeLoadImage, {
description:
"Verify loaded native bytes, source mappings, relocations and entry",
@@ -722,3 +723,51 @@ const registerSearchCommand = (cli: CliInstance, logger: Logger): void => {
),
});
};
+
+const registerAnnotationCommand = (cli: CliInstance, logger: Logger): void => {
+ cli.command(CLI_COMMANDS.annotateNativeFunction, {
+ description: "Edit function annotations and return refreshed analysis",
+ args: z.object({
+ path: z.string().describe("Local executable path"),
+ procedure: z
+ .string()
+ .describe("Exact function entry address or unique name"),
+ }),
+ options: z.object({
+ name: z.string().min(1).optional().describe("Analyst function name"),
+ comment: z
+ .string()
+ .optional()
+ .describe("Regular entry comment; empty text clears it"),
+ "inline-comment": z
+ .string()
+ .optional()
+ .describe("Inline entry comment; empty text clears it"),
+ "target-format": formatSelectionOption,
+ provider: providerSelectionOption,
+ }),
+ run: ({ args, options }) =>
+ logCliCommand(logger, CLI_COMMANDS.annotateNativeFunction, () =>
+ runDirectAnalysis(
+ args.path,
+ "annotate_native_function",
+ {
+ procedure: args.procedure,
+ ...(options.name === undefined ? {} : { name: options.name }),
+ ...(options.comment === undefined
+ ? {}
+ : { comment: options.comment }),
+ ...(options["inline-comment"] === undefined
+ ? {}
+ : { inline_comment: options["inline-comment"] }),
+ },
+ directAnalysisOptions(
+ logger,
+ undefined,
+ options.provider,
+ options["target-format"],
+ ),
+ ),
+ ),
+ });
+};
diff --git a/src/cliCommandNames.ts b/src/cliCommandNames.ts
index 198d160cb..d37f401da 100644
--- a/src/cliCommandNames.ts
+++ b/src/cliCommandNames.ts
@@ -14,6 +14,7 @@ export const CLI_COMMANDS = Object.freeze({
capabilities: "capabilities",
providers: "providers",
function: "function",
+ annotateNativeFunction: "annotate-native-function",
inspectNativeApi: "inspect-native-api",
instructions: "instructions",
search: "search",
diff --git a/src/contracts/officialToolContracts.ts b/src/contracts/officialToolContracts.ts
index aeda4d82a..d23e5e191 100644
--- a/src/contracts/officialToolContracts.ts
+++ b/src/contracts/officialToolContracts.ts
@@ -1,4 +1,5 @@
import { z } from "zod";
+import { nativeFunctionAnnotationsInputSchema } from "../domain/nativeFunctionAnnotations.js";
import {
officialOutputSchemas,
@@ -36,6 +37,11 @@ const official = (
/** Bridge operations exposed without additional application composition. */
export const OFFICIAL_TOOL_CONTRACTS = [
+ official(
+ "annotate_native_function",
+ "Atomically update one function name and/or entry comments, read them back, and return a refreshed complete function dossier. Ghidra changes its ephemeral session analysis database only; original executable bytes remain unchanged. Empty comment text clears that comment. Edits remain available to subsequent MCP calls until close; CLI returns the updated dossier before discarding its session. Invalid edits roll back the entire operation. Windows P0 and providers without this capability are unsupported.",
+ nativeFunctionAnnotationsInputSchema,
+ ),
official(
"inspect_native_load_image",
"Verify the provider's loaded DOS MZ or explicitly selected COM image against its immutable target snapshot: complete original/modified source-byte digests, header/module file mappings and memory digests, relocations and external entry. Returns measured observations and independent checks with mismatch coordinates. COM verification includes its imposed entry register context and does not claim PSP/runtime coverage. Overlay and uninitialized coverage remain explicit; other formats return unsupported. Does not execute or modify the target.",
diff --git a/src/contracts/toolContractExamples.ts b/src/contracts/toolContractExamples.ts
index 5ddc8aa35..6a47936e2 100644
--- a/src/contracts/toolContractExamples.ts
+++ b/src/contracts/toolContractExamples.ts
@@ -42,6 +42,11 @@ export const TOOL_EXAMPLE_OVERRIDES: Readonly<
get_call_graph: { address: "0x1000" },
find_xrefs_to_name: { name: "malloc" },
analyze_function: { procedure: "main" },
+ annotate_native_function: {
+ procedure: "0x10100",
+ name: "entry",
+ comment: "Analyst observation",
+ },
analyze_swift_types: { category: "classes", pattern: "Account" },
inspect_native_api: { procedure: "main" },
trace_feature: { query: "license" },
diff --git a/src/contracts/toolEffects.ts b/src/contracts/toolEffects.ts
index d61fd2fbc..2022eb404 100644
--- a/src/contracts/toolEffects.ts
+++ b/src/contracts/toolEffects.ts
@@ -41,6 +41,12 @@ const sessionEvidence = effects({ mutatesSession: true });
/** Explicit effect audit for every public tool. */
export const TOOL_EFFECTS: Readonly> = {
+ annotate_native_function: effects({
+ mutatesTarget: true,
+ mutatesSession: true,
+ launchesProcess: true,
+ writesFilesystem: true,
+ }),
inspect_native_load_image: evidence,
inspect_native_dispatch_metadata: evidence,
trace_native_ui_action: evidence,
diff --git a/src/contracts/toolOutputSchemaGroups.ts b/src/contracts/toolOutputSchemaGroups.ts
index 6d8a01b64..2a8665591 100644
--- a/src/contracts/toolOutputSchemaGroups.ts
+++ b/src/contracts/toolOutputSchemaGroups.ts
@@ -1,4 +1,5 @@
import { z } from "zod";
+import { nativeFunctionAnnotationsSchema } from "../domain/nativeFunctionAnnotations.js";
import { nativeLoadImageSchema } from "../domain/nativeLoadImage.js";
import { nativeUiResultSchema } from "../domain/nativeUiObservation.js";
import { nativeValueTraceSchema } from "../domain/nativeValueTrace.js";
@@ -101,6 +102,7 @@ const addressedString = z.object({
/** Exact structured-content schemas shared by direct analysis providers. */
export const officialOutputSchemas: Readonly