674 lines
40 KiB
Markdown
674 lines
40 KiB
Markdown
<div align="center">
|
|
|
|
**English** · [简体中文](README_zh.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [العربية](README_ar.md)
|
|
|
|
# REA: Reverse Engineer Anything
|
|
|
|
### Reverse engineer anything with agents, from app behavior down to native binaries.
|
|
|
|
**See a feature you like. Understand how it works, down to the binary level.**
|
|
|
|
[](https://www.npmjs.com/package/rea-agents)
|
|
[](https://github.com/morluto/rea/actions/workflows/ci.yml)
|
|
[](#tool-catalog-for-investigation)
|
|
[](https://nodejs.org/)
|
|
[](LICENSE)
|
|
[](https://discord.gg/GkcryMnJDM)
|
|
|
|
[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [Tool catalog](#tool-catalog-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
|
|
|
|
<table aria-label="REA community">
|
|
<tr>
|
|
<td align="center" width="360">
|
|
<a href="https://discord.gg/GkcryMnJDM">
|
|
<img src="docs/assets/discord.svg" height="42" alt="Discord" /><br />
|
|
<strong>Join the Reverse Engineering Community</strong>
|
|
</a><br />
|
|
<sub>Discord · Q&A · Show and Tell</sub>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br />
|
|
|
|
<code>npm install --global rea-agents && rea setup</code>
|
|
|
|
<br />
|
|
|
|
<img src="docs/assets/rea-hopper-analysis.png" alt="REA launching its analysis bridge inside Hopper while inspecting a native binary" width="1200" />
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
See a feature in an app that you want in your own product? Ask your agent to investigate it with REA. It can inspect the app without its source code, explain how the feature works, show the evidence, and build a version for your project.
|
|
|
|
REA connects your agent to tools for inspecting native binaries, JavaScript and Electron apps, .NET assemblies, and websites. You can also use the same tools from your terminal. Analysis runs locally, and results include the evidence and limitations behind each conclusion.
|
|
|
|
Setup configures your agent and connects it to Hopper or Ghidra. If you need an analysis tool, setup can install Hopper for you.
|
|
|
|
## Just ask your agent
|
|
|
|
After [setup](#quick-start), restart your agent and ask:
|
|
|
|
```text
|
|
Understand how search works in the Notes app, show me the evidence, and build a
|
|
similar feature for my project.
|
|
```
|
|
|
|
Replace Notes with the app you want to understand, or ask for an overview first.
|
|
|
|
## The investigation model
|
|
|
|
<table>
|
|
<tr>
|
|
<td width="33%" valign="top">
|
|
<strong>Decompile</strong><br /><br />
|
|
Open an app and recover readable code, strings, names, and other clues about how it works.
|
|
</td>
|
|
<td width="33%" valign="top">
|
|
<strong>Understand</strong><br /><br />
|
|
Follow the code from one part of the app to another until the agent can explain how a feature actually works.
|
|
</td>
|
|
<td width="33%" valign="top">
|
|
<strong>Recreate</strong><br /><br />
|
|
Turn what the agent learned into a feature for your own product, adapted to your stack, interface, and requirements.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
REA shows how it reached its conclusions. It does not claim to recover original source code or automatically clone an application.
|
|
|
|
## Why REA
|
|
|
|
| | |
|
|
| ------------------------ | ----------------------------------------------------------------------------------------------------- |
|
|
| **Built for agents** | Ask what an app does and let your agent inspect it instead of guessing. |
|
|
| **CLI and MCP** | Run the same reverse-engineering capabilities from your terminal or agent. |
|
|
| **Guided setup** | Configure your agent, connect an existing analysis tool, or install Hopper with your approval. |
|
|
| **From insight to code** | Understand a feature, then build your own version in the same coding session. |
|
|
| **Local by design** | Analysis runs on your supported local host. REA does not upload the app to a hosted analysis service. |
|
|
| **Keeps context** | Investigate several apps without starting over for every question. |
|
|
|
|
## Quick start
|
|
|
|
### Run setup (recommended)
|
|
|
|
```bash
|
|
npx --yes rea-agents@latest setup
|
|
```
|
|
|
|
Choose **Agent Integration**, select your agents, then review and approve the plan. Setup configures MCP access and installs REA's guided workflow. It can connect an existing Hopper or Ghidra installation, or offer to install Hopper if you need it.
|
|
|
|
Setup shows its changes before applying them and backs up existing configuration. It does not install or upgrade Node.js, npm, Homebrew, Ghidra, or Java. See [Installation and setup](docs/installation.md) for requirements, setup options, and the optional curl installer.
|
|
|
|
### With an agent (recommended)
|
|
|
|
After setup, restart your agent and [describe the app or feature](#just-ask-your-agent) you want to understand. Hopper can run in demo mode; if it shows a first-run prompt, choose the demo or enter an existing license.
|
|
|
|
REA can configure Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, and Windsurf. It detects Devin but does not configure it. Other agents can use the [manual MCP configuration](#manual-mcp-configuration).
|
|
|
|
### From the terminal with npx
|
|
|
|
After setup, run:
|
|
|
|
```bash
|
|
npx -y rea-agents@latest doctor
|
|
npx -y rea-agents@latest analyze /Applications/Notes.app
|
|
```
|
|
|
|
### Install the rea command
|
|
|
|
If you prefer a global command:
|
|
|
|
```bash
|
|
npm install --global rea-agents
|
|
rea setup
|
|
rea doctor
|
|
rea analyze /Applications/Notes.app
|
|
```
|
|
|
|
Update it with `rea upgrade`. For project-local installations or one-off runs, use `npx`.
|
|
|
|
### Requirements
|
|
|
|
- macOS 12 or newer
|
|
- Ubuntu 24.04+, Fedora 41+, or 64-bit Arch Linux
|
|
- Node.js 22.19+ or 24.11+ (including newer releases)
|
|
- 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.
|
|
|
|
Windows Ghidra support is experimental and currently unavailable. The required Windows process ownership, private-directory permissions, and safe-path checks are not implemented. See [Windows Ghidra P0](docs/windows-ghidra-p0.md) for the remaining requirements.
|
|
|
|
If something is not working, run:
|
|
|
|
```bash
|
|
npx -y rea-agents@latest doctor
|
|
```
|
|
|
|
`doctor` checks your host, dependencies, analysis tools, and agent configuration without changing them. Use `--json` for structured diagnostics.
|
|
|
|
### Linux installation and troubleshooting
|
|
|
|
On macOS, setup can install Hopper in `~/Applications` after approval. It verifies the official download and does not need Homebrew or administrator privileges.
|
|
|
|
On supported Linux distributions, setup can install Hopper and its demo-session dependencies through your system package manager. You may see a system authorization prompt. Demo sessions use a private virtual display, leaving your desktop alone. See [Hopper installation](docs/installation.md#hopper) for download verification and platform details.
|
|
|
|
The normal Linux launcher is `/opt/hopper/bin/Hopper`. If Hopper was installed elsewhere:
|
|
|
|
```bash
|
|
export HOPPER_LAUNCHER_PATH=/absolute/path/to/Hopper
|
|
rea doctor --json
|
|
```
|
|
|
|
If doctor reports a missing analysis engine even though the file exists, inspect shared-library resolution with:
|
|
|
|
```bash
|
|
ldd /opt/hopper/bin/Hopper | grep 'not found'
|
|
```
|
|
|
|
Install the missing packages and rerun `rea setup`. The Linux demo needs Xvfb, Python 3, X11, and XTEST; approved setup installs these dependencies. If you use the curl installer, add `~/.local/bin` to your shell `PATH` when needed.
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
Set the installation paths, then run setup:
|
|
|
|
```bash
|
|
export GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.1.4_PUBLIC
|
|
export JAVA_HOME=/absolute/path/to/jdk-21 # optional when java and javac resolve from PATH
|
|
rea doctor --json
|
|
rea setup
|
|
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 **22 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.
|
|
|
|
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.
|
|
|
|
Windows operations remain unavailable pending the controls described in the [Windows Ghidra P0 guide](docs/windows-ghidra-p0.md). See [Ghidra installation](docs/installation.md#ghidra), [provider evaluation](docs/provider-evaluation.md), and [testing](docs/testing.md) for configuration details, coverage, and real-provider verification.
|
|
|
|
To remove only REA-owned MCP registrations and the managed skill:
|
|
|
|
```bash
|
|
rea uninstall
|
|
rea uninstall --purge-data # also removes only ~/.rea/cache and ~/.rea/state
|
|
```
|
|
|
|
Uninstall preserves Hopper, Node.js, Evidence files, captures, unrelated skills, and other MCP servers. It refuses malformed client configuration and never follows purge-data symlinks.
|
|
|
|
### CLI or agent?
|
|
|
|
| If you want to… | Use |
|
|
| ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
| Ask an agent to investigate an app and build a feature | Run setup, restart your agent, then describe the task |
|
|
| Inspect or decompile one part of an app from the Terminal | `rea analyze` or `rea decompile` |
|
|
| Validate, canonicalize, or compare Evidence bundles | `rea evidence-import`, `rea evidence-export`, or `rea compare` |
|
|
| Map a local JavaScript/Electron application without executing it | `rea analyze PATH` or `rea analyze-javascript-application` |
|
|
| Reuse immutable analysis results without relaunching a provider | Pass `--snapshot /approved/path/analysis.json` to a deep-analysis command |
|
|
| Import source as historical reference | `rea import-reference-source` |
|
|
| Capture or compare controlled process behavior | `rea capture-process` or `rea compare-process-captures` |
|
|
|
|
```bash
|
|
rea evidence-import /absolute/path/to/evidence/bundle.json
|
|
rea evidence-export /absolute/path/to/evidence/bundle.json /absolute/path/to/evidence/canonical.json
|
|
rea compare /absolute/path/to/evidence/left.json /absolute/path/to/evidence/right.json
|
|
```
|
|
|
|
Analyze a JavaScript application directory or ASAR without executing it:
|
|
|
|
```bash
|
|
rea analyze /absolute/path/to/releases/app.asar --json
|
|
rea analyze-javascript-application /absolute/path/to/releases/app.asar --json
|
|
```
|
|
|
|
For a directory or `.asar`, generic `rea analyze` automatically selects the
|
|
static JavaScript application provider when neither `--provider` nor
|
|
`--snapshot` is supplied. Both routes return the analysis and its Evidence
|
|
context inline.
|
|
|
|
Import an older source tree as a reference. REA keeps it separate from observations of the current app:
|
|
|
|
```bash
|
|
rea import-reference-source /absolute/path/to/source
|
|
```
|
|
|
|
Imports read the path supplied to the command and validate every Evidence ID and manifest. Exports never replace an existing file unless `--overwrite` is explicit.
|
|
|
|
Use a snapshot to save successful analysis results and reuse them on later runs. REA reuses a result only when the target bytes, operation, parameters, analysis tool, and settings match. It does not cache changes or cursor-dependent calls. Snapshot files stay local and use owner-only permissions.
|
|
|
|
```bash
|
|
rea analyze /absolute/path/to/app --snapshot /absolute/path/to/analysis/app.json
|
|
# The same exact query can be answered from that snapshot.
|
|
rea analyze /absolute/path/to/app --snapshot /absolute/path/to/analysis/app.json
|
|
```
|
|
|
|
Exact CLI evidence replays happen before any provider process starts. In MCP sessions,
|
|
pass `snapshot_path` to `open_binary` to import a snapshot atomically while
|
|
opening its matching target; MCP providers may still start before a cached call
|
|
is replayed. Pass `snapshot_path` and, when required, `overwrite: true` to
|
|
`close_binary` to save atomically before Hopper resources are released. If the
|
|
save fails, REA deliberately leaves the session open.
|
|
|
|
## One prompt, a full investigation
|
|
|
|
```text
|
|
Reverse engineer the Notes app. Find how offline search works, explain it,
|
|
and build a version for my project using TypeScript and SQLite.
|
|
```
|
|
|
|
REA gives the agent a clear path from that request to working code:
|
|
|
|
| Step | What the agent does | REA tools |
|
|
| ---: | --------------------------------------- | ---------------------------------------------------------------- |
|
|
| 1 | Opens and identifies the binary | `open_binary`, `binary_overview` |
|
|
| 2 | Finds likely offline-search clues | `search_strings`, `search_procedures`, `list_names` |
|
|
| 3 | Connects those clues to executable code | `find_xrefs_to_name`, `xrefs`, `procedure_callers` |
|
|
| 4 | Reconstructs the relevant control flow | `get_call_graph`, `procedure_callees`, `procedure_info` |
|
|
| 5 | Decompiles the relevant routines | `procedure_pseudo_code`, `procedure_assembly`, `batch_decompile` |
|
|
| 6 | Builds the feature in your project | code adapted to your stack, product, and requirements |
|
|
|
|
REA handles the app analysis in steps 1 through 5. The agent performs step 6 with its normal file-editing and test tools, using what it learned about the app.
|
|
|
|
## What agents can do
|
|
|
|
- Investigate a feature you like and build a version tailored to your own product.
|
|
- Explain how a feature works when its source code is unavailable.
|
|
- Reconstruct an app's authentication, storage, update, or networking flow.
|
|
- Recover enough structure to document an undocumented format or interface.
|
|
- Trace a suspicious behavior from a string or symbol to the code that implements it.
|
|
- Turn recovered behavior into product features, tests, migration notes, ports, or interoperable replacements.
|
|
- Analyze Swift and Objective-C metadata without manually untangling every mangled symbol.
|
|
- Leave names, comments, and bookmarks in Hopper so human and agent analysis reinforce each other.
|
|
|
|
See [native investigation](docs/native-investigation.md) for keyed archives, instruction/call/type primitives, typed dispatch metadata, value traces and approved native desktop observation.
|
|
|
|
## Tool catalog for investigation
|
|
|
|
| Tool family | Count | Examples |
|
|
| ------------------------- | ----: | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Native inspection | 39 | functions, pseudocode, assembly, strings, symbols, calls, references, annotations, byte reads, and file offsets |
|
|
| Investigation workflows | 15 | 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 approved extraction |
|
|
| Managed PE/CLI | 8 | .NET identity, metadata, CIL instructions, native dependencies, reconstruction imports, runtime-correlation plans, and build comparisons |
|
|
| Browser observation | 9 | page structure, network metadata, scripts, source maps, WebMCP discovery, screenshots, capture comparisons, and approved browser scenarios |
|
|
| Electron analysis | 5 | renderer observation, static app mapping, static/runtime reconciliation, and approved click/wait scenarios |
|
|
| JavaScript runtime | 2 | Node/Electron Inspector target discovery, script locations, and execution-context events |
|
|
| Application workflows | 10 | cross-layer feature traces, build comparisons, historical source mapping, return-shape comparison, approved Linux replay, and reconstruction checks |
|
|
| Workspace and observation | 22 | sessions, evidence bundles, navigation context, finite replay machines, process/artifact/function comparisons, and open-question tracking |
|
|
|
|
The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness implements controlled behavioral capture.
|
|
|
|
## Current status
|
|
|
|
REA supports native application, JavaScript, Electron, .NET, and browser investigation on macOS and Linux. Individual tools have their own platform and approval requirements; use `rea capabilities` to check what is available on your host.
|
|
|
|
- **Native binaries:** Open Mach-O, ELF, PE, and Mac `.app` targets through Hopper or Ghidra. Inspect functions, strings, assembly, decompilation, calls, and references. Hopper also accepts `.hop` databases and supports annotations.
|
|
- **Packages and resources:** Inspect directories, ZIP, APK, IPA, ASAR, plists, compiled Interface Builder files, and Apple asset catalogs. Extraction requires approval. On macOS, DMG traversal also requires approval and `REA_ARTIFACT_NATIVE_MOUNT_ENABLED=true`.
|
|
- **JavaScript and Electron:** Map modules, imports, source maps, routes, IPC channels, storage, and native add-ons without running the app. Compare builds and trace a feature across the recovered graph. Dynamic and ambiguous relationships remain unresolved. See [JavaScript application workflows](docs/javascript-application-workflows.md).
|
|
- **Websites:** Inspect an approved page in an existing Chrome-family browser. Capture page structure, network metadata, script evidence, and approved screenshots. Passive observation does not navigate or execute page JavaScript. See [browser observation](docs/browser-observation.md).
|
|
- **Electron and Node runtime observation:** Inspect approved Electron pages or attach to a Node/Electron V8 Inspector target. Inspector observation records script locations and execution-context events; it does not infer imports, IPC activity, or which modules executed. See [runtime observation](docs/javascript-runtime-observation.md).
|
|
- **.NET assemblies:** Inspect metadata and CIL instructions, compare builds, and check declared native dependencies without loading or running the assembly. Imported decompiler output is labeled as analyst inference. Runtime-correlation plans are supported, but an executor is not implemented. See [managed-code analysis](docs/managed-code-analysis.md).
|
|
- **Controlled behavior capture:** Run approved process, browser, or Electron scenarios and compare the resulting evidence. Each requires its own configuration and approval. Missing observations cannot establish that two runs behaved the same way.
|
|
- **JavaScript replay:** Run selected extracted modules in the separately approved Linux sandbox. Replay requires the isolation controls described in [controlled JavaScript replay](docs/controlled-javascript-replay.md).
|
|
- **Evidence and comparison:** Save results with artifact identity, provider, locations, confidence, and limitations. Export or import bundles, compare artifacts and functions, and connect static findings to runtime observations without claiming causality from correlation.
|
|
- **Open questions:** Track unresolved findings, contradictions, and follow-up probes. Reconstruction checks report pass, fail, or unknown rather than treating missing evidence as a pass.
|
|
- **Guided workflows:** Start six [MCP investigation workflows](docs/mcp-prompts.md) with suggestions based on your current session.
|
|
|
|
Windows Ghidra operations are currently unavailable. Hopper-only features, such as GUI controls and annotations, are not available through Ghidra.
|
|
|
|
### Website observation with CDP
|
|
|
|
REA can inspect an already-running Chrome-family browser that you own. Browser observation is disabled by default and requires a literal loopback CDP endpoint plus exact approved page origins:
|
|
|
|
```bash
|
|
export REA_BROWSER_OBSERVE_ENABLED=true
|
|
export REA_BROWSER_CDP_ENDPOINTS_JSON='["http://127.0.0.1:9222"]'
|
|
export REA_BROWSER_ALLOWED_ORIGINS_JSON='["http://127.0.0.1:3000"]'
|
|
|
|
rea list-browser-targets http://127.0.0.1:9222 --approved --json
|
|
rea inspect-web-page http://127.0.0.1:9222 TARGET_ID --approved --json
|
|
```
|
|
|
|
The eight passive browser tools work through both CLI and MCP. They inspect the page without navigating, clicking, or evaluating its JavaScript. Credentials, cookies, authorization headers, and raw payload values are not retained. Script sources, accessibility text, screenshots, and selected console or payload summaries require separate capture approval. REA cannot observe activity that happened before it attached. See [browser observation](docs/browser-observation.md) for browser startup, capture options, and limits.
|
|
|
|
### Controlled browser scenarios
|
|
|
|
`capture_browser_scenario` runs an approved sequence of browser actions through
|
|
Playwright. Unlike passive observation, it can interact with the page. Each
|
|
step records evidence such as screenshots, page structure, navigation, and
|
|
network activity. Missing or truncated observations cannot establish that two
|
|
runs behaved the same way.
|
|
|
|
```bash
|
|
export REA_BROWSER_SCENARIO_ENABLED=true
|
|
export REA_BROWSER_SCENARIO_EXECUTABLE_ROOTS_JSON='["/usr/bin"]'
|
|
export REA_BROWSER_SCENARIO_CDP_ENDPOINTS_JSON='["http://127.0.0.1:9222"]'
|
|
export REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON='["http://127.0.0.1:3000"]'
|
|
export REA_BROWSER_SCENARIO_ALLOWED_ENV_JSON='["REA_TEST_PASSWORD"]'
|
|
|
|
rea capture-browser-scenario ./scenario.json --json
|
|
```
|
|
|
|
Launch mode owns a temporary browser profile and removes it after terminating
|
|
the launched browser. Connect mode accepts one exact loopback CDP target and
|
|
disconnects without closing the external browser. Automation has no default
|
|
grant: use the shared project/session policy, or set
|
|
`REA_BROWSER_SCENARIO_AUTO_GRANT=true` only for a trusted unattended
|
|
environment. Scenario JSON contains secret references and environment-variable
|
|
names, never secret values. See the
|
|
[browser scenario contract](docs/browser-scenario-contract.md).
|
|
|
|
### Node and Electron V8 Inspector observation
|
|
|
|
Node and Electron runtime observation is disabled by default. Enable it to attach to an existing Inspector target:
|
|
|
|
```bash
|
|
export REA_V8_INSPECTOR_OBSERVE_ENABLED=true
|
|
|
|
rea list-javascript-runtime-targets http://127.0.0.1:9229 --json
|
|
rea observe-javascript-runtime http://127.0.0.1:9229 TARGET_ID \
|
|
--runtime-kind node --json
|
|
```
|
|
|
|
REA records script locations and execution-context events without evaluating
|
|
code or setting breakpoints. These observations do not establish import
|
|
relationships, event activity, IPC, process identity, or Electron roles. See
|
|
[Node and Electron runtime observation](docs/javascript-runtime-observation.md)
|
|
for the exact coverage.
|
|
|
|
Exact package, tool-family, provider, setup-client, schema, and CLI facts are generated from source in [`docs/product-catalog.json`](docs/product-catalog.json). PR CI verifies this catalog, narrative documentation, generated schemas, and a clean TypeDoc render.
|
|
|
|
## Roadmap
|
|
|
|
The [current status](#current-status) section describes shipped capabilities. These are the next areas of work.
|
|
|
|
### Now
|
|
|
|
1. **Keep documentation accurate:** update the generated catalog and documentation checks when tools, providers, setup options, or versions change.
|
|
2. **Test more native binaries:** expand architecture and indirect-call coverage across Hopper and Ghidra.
|
|
|
|
### Next
|
|
|
|
1. **Test replay isolation:** add hostile fixtures and test the Linux replay sandbox across more kernels.
|
|
2. **Connect more application layers:** add static extractors and approved runtime observations to feature traces.
|
|
3. **Extend .NET analysis:** improve comparisons of obfuscated assemblies and connect managed findings to verified native analysis. See the [managed-code guide](docs/managed-code-analysis.md).
|
|
4. **Compare more runtime behavior:** expand process, protocol, filesystem, reconnect, and version-comparison coverage.
|
|
|
|
### Later
|
|
|
|
1. **Expand browser and Electron interaction:** add approved scenario actions beyond the current click and wait operations.
|
|
2. **Observe native apps at runtime:** explore LLDB, Frida, system logs, and native API tracing with explicit approval.
|
|
3. **Evaluate more tools and targets:** assess IDA/Hex-Rays, Binary Ninja, Rizin, LIEF, Windows-native tools, mobile apps, and firmware.
|
|
|
|
Setup already lets you choose agent integration and Hopper installation. Support for installing additional analysis tools is future work, described in the [installation roadmap](docs/roadmap.md).
|
|
|
|
See [provider evaluation](docs/provider-evaluation.md) for coverage and remaining requirements, and the [native investigation guide](docs/native-investigation.md) for UI, dispatch, and value-flow analysis.
|
|
|
|
## Using REA with other agents
|
|
|
|
Setup detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, and Devin. It automatically configures the first six when present; detected Devin installations are reported but left unchanged. Any agent that supports local MCP servers can use REA with the configuration below.
|
|
|
|
### Manual MCP configuration
|
|
|
|
<!-- x-release-please-start-version -->
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"rea": {
|
|
"command": "npx",
|
|
"args": ["-y", "rea-agents@3.2.1", "mcp"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<!-- x-release-please-end -->
|
|
|
|
Persistent registrations should use one exact package version. `rea setup`
|
|
maintains that pin, upgrades the bundled skill at the same time, and gives Codex
|
|
a 30-second startup allowance for a cold package-runner start. An interactive
|
|
`rea upgrade` opens the updated setup plan after installing the new executable;
|
|
structured or non-interactive upgrades tell you to run that sync explicitly.
|
|
Restart clients whose approved registration changed.
|
|
|
|
MCP clients that support prompts can also discover six ordered investigation
|
|
workflows through `prompts/list`. Their optional identifier arguments use the
|
|
current session for bounded `completion/complete` suggestions; see
|
|
[Guided MCP prompts and completion](docs/mcp-prompts.md).
|
|
|
|
## How it works
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Agent["Agent"] --> REA["REA<br/>CLI + MCP"]
|
|
Terminal --> REA
|
|
REA --> Session["Target-bound session router"]
|
|
Session --> Registry["Deep-provider registry<br/>deterministic selection"]
|
|
Registry --> Hopper["Hopper provider"]
|
|
Registry --> Ghidra["Ghidra provider<br/>read-only inventory + function analysis"]
|
|
Hopper --> Runtime["Owned provider runtime<br/>deadline + bounded diagnostics + cleanup"]
|
|
Ghidra --> Runtime
|
|
Session --> Native["Native macOS provider"]
|
|
Session --> Artifact["Artifact graph provider"]
|
|
REA --> Browser["Browser CDP provider"]
|
|
REA --> Process["Process capture provider"]
|
|
Runtime --> Target["Target software"]
|
|
Process --> Target
|
|
Native --> Target
|
|
Artifact --> Target
|
|
```
|
|
|
|
The CLI and MCP server use the same application workflows and evidence contracts. A provider declares which capabilities it supports and the side effects those capabilities may have. Terminal commands are short-lived; an MCP session can retain an active target and evidence ledger for the session.
|
|
|
|
## CLI
|
|
|
|
The agent workflow above is the easiest way to use REA. For a one-off overview from the Terminal:
|
|
|
|
```bash
|
|
npx -y rea-agents@latest analyze /Applications/Notes.app
|
|
npx -y rea-agents@latest inspect /Applications/Notes.app
|
|
npx -y rea-agents@latest search /Applications/Notes.app "offline"
|
|
npx -y rea-agents@latest function /Applications/Notes.app 0x1000
|
|
npx -y rea-agents@latest xrefs /Applications/Notes.app 0x1000
|
|
npx -y rea-agents@latest trace /Applications/Notes.app "offline"
|
|
npx -y rea-agents@latest compare /absolute/path/to/left-evidence.json /absolute/path/to/right-evidence.json
|
|
npx -y rea-agents@latest capabilities
|
|
npx -y rea-agents@latest providers
|
|
```
|
|
|
|
Run `npx -y rea-agents@latest --help` for direct decompilation, bounded search and
|
|
other options. `analyze` and `inspect` share the same overview workflow;
|
|
`function`, `xrefs`, and `trace` return the same Evidence envelopes as MCP.
|
|
|
|
Or install the `rea` command globally:
|
|
|
|
```bash
|
|
npm install --global rea-agents
|
|
rea --help
|
|
rea upgrade
|
|
rea mcp
|
|
```
|
|
|
|
REA accepts a Mac `.app` folder directly. If an agent cannot find an app by name, tell it where the app is installed.
|
|
|
|
### Choosing a deep-analysis provider
|
|
|
|
Choose which analysis tool to use from the CLI:
|
|
|
|
```bash
|
|
rea providers --json
|
|
rea analyze /absolute/path/to/program --provider hopper
|
|
REA_ANALYSIS_PROVIDER=hopper rea decompile /absolute/path/to/program 0x1000
|
|
```
|
|
|
|
For MCP, pass the optional selector on `open_binary`:
|
|
|
|
```json
|
|
{
|
|
"path": "/absolute/path/to/program",
|
|
"provider_id": "hopper"
|
|
}
|
|
```
|
|
|
|
Use `--provider`, or `provider_id` in MCP, to choose Hopper or Ghidra for a target. This choice overrides `REA_ANALYSIS_PROVIDER`.
|
|
|
|
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 22 read-only operations on supported Linux and macOS hosts. GUI controls and annotation changes require Hopper. Windows Ghidra operations remain unavailable.
|
|
|
|
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.
|
|
|
|
### CLI exit status
|
|
|
|
| Status | Meaning |
|
|
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `0` | The operation completed. Results may still include warnings, partial evidence, or unresolved questions. |
|
|
| `1` | The operation could not complete, for example because of invalid input, missing permission, cancellation, or timeout. Structured output reports the reason when available. |
|
|
| `128 + N` | The process ended from signal `N`, where the shell or runtime preserves the conventional signal-derived status. |
|
|
|
|
`setup` returns `1` for `planned`, `needs_confirmation`, or `needs_human`
|
|
because configuration is not ready; rerun it after approval or remediation.
|
|
`doctor` returns `1` when any check is unhealthy. Output format, full envelopes,
|
|
filters, and token controls never change the operation status.
|
|
|
|
When REA feeds a shell pipeline, enable `pipefail` so a downstream formatter
|
|
cannot hide its failure:
|
|
|
|
```bash
|
|
set -o pipefail
|
|
rea inventory-artifact ./app.asar --json | jq . > inventory.json
|
|
```
|
|
|
|
## Current Hopper provider
|
|
|
|
REA starts Hopper when an operation needs it. On macOS, Hopper may bring its window or a dialog to the foreground even though REA requests background startup. Demo or license prompts may need your attention.
|
|
|
|
Hopper handles one analysis request at a time. Cancelling your wait does not stop work already running inside Hopper; the session reports whether it is still busy. Successful decompilation results are cached until a relevant rename or comment change.
|
|
|
|
Use `rea instructions` when you only need assembly instructions for a function. It avoids decompilation and a whole-program inventory.
|
|
|
|
Closing a session shuts down REA's bridge and removes its temporary socket directory while preserving a Hopper application you may be using. If cleanup cannot be verified, `close_binary` reports `cleanup_incomplete` and the affected resources.
|
|
|
|
## Advanced process-capture setup
|
|
|
|
Process capture is disabled by default. Enabling it requires
|
|
`REA_PROCESS_CAPTURE_ENABLED=true`, approved executable and working roots in
|
|
`REA_PROCESS_EXECUTABLE_ROOTS_JSON` and `REA_PROCESS_WORKING_ROOTS_JSON`, and an
|
|
environment allowlist in `REA_PROCESS_ALLOWED_ENV_JSON`. Because the current PTY
|
|
adapter uses host networking, it also requires
|
|
`REA_PROCESS_ALLOW_EXTERNAL_NETWORK=true`.
|
|
|
|
Set `REA_PROCESS_CAPTURE_AUTO_GRANT=false` to configure those process-capture
|
|
limits as a ceiling without implicitly granting them. This mode remains
|
|
fail-closed until a narrower grant is established.
|
|
|
|
Capture a scenario or compare two saved Process Capture Evidence records:
|
|
|
|
```bash
|
|
rea capture-process ./scenario.json > authority.json
|
|
rea capture-process ./reconstruction.json > reconstruction.json
|
|
rea compare-process-captures authority.json reconstruction.json
|
|
```
|
|
|
|
The comparison reports each observed dimension separately and identifies the
|
|
first terminal, interaction, exit, filesystem, protocol, process, or shim
|
|
divergence. See [Process Capture](docs/process-capture.md) for scenario
|
|
fields, command-shim replay, checkpoint triggers, limits, and safety behavior.
|
|
|
|
REA installs a prebuilt PTY backend for supported macOS, Linux, and Windows
|
|
architectures. If the capability check reports that the backend is unavailable,
|
|
reinstall REA for the current platform and architecture.
|
|
|
|
ASAR inventory verifies Electron integrity metadata for both archive entries
|
|
and `.asar.unpacked` companion files. Integrity failures identify the logical
|
|
path, declared and calculated SHA-256 values, and whether the entry was
|
|
unpacked; REA does not silently accept the mismatched artifact. If a supplied
|
|
ASAR declares unpacked companion bytes that are absent from the local artifact
|
|
set, REA keeps that occurrence as `unavailable` and continues analyzing the
|
|
embedded JavaScript instead of treating the missing native/resource bytes as
|
|
verified or absent.
|
|
|
|
## Security model
|
|
|
|
Analysis runs locally. REA communicates with Hopper and Ghidra through authenticated private local sockets. Your agent or model provider has its own data policy.
|
|
|
|
Runtime observation and execution features are disabled by default and require configuration and approval. Analysis tools and launched targets run with your user permissions. Extracted JavaScript replay uses a separate Linux sandbox and requires the isolation controls described in [ADR-0002](docs/adr/0002-controlled-replay-authority-and-sandbox.md).
|
|
|
|
Windows Ghidra operations are blocked until REA implements the required process ownership, private-directory permissions, and safe-path checks. Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md).
|
|
|
|
## FAQ
|
|
|
|
<details>
|
|
<summary><strong>Does Hopper need to be running before I start REA?</strong></summary>
|
|
|
|
No. REA starts Hopper when an operation needs it. An already-running Hopper application is also supported.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Why did Hopper appear in front of my other windows?</strong></summary>
|
|
|
|
Hopper's launcher internally activates the application. REA requests background startup, but macOS and Hopper may still bring a window or dialog forward. See [Current Hopper provider](#current-hopper-provider).
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Does REA include Hopper?</strong></summary>
|
|
|
|
No. Setup can install Hopper for you, but Hopper remains separate software with its own license. REA supplies the CLI, MCP server, and workflows that make it usable by agents.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Does REA install or include Ghidra or Java?</strong></summary>
|
|
|
|
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).
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Does REA upload the app?</strong></summary>
|
|
|
|
REA has no hosted analysis service. Current providers analyze artifacts and capture behavior locally. Your agent or model provider may have its own data policy, so review that separately.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Can REA recover the original source code?</strong></summary>
|
|
|
|
No decompiler can guarantee the original source. REA gives an agent pseudocode, assembly, symbols, strings, metadata, and relationships that it can use to explain or compatibly recreate observed behavior.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Which agents can use REA?</strong></summary>
|
|
|
|
Any agent that can run a local MCP server can use the manual configuration. Setup detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, and Devin; it automatically configures the first six when present and reports Devin without modifying it.
|
|
|
|
</details>
|
|
|
|
## Development
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution checks, and [docs/testing.md](docs/testing.md) for test scopes and real-tool verification. PR CI publishes generated API documentation as the `api-docs` artifact.
|
|
|
|
`npm run verify:agent` evaluates native, JavaScript, managed, and browser investigation tasks through a real local Codex CLI. Its report covers tool selection, repeated calls, token use, completion quality, and handling of permissions and unknowns.
|
|
|
|
`npm run evidence:generate` regenerates the managed conformance manifest and Evidence completion ledger from live verification results. `npm run evidence:check` reruns verification and checks for drift. Unsupported claims remain explicit and do not count as passes. See [testing](docs/testing.md) for verification commands and process-cleanup checks.
|
|
|
|
## Project links
|
|
|
|
[npm](https://www.npmjs.com/package/rea-agents) · [Issues](https://github.com/morluto/rea/issues) · [Security](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Hopper](https://www.hopperapp.com/) · [Ghidra](https://github.com/NationalSecurityAgency/ghidra)
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|