docs: clarify README wording and analysis tool support
This commit is contained in:
+34
-26
@@ -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
@@ -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
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user