[PR #245] [MERGED] feat(ghidra): add private headless provider session #1895

New issue

Closed

opened 2026-10-16 21:12:17 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:12:17 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/245
Author: @N0zoM1z0
Created: 7/15/2026
Status: ✅ Merged
Merged: 7/15/2026
Merged by: @N0zoM1z0

Base: main ← Head: agent/add-ghidra-headless-session

📝 Commits (1)

4298942 feat(ghidra): add private headless provider session

📊 Changes

234 files changed (+8969 additions, -514 deletions)

View changed files

📝 AGENTS.md (+11 -5)
📝 README.md (+35 -8)
📝 README_ar.md (+9 -4)
📝 README_ja.md (+6 -2)
📝 README_ko.md (+6 -2)
📝 README_zh.md (+7 -3)
📝 SECURITY.md (+30 -4)
➕ bridge/ghidra/ReaGhidraBridge.java (+282 -0)
📝 docs/adr/0001-provider-selection-and-analysis-profiles.md (+19 -13)
📝 docs/adr/README.md (+3 -3)
📝 docs/api/assets/hierarchy.js (+1 -1)
📝 docs/api/assets/navigation.js (+1 -1)
📝 docs/api/assets/search.js (+1 -1)
📝 docs/api/classes/application_PermissionAuthority.PermissionPathError.html (+1 -1)
📝 docs/api/classes/application_ProcessCaptureError.ProcessCaptureError.html (+1 -1)
📝 docs/api/classes/application_ProjectPermissionStore.ProjectPermissionStoreError.html (+1 -1)
📝 docs/api/classes/domain_errors.AnalysisCancelledError.html (+1 -1)
📝 docs/api/classes/domain_errors.AnalysisCapabilityUnavailableError.html (+1 -1)
📝 docs/api/classes/domain_errors.AnalysisError.html (+1 -1)
📝 docs/api/classes/domain_errors.AnalysisInputError.html (+1 -1)

...and 80 more files

📄 Description

Summary

add a BYO Ghidra 12.1.2 headless provider foundation for Linux x64 with JDK 21
add a packaged HeadlessScript, bounded authenticated Unix-socket protocol, TypeScript client/launcher, provider identity, deterministic analysis-profile metadata, and clean session shutdown
generalize doctor and setup composition so provider-specific discovery stays outside the domain/application core
document the exact support boundary across every README, installation/security guidance, ADRs, roadmap, architecture, provider evaluation, product catalog, and generated API docs
add production-seam tests, fake bridge fixtures, packed-asset verification, and a real-Ghidra verifier
redact URL-shaped transitional CDP target titles at the discovery boundary after real-browser CI exposed a pre-existing query-value leak

Why

Hopper remains the only operation-capable binary provider, which prevents Linux users from using REA's analysis-provider path without proprietary software. This PR establishes the secure, reproducible Ghidra runtime/session layer required before exposing direct read-only binary operations in the next PR.

Contract and behavior

accepts absolute GHIDRA_INSTALL_DIR and optional absolute JAVA_HOME
validates the exact Ghidra version, Java major, platform, architecture, and analyzeHeadless location with actionable doctor diagnostics
keeps setup additive and idempotent: it prints the proposed provider environment, requires approval, preserves existing Hopper configuration, and never downloads or installs Ghidra, Java, Node.js, Homebrew, or unrelated software
creates an isolated private runtime/project for each session, imports and analyzes one target, performs a metadata handshake, and reports provider/version/profile/language/compiler metadata
authenticates bridge requests with a per-session token kept out of argv and environment variables; bounds framing, diagnostics, startup, requests, CPU, heap, and analysis time
clears inherited JVM option injection variables and removes owned projects/runtime roots during shutdown
registers Ghidra with an intentionally empty binary-operation contract in this foundation PR; the MCP/CLI tool inventory remains 78 and Hopper remains the operation-capable provider
sanitizes a Chrome transitional target title when Chrome represents it as an HTTP(S) URL, while preserving ordinary human-readable titles

Verification

npm run check — 118 test files and 813 tests passed; 82.89% statement and 71.80% branch coverage
npm run knip
npm run jscpd — 1.43% duplicated lines before the final bounded regression addition
npm run scan:todos
npm run verify:package — real tarball passed CLI, setup transaction, skill, 78-tool/6-prompt target-free MCP, and target lifecycle checks
GHIDRA_INSTALL_DIR=/path/to/ghidra_12.1.2_PUBLIC npm run verify:ghidra — performed on Linux x64 with Ghidra 12.1.2 and JDK 21 against /usr/bin/true; metadata matched and cleanup was complete
GitHub real-browser verification — passed against the final head and exercised the transitional-title redaction regression
real Hopper verification was not performed because this PR does not change Hopper launch/protocol behavior

Follow-up boundary

This PR deliberately ships zero Ghidra binary-analysis operations. The next roadmap PR will implement the first read-only direct-operation slice against this session foundation.

_{🔄 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/245 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 7/15/2026 **Status:** ✅ Merged **Merged:** 7/15/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `agent/add-ghidra-headless-session` --- ### 📝 Commits (1) - [`4298942`](https://github.com/morluto/rea/commit/4298942ed1946f0f52cfa83b276aa7a84d7c734c) feat(ghidra): add private headless provider session ### 📊 Changes **234 files changed** (+8969 additions, -514 deletions) <details> <summary>View changed files</summary> 📝 `AGENTS.md` (+11 -5) 📝 `README.md` (+35 -8) 📝 `README_ar.md` (+9 -4) 📝 `README_ja.md` (+6 -2) 📝 `README_ko.md` (+6 -2) 📝 `README_zh.md` (+7 -3) 📝 `SECURITY.md` (+30 -4) ➕ `bridge/ghidra/ReaGhidraBridge.java` (+282 -0) 📝 `docs/adr/0001-provider-selection-and-analysis-profiles.md` (+19 -13) 📝 `docs/adr/README.md` (+3 -3) 📝 `docs/api/assets/hierarchy.js` (+1 -1) 📝 `docs/api/assets/navigation.js` (+1 -1) 📝 `docs/api/assets/search.js` (+1 -1) 📝 `docs/api/classes/application_PermissionAuthority.PermissionPathError.html` (+1 -1) 📝 `docs/api/classes/application_ProcessCaptureError.ProcessCaptureError.html` (+1 -1) 📝 `docs/api/classes/application_ProjectPermissionStore.ProjectPermissionStoreError.html` (+1 -1) 📝 `docs/api/classes/domain_errors.AnalysisCancelledError.html` (+1 -1) 📝 `docs/api/classes/domain_errors.AnalysisCapabilityUnavailableError.html` (+1 -1) 📝 `docs/api/classes/domain_errors.AnalysisError.html` (+1 -1) 📝 `docs/api/classes/domain_errors.AnalysisInputError.html` (+1 -1) _...and 80 more files_ </details> ### 📄 Description ## Summary - add a BYO Ghidra 12.1.2 headless provider foundation for Linux x64 with JDK 21 - add a packaged `HeadlessScript`, bounded authenticated Unix-socket protocol, TypeScript client/launcher, provider identity, deterministic analysis-profile metadata, and clean session shutdown - generalize doctor and setup composition so provider-specific discovery stays outside the domain/application core - document the exact support boundary across every README, installation/security guidance, ADRs, roadmap, architecture, provider evaluation, product catalog, and generated API docs - add production-seam tests, fake bridge fixtures, packed-asset verification, and a real-Ghidra verifier - redact URL-shaped transitional CDP target titles at the discovery boundary after real-browser CI exposed a pre-existing query-value leak ## Why Hopper remains the only operation-capable binary provider, which prevents Linux users from using REA's analysis-provider path without proprietary software. This PR establishes the secure, reproducible Ghidra runtime/session layer required before exposing direct read-only binary operations in the next PR. ## Contract and behavior - accepts absolute `GHIDRA_INSTALL_DIR` and optional absolute `JAVA_HOME` - validates the exact Ghidra version, Java major, platform, architecture, and `analyzeHeadless` location with actionable doctor diagnostics - keeps setup additive and idempotent: it prints the proposed provider environment, requires approval, preserves existing Hopper configuration, and never downloads or installs Ghidra, Java, Node.js, Homebrew, or unrelated software - creates an isolated private runtime/project for each session, imports and analyzes one target, performs a metadata handshake, and reports provider/version/profile/language/compiler metadata - authenticates bridge requests with a per-session token kept out of argv and environment variables; bounds framing, diagnostics, startup, requests, CPU, heap, and analysis time - clears inherited JVM option injection variables and removes owned projects/runtime roots during shutdown - registers Ghidra with an intentionally empty binary-operation contract in this foundation PR; the MCP/CLI tool inventory remains 78 and Hopper remains the operation-capable provider - sanitizes a Chrome transitional target title when Chrome represents it as an HTTP(S) URL, while preserving ordinary human-readable titles ## Verification - `npm run check` — 118 test files and 813 tests passed; 82.89% statement and 71.80% branch coverage - `npm run knip` - `npm run jscpd` — 1.43% duplicated lines before the final bounded regression addition - `npm run scan:todos` - `npm run verify:package` — real tarball passed CLI, setup transaction, skill, 78-tool/6-prompt target-free MCP, and target lifecycle checks - `GHIDRA_INSTALL_DIR=/path/to/ghidra_12.1.2_PUBLIC npm run verify:ghidra` — performed on Linux x64 with Ghidra 12.1.2 and JDK 21 against `/usr/bin/true`; metadata matched and cleanup was complete - GitHub `real-browser` verification — passed against the final head and exercised the transitional-title redaction regression - real Hopper verification was not performed because this PR does not change Hopper launch/protocol behavior ## Follow-up boundary This PR deliberately ships zero Ghidra binary-analysis operations. The next roadmap PR will implement the first read-only direct-operation slice against this session foundation. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:12:17 +00:00