diff --git a/README.md b/README.md index 89607b6b7..496fe21e6 100644 --- a/README.md +++ b/README.md @@ -170,12 +170,12 @@ Uninstall preserves Hopper, Homebrew, Node.js, evidence, captures, external evid ### CLI or coding agent? -| If you want to… | Use | -| --------------------------------------------------------- | ---------------------------------------------- | -| Ask an agent to investigate an app and build a feature | Install the skill, then talk to your agent | -| Inspect or decompile one part of an app from the Terminal | `rea analyze` or `rea decompile` | -| Validate or canonicalize an Evidence v2 bundle | `rea evidence-import` or `rea evidence-export` | -| Import source as historical reference | `rea import-reference-source` | +| If you want to… | Use | +| --------------------------------------------------------- | -------------------------------------------------------------- | +| Ask an agent to investigate an app and build a feature | Install the skill, then talk to your agent | +| Inspect or decompile one part of an app from the Terminal | `rea analyze` or `rea decompile` | +| Validate, canonicalize, or compare Evidence v2 bundles | `rea evidence-import`, `rea evidence-export`, or `rea compare` | +| Import source as historical reference | `rea import-reference-source` | Filesystem evidence commands and MCP file tools are disabled until the operator approves absolute roots: @@ -183,6 +183,7 @@ Filesystem evidence commands and MCP file tools are disabled until the operator export REA_EVIDENCE_ROOTS_JSON='["/absolute/path/to/evidence"]' 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 ``` Historical source import requires a separate allowlist and never treats source as current behavioral authority: @@ -276,6 +277,8 @@ REA is growing into a toolkit for understanding software across static artifacts Roadmap items describe direction, not shipped support. New providers must produce the same evidence and safety metadata as existing capabilities before they become part of the public workflow. +See the [static-analysis provider evaluation](docs/provider-evaluation.md) for the current research matrix and admission gate. + ## Using REA with other coding agents Setup currently configures Claude Desktop and Cursor automatically. Any coding agent that supports local MCP servers can use REA with the configuration below. @@ -320,9 +323,20 @@ The agent workflow above is the easiest way to use REA. For a one-off overview f ```bash npx -y rea-agents analyze /Applications/Notes.app +npx -y rea-agents inspect /Applications/Notes.app +npx -y rea-agents inspect /Applications/Notes.app --detail detailed --limit 20 +npx -y rea-agents search /Applications/Notes.app "offline" +npx -y rea-agents function /Applications/Notes.app 0x1000 +npx -y rea-agents xrefs /Applications/Notes.app 0x1000 +npx -y rea-agents trace /Applications/Notes.app "offline" +npx -y rea-agents compare /absolute/path/to/left-evidence.json /absolute/path/to/right-evidence.json +npx -y rea-agents capabilities +npx -y rea-agents providers ``` -Run `npx -y rea-agents --help` for direct decompilation and other options. +Run `npx -y rea-agents --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 v2 envelopes as MCP. Or install the `rea` command globally: @@ -347,9 +361,9 @@ Closing a REA session shuts down its bridge and removes its private socket direc 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`. +environment allowlist in `REA_PROCESS_ALLOWED_ENV_JSON`. Scenarios use the +owned loopback replay by default; a scenario requesting host networking also +requires `REA_PROCESS_ALLOW_EXTERNAL_NETWORK=true`. If the native PTY backend is unavailable, install Xcode command-line tools and run `npm run rebuild:native`. Linux source builds require Python, `make`, and a diff --git a/README_ar.md b/README_ar.md index e318a9041..65b1e4dba 100644 --- a/README_ar.md +++ b/README_ar.md @@ -199,6 +199,7 @@ flowchart LR ```bash npx -y rea-agents analyze /Applications/Notes.app +npx -y rea-agents compare /absolute/path/to/left-evidence.json /absolute/path/to/right-evidence.json ``` شغّل `npx -y rea-agents --help` لمعرفة خيارات فك الترجمة المباشر والخيارات الأخرى. @@ -243,7 +244,7 @@ export HOPPER_LOADER_ARGS_JSON='["-l", "Mach-O", "--aarch68"]'
هل يعمل REA على Linux أو Windows؟ -ليس حاليًا. يعتمد المحول الحالي على تطبيق Hopper لنظام macOS وواجهة Python الخاصة به. +نعم، يعمل REA على macOS 12+ وUbuntu 24.04+ وFedora 41+ وArch Linux ‏64 بت؛ Windows غير مدعوم حاليًا. يعتمد التحليل العميق على تطبيق Hopper وواجهة Python الخاصة به.
diff --git a/docs/provider-evaluation.md b/docs/provider-evaluation.md new file mode 100644 index 000000000..21d509e2e --- /dev/null +++ b/docs/provider-evaluation.md @@ -0,0 +1,59 @@ +# Static-analysis provider evaluation + +Status: research for issue #26; no provider implementation is approved by this note. + +REA should add another analysis provider only after the provider-neutral capability +contracts, Evidence v2 metadata, ownership rules, and multi-fixture conformance +suite are complete. A provider is not a drop-in replacement for Hopper: every +capability must be mapped explicitly, with truthful `unavailable` results where +the engine cannot provide equivalent semantics. + +## Shortlist + +| Provider | License / automation surface | What it brings | REA fit and blockers | +| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Ghidra](https://github.com/NationalSecurityAgency/ghidra) | Apache-2.0 source license; `analyzeHeadless`, Java APIs, and PyGhidra | Broad static analysis, many processors and formats, scripting, and project/database workflows | Strong candidate for a full provider. Requires a Java/JDK runtime, isolated project/cache directories, process supervision, and a stable adapter for Ghidra's project-oriented model. | +| [Rizin](https://github.com/rizinorg/rizin) / [rz-pipe](https://github.com/rizinorg/rz-pipe) | Rizin repository contains LGPL-3.0 and GPL-3.0 components; `rizin`, `rz-bin`, and language bridges through `rzpipe` | Portable CLI analysis, disassembly/debugging, many architectures and file formats, JSON command output | Good candidate for a process-backed Linux provider and fast metadata fallback. License/component inventory must be preserved; command output needs version-pinned parsers and semantic conformance before evidence is trusted. | +| [LIEF](https://github.com/lief-project/LIEF) | Apache-2.0; C++, Python, and other bindings | Deterministic parsing and modification of ELF, PE, Mach-O, COFF, and related executable formats; headers, sections, symbols, relocations, and functions | Best near-term complement, not a decompiler replacement. It can cover format metadata and artifact evidence without a long-lived analysis process; function semantics, pseudocode, CFG, and cross-reference parity remain out of scope unless separately demonstrated. | +| [Binary Ninja](https://docs.binary.ninja/dev/index.html) | API/documentation components are MIT, while the analysis product is licensed by edition; commercial, Ultimate, or Headless license is required for headless automation | Python/Core/C++/Rust APIs, headless loading, IL layers, function analysis, plugins, and configurable analysis | Strong technical fit for a native provider, especially function dossiers. Commercial licensing, license-secret handling, native runtime packaging, and multithreaded lifecycle rules are material deployment blockers. | + +## Recommended order + +1. Use LIEF first for provider-neutral binary metadata where the current + contracts already describe headers, sections, symbols, and relocations. +2. Evaluate Rizin as a separate process provider for portable disassembly and + command-backed queries, with JSON-only parsing and fixture assertions. +3. Evaluate Ghidra or Binary Ninja for decompilation and richer function + semantics only after the conformance fixtures can compare evidence by + capability rather than by provider-specific output text. + +## Required admission gate + +Before implementation, an adapter proposal must provide: + +- a capability matrix covering supported, unsupported, and degraded results; +- provider identity, version, target digest, authority, limitations, and + deterministic locations in every Evidence v2 record; +- bounded subprocess or library lifetime, cancellation, timeouts, and cleanup; +- sanitized diagnostics that do not expose license material, host paths, or + provider tracebacks; +- the same source-owned fixture corpus across architectures and formats; +- repeatable checks for function identity, addresses, strings, names, xrefs, + CFG, and pseudocode wherever those capabilities are claimed. + +This keeps issue #26 a decision record rather than prematurely committing REA +to an engine whose semantics or redistribution terms have not been verified. + +## Primary-source notes + +- Ghidra documents headless batch mode and its Java/Python runtime requirements + in its [Getting Started guide](https://github.com/NationalSecurityAgency/ghidra/blob/master/GhidraDocs/GettingStarted.md). +- Rizin lists supported formats, architectures, tools, and `rzpipe` bridges in + its [repository README](https://github.com/rizinorg/rizin); `rz-pipe` documents + JSON command transport and pipe backends. +- LIEF's [format tutorial](https://lief.re/doc/stable/tutorials/01_play_with_formats.html) + and [Python API](https://lief.re/doc/latest/api/binary_abstraction/python.html) + document parsing and format-agnostic binary access. +- Binary Ninja documents its [headless automation model](https://docs.binary.ninja/dev/batch.html), + [edition licenses](https://docs.binary.ninja/about/license.html), and the + [MIT license for API/documentation components](https://docs.binary.ninja/about/open-source.html).