docs: clarify README wording and analysis tool support

This commit is contained in:
morluto
2026-10-05 17:52:22 +08:00
parent 09830dad05
commit 97822f233b
5 changed files with 193 additions and 336 deletions
+34 -26
View File
@@ -87,7 +87,7 @@ current state, prints the proposed effects, and asks for final approval with
**Yes** as the default. Selection alone never authorizes a mutation. The plan
identifies:
- an existing Hopper installation, a validated bring-your-own Ghidra environment, or the official Hopper package it proposes to install;
- an existing Hopper installation, a verified existing Ghidra installation, or the official Hopper package it proposes to install;
- each detected agent configuration path;
- the REA skill destination;
- external software, network origins, integrity evidence, and package-manager
@@ -100,8 +100,8 @@ entries, create backups, use atomic replacement, and verify their result.
Progress remains append-only so completed and failed operations stay visible in
terminal history. After a successful run, the completion message names the
verified capabilities now available—for example configured MCP clients, the
selected analysis provider, and the installed skill—and gives the corresponding
verified capabilities now available, such as configured MCP clients, the
selected analysis provider, and the installed skill, and gives the corresponding
next action. When an agent must restart to load its registration, REA says so;
otherwise it suggests beginning an investigation. It does not advertise a
capability that the final diagnostic check did not verify.
@@ -193,15 +193,22 @@ copying license secrets into logs, or killing unrelated Hopper processes.
## Ghidra
REA's Ghidra provider is bring-your-own and supports Linux x64 with the exact
official Ghidra 12.1.4 release and a 64-bit full JDK 21. macOS is not an
admitted Ghidra host. An experimental
Windows x64 P0 supports approved native x86-64 PE applications. It supplies
discovery, analysis-profile commitment, an isolated read-only headless session,
ten inventory/name/search operations and nine function-analysis operations,
for 19 read-only operations total. Function analysis covers metadata,
decompilation, assembly, resolved calls, typed references, xrefs, CFG, and
dossiers. GUI state and analysis mutations remain unavailable through Ghidra.
REA connects to an existing Ghidra installation on Linux x64 or macOS x64/arm64.
It requires Ghidra 12.1.4 and a 64-bit full JDK 21. On macOS, the installation
must include the native decompiler for the host architecture; REA does not
build it or change Gatekeeper quarantine settings.
The adapter exposes 22 read-only operations: ten inventory/name/search
operations and twelve function-analysis operations. These cover metadata,
decompilation, assembly, resolved calls, typed references, xrefs, function
dossiers, instructions, and recovered data types. GUI controls and annotation
changes require Hopper.
Windows Ghidra operations are currently unavailable. The adapter reports
`unsupported_host` until verified Job Object process ownership, private runtime
DACLs, and reparse-safe path admission are implemented. The
[Windows Ghidra P0 guide](windows-ghidra-p0.md) describes the intended boundary
and remaining controls.
Extract Ghidra and install the JDK outside REA, then export absolute paths:
@@ -212,7 +219,7 @@ rea doctor --json
rea setup
```
PowerShell configuration for Windows uses the same non-secret paths:
For Windows diagnostics, use the same installation paths in PowerShell. These settings do not enable the blocked analysis operations:
```powershell
$env:GHIDRA_INSTALL_DIR = "C:\tools\ghidra_12.1.4_PUBLIC"
@@ -222,9 +229,9 @@ rea providers --json
```
`rea setup` does not mutate Windows client configuration or install Hopper,
Ghidra, Java, Python, or another package. Register the built `rea mcp` command
manually in the intended client and preserve the two environment variables.
See [Windows Ghidra P0](windows-ghidra-p0.md) for a complete example.
Ghidra, Java, Python, or another package. Manual MCP registration does not
enable the blocked Ghidra operations. See [Windows Ghidra P0](windows-ghidra-p0.md)
for diagnostics and the proposed registration format.
Doctor validates the platform, architecture, application version,
`support/analyzeHeadless` or `support/analyzeHeadless.bat`, Java
@@ -237,12 +244,10 @@ installs, upgrades, or modifies Ghidra or Java.
Each verified session uses an ephemeral temporary project and isolated
home/cache/config/temp paths. REA passes `-readOnly`, `-deleteProject`, uses
Ghidra's default analysis and resource settings, and loads its packaged Java
bridge via `-scriptPath`; it never opens an existing user project. Linux uses a
current-user-only local bridge socket and descriptor. Windows P0 uses
token-authenticated IPv4 loopback, a token-free endpoint record, and bounded
process-tree termination. It does not yet prove private DACL,
reparse-point-safe, or Job Object semantics; use only approved non-sensitive
fixtures.
bridge via `-scriptPath`; it never opens an existing user project. Linux and
macOS use a current-user-only local bridge socket and descriptor. The
experimental Windows transport uses authenticated IPv4 loopback, but missing
native ownership and path controls keep Windows operations unavailable.
Operations begin only after default auto-analysis completes. The provider
startup deadline fails the open rather than exposing partial analysis. One
@@ -256,8 +261,9 @@ remain unknown, reference-kind provenance is preserved, and provider-specific
pseudocode is never treated as original source or Hopper-equivalent text.
Run `GHIDRA_INSTALL_DIR=... npm run verify:ghidra` from a source checkout to
compile and analyze debug and stripped x86-64 ELF fixtures on Linux x64. This lane needs only a host C compiler
in addition to Ghidra and its JDK.
compile and analyze debug and stripped host-native fixtures (ELF on Linux x64
or Mach-O on macOS), plus a native DWARF 4 type-layout object. This lane needs a
host C compiler in addition to Ghidra and its JDK.
Run `GHIDRA_INSTALL_DIR=... npm run verify:ghidra:cross-format` to add AArch64
ELF, x86-64 PE, and x86-64 Mach-O fixture coverage. This separate lane needs
@@ -267,8 +273,10 @@ host-native Ghidra acceptance lane.
On a controlled Windows x64 runner, use
`npm run verify:ghidra:windows`. The verifier generates a deterministic native
PE fixture from source bytes, exercises every admitted Ghidra operation, checks
target/snapshot/import digest identity, and requires complete runtime cleanup.
PE fixture from source bytes and requires the Windows native authority before
opening the provider. This lane remains blocked until those controls are
implemented; its intended checks include operation coverage, digest identity,
and complete runtime cleanup.
## Diagnose, update, and remove
+26 -27
View File
@@ -2,31 +2,29 @@
## Shipped behavior
REA setup currently configures the capabilities that exist today: its bundled
skill, detected agent integrations, optional Hopper provider, and validated
bring-your-own Ghidra paths. It detects
Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, and Devin. The
first six have documented local MCP configuration boundaries and can be updated
additively; Devin is reported but left unchanged.
REA setup lets you select agent integration and optional Hopper installation.
It installs the bundled workflow, configures detected agents, and can save
verified paths for an existing Ghidra installation. It detects Claude Code,
Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, and Devin. The first six
can be configured; Devin is reported but left unchanged.
The Ghidra foundation supports Linux x64 with exact Ghidra 12.1.4 and a 64-bit
full JDK 21. macOS is not an admitted Ghidra host. An experimental
Windows x64 P0 admits approved native x86-64 PE
applications through the same 19-operation Java bridge. Doctor validates those coordinates; approved Linux setup propagates them
to MCP registrations without installing or modifying either dependency. REA's
packaged Java bridge then proves an isolated read-only headless import,
post-analysis handshake, complete cleanup, ten admitted read-only inventory
operations, and nine function-analysis operations. Real source-owned x86-64
debug/stripped ELF, AArch64 ELF, PE, and Mach-O fixtures cover program,
procedure, string, symbol, external/thunk, memory, resolution, search,
decompilation, assembly, calls, typed references, xrefs, and CFG semantics.
Function dossiers also expose bounded Ghidra high-p-code def-use and memory or
control-flow effects, mark decompiler-dead operations, and report truncation
plus known omitted counts. This is intra-function
decompiler evidence; cross-function state flow remains unimplemented.
Hosted Windows CI covers build, package, target admission, transport, and
lifecycle seams; a controlled self-hosted workflow covers the real Ghidra P0
claim.
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 ten inventory operations and twelve function-analysis
operations, for 22 read-only operations total. Approved setup saves verified
installation paths in agent configurations without installing or changing
Ghidra or Java.
Real-provider verification uses host-native debug and stripped fixtures plus
a native type-layout object. A separate lane covers AArch64 ELF, PE, and
Mach-O cross-target fixtures. See [testing](testing.md) for the prerequisites
and exact commands.
Windows Ghidra operations remain unavailable until REA implements verified
Job Object process ownership, private runtime DACLs, and reparse-safe path
admission. Windows package and adapter tests do not establish a usable real
Ghidra session. The [Windows P0 guide](windows-ghidra-p0.md) describes the
intended boundary and remaining requirements.
## Ghidra maintenance boundary
@@ -36,7 +34,7 @@ not expected to match; unresolved targetless flow remains unknown. Automatic
Ghidra acquisition, if ever added, remains a separately planned and approved
related-tool change; setup must never install Java.
Before Windows advances beyond P0, add current-user-only DACL creation and
Before enabling Windows Ghidra operations, add current-user-only DACL creation and
readback, handle-based reparse-point-safe path authority, a DACL-protected IPC
backend, and Job Object assignment before provider execution. Process capture,
controlled replay, Hopper, and broad filesystem-sensitive workflows remain
@@ -44,8 +42,9 @@ separate Windows projects rather than implied parity.
## Capability-selective setup
After REA ships at least two real optional toolchains, setup can evolve into a
capability-oriented wizard. It may ask whether the operator wants to investigate
Setup already lets users select agent integration and Hopper installation.
Once REA supports installing additional analysis tools, it can expand these
choices to match the work a user wants to do. It may ask whether the operator wants to investigate
native binaries, websites, mobile applications, firmware, or runtime protocols,
then propose only the tools needed for the selected work.
+20 -13
View File
@@ -1,19 +1,25 @@
# Windows Ghidra P0
Status: experimental. This boundary is useful for approved local fixtures, but
it is not general Windows REA support and must not be used for hostile,
sensitive, security-decision, or concurrently mutable targets.
Status: experimental and currently unavailable. The production adapter reports
`unsupported_host` because verified Job Object process ownership, private
runtime DACLs, and reparse-safe path admission are not implemented. Installation
paths or manual MCP registration do not enable operations.
This guide describes the intended P0 boundary and adapter mechanisms. It does
not establish general Windows REA support. Even after the required controls
are implemented, hostile, sensitive, security-decision, and concurrently
mutable targets require separate acceptance.
## Supported boundary
The P0 accepts exactly:
Once the required native controls are implemented, the intended P0 is limited to:
- a Windows x64 host;
- Node.js 22.19+ or 24.11+;
- an operator-installed official Ghidra 12.1.4 distribution;
- a 64-bit full JDK 21;
- an explicit native, non-managed, non-DLL x86-64 PE application; and
- the existing 19 read-only Ghidra inventory and function-analysis operations.
- the 22 read-only Ghidra inventory and function-analysis operations.
Hopper, Ghidra GUI state, mutation, controlled JavaScript replay, process
capture, browser/Electron observation, artifact extraction, and general
@@ -27,7 +33,7 @@ another package on Windows. The production adapter uses the packaged Java
## Configuration
Install REA, Ghidra, and JDK 21 separately. In PowerShell:
For installation diagnostics, configure REA, Ghidra, and JDK 21 in PowerShell. Analysis remains blocked:
```powershell
npm install --global rea-agents
@@ -135,7 +141,7 @@ Hosted CI builds, type-checks, runs the curated Windows tests, records the named
host capability report, packs the real npm artifact, installs it in isolation,
and compares the packaged MCP catalog with `TOOL_CONTRACTS`.
The controlled real-engine lane is intentionally separate:
The controlled real-engine lane requires the missing native authority and currently remains blocked:
```powershell
$env:GHIDRA_INSTALL_DIR = "C:\tools\ghidra_12.1.4_PUBLIC"
@@ -144,13 +150,14 @@ npm ci
npm run verify:ghidra:windows
```
The verifier creates an ignored deterministic x86-64 PE fixture, checks its
fixed SHA-256, opens Ghidra 12.1.4 through the production Java bridge, exercises
all 19 admitted operations, verifies the target/snapshot/import digest chain,
and checks endpoint, project, process, and runtime cleanup. The GitHub workflow
The verifier requires the native authority before opening Ghidra. Its intended
checks include a deterministic x86-64 PE fixture, the read-only operation
contract, target/snapshot/import digest linkage, and endpoint, project,
process, and runtime cleanup. The GitHub workflow
accepts only the fixed `real-ghidra-windows` repository-dispatch event against
default-branch `main`, a protected `real-ghidra-windows` environment, and a
self-hosted runner labelled `Windows`, `x64`, and `ghidra-12-1-2`.
Passing this verifier proves the bounded P0 operation claim. It does not close
the DACL, reparse-point, named-pipe, or Job Object gates above.
Build, package, or adapter-test success does not prove the P0 operation claim.
Real-engine acceptance requires the native controls and the separate
verification lane; broader target and IPC security requirements remain distinct.