[PR #709] [MERGED] feat(ghidra): add atomic function annotation edits #2189

New issue

Closed

opened 2026-10-16 21:15:25 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:15:25 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/709
Author: @N0zoM1z0
Created: 10/6/2026
Status: ✅ Merged
Merged: 10/6/2026
Merged by: @N0zoM1z0

Base: main ← Head: feat/ghidra-analysis-metadata

📝 Commits (6)

0af715e feat(ghidra): edit function annotations atomically
38a2660 chore: merge latest main for Ghidra annotation integration
1b8649a fix(ghidra): preserve qualified function annotation identity
48dea3a chore: integrate Windows read-only Ghidra boundary
83af13f chore: integrate latest process evidence identity fixes
d9dd102 test(ghidra): align verification with annotation authority

📊 Changes

49 files changed (+730 additions, -72 deletions)

View changed files

📝 AGENTS.md (+1 -1)
📝 README.md (+7 -7)
📝 README_ar.md (+1 -1)
📝 README_ja.md (+1 -1)
📝 README_ko.md (+1 -1)
📝 README_zh.md (+1 -1)
📝 bridge/ghidra/ReaGhidraBridge.java (+100 -2)
📝 docs/adr/0001-provider-selection-and-analysis-profiles.md (+4 -2)
📝 docs/ghidra-dos.md (+19 -0)
📝 docs/installation.md (+5 -3)
📝 docs/native-investigation.md (+4 -2)
📝 docs/product-catalog.json (+11 -8)
📝 docs/provider-evaluation.md (+10 -7)
📝 docs/roadmap.md (+3 -1)
📝 docs/verification/managed-conformance-manifest.json (+2 -2)
📝 scripts/verify-packaged-ghidra-windows.mjs (+4 -1)
📝 scripts/verify-packed-bridge.mjs (+5 -1)
📝 scripts/verify-real-ghidra-com.mjs (+89 -0)
📝 scripts/verify-real-ghidra-dos.mjs (+5 -1)
📝 scripts/verify-real-ghidra-windows.mjs (+14 -2)

...and 29 more files

📄 Description

Changes

Add annotate_native_function and CLI annotate-native-function: atomically edit one local function name and/or entry comments, verify readback, and return a refreshed complete function dossier inline. Existing boolean naming/comment proxies do not provide this atomic edit plus refreshed analysis outcome.

Omitted fields preserve metadata; empty comment text clears it. Ghidra maps regular/inline comments to PRE/EOL and uses USER_DEFINED names. Namespaces remain intact and readback uses the same qualified name as function inventories.
End GhidraScript's inherited outer transaction before the resident service, then own one transaction per edit. A late invalid name rolls back earlier comment writes and retains earlier successful edits.
Flush name/function/string inventories and decompiler caches after edits or rollback; declare mutation effects so immutable analysis snapshots cannot serve stale metadata.
Preserve executable bytes and body ranges. Edits live only in the ephemeral MCP session; CLI returns updated evidence before close. This does not save a project or alter ABI, types or instructions.
Bind handshake mutation authority to the transport and exact capability set. Windows P0 and Hopper do not admit this new operation.
Preserve the rejected function-name constraint and address in typed caller issues.
Regenerate canonical contracts/catalogs and update guides and README family counts.

Verification

Integrated origin/main ab5a1c61 before publication, including Windows native read-only authority 26881da7. Before merge, also tested a temporary conflict-free integration with latest main c3bc38bf (function comparison source parameters), with 70 tests across source and actual MCP boundaries passing; then restored the exact CI-tested PR head.

107 focused tests across 10 files passed, covering Ghidra parsing/provider/handshake/transport, CLI catalog, canonical contracts and actual pinned-SDK MCP handlers.
Namespace/diagnostic follow-up: 25 focused source tests passed.
Latest Windows main integration: 80 affected tests across 9 files passed after updating the removed capability constant reference; the 5-test annotation file was rerun on its corrected source. Windows capability reporting keeps mutation unavailable even when its native controls are present; Windows real/package verifiers exclude the unadmitted mutation.
Initial CI exposed stale read-only capability/profile assertions and a packaged-bridge literal check. Updated them for transport-bound authority; the two failed tests and actual packaged-bridge/Hopper regex probe passed locally. DOS verifier profile assertions and MCP fixture authority were aligned as well.
Typecheck and lint passed; generated documents checked. Latest process Evidence main follow-up: 25 affected source tests passed; no Ghidra code changed in that follow-up.
Real Linux Ghidra 12.1.4, public COM fixture, actual npm artifact CLI/MCP: complete load-image/memory/mapping parity, metadata readback, late-failure transaction rollback, retained previous edits, fresh inventories/decompiler, comment clearing, unchanged input, and owned-process cleanup. Run 87b2e895-2072-4f22-bda9-a5793c695ee0. Artifact used the locked workspace dependencies; this is not a fresh dependency installation claim.
Public MZ far-return routine plus two private local analysis artifacts passed annotation/rollback/cache/body/byte checks and verified load-image checks; run dd5a90bd-b456-4c86-8e92-82f681d48aee. Private paths, executables, projects and outputs are excluded from the repository and package.
Real namespaced C++ routine CLI proof passed before publication; run 36adcb9c-3717-47f0-887a-338986f53126. Final publication artifact namespace/diagnostic follow-up passed with one CPU and bounded heaps; run 08c095c8-4fa0-46c9-a441-b6e953ae075a. It verified qualified-name readback, refreshed decompilation, precise invalid-name issues, unchanged source bytes, and no owned descendants. Windows-main publication artifact proof also passed: ca02e291-6fdc-4672-a7b2-9f5f300fe28a, with qualified rename, refreshed decompilation, precise invalid-name issues, unchanged source bytes and no owned descendants. The full COM artifact proof precedes this narrow namespace/diagnostic hardening; its transaction/cache code is unchanged.

Local work now runs sequentially on one CPU with lower priority, Node old-space capped at 768 MiB and Java heap at 512 MiB. The Go compiler has one runtime worker and a 768 MiB soft memory target; these are not total RSS limits. No host configuration changes.

No real macOS/Hopper verification performed for these changes. Windows mutation remains unavailable. No demo or game reconstruction is included.

Example

{"name":"annotate_native_function","arguments":{"procedure":"0x10100","name":"entry","comment":"Recovered startup role","inline_comment":"Inspect segment setup"}}

rea annotate-native-function /local/program.com 0x10100 --target-format dos-com --provider ghidra --name entry --comment 'Recovered startup role' --json

Both return annotation readback and the refreshed dossier inside normal Evidence. Analyst-authored names/comments do not establish original-source naming authority.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/709 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/6/2026 **Status:** ✅ Merged **Merged:** 10/6/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `feat/ghidra-analysis-metadata` --- ### 📝 Commits (6) - [`0af715e`](https://github.com/morluto/rea/commit/0af715ed2d7fca4865cedcdcad9b56a45a442190) feat(ghidra): edit function annotations atomically - [`38a2660`](https://github.com/morluto/rea/commit/38a266020c91a846f28c81eb1253207c3e1fe71a) chore: merge latest main for Ghidra annotation integration - [`1b8649a`](https://github.com/morluto/rea/commit/1b8649a3b7faaf1608a8bb39d8cdf44949512e28) fix(ghidra): preserve qualified function annotation identity - [`48dea3a`](https://github.com/morluto/rea/commit/48dea3aaba37787b148d04af26432f328426273e) chore: integrate Windows read-only Ghidra boundary - [`83af13f`](https://github.com/morluto/rea/commit/83af13f4ad424cc332b8c5c4ddfccab8de258672) chore: integrate latest process evidence identity fixes - [`d9dd102`](https://github.com/morluto/rea/commit/d9dd102977e3999c763fd52b1a8f79dae0d46937) test(ghidra): align verification with annotation authority ### 📊 Changes **49 files changed** (+730 additions, -72 deletions) <details> <summary>View changed files</summary> 📝 `AGENTS.md` (+1 -1) 📝 `README.md` (+7 -7) 📝 `README_ar.md` (+1 -1) 📝 `README_ja.md` (+1 -1) 📝 `README_ko.md` (+1 -1) 📝 `README_zh.md` (+1 -1) 📝 `bridge/ghidra/ReaGhidraBridge.java` (+100 -2) 📝 `docs/adr/0001-provider-selection-and-analysis-profiles.md` (+4 -2) 📝 `docs/ghidra-dos.md` (+19 -0) 📝 `docs/installation.md` (+5 -3) 📝 `docs/native-investigation.md` (+4 -2) 📝 `docs/product-catalog.json` (+11 -8) 📝 `docs/provider-evaluation.md` (+10 -7) 📝 `docs/roadmap.md` (+3 -1) 📝 `docs/verification/managed-conformance-manifest.json` (+2 -2) 📝 `scripts/verify-packaged-ghidra-windows.mjs` (+4 -1) 📝 `scripts/verify-packed-bridge.mjs` (+5 -1) 📝 `scripts/verify-real-ghidra-com.mjs` (+89 -0) 📝 `scripts/verify-real-ghidra-dos.mjs` (+5 -1) 📝 `scripts/verify-real-ghidra-windows.mjs` (+14 -2) _...and 29 more files_ </details> ### 📄 Description ## Changes Add `annotate_native_function` and CLI `annotate-native-function`: atomically edit one local function name and/or entry comments, verify readback, and return a refreshed complete function dossier inline. Existing boolean naming/comment proxies do not provide this atomic edit plus refreshed analysis outcome. - Omitted fields preserve metadata; empty comment text clears it. Ghidra maps regular/inline comments to PRE/EOL and uses USER_DEFINED names. Namespaces remain intact and readback uses the same qualified name as function inventories. - End GhidraScript's inherited outer transaction before the resident service, then own one transaction per edit. A late invalid name rolls back earlier comment writes and retains earlier successful edits. - Flush name/function/string inventories and decompiler caches after edits or rollback; declare mutation effects so immutable analysis snapshots cannot serve stale metadata. - Preserve executable bytes and body ranges. Edits live only in the ephemeral MCP session; CLI returns updated evidence before close. This does not save a project or alter ABI, types or instructions. - Bind handshake mutation authority to the transport and exact capability set. Windows P0 and Hopper do not admit this new operation. - Preserve the rejected function-name constraint and address in typed caller issues. - Regenerate canonical contracts/catalogs and update guides and README family counts. ## Verification Integrated origin/main `ab5a1c61` before publication, including Windows native read-only authority `26881da7`. Before merge, also tested a temporary conflict-free integration with latest main `c3bc38bf` (function comparison source parameters), with 70 tests across source and actual MCP boundaries passing; then restored the exact CI-tested PR head. - 107 focused tests across 10 files passed, covering Ghidra parsing/provider/handshake/transport, CLI catalog, canonical contracts and actual pinned-SDK MCP handlers. - Namespace/diagnostic follow-up: 25 focused source tests passed. - Latest Windows main integration: 80 affected tests across 9 files passed after updating the removed capability constant reference; the 5-test annotation file was rerun on its corrected source. Windows capability reporting keeps mutation unavailable even when its native controls are present; Windows real/package verifiers exclude the unadmitted mutation. - Initial CI exposed stale read-only capability/profile assertions and a packaged-bridge literal check. Updated them for transport-bound authority; the two failed tests and actual packaged-bridge/Hopper regex probe passed locally. DOS verifier profile assertions and MCP fixture authority were aligned as well. - Typecheck and lint passed; generated documents checked. Latest process Evidence main follow-up: 25 affected source tests passed; no Ghidra code changed in that follow-up. - **Real Linux Ghidra 12.1.4**, public COM fixture, actual npm artifact CLI/MCP: complete load-image/memory/mapping parity, metadata readback, late-failure transaction rollback, retained previous edits, fresh inventories/decompiler, comment clearing, unchanged input, and owned-process cleanup. Run `87b2e895-2072-4f22-bda9-a5793c695ee0`. Artifact used the locked workspace dependencies; this is not a fresh dependency installation claim. - Public MZ far-return routine plus two private local analysis artifacts passed annotation/rollback/cache/body/byte checks and verified load-image checks; run `dd5a90bd-b456-4c86-8e92-82f681d48aee`. Private paths, executables, projects and outputs are excluded from the repository and package. - Real namespaced C++ routine CLI proof passed before publication; run `36adcb9c-3717-47f0-887a-338986f53126`. Final publication artifact namespace/diagnostic follow-up passed with one CPU and bounded heaps; run `08c095c8-4fa0-46c9-a441-b6e953ae075a`. It verified qualified-name readback, refreshed decompilation, precise invalid-name issues, unchanged source bytes, and no owned descendants. Windows-main publication artifact proof also passed: `ca02e291-6fdc-4672-a7b2-9f5f300fe28a`, with qualified rename, refreshed decompilation, precise invalid-name issues, unchanged source bytes and no owned descendants. The full COM artifact proof precedes this narrow namespace/diagnostic hardening; its transaction/cache code is unchanged. Local work now runs sequentially on one CPU with lower priority, Node old-space capped at 768 MiB and Java heap at 512 MiB. The Go compiler has one runtime worker and a 768 MiB soft memory target; these are not total RSS limits. No host configuration changes. No real macOS/Hopper verification performed for these changes. Windows mutation remains unavailable. No demo or game reconstruction is included. ## Example ```json {"name":"annotate_native_function","arguments":{"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 ``` Both return annotation readback and the refreshed dossier inside normal Evidence. Analyst-authored names/comments do not establish original-source naming authority. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:15:25 +00:00