Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
Document the 68-tool contract
morluto77db2ecc1c81
diff --git a/README.md b/README.mdindex aae5db2f2..708d32655 100644--- a/README.md+++ b/README.md@@ -10,11 +10,11 @@[](https://www.npmjs.com/package/rea-agents)[](https://github.com/morluto/rea/actions/workflows/ci.yml)-[](#50-tools-for-investigation)+[](#68-tools-for-investigation)[](https://nodejs.org/)[](LICENSE)-[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [50 tools](#50-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)+[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [68 tools](#68-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)<br />@@ -104,6 +104,14 @@ If macOS or an installer asks for confirmation, complete the prompt and run theIf process capture reports that its native PTY backend is unavailable, install Xcode command-line tools and run `npm run rebuild:native`. Linux source builds require Python, `make`, and a C++ toolchain. Compatible packaged binaries do not require this rebuild.+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`. The current PTY adapter+uses host networking, so it additionally requires the explicit operator grant+`REA_PROCESS_ALLOW_EXTERNAL_NETWORK=true`. Without that grant the adapter+refuses to launch; loopback replay alone does not constitute network isolation.+You do not need to install the reverse-engineering tools manually. Setup installs Homebrew and [Hopper](https://www.hopperapp.com/) when needed, configures detected Claude Desktop and Cursor installations, and installs the REA skill. Hopper is separate software and requires its own license; setup installs it but does not provide a license.If something is not working, run:@@ -114,10 +122,23 @@ npx -y rea-agents doctor### 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` |+| 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` |++Filesystem evidence commands and MCP file tools are disabled until the operator approves absolute roots:++```bash+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+```++Exports never replace an existing file unless `--overwrite` is explicit. Imports are size/depth bounded, validate every Evidence v2 ID and manifest, and never execute bundle content.++Completion metadata is verifier-owned. Run `npm run completion:generate` after changing contracts, schemas, providers, scenarios, package metadata, verifier inputs, or the managed skill. CI runs `npm run completion:check`; it detects stale or tampered hashes and never rewrites a branch. Unsupported and unknown outcomes remain separate from passes, and a pass or failure requires indexed Evidence v2 IDs.## One prompt, a full investigation@@ -151,26 +172,38 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its- 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.-## 50 tools for investigation+## 68 tools for investigation| Tool family | Count | Examples || ------------------------- | ----: | ----------------------------------------------------------------------------------------------------------------------- || Native inspection | 33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations || Investigation workflows | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery |-| Workspace and observation | 7 | target lifecycle, Evidence v2 bundle import/export, deterministic process capture and comparison |+| Native macOS utilities | 5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing |+| Artifact graph | 2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected transactional extraction |+| Workspace and observation | 18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle |-The public interface describes what the agent is trying to learn. Providers decide how to answer. Hopper currently implements the native-analysis capabilities; the process harness implements controlled behavioral capture. Future providers can satisfy the same capability without changing the agent's investigation workflow.+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 statusREA is already useful for native application investigation on macOS:-- Open Mach-O, ELF, PE, `.app`, and Hopper database targets.+- Open Mach-O, ELF, PE, `.app`, ZIP, APK, IPA, ASAR, plist, JavaScript, source-map, and Hopper database targets.+- Traverse content-addressed artifact graphs without extraction; materialize only approved occurrences into absent output roots.- Build bounded function dossiers with pseudocode, assembly, CFG edges, comments, calls, references, strings, and names.- Search and trace features across symbols, strings, metadata, references, and call paths.- Record every successful result as deterministic Evidence v2 with artifact and provider identity, confidence, authority, limitations, and locations.- Export and import evidence bundles across sessions.- Capture approved PTY scenarios, child processes, filesystem changes, and loopback HTTP/WebSocket exchanges, then compare normalized captures.+- Compare complete artifact inventories by stable path, content, metadata, and relations; incomplete evidence never implies equivalence.+- Compare explicit function dossiers across text, calls, references, strings, and address-normalized CFG topology with per-facet unknowns.+- Compare canonical Evidence bundles by exact membership, explicit observation pairs, and residual-unknown histories without turning omissions into behavioral absence.+- Aggregate runtime comparisons into observed behavior changes while keeping static artifact/function differences labeled as candidates.+- Build bounded, Evidence-cited direct call paths by exact address without treating missing dossiers as graph leaves.+- Correlate exact static/runtime findings through explicit hypotheses without claiming causality from cochange.+- Verify finite behavioral and structural reconstruction specifications with pass, fail, and unknown kept distinct.+- Track residual unknowns through immutable CAS revisions, evidence-qualified resolution, contradictions, probes, and validated dependency relationships.+- With explicit `unknown_registry_approved: true`, record bounded trace/capture residuals, typed provider unavailability, and capture disagreements automatically.Hopper is the first provider, not the boundary of the project. Some current workflows still require Hopper and macOS; every evidence record identifies the provider and limitations behind its result.@@ -215,10 +248,14 @@ flowchart LRREA --> Workspace["Investigation workspace<br/>evidence + artifacts + captures"]Workspace --> Router["Capability router"]Router --> Hopper["Hopper provider"]+ Router --> Native["Native macOS provider"]+ Router --> Artifact["Artifact graph provider"]Router --> Process["Process capture provider"]- Router -. roadmap .-> More["Artifact, browser, dynamic,<br/>and additional static providers"]+ Router -. roadmap .-> More["Browser, dynamic,<br/>and additional static providers"]Hopper --> 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 across an investigation.diff --git a/README_ar.md b/README_ar.mdindex cabf5b3d6..836f85cd0 100644--- a/README_ar.md+++ b/README_ar.md@@ -10,11 +10,11 @@[](https://www.npmjs.com/package/rea-agents)[](https://github.com/morluto/rea/actions/workflows/ci.yml)-[](#منصة-من-50-أداة)+[](#منصة-من-68-أداة)[](https://nodejs.org/)[](LICENSE)-[البدء السريع](#البدء-السريع) · [من الملف التنفيذي إلى السلوك](#من-الملف-التنفيذي-إلى-السلوك) · [50 أداة](#منصة-من-50-أداة) · [كيف يعمل](#كيف-يعمل) · [الأسئلة الشائعة](#الأسئلة-الشائعة)+[البدء السريع](#البدء-السريع) · [من الملف التنفيذي إلى السلوك](#من-الملف-التنفيذي-إلى-السلوك) · [68 أداة](#منصة-من-68-أداة) · [كيف يعمل](#كيف-يعمل) · [الأسئلة الشائعة](#الأسئلة-الشائعة)<br />@@ -145,13 +145,15 @@ npx -y rea-agents doctorافحص التحقق من الإدخال، والتشفير، والصلاحيات، والتخزين، ومسارات الأخطاء من دون رفع الملف التنفيذي إلى خدمة بعيدة.-## منصة من 50 أداة+## منصة من 68 أداة| عائلة الأدوات | العدد | أمثلة || --------------------- | ----: | ----------------------------------------------------------------------------------- || فحص الملفات التنفيذية | 33 | الدوال، والشيفرة شبه المصدرية، والتعليمات، والسلاسل، والأسماء، والمراجع، والتعليقات || التحليل المركب | 10 | النظرة العامة، وفك الترجمة الدفعي، ومخططات الاستدعاء، والمراجع، واكتشاف الأنواع |-| جلسة الملف التنفيذي | 7 | فتح الأهداف وحزم الأدلة والتقاط العمليات ومقارنتها |+| أدوات macOS الأصلية | 5 | بيانات Mach-O والتوقيعات وملفات plist والمعماريات وفك رموز Swift دون تشغيل Hopper |+| رسم القطع الأثرية | 2 | جرد حتمي للدلائل وZIP/APK/IPA وASAR واستخراج معاملاتي محدد صراحة |+| جلسة الملف التنفيذي | 18 | فتح الأهداف وحزم الأدلة ومقارنة العمليات والقطع والدوال وسجل المجهولات المتبقية |## استخدام REA مع وكلاء برمجة آخرين@@ -200,7 +202,7 @@ npx -y rea-agents analyze /Applications/Notes.appلتجنب مربع اختيار معمارية ملف شامل، حدد معطيات المحمل مسبقًا:```bash-export HOPPER_LOADER_ARGS_JSON='["-l", "Mach-O", "--aarch64"]'+export HOPPER_LOADER_ARGS_JSON='["-l", "Mach-O", "--aarch68"]'```يدير REA دورة حياة Hopper ويحاول إغلاق العمليات التي بدأها عند انتهاء الأمر أو جلسة MCP.diff --git a/README_ja.md b/README_ja.mdindex 184553d6f..e90ff7899 100644--- a/README_ja.md+++ b/README_ja.md@@ -10,11 +10,11 @@[](https://www.npmjs.com/package/rea-agents)[](https://github.com/morluto/rea/actions/workflows/ci.yml)-[](#50-ツールのワークベンチ)+[](#68-ツールのワークベンチ)[](https://nodejs.org/)[](LICENSE)-[クイックスタート](#クイックスタート) · [バイナリから動作へ](#バイナリから動作へ) · [50 ツール](#50-ツールのワークベンチ) · [仕組み](#仕組み) · [FAQ](#faq)+[クイックスタート](#クイックスタート) · [バイナリから動作へ](#バイナリから動作へ) · [68 ツール](#68-ツールのワークベンチ) · [仕組み](#仕組み) · [FAQ](#faq)<br />@@ -135,13 +135,15 @@ REA は手順 1〜5 のバイナリ解析を処理し、手順 6 はエージェ- Swift / Objective-C のメタデータを解析する。- Hopper に名前、コメント、ブックマークを残し、人間とエージェントの調査を共有する。-## 50 ツールのワークベンチ+## 68 ツールのワークベンチ-| ツール群 | 数 | 例 |-| ------------------ | --: | ------------------------------------------------------------------------------------------------------------------- |-| バイナリ調査 | 33 | プロシージャ、疑似コード、アセンブリ、文字列、名前、セグメント、callers、callees、xrefs、注釈 |-| 合成解析 | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift / ObjC 検出 |-| バイナリセッション | 7 | `open_binary`、`binary_session`、証拠バンドル、プロセス取得と比較 |+| ツール群 | 数 | 例 |+| ---------------------- | --: | ------------------------------------------------------------------------------------------------------------------- |+| バイナリ調査 | 33 | プロシージャ、疑似コード、アセンブリ、文字列、名前、セグメント、callers、callees、xrefs、注釈 |+| 合成解析 | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift / ObjC 検出 |+| macOS ネイティブ | 5 | Mach-O メタデータ、署名、plist、アーキテクチャ、Swift デマングル。Hopper 起動不要 |+| アーティファクトグラフ | 2 | ディレクトリ、ZIP/APK/IPA、ASAR の決定的一覧と明示選択されたトランザクション抽出 |+| バイナリセッション | 18 | `open_binary`、`binary_session`、証拠バンドル、プロセス/成果物/関数比較、残余未知レジストリ |## 他のコーディングエージェントで使うdiff --git a/README_ko.md b/README_ko.mdindex cb720ea32..50f419c1d 100644--- a/README_ko.md+++ b/README_ko.md@@ -10,11 +10,11 @@[](https://www.npmjs.com/package/rea-agents)[](https://github.com/morluto/rea/actions/workflows/ci.yml)-[](#50개-도구로-구성된-워크벤치)+[](#68개-도구로-구성된-워크벤치)[](https://nodejs.org/)[](LICENSE)-[빠른 시작](#빠른-시작) · [바이너리에서 동작까지](#바이너리에서-동작까지) · [50개 도구](#50개-도구로-구성된-워크벤치) · [작동 방식](#작동-방식) · [FAQ](#faq)+[빠른 시작](#빠른-시작) · [바이너리에서 동작까지](#바이너리에서-동작까지) · [68개 도구](#68개-도구로-구성된-워크벤치) · [작동 방식](#작동-방식) · [FAQ](#faq)<br />@@ -135,13 +135,15 @@ REA는 1–5단계의 바이너리 분석을 처리합니다. 6단계는 에이- Swift 및 Objective-C 메타데이터를 분석합니다.- Hopper에 이름, 주석, 북마크를 남겨 사람과 에이전트의 분석을 연결합니다.-## 50개 도구로 구성된 워크벤치+## 68개 도구로 구성된 워크벤치-| 도구 그룹 | 수 | 예시 |-| ------------- | --: | -------------------------------------------------------------------------------------------------------------------- |-| 바이너리 검사 | 33 | 프로시저, 의사 코드, 어셈블리, 문자열, 이름, 세그먼트, callers, callees, xrefs, 주석 |-| 합성 분석 | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift 및 ObjC 탐색 |-| 바이너리 세션 | 7 | `open_binary`, `binary_session`, 증거 번들, 프로세스 캡처 및 비교 |+| 도구 그룹 | 수 | 예시 |+| ------------------- | --: | -------------------------------------------------------------------------------------------------------------------- |+| 바이너리 검사 | 33 | 프로시저, 의사 코드, 어셈블리, 문자열, 이름, 세그먼트, callers, callees, xrefs, 주석 |+| 합성 분석 | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift 및 ObjC 탐색 |+| macOS 네이티브 도구 | 5 | Mach-O 메타데이터, 코드 서명, plist, 아키텍처, Swift 디맹글링. Hopper 실행 불필요 |+| 아티팩트 그래프 | 2 | 디렉터리, ZIP/APK/IPA, ASAR 결정적 인벤토리와 명시적으로 선택한 트랜잭션 추출 |+| 바이너리 세션 | 18 | `open_binary`, `binary_session`, 증거 번들, 프로세스·아티팩트·함수 비교, 잔여 미지수 레지스트리 |## 다른 코딩 에이전트에서 사용하기diff --git a/README_zh.md b/README_zh.mdindex 89650781c..f1fc965a4 100644--- a/README_zh.md+++ b/README_zh.md@@ -10,11 +10,11 @@[](https://www.npmjs.com/package/rea-agents)[](https://github.com/morluto/rea/actions/workflows/ci.yml)-[](#50-个工具组成的工作台)+[](#68-个工具组成的工作台)[](https://nodejs.org/)[](LICENSE)-[快速开始](#快速开始) · [从二进制到行为](#从二进制到行为) · [50 个工具](#50-个工具组成的工作台) · [工作原理](#工作原理) · [常见问题](#常见问题)+[快速开始](#快速开始) · [从二进制到行为](#从二进制到行为) · [68 个工具](#68-个工具组成的工作台) · [工作原理](#工作原理) · [常见问题](#常见问题)<br />@@ -135,13 +135,15 @@ REA 负责第 1–5 步中的二进制分析。第 6 步由智能体使用其常- 分析 Swift 和 Objective-C 元数据。- 在 Hopper 中留下名称、注释与书签,使人与智能体的分析互相增强。-## 50 个工具组成的工作台+## 68 个工具组成的工作台-| 工具类别 | 数量 | 示例 |-| ---------- | ---: | -------------------------------------------------------------------------------------------------------------------- |-| 二进制检查 | 33 | 过程、伪代码、汇编、字符串、名称、段、调用者、被调用者、交叉引用、注释 |-| 组合分析 | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`、Swift 与 ObjC 发现 |-| 二进制会话 | 7 | `open_binary`、`binary_session`、证据包、进程捕获与比较 |+| 工具类别 | 数量 | 示例 |+| -------------- | ---: | -------------------------------------------------------------------------------------------------------------------- |+| 二进制检查 | 33 | 过程、伪代码、汇编、字符串、名称、段、调用者、被调用者、交叉引用、注释 |+| 组合分析 | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`、Swift 与 ObjC 发现 |+| macOS 原生工具 | 5 | Mach-O 元数据、代码签名、plist、架构与 Swift 符号还原,无需启动 Hopper |+| 制品图谱 | 2 | 确定性目录、ZIP/APK/IPA 与 ASAR 清单,以及显式选择的事务式提取 |+| 二进制会话 | 18 | `open_binary`、`binary_session`、证据包、进程、制品与函数比较、残余未知项注册表 |## 与其他编程智能体一起使用