docs: document CLI safety and provider evaluation
This commit is contained in:
morluto
parent
0d36976277
commit
efc9bd270f
34
README.md
34
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
|
||||
|
|
|
|||
|
|
@ -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"]'
|
|||
<details>
|
||||
<summary><strong>هل يعمل REA على Linux أو Windows؟</strong></summary>
|
||||
|
||||
ليس حاليًا. يعتمد المحول الحالي على تطبيق Hopper لنظام macOS وواجهة Python الخاصة به.
|
||||
نعم، يعمل REA على macOS 12+ وUbuntu 24.04+ وFedora 41+ وArch Linux 64 بت؛ Windows غير مدعوم حاليًا. يعتمد التحليل العميق على تطبيق Hopper وواجهة Python الخاصة به.
|
||||
|
||||
</details>
|
||||
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
Loading…
Reference in New Issue