mirror of
https://github.com/morluto/rea.git
synced 2026-10-26 17:35:11 +00:00
docs: redesign and localize README
This commit is contained in:
morluto committed
1 parent
5ed56d63e0
commit
910eda6f32
5 files changed
+1183
-44
No files matched your search
@@ -1,65 +1,156 @@
|
||||
# REA
|
||||
<div align="center">
|
||||
|
||||
[npm package](https://www.npmjs.com/package/@morluto/rea) · [Issues](https://github.com/morluto/rea/issues) · [Hopper Disassembler](https://www.hopperapp.com/)
|
||||
**English** · [简体中文](README_zh.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [العربية](README_ar.md)
|
||||
|
||||
REA gives coding agents access to Hopper Disassembler through one `rea` command. It exposes 42 MCP tools: 31 direct Hopper operations, 8 composed analysis workflows, and 3 target-session tools.
|
||||
# REA: Reverse Engineer Anything
|
||||
|
||||
REA uses Hopper's public Python API through its own authenticated local bridge. It does not use Hopper's bundled MCP server.
|
||||
### One CLI and MCP server for coding agents to reverse engineer anything
|
||||
|
||||
**REA is not a disassembler.** Hopper Disassembler is a separate macOS dependency that must be installed and licensed independently. REA launches and controls Hopper underneath through its public Python API.
|
||||
**See a feature you like. Understand how it works. Build it your way.**
|
||||
|
||||
## Requirements
|
||||
[](https://www.npmjs.com/package/@morluto/rea)
|
||||
[](https://github.com/morluto/rea/actions/workflows/ci.yml)
|
||||
[](#the-42-tool-workbench)
|
||||
[](https://nodejs.org/)
|
||||
[](LICENSE)
|
||||
|
||||
[Quick start](#quick-start) · [See the workflow](#one-prompt-a-full-investigation) · [From binary to behavior](#from-binary-to-behavior) · [42 tools](#the-42-tool-workbench) · [How it works](#how-it-works) · [FAQ](#faq)
|
||||
|
||||
<br />
|
||||
|
||||
<code>npx -y @morluto/rea setup --yes</code>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
See a feature in an app that you want in your own product? Give the app to your coding agent—even without its source code. With REA, the agent can investigate the feature, understand how it works, and build a version adapted to your stack, design, and requirements.
|
||||
|
||||
REA makes that possible through one CLI and MCP server. Your agent can recover pseudocode, trace behavior across functions, inspect strings and types, and carry the evidence directly into its normal coding workflow. REA handles the reverse-engineering toolchain, analysis session, and target lifecycle behind one interface.
|
||||
|
||||
## From binary to behavior
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="33%" valign="top">
|
||||
<strong>Decompile</strong><br /><br />
|
||||
Open a native app or executable and recover procedures, pseudocode, assembly, strings, symbols, segments, and metadata.
|
||||
</td>
|
||||
<td width="33%" valign="top">
|
||||
<strong>Understand</strong><br /><br />
|
||||
Follow callers, callees, cross-references, and call graphs until the agent can explain how a feature or algorithm 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 keeps the investigation grounded in binary evidence. It does not claim to recover original source code or automatically clone an application.
|
||||
|
||||
## Why REA
|
||||
|
||||
| | |
|
||||
| ------------------------ | -------------------------------------------------------------------------------------------------------- |
|
||||
| **Built for agents** | Ask what a compiled app does and let your agent gather evidence instead of guessing. |
|
||||
| **CLI and MCP** | Run the same reverse-engineering capabilities from your terminal or coding agent. |
|
||||
| **Complexity handled** | REA sets up the tools, opens the app, keeps the investigation running, and cleans up afterward. |
|
||||
| **From insight to code** | Understand a feature, then use the evidence to build your own implementation in the same coding session. |
|
||||
| **Local by design** | Analysis runs on your Mac. REA does not upload the binary to a hosted analysis service. |
|
||||
| **Keeps context** | Investigate several binaries without starting the analysis over for every question. |
|
||||
|
||||
## Quick start
|
||||
|
||||
### Requirements
|
||||
|
||||
- macOS 12 or newer
|
||||
- Node.js 22 or newer
|
||||
- Hopper Disassembler
|
||||
- [Hopper Disassembler](https://www.hopperapp.com/)
|
||||
|
||||
REA does not bundle Hopper. `rea setup --yes` can install Homebrew when absent, install Hopper with the `hopper-disassembler` Homebrew cask, configure detected MCP clients, and install the REA agent skill. Setup is idempotent and returns structured remediation when an installer needs human attention.
|
||||
REA does not bundle Hopper. Setup can install Homebrew when absent, install the `hopper-disassembler` cask, configure detected Claude Desktop and Cursor MCP clients, and install the REA agent skill. Existing client configuration is backed up, updated atomically, and read back before setup reports success.
|
||||
|
||||
## Install
|
||||
Hopper is the separate macOS analysis engine REA controls behind the scenes. Most users interact with REA through the CLI or their agent, but Hopper must be installed and licensed.
|
||||
|
||||
Quick start:
|
||||
### 1. Set up REA
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea setup --yes
|
||||
```
|
||||
|
||||
### 2. Check the integration
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea doctor
|
||||
```
|
||||
|
||||
### 3. Start the MCP server
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea mcp
|
||||
```
|
||||
|
||||
The final command starts the stdio MCP server for clients that launch it directly. `setup` can write the equivalent persistent client registration automatically.
|
||||
The MCP command speaks stdio, so it waits silently for a connected client. If setup detected your client, restart that client and use the registered `rea` server instead of running the command by hand.
|
||||
|
||||
For source-checkout development:
|
||||
Then ask your agent:
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run build
|
||||
npm link
|
||||
rea setup --yes
|
||||
```text
|
||||
Open /path/to/MyApp, summarize the binary, find the authentication flow,
|
||||
decompile the relevant procedures, and show the evidence behind your conclusion.
|
||||
```
|
||||
|
||||
The CLI and MCP adapter call the same binary-session runtime directly; neither invokes the other. One-shot `analyze` and `decompile` commands close their bridge session before returning. MCP mode keeps one session alive so an agent can switch targets.
|
||||
## One prompt, a full investigation
|
||||
|
||||
```bash
|
||||
rea --help
|
||||
rea --llms
|
||||
rea doctor --target /path/to/binary
|
||||
rea mcp add
|
||||
```text
|
||||
Open MyApp, find how its offline search feature works, explain the control flow,
|
||||
and build a version for my project using TypeScript and SQLite.
|
||||
```
|
||||
|
||||
REA gives the agent a grounded 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 | Recovers the implementation | `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 binary-analysis work in steps 1–5. The agent performs step 6 with its normal file-editing and test tools, keeping the recreated behavior tied to evidence from the binary.
|
||||
|
||||
## 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.
|
||||
- Compare implementation paths across two app versions by switching targets in one session.
|
||||
- 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.
|
||||
|
||||
## The 42-tool workbench
|
||||
|
||||
| Tool family | Count | Examples |
|
||||
| ----------------- | ----: | ------------------------------------------------------------------------------------------------------ |
|
||||
| Binary inspection | 31 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations |
|
||||
| Composed analysis | 8 | `binary_overview`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift and ObjC discovery |
|
||||
| Binary session | 3 | `open_binary`, `binary_session`, `close_binary` |
|
||||
|
||||
The public inventory is contract-tested and verified through an isolated packaged MCP client. Real-Hopper verification separately checks the same 42-tool surface against two binaries.
|
||||
|
||||
## MCP workflow
|
||||
|
||||
Start the MCP adapter with `rea mcp` (or `rea --mcp`) with no target. In the connected agent:
|
||||
|
||||
1. Call `open_binary` with any readable local binary or `.hop` path.
|
||||
2. Call `binary_overview`, then use decompilation, strings, symbols, and xrefs tools.
|
||||
1. Call `open_binary` with a readable local binary or `.hop` path.
|
||||
2. Start with `binary_overview`, then narrow the investigation with strings, symbols, decompilation, callers, callees, and xrefs.
|
||||
3. Call `open_binary` again to switch targets. If the new target fails, REA attempts to reopen the previous target.
|
||||
4. Call `close_binary` when finished. `binary_session` reports current state.
|
||||
4. Call `close_binary` when finished. `binary_session` reports the current state at any time.
|
||||
|
||||
Relative target paths resolve against the MCP server's working directory. Mach-O/FAT, ELF, PE, and Hopper databases are detected automatically. FAT loading selects the host-compatible architecture.
|
||||
Relative paths resolve from the MCP server's working directory. REA detects Mach-O/FAT, ELF, PE, and Hopper databases automatically. FAT binaries select the host-compatible architecture without presenting Hopper's common architecture picker.
|
||||
|
||||
`HOPPER_TARGET_PATH` is optional and opens an initial target at server startup. `HOPPER_LAUNCHER_PATH` overrides the Hopper launcher. `HOPPER_TARGET_KIND` selects `executable` or `database` for an initial target. `HOPPER_LOADER_ARGS_JSON` overrides REA's derived Hopper loader arguments for supported executable formats.
|
||||
|
||||
Manual target-free MCP configuration:
|
||||
### Manual MCP configuration
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -72,39 +163,127 @@ Manual target-free MCP configuration:
|
||||
}
|
||||
```
|
||||
|
||||
The first `open_binary` can take time while Hopper analyzes the file. Analysis calls made without an open target return an actionable `NoBinaryOpenError`.
|
||||
## How it works
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Agent["Coding agent"] -->|stdio MCP| REA["REA server<br/>42 tools"]
|
||||
REA --> Session["Binary session<br/>open · switch · close"]
|
||||
Session -->|authenticated Unix socket| Bridge["REA Python bridge<br/>inside Hopper"]
|
||||
Bridge --> API["Hopper public<br/>Python API"]
|
||||
```
|
||||
|
||||
The CLI and MCP adapter call the same binary-session and analysis runtime directly; neither invokes the other. One-shot commands acquire and close their resources for each operation. MCP mode keeps one session alive across calls and target switches.
|
||||
|
||||
## CLI
|
||||
|
||||
Use the package without installing it globally:
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea --help
|
||||
npx -y @morluto/rea doctor --target /path/to/binary
|
||||
npx -y @morluto/rea analyze /path/to/binary
|
||||
npx -y @morluto/rea decompile /path/to/binary 0x100003f20
|
||||
```
|
||||
|
||||
Or install the `rea` command globally:
|
||||
|
||||
```bash
|
||||
npm install --global @morluto/rea
|
||||
rea --help
|
||||
rea mcp
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
| Variable | Purpose |
|
||||
| ------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| `HOPPER_TARGET_PATH` | Optional initial binary or `.hop` target. Target-free MCP sessions use `open_binary`. |
|
||||
| `HOPPER_LAUNCHER_PATH` | Override the Hopper launcher path. |
|
||||
| `HOPPER_TARGET_KIND` | Select `executable` or `database` for an initial target. |
|
||||
| `HOPPER_LOADER_ARGS_JSON` | Override REA's derived Hopper loader arguments with a JSON array of strings. |
|
||||
|
||||
## Hopper application behavior
|
||||
|
||||
REA starts Hopper when needed; Hopper does not have to be running first. Hopper's launcher internally activates the application, so opening a target may bring Hopper to the foreground. REA asks macOS to start Hopper hidden and in the background when possible, but cannot guarantee that Hopper will remain behind the current application.
|
||||
REA starts Hopper when needed; Hopper does not need to be running first. Hopper's launcher internally activates the application, so opening a target may bring Hopper to the foreground. REA asks macOS to start Hopper hidden and in the background when possible, but cannot guarantee that it will remain behind the current application.
|
||||
|
||||
Explicit format and architecture loader arguments prevent Hopper's common FAT/ARM selection dialogs. Other Hopper or macOS dialogs can still require a person. REA reports timeouts and setup remediation through the CLI or MCP result instead of trying to answer UI prompts.
|
||||
REA derives explicit format and architecture arguments to prevent common FAT and ARM selection dialogs. Other Hopper or macOS dialogs may still require a person. REA reports timeouts and remediation through CLI or MCP results instead of attempting to answer UI prompts.
|
||||
|
||||
Closing a REA session shuts down its bridge and removes its private socket directory. It does not quit a Hopper application the user may be using.
|
||||
|
||||
## Local security boundary
|
||||
## Security model
|
||||
|
||||
Each bridge session uses a random capability token and a Unix socket restricted to the current user. This rejects unauthenticated connections and access from other local user accounts, but it does not defend against a malicious process already running as the same user. REA bounds protocol messages and exposes sanitized error messages instead of launcher stderr or internal exception causes.
|
||||
Each bridge session has a random capability token and a Unix socket restricted to the current user. Protocol messages are bounded, and caller-visible errors omit launcher stderr and internal exception causes.
|
||||
|
||||
This boundary prevents unrelated local processes from accidentally using a bridge session; it is not a sandbox. Opening an untrusted binary still delegates parsing and analysis to Hopper under the current macOS user account.
|
||||
This boundary rejects unauthenticated connections and other local user accounts, but it is not a sandbox and does not defend against a malicious process already running as the same user. Opening an untrusted binary delegates parsing and analysis to Hopper with the current macOS user's permissions. Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md).
|
||||
|
||||
## Development and verification
|
||||
## 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 [Hopper application behavior](#hopper-application-behavior).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Does REA include Hopper?</strong></summary>
|
||||
|
||||
No. Hopper is separately installed and licensed software. REA supplies the CLI, MCP server, session management, analysis workflows, and authenticated bridge that make Hopper usable by agents.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Does REA upload my binary?</strong></summary>
|
||||
|
||||
REA has no hosted analysis service. It passes local operations to Hopper through a current-user Unix socket. Your coding 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 client that can launch a stdio MCP server can use the manual configuration. Setup currently detects and configures Claude Desktop and Cursor automatically.
|
||||
|
||||
</details>
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run check
|
||||
npm pack --dry-run
|
||||
npm run verify:package
|
||||
npm pack --dry-run
|
||||
```
|
||||
|
||||
Real-Hopper verification requires two distinct binaries:
|
||||
|
||||
```bash
|
||||
HOPPER_TARGET_PATH=/path/to/target-a \
|
||||
HOPPER_SECOND_TARGET_PATH=/path/to/distinct-target-b \
|
||||
npm run verify:hopper
|
||||
```
|
||||
|
||||
Real-Hopper verification requires Hopper and two distinct binaries. It checks target-free startup, all 42 tools, analysis, bounded decompilation, target switching, bridge cleanup, and server shutdown. The verifier terminates only Hopper bundle processes that appeared during its run; it preserves Hopper processes that were already running.
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture guidelines, pull-request expectations, and the maintainer release checklist. Generated API documentation is available under [`docs/api`](docs/api/index.html).
|
||||
|
||||
The npm package is named `@morluto/rea`, while the product and installed executable remain `REA` and `rea`. Setup writes a floating MCP registration using `npx -y @morluto/rea mcp`. See [CONTRIBUTING.md](CONTRIBUTING.md) for the release checklist and local-tarball verification workflow.
|
||||
## Project links
|
||||
|
||||
Security reports should follow [SECURITY.md](SECURITY.md).
|
||||
[npm](https://www.npmjs.com/package/@morluto/rea) · [Issues](https://github.com/morluto/rea/issues) · [Security](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Hopper](https://www.hopperapp.com/)
|
||||
|
||||
## License
|
||||
|
||||
MIT, see [LICENSE](LICENSE).
|
||||
[MIT](LICENSE)
|
||||
+274
@@ -0,0 +1,274 @@
|
||||
<div align="center">
|
||||
|
||||
[English](README.md) · [简体中文](README_zh.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · **العربية**
|
||||
|
||||
# REA: هندسة أي شيء عكسيًا
|
||||
|
||||
### واجهة CLI وخادم MCP واحدان يمكّنان وكلاء البرمجة من إجراء هندسة عكسية لأي شيء
|
||||
|
||||
**اعثر على ميزة تعجبك. افهم آلية عملها. ابنها بالطريقة التي تريدها.**
|
||||
|
||||
[](https://www.npmjs.com/package/@morluto/rea)
|
||||
[](https://github.com/morluto/rea/actions/workflows/ci.yml)
|
||||
[](#منصة-من-42-أداة)
|
||||
[](https://nodejs.org/)
|
||||
[](LICENSE)
|
||||
|
||||
[البدء السريع](#البدء-السريع) · [من الملف التنفيذي إلى السلوك](#من-الملف-التنفيذي-إلى-السلوك) · [42 أداة](#منصة-من-42-أداة) · [كيف يعمل](#كيف-يعمل) · [الأسئلة الشائعة](#الأسئلة-الشائعة)
|
||||
|
||||
<br />
|
||||
|
||||
<code>npx -y @morluto/rea setup --yes</code>
|
||||
|
||||
</div>
|
||||
|
||||
هل وجدت في تطبيق ما ميزة تريدها في منتجك؟ أعط التطبيق إلى وكيل البرمجة حتى من دون شيفرته المصدرية. باستخدام REA، يستطيع الوكيل استقصاء الميزة وفهم آلية عملها ثم بناء نسخة ملائمة لتقنياتك وتصميمك ومتطلباتك.
|
||||
|
||||
يوفر REA هذه العملية عبر CLI وخادم MCP واحدين. يستطيع الوكيل استعادة الشيفرة شبه المصدرية، وتتبع السلوك بين الدوال، وفحص السلاسل والأنواع، ثم استخدام الأدلة مباشرة في عمله البرمجي المعتاد. ويجمع REA سلسلة أدوات الهندسة العكسية وجلسة التحليل ودورة حياة الهدف خلف واجهة واحدة.
|
||||
|
||||
## من الملف التنفيذي إلى السلوك
|
||||
|
||||
| فك الترجمة | الفهم | إعادة الإنشاء |
|
||||
| ----------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| استخرج الشيفرة شبه المصدرية، والتعليمات، والسلاسل النصية، والرموز | تتبع تدفق التحكم والمراجع المتبادلة والاستدعاءات والأنواع | حوّل ما تعلمه الوكيل إلى ميزة تناسب تقنياتك وواجهتك ومتطلباتك |
|
||||
|
||||
يربط REA الاستقصاء بأدلة من الملف التنفيذي. وهو لا يدّعي استعادة الشيفرة المصدرية الأصلية أو استنساخ التطبيق تلقائيًا.
|
||||
|
||||
## لماذا REA؟
|
||||
|
||||
| | |
|
||||
| -------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| **مصمم للوكلاء** | اسأل عما يفعله تطبيق مترجم ودع الوكيل يجمع الأدلة بدلًا من التخمين. |
|
||||
| **CLI وMCP** | استخدم قدرات الهندسة العكسية نفسها من الطرفية أو وكيل البرمجة. |
|
||||
| **يتولى التعقيد** | يدير REA إعداد الأدوات وفتح التطبيق واستمرار الاستقصاء والتنظيف بعد الانتهاء. |
|
||||
| **سير عمل كامل** | انتقل من النظرة الأولى إلى الشيفرة شبه المصدرية وعلاقات الاستدعاء والأنواع وأدلة التنفيذ. |
|
||||
| **محلي حسب التصميم** | يجري التحليل على جهاز Mac ولا يرفع REA الملف التنفيذي إلى خدمة تحليل مستضافة. |
|
||||
| **يحافظ على السياق** | استقصِ عدة ملفات تنفيذية من دون بدء التحليل من جديد عند كل سؤال. |
|
||||
|
||||
## البدء السريع
|
||||
|
||||
### 1. المتطلبات
|
||||
|
||||
- macOS 12 أو أحدث
|
||||
- Node.js 22 أو أحدث
|
||||
- [Hopper Disassembler](https://www.hopperapp.com/) مثبتًا ومرخصًا
|
||||
|
||||
لا تتضمن حزمة REA برنامج Hopper. يستطيع الإعداد تثبيت Homebrew عند غيابه، وتثبيت حزمة `hopper-disassembler`، وتهيئة عملاء Claude Desktop وCursor المكتشفين، وتثبيت مهارة وكيل REA. تُنسخ إعدادات العملاء الحالية احتياطيًا، ثم تُحدّث ذريًا وتُقرأ مرة أخرى قبل الإبلاغ عن النجاح.
|
||||
|
||||
### 2. إعداد وكلائك
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea setup --yes
|
||||
```
|
||||
|
||||
يكتشف هذا الأمر عملاء الوكلاء المدعومين ويسجل خادم MCP باستخدام أمر عائم:
|
||||
|
||||
```text
|
||||
npx -y @morluto/rea mcp
|
||||
```
|
||||
|
||||
### 3. تحقق من البيئة
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea doctor
|
||||
```
|
||||
|
||||
### 4. حلّل ملفًا تنفيذيًا
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea analyze /path/to/app
|
||||
npx -y @morluto/rea decompile /path/to/app 0x100003f20
|
||||
```
|
||||
|
||||
أو شغّل خادم MCP مباشرة:
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea mcp
|
||||
```
|
||||
|
||||
## استقصاء كامل بطلب واحد
|
||||
|
||||
بعد الإعداد، يمكنك أن تطلب من وكيلك:
|
||||
|
||||
> افتح التطبيق، واكتشف آلية عمل البحث من دون اتصال، واشرح تدفق التحكم، ثم ابنِ نسخة لمشروعي باستخدام TypeScript وSQLite.
|
||||
|
||||
يمكن للوكيل تحويل ذلك إلى سير عمل قابل للتحقق:
|
||||
|
||||
```text
|
||||
فتح الهدف
|
||||
→ انتظار اكتمال تحليل Hopper
|
||||
→ جرد المعماريات والرموز والسلاسل النصية
|
||||
→ تحديد نقاط الدخول والدوال المهمة
|
||||
→ تتبع الاستدعاءات والمراجع المتبادلة وتدفق التحكم
|
||||
→ فك ترجمة التنفيذ ذي الصلة
|
||||
→ تلخيص السلوك والقيود والحالات الطرفية
|
||||
→ بناء الميزة بما يلائم تقنيات المشروع ومتطلباته
|
||||
```
|
||||
|
||||
## ما الذي يمكنك فعله؟
|
||||
|
||||
### فهم تطبيق لا تملك مصدره
|
||||
|
||||
اكشف نقاط الدخول، وأسماء الفئات، والسلاسل النصية، والأطر المستخدمة، ومسارات الميزات من الملف التنفيذي وحده.
|
||||
|
||||
### بناء ميزة تعجبك بطريقتك
|
||||
|
||||
استقصِ الميزة، وافهم سلوكها، ثم ابنِ نسخة ملائمة لمنتجك وتقنياتك ومتطلباتك.
|
||||
|
||||
### توثيق بروتوكول أو تنسيق غير موثق
|
||||
|
||||
تتبع الموزعات، والثوابت، والمقارنات، والقراءة والكتابة لفهم الرسائل وتنسيقات الملفات وآلات الحالات.
|
||||
|
||||
### إعادة إنشاء سلوك متوافق
|
||||
|
||||
حوّل منطقًا مفكوك الترجمة إلى مواصفات واضحة، ثم نفذ بديلًا نظيفًا تحكمه اختبارات السلوك الملحوظ.
|
||||
|
||||
### تدقيق منطق أمني حساس
|
||||
|
||||
افحص التحقق من الإدخال، والتشفير، والصلاحيات، والتخزين، ومسارات الأخطاء من دون رفع الملف التنفيذي إلى خدمة بعيدة.
|
||||
|
||||
## منصة من 42 أداة
|
||||
|
||||
| عائلة الأدوات | العدد | أمثلة |
|
||||
| --------------------- | ----: | ----------------------------------------------------------------------------------- |
|
||||
| فحص الملفات التنفيذية | 31 | الدوال، والشيفرة شبه المصدرية، والتعليمات، والسلاسل، والأسماء، والمراجع، والتعليقات |
|
||||
| التحليل المركب | 8 | النظرة العامة، وفك الترجمة الدفعي، ومخططات الاستدعاء، والمراجع، واكتشاف الأنواع |
|
||||
| جلسة الملف التنفيذي | 3 | `open_binary` و`binary_session` و`close_binary` |
|
||||
|
||||
تُختبر قائمة الأدوات العامة بعقود آلية وعميل MCP معزول من الحزمة. ويتحقق الاختبار باستخدام محرك التحليل الفعلي من واجهة الأدوات الـ42 نفسها على ملفين تنفيذيين.
|
||||
|
||||
## استخدام REA مع وكيل MCP
|
||||
|
||||
يسجل `rea setup` تكوينًا مكافئًا لما يلي:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"rea": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@morluto/rea", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
يمكنك أيضًا تشغيل وضع MCP مباشرة:
|
||||
|
||||
```bash
|
||||
rea mcp
|
||||
rea --mcp
|
||||
```
|
||||
|
||||
كلا الأمرين يشغل خادم stdio نفسه. تبقى جلسة Hopper حية بين طلبات الأدوات، ويمكن للوكيل تبديل الأهداف من دون إعادة بناء الخادم.
|
||||
|
||||
## كيف يعمل؟
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Human[المستخدم] --> Agent[وكيل البرمجة]
|
||||
Agent -->|MCP| REA[REA]
|
||||
Human -->|CLI| REA
|
||||
REA --> Runtime[طبقة الجلسة والتحليل المشتركة]
|
||||
Runtime --> Bridge[جسر Python داخل العملية]
|
||||
Bridge --> Hopper[Hopper Disassembler]
|
||||
Hopper --> Binary[ملف تنفيذي أو قاعدة .hop]
|
||||
```
|
||||
|
||||
لا يستدعي محول CLI خادم MCP، ولا يستدعي خادم MCP واجهة CLI. كلاهما يعتمد مباشرة على طبقة التشغيل المشتركة نفسها.
|
||||
|
||||
## أوامر CLI
|
||||
|
||||
```text
|
||||
rea setup [--yes] تسجيل REA لدى عملاء الوكلاء
|
||||
rea doctor فحص Node.js وHopper وتكوين العملاء
|
||||
rea analyze <target> تحليل ملف تنفيذي أو قاعدة Hopper
|
||||
rea decompile <target> <address> فك ترجمة دالة عند عنوان محدد
|
||||
rea mcp تشغيل خادم MCP عبر stdio
|
||||
rea mcp add إضافة تسجيلات MCP
|
||||
rea mcp doctor تشخيص تسجيلات MCP
|
||||
rea --mcp اسم بديل متوافق لوضع MCP
|
||||
```
|
||||
|
||||
اعرض جميع الخيارات باستخدام:
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea --help
|
||||
```
|
||||
|
||||
## سلوك Hopper
|
||||
|
||||
يستطيع REA تشغيل Hopper تلقائيًا؛ لا حاجة إلى افتراض أنه يعمل مسبقًا. لكنه تطبيق macOS رسومي، لذلك قد يطلب التركيز أو يعرض حوارًا عندما يفرض Hopper قرارًا تفاعليًا. لا يمكن لـ REA ضمان تشغيل غير مرئي تمامًا لأن هذه الواجهة يملكها Hopper وmacOS.
|
||||
|
||||
لتجنب مربع اختيار معمارية ملف شامل، حدد معطيات المحمل مسبقًا:
|
||||
|
||||
```bash
|
||||
export HOPPER_LOADER_ARGS_JSON='["-l", "Mach-O", "--aarch64"]'
|
||||
```
|
||||
|
||||
يدير REA دورة حياة Hopper ويحاول إغلاق العمليات التي بدأها عند انتهاء الأمر أو جلسة MCP.
|
||||
|
||||
## الأمان والخصوصية
|
||||
|
||||
- يبقى تحليل الملف التنفيذي محليًا بين REA وHopper.
|
||||
- لا يرفع REA الأهداف إلى خدمة مستضافة.
|
||||
- راجع الملفات التنفيذية غير الموثوقة واعزلها كما تفعل مع أي مدخل أصلي قد يكون ضارًا.
|
||||
- أبلغ عن الثغرات وفق [سياسة الأمان](SECURITY.md)، وليس عبر قضية عامة.
|
||||
|
||||
## الأسئلة الشائعة
|
||||
|
||||
<details>
|
||||
<summary><strong>هل يتضمن REA محرك فك ترجمة خاصًا به؟</strong></summary>
|
||||
|
||||
لا. يوفر REA طبقة الوكيل وواجهة CLI وإدارة الجلسات وسير العمل، بينما يوفر Hopper محرك التحليل وفك الترجمة.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>هل يجب أن يكون Hopper مفتوحًا مسبقًا؟</strong></summary>
|
||||
|
||||
لا. يستطيع REA تشغيله. لكن Hopper قد يصبح مرئيًا أو يطلب إدخالًا عند الحاجة إلى قرار تفاعلي.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>هل يعمل REA على Linux أو Windows؟</strong></summary>
|
||||
|
||||
ليس حاليًا. يعتمد المحول الحالي على تطبيق Hopper لنظام macOS وواجهة Python الخاصة به.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>هل يمكنني تحليل قواعد Hopper المحفوظة؟</strong></summary>
|
||||
|
||||
نعم. يدعم وقت التشغيل الملفات التنفيذية وقواعد `.hop`.
|
||||
|
||||
</details>
|
||||
|
||||
## التطوير
|
||||
|
||||
```bash
|
||||
git clone https://github.com/morluto/rea.git
|
||||
cd rea
|
||||
npm ci
|
||||
npm run check
|
||||
```
|
||||
|
||||
يتطلب التحقق الحقيقي من Hopper تثبيتًا محليًا وملفات اختبار مناسبة:
|
||||
|
||||
```bash
|
||||
npm run verify:hopper
|
||||
```
|
||||
|
||||
راجع [CONTRIBUTING.md](CONTRIBUTING.md) لإرشادات التطوير والإصدار.
|
||||
|
||||
## المشروع
|
||||
|
||||
- [حزمة npm](https://www.npmjs.com/package/@morluto/rea)
|
||||
- [GitHub](https://github.com/morluto/rea)
|
||||
- [القضايا والطلبات](https://github.com/morluto/rea/issues)
|
||||
- [Hopper Disassembler](https://www.hopperapp.com/)
|
||||
- [سياسة الأمان](SECURITY.md)
|
||||
|
||||
## الترخيص
|
||||
|
||||
[MIT](LICENSE)
|
||||
+228
@@ -0,0 +1,228 @@
|
||||
<div align="center">
|
||||
|
||||
[English](README.md) · [简体中文](README_zh.md) · **日本語** · [한국어](README_ko.md) · [العربية](README_ar.md)
|
||||
|
||||
# REA：あらゆるものをリバースエンジニアリング
|
||||
|
||||
### コーディングエージェントがあらゆるものをリバースエンジニアリングするための、ひとつの CLI / MCP サーバー
|
||||
|
||||
**気になる機能を見つけ、仕組みを理解し、自分の形で実装する。**
|
||||
|
||||
[](https://www.npmjs.com/package/@morluto/rea)
|
||||
[](https://github.com/morluto/rea/actions/workflows/ci.yml)
|
||||
[](#42-ツールのワークベンチ)
|
||||
[](https://nodejs.org/)
|
||||
[](LICENSE)
|
||||
|
||||
[クイックスタート](#クイックスタート) · [バイナリから動作へ](#バイナリから動作へ) · [42 ツール](#42-ツールのワークベンチ) · [仕組み](#仕組み) · [FAQ](#faq)
|
||||
|
||||
<br />
|
||||
|
||||
<code>npx -y @morluto/rea setup --yes</code>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
アプリの気になる機能を自分のプロダクトにも取り入れたいと思ったことはありませんか。ソースコードがなくても、そのアプリをコーディングエージェントに渡せます。REA を使えば、エージェントが機能を調査して仕組みを理解し、あなたの技術スタック、デザイン、要件に合わせた形で実装できます。
|
||||
|
||||
REA はこの流れをひとつの CLI / MCP サーバーで実現します。エージェントは疑似コードを復元し、関数をまたぐ動作を追跡し、文字列や型を調べ、その根拠を通常のコーディング作業へ直接持ち込めます。REA はツールチェーン、解析セッション、ターゲットのライフサイクルをひとつのインターフェースで扱います。
|
||||
|
||||
## バイナリから動作へ
|
||||
|
||||
| 逆コンパイル | 理解 | 再現 |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| ネイティブアプリや実行ファイルから、プロシージャ、疑似コード、アセンブリ、文字列、シンボル、セグメント、メタデータを復元します。 | 呼び出し元、呼び出し先、クロスリファレンス、コールグラフをたどり、機能やアルゴリズムの実際の動作を説明できる状態にします。 | エージェントが得た知見を、あなたの技術スタック、画面、要件に合うプロダクト機能へ変えます。 |
|
||||
|
||||
REA は調査をバイナリ上の根拠に結び付けます。元のソースコードを復元したり、アプリ全体を自動複製したりするとは主張しません。
|
||||
|
||||
## REA を選ぶ理由
|
||||
|
||||
| | |
|
||||
| ---------------------- | ------------------------------------------------------------------------------------- |
|
||||
| **エージェント向け** | コンパイル済みアプリについて質問し、推測ではなく根拠を集めさせることができます。 |
|
||||
| **CLI と MCP** | ターミナルとコーディングエージェントから同じリバースエンジニアリング機能を使えます。 |
|
||||
| **複雑さを処理** | ツール設定、アプリの読み込み、調査の維持、終了後のクリーンアップを REA が担います。 |
|
||||
| **一連の調査に対応** | 最初の概要から疑似コード、呼び出し関係、型、実装の手掛かりまで掘り下げられます。 |
|
||||
| **ローカルで解析** | 解析は Mac 上で実行され、REA がバイナリをホスト型解析サービスへ送ることはありません。 |
|
||||
| **コンテキストを維持** | 質問ごとに解析を最初からやり直さず、複数のバイナリを続けて調査できます。 |
|
||||
|
||||
## クイックスタート
|
||||
|
||||
### 必要環境
|
||||
|
||||
- macOS 12 以降
|
||||
- Node.js 22 以降
|
||||
- [Hopper Disassembler](https://www.hopperapp.com/)
|
||||
|
||||
REA に Hopper は含まれません。Setup は必要に応じて Homebrew と `hopper-disassembler` cask をインストールし、検出した Claude Desktop / Cursor の MCP 設定と REA エージェントスキルを構成します。既存設定はバックアップされ、アトミックに更新された後、読み戻し検証されます。
|
||||
|
||||
```bash
|
||||
# 1. インストールと設定
|
||||
npx -y @morluto/rea setup --yes
|
||||
|
||||
# 2. 統合を診断
|
||||
npx -y @morluto/rea doctor
|
||||
|
||||
# 3. stdio MCP サーバーを起動
|
||||
npx -y @morluto/rea mcp
|
||||
```
|
||||
|
||||
MCP コマンドは stdio で通信するため、クライアント接続を静かに待ちます。Setup がクライアントを構成した場合は、そのクライアントを再起動して登録済みの `rea` サーバーを使用してください。
|
||||
|
||||
エージェントへの依頼例：
|
||||
|
||||
```text
|
||||
/path/to/MyApp を開き、バイナリの概要を示し、認証フローを見つけ、
|
||||
関連プロシージャを逆コンパイルして、結論を支える根拠を提示してください。
|
||||
```
|
||||
|
||||
## ひとつのプロンプトで調査を完結
|
||||
|
||||
```text
|
||||
MyApp を開き、オフライン検索機能の仕組みと制御フローを説明し、
|
||||
TypeScript と SQLite を使って私のプロジェクト向けに実装してください。
|
||||
```
|
||||
|
||||
| 手順 | エージェントの処理 | REA ツール |
|
||||
| ---: | ------------------------------ | ---------------------------------------------------------------- |
|
||||
| 1 | バイナリを開いて識別 | `open_binary`, `binary_overview` |
|
||||
| 2 | オフライン検索の手掛かりを探す | `search_strings`, `search_procedures`, `list_names` |
|
||||
| 3 | 手掛かりと実行コードを接続 | `find_xrefs_to_name`, `xrefs`, `procedure_callers` |
|
||||
| 4 | 制御フローを復元 | `get_call_graph`, `procedure_callees`, `procedure_info` |
|
||||
| 5 | 実装を復元 | `procedure_pseudo_code`, `procedure_assembly`, `batch_decompile` |
|
||||
| 6 | プロジェクトに機能を実装する | 技術スタック、プロダクト、要件に合わせたコード |
|
||||
|
||||
REA は手順 1〜5 のバイナリ解析を処理し、手順 6 はエージェントの通常の編集・テストツールが行います。
|
||||
|
||||
## エージェントにできること
|
||||
|
||||
- ソースコードがない機能の仕組みを説明する。
|
||||
- アプリの認証、保存、更新、ネットワークフローを復元する。
|
||||
- 非公開の形式やインターフェースを文書化できる構造を回収する。
|
||||
- 文字列やシンボルから疑わしい動作の実装コードまで追跡する。
|
||||
- 同じセッションで 2 バージョンを切り替え、実装経路を比較する。
|
||||
- 気になる機能を調査し、自分のプロダクトに合わせた形で実装する。
|
||||
- 復元した動作をプロダクト機能、テスト、移行ノート、移植、相互運用できる代替実装へ変換する。
|
||||
- Swift / Objective-C のメタデータを解析する。
|
||||
- Hopper に名前、コメント、ブックマークを残し、人間とエージェントの調査を共有する。
|
||||
|
||||
## 42 ツールのワークベンチ
|
||||
|
||||
| ツール群 | 数 | 例 |
|
||||
| ------------------ | --: | ----------------------------------------------------------------------------------------------- |
|
||||
| バイナリ調査 | 31 | プロシージャ、疑似コード、アセンブリ、文字列、名前、セグメント、callers、callees、xrefs、注釈 |
|
||||
| 合成解析 | 8 | `binary_overview`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift / ObjC 検出 |
|
||||
| バイナリセッション | 3 | `open_binary`, `binary_session`, `close_binary` |
|
||||
|
||||
公開ツール一覧は契約テストと分離されたパッケージ MCP クライアントで検証されています。実 Hopper 検証では 2 つのバイナリを使って同じ 42 ツールを確認します。
|
||||
|
||||
## MCP ワークフロー
|
||||
|
||||
1. `open_binary` で読み取り可能なローカルバイナリまたは `.hop` を開きます。
|
||||
2. `binary_overview` から始め、文字列、シンボル、逆コンパイル、callers、callees、xrefs で範囲を絞ります。
|
||||
3. `open_binary` を再度呼び出してターゲットを切り替えます。失敗時は以前のターゲットを再度開きます。
|
||||
4. 終了時に `close_binary` を呼びます。`binary_session` はいつでも状態を返します。
|
||||
|
||||
REA は Mach-O/FAT、ELF、PE、Hopper データベースを自動判定します。相対パスは MCP サーバーの作業ディレクトリ基準で、FAT バイナリではホスト互換アーキテクチャを選択します。
|
||||
|
||||
### MCP 手動設定
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"rea": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@morluto/rea", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 仕組み
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Agent["コーディングエージェント"] -->|stdio MCP| REA["REA サーバー<br/>42 ツール"]
|
||||
REA --> Session["バイナリセッション<br/>開く · 切替 · 閉じる"]
|
||||
Session -->|認証済み Unix ソケット| Bridge["Hopper 内の<br/>REA Python ブリッジ"]
|
||||
Bridge --> API["Hopper 公開<br/>Python API"]
|
||||
```
|
||||
|
||||
CLI と MCP アダプターは同じセッション・解析ランタイムを直接使用し、互いを呼び出しません。単発コマンドは処理ごとにリソースを閉じ、MCP モードは複数の呼び出しやターゲット切り替えをまたいでセッションを維持します。
|
||||
|
||||
## CLI
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea --help
|
||||
npx -y @morluto/rea doctor --target /path/to/binary
|
||||
npx -y @morluto/rea analyze /path/to/binary
|
||||
npx -y @morluto/rea decompile /path/to/binary 0x100003f20
|
||||
```
|
||||
|
||||
グローバルな `rea` コマンドとしてもインストールできます。
|
||||
|
||||
```bash
|
||||
npm install --global @morluto/rea
|
||||
rea --help
|
||||
rea mcp
|
||||
```
|
||||
|
||||
## Hopper アプリの動作
|
||||
|
||||
REA は必要なときに Hopper を起動します。Hopper のランチャーは内部でアプリをアクティブ化するため、ターゲットを開くと Hopper が前面に出る場合があります。REA はバックグラウンド起動を要求しますが、常に背面に留まる保証はありません。
|
||||
|
||||
明示的な形式・アーキテクチャ引数により一般的な FAT / ARM 選択ダイアログを避けますが、別の Hopper / macOS ダイアログは人の操作を必要とする場合があります。セッションを閉じるとブリッジとソケットを削除しますが、ユーザーが利用中の Hopper は終了しません。
|
||||
|
||||
## セキュリティモデル
|
||||
|
||||
各セッションはランダムな capability token と現在のユーザーだけが使える Unix ソケットを使用します。これはサンドボックスではなく、同じユーザー権限で動作する悪意あるプロセスを防御しません。信頼できないバイナリの解析は、現在の macOS ユーザー権限で Hopper に委譲されます。脆弱性は [SECURITY.md](SECURITY.md) の非公開手順で報告してください。
|
||||
|
||||
## FAQ
|
||||
|
||||
<details><summary><strong>Hopper を先に起動する必要がありますか？</strong></summary>
|
||||
|
||||
いいえ。REA が必要時に起動します。すでに起動している Hopper にも対応します。
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary><strong>REA に Hopper は含まれますか？</strong></summary>
|
||||
|
||||
含まれません。Hopper は別途インストール・ライセンスが必要です。REA は CLI、MCP、セッション、解析ワークフロー、認証ブリッジを提供します。
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary><strong>バイナリはアップロードされますか？</strong></summary>
|
||||
|
||||
REA にホスト型解析サービスはありません。ローカル Unix ソケット経由で Hopper を操作します。エージェントやモデル提供者のデータポリシーは別途確認してください。
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary><strong>元のソースコードを復元できますか？</strong></summary>
|
||||
|
||||
保証できません。REA は疑似コード、アセンブリ、シンボル、文字列、メタデータ、関係を提供し、エージェントが観察した動作を説明または互換再現できるようにします。
|
||||
|
||||
</details>
|
||||
|
||||
## 開発
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run check
|
||||
npm run verify:package
|
||||
npm pack --dry-run
|
||||
```
|
||||
|
||||
実 Hopper 検証には異なる 2 つのバイナリが必要です。
|
||||
|
||||
```bash
|
||||
HOPPER_TARGET_PATH=/path/to/target-a \
|
||||
HOPPER_SECOND_TARGET_PATH=/path/to/distinct-target-b \
|
||||
npm run verify:hopper
|
||||
```
|
||||
|
||||
アーキテクチャ規約、Pull Request、リリース手順は [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
|
||||
|
||||
## ライセンス
|
||||
|
||||
[MIT](LICENSE)
|
||||
+228
@@ -0,0 +1,228 @@
|
||||
<div align="center">
|
||||
|
||||
[English](README.md) · [简体中文](README_zh.md) · [日本語](README_ja.md) · **한국어** · [العربية](README_ar.md)
|
||||
|
||||
# REA: 무엇이든 리버스 엔지니어링
|
||||
|
||||
### 코딩 에이전트가 무엇이든 리버스 엔지니어링할 수 있게 하는 하나의 CLI 및 MCP 서버
|
||||
|
||||
**마음에 드는 기능을 찾고, 작동 방식을 이해하고, 원하는 방식으로 구현하세요.**
|
||||
|
||||
[](https://www.npmjs.com/package/@morluto/rea)
|
||||
[](https://github.com/morluto/rea/actions/workflows/ci.yml)
|
||||
[](#42개-도구로-구성된-워크벤치)
|
||||
[](https://nodejs.org/)
|
||||
[](LICENSE)
|
||||
|
||||
[빠른 시작](#빠른-시작) · [바이너리에서 동작까지](#바이너리에서-동작까지) · [42개 도구](#42개-도구로-구성된-워크벤치) · [작동 방식](#작동-방식) · [FAQ](#faq)
|
||||
|
||||
<br />
|
||||
|
||||
<code>npx -y @morluto/rea setup --yes</code>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
어떤 앱에서 마음에 드는 기능을 자신의 제품에도 넣고 싶나요? 소스 코드가 없어도 앱을 코딩 에이전트에 전달할 수 있습니다. REA를 사용하면 에이전트가 기능을 조사하고 작동 방식을 이해한 뒤, 사용자의 기술 스택, 디자인, 요구 사항에 맞는 버전을 구현할 수 있습니다.
|
||||
|
||||
REA는 이 과정을 하나의 CLI 및 MCP 서버로 제공합니다. 에이전트는 의사 코드를 복구하고, 함수 사이의 동작을 추적하고, 문자열과 타입을 조사한 뒤 그 증거를 일반 코딩 작업에 바로 활용할 수 있습니다. REA는 도구 체인, 분석 세션, 대상 수명 주기를 하나의 인터페이스로 처리합니다.
|
||||
|
||||
## 바이너리에서 동작까지
|
||||
|
||||
| 디컴파일 | 이해 | 재현 |
|
||||
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| 네이티브 앱이나 실행 파일에서 프로시저, 의사 코드, 어셈블리, 문자열, 심볼, 세그먼트, 메타데이터를 복구합니다. | 호출자, 피호출자, 상호 참조, 호출 그래프를 따라 기능이나 알고리즘의 실제 동작을 설명합니다. | 에이전트가 배운 내용을 사용자의 기술 스택, 화면, 요구 사항에 맞는 제품 기능으로 만듭니다. |
|
||||
|
||||
REA는 분석을 바이너리 증거에 근거하게 합니다. 원본 소스 코드를 복원하거나 앱 전체를 자동으로 복제한다고 주장하지 않습니다.
|
||||
|
||||
## REA를 사용하는 이유
|
||||
|
||||
| | |
|
||||
| ------------------ | ---------------------------------------------------------------------------------- |
|
||||
| **에이전트용** | 컴파일된 앱에 관해 질문하고 추측 대신 증거를 수집하게 합니다. |
|
||||
| **CLI와 MCP** | 터미널과 코딩 에이전트에서 동일한 리버스 엔지니어링 기능을 사용합니다. |
|
||||
| **복잡성 처리** | 도구 설정, 앱 열기, 조사 유지, 작업 후 정리를 REA가 처리합니다. |
|
||||
| **전체 조사 과정** | 첫 개요에서 의사 코드, 호출 관계, 타입, 구현 단서까지 이어서 조사합니다. |
|
||||
| **로컬 분석** | 분석은 Mac에서 실행되며 REA는 바이너리를 호스팅 분석 서비스에 업로드하지 않습니다. |
|
||||
| **컨텍스트 유지** | 질문마다 분석을 처음부터 시작하지 않고 여러 바이너리를 연속으로 조사합니다. |
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
### 요구 사항
|
||||
|
||||
- macOS 12 이상
|
||||
- Node.js 22 이상
|
||||
- [Hopper Disassembler](https://www.hopperapp.com/)
|
||||
|
||||
REA는 Hopper를 번들하지 않습니다. Setup은 필요할 때 Homebrew와 `hopper-disassembler` cask를 설치하고, 감지된 Claude Desktop 및 Cursor MCP 클라이언트와 REA 에이전트 스킬을 구성합니다. 기존 설정은 백업되고 원자적으로 갱신된 뒤 다시 읽어 검증합니다.
|
||||
|
||||
```bash
|
||||
# 1. 설치 및 구성
|
||||
npx -y @morluto/rea setup --yes
|
||||
|
||||
# 2. 통합 진단
|
||||
npx -y @morluto/rea doctor
|
||||
|
||||
# 3. stdio MCP 서버 시작
|
||||
npx -y @morluto/rea mcp
|
||||
```
|
||||
|
||||
MCP 명령은 stdio로 통신하므로 클라이언트 연결을 조용히 기다립니다. Setup이 클라이언트를 구성했다면 클라이언트를 다시 시작하고 등록된 `rea` 서버를 사용하세요.
|
||||
|
||||
에이전트에게 다음과 같이 요청할 수 있습니다.
|
||||
|
||||
```text
|
||||
/path/to/MyApp을 열고 바이너리를 요약한 다음 인증 흐름을 찾아
|
||||
관련 프로시저를 디컴파일하고 결론을 뒷받침하는 증거를 보여 주세요.
|
||||
```
|
||||
|
||||
## 하나의 프롬프트로 전체 조사
|
||||
|
||||
```text
|
||||
MyApp을 열고 오프라인 검색 기능의 작동 방식과 제어 흐름을 설명한 다음,
|
||||
TypeScript와 SQLite를 사용해 제 프로젝트에 맞는 버전을 구현해 주세요.
|
||||
```
|
||||
|
||||
| 단계 | 에이전트 작업 | REA 도구 |
|
||||
| ---: | ----------------------- | ---------------------------------------------------------------- |
|
||||
| 1 | 바이너리 열기 및 식별 | `open_binary`, `binary_overview` |
|
||||
| 2 | 오프라인 검색 단서 찾기 | `search_strings`, `search_procedures`, `list_names` |
|
||||
| 3 | 단서를 실행 코드에 연결 | `find_xrefs_to_name`, `xrefs`, `procedure_callers` |
|
||||
| 4 | 제어 흐름 재구성 | `get_call_graph`, `procedure_callees`, `procedure_info` |
|
||||
| 5 | 구현 복구 | `procedure_pseudo_code`, `procedure_assembly`, `batch_decompile` |
|
||||
| 6 | 프로젝트에 기능 구현 | 기술 스택, 제품, 요구 사항에 맞는 코드 |
|
||||
|
||||
REA는 1–5단계의 바이너리 분석을 처리합니다. 6단계는 에이전트가 일반 파일 편집 및 테스트 도구로 수행합니다.
|
||||
|
||||
## 에이전트가 할 수 있는 일
|
||||
|
||||
- 소스 코드가 없는 기능의 동작을 설명합니다.
|
||||
- 앱의 인증, 저장소, 업데이트 또는 네트워크 흐름을 재구성합니다.
|
||||
- 문서화되지 않은 형식이나 인터페이스의 구조를 복구합니다.
|
||||
- 문자열이나 심볼에서 의심스러운 동작을 구현한 코드까지 추적합니다.
|
||||
- 한 세션에서 두 앱 버전을 전환하며 구현 경로를 비교합니다.
|
||||
- 마음에 드는 기능을 조사하고 자신의 제품에 맞는 버전으로 구현합니다.
|
||||
- 복구한 동작을 제품 기능, 테스트, 마이그레이션 문서, 포팅 또는 상호 운용 가능한 대체품으로 변환합니다.
|
||||
- Swift 및 Objective-C 메타데이터를 분석합니다.
|
||||
- Hopper에 이름, 주석, 북마크를 남겨 사람과 에이전트의 분석을 연결합니다.
|
||||
|
||||
## 42개 도구로 구성된 워크벤치
|
||||
|
||||
| 도구 그룹 | 수 | 예시 |
|
||||
| ------------- | --: | ------------------------------------------------------------------------------------------------ |
|
||||
| 바이너리 검사 | 31 | 프로시저, 의사 코드, 어셈블리, 문자열, 이름, 세그먼트, callers, callees, xrefs, 주석 |
|
||||
| 합성 분석 | 8 | `binary_overview`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift 및 ObjC 탐색 |
|
||||
| 바이너리 세션 | 3 | `open_binary`, `binary_session`, `close_binary` |
|
||||
|
||||
공개 도구 목록은 계약 테스트와 격리된 패키지 MCP 클라이언트로 검증됩니다. 실제 Hopper 검증은 서로 다른 두 바이너리에서 같은 42개 도구를 확인합니다.
|
||||
|
||||
## MCP 워크플로
|
||||
|
||||
1. `open_binary`로 읽을 수 있는 로컬 바이너리 또는 `.hop` 파일을 엽니다.
|
||||
2. `binary_overview`로 시작하고 문자열, 심볼, 디컴파일, callers, callees, xrefs로 범위를 좁힙니다.
|
||||
3. `open_binary`를 다시 호출해 대상을 전환합니다. 새 대상이 실패하면 이전 대상을 다시 엽니다.
|
||||
4. 완료되면 `close_binary`를 호출합니다. `binary_session`은 언제든 현재 상태를 반환합니다.
|
||||
|
||||
REA는 Mach-O/FAT, ELF, PE, Hopper 데이터베이스를 자동으로 감지합니다. 상대 경로는 MCP 서버 작업 디렉터리를 기준으로 하며 FAT 바이너리는 호스트와 호환되는 아키텍처를 선택합니다.
|
||||
|
||||
### 수동 MCP 구성
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"rea": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@morluto/rea", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 작동 방식
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Agent["코딩 에이전트"] -->|stdio MCP| REA["REA 서버<br/>42개 도구"]
|
||||
REA --> Session["바이너리 세션<br/>열기 · 전환 · 닫기"]
|
||||
Session -->|인증 Unix 소켓| Bridge["Hopper 내부<br/>REA Python 브리지"]
|
||||
Bridge --> API["Hopper 공개<br/>Python API"]
|
||||
```
|
||||
|
||||
CLI와 MCP 어댑터는 같은 세션 및 분석 런타임을 직접 사용하며 서로를 호출하지 않습니다. 일회성 명령은 매 작업 후 리소스를 닫고 MCP 모드는 여러 호출과 대상 전환 동안 세션을 유지합니다.
|
||||
|
||||
## CLI
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea --help
|
||||
npx -y @morluto/rea doctor --target /path/to/binary
|
||||
npx -y @morluto/rea analyze /path/to/binary
|
||||
npx -y @morluto/rea decompile /path/to/binary 0x100003f20
|
||||
```
|
||||
|
||||
전역 `rea` 명령으로 설치할 수도 있습니다.
|
||||
|
||||
```bash
|
||||
npm install --global @morluto/rea
|
||||
rea --help
|
||||
rea mcp
|
||||
```
|
||||
|
||||
## Hopper 앱 동작
|
||||
|
||||
REA는 필요할 때 Hopper를 시작합니다. Hopper 런처는 내부적으로 앱을 활성화하므로 대상을 열 때 Hopper가 다른 창 앞으로 나타날 수 있습니다. REA는 백그라운드 시작을 요청하지만 항상 뒤에 머무르는 것을 보장할 수 없습니다.
|
||||
|
||||
명시적인 형식과 아키텍처 인자로 일반적인 FAT/ARM 선택 대화상자를 피하지만, 다른 Hopper 또는 macOS 대화상자에는 사람이 응답해야 할 수 있습니다. 세션 종료 시 브리지와 소켓 디렉터리를 제거하지만 사용자가 작업 중인 Hopper 앱은 종료하지 않습니다.
|
||||
|
||||
## 보안 모델
|
||||
|
||||
각 세션은 무작위 capability token과 현재 사용자 전용 Unix 소켓을 사용합니다. 이는 샌드박스가 아니며 같은 사용자로 실행되는 악성 프로세스를 방어하지 않습니다. 신뢰할 수 없는 바이너리를 열면 현재 macOS 사용자 권한으로 Hopper가 분석합니다. 취약점은 [SECURITY.md](SECURITY.md)의 비공개 절차로 신고하세요.
|
||||
|
||||
## FAQ
|
||||
|
||||
<details><summary><strong>Hopper를 미리 실행해야 하나요?</strong></summary>
|
||||
|
||||
아니요. REA가 필요할 때 시작하며 이미 실행 중인 Hopper도 지원합니다.
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary><strong>REA에 Hopper가 포함되나요?</strong></summary>
|
||||
|
||||
아니요. Hopper는 별도로 설치하고 라이선스를 받아야 합니다. REA는 CLI, MCP, 세션 관리, 분석 워크플로 및 인증 브리지를 제공합니다.
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary><strong>바이너리가 업로드되나요?</strong></summary>
|
||||
|
||||
REA에는 호스팅 분석 서비스가 없습니다. 로컬 Unix 소켓을 통해 Hopper를 조작합니다. 에이전트나 모델 공급자의 데이터 정책은 별도로 확인하세요.
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary><strong>원본 소스 코드를 복구할 수 있나요?</strong></summary>
|
||||
|
||||
보장할 수 없습니다. REA는 의사 코드, 어셈블리, 심볼, 문자열, 메타데이터 및 관계를 제공하여 에이전트가 관찰된 동작을 설명하거나 호환되게 재현하도록 돕습니다.
|
||||
|
||||
</details>
|
||||
|
||||
## 개발
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run check
|
||||
npm run verify:package
|
||||
npm pack --dry-run
|
||||
```
|
||||
|
||||
실제 Hopper 검증에는 서로 다른 두 바이너리가 필요합니다.
|
||||
|
||||
```bash
|
||||
HOPPER_TARGET_PATH=/path/to/target-a \
|
||||
HOPPER_SECOND_TARGET_PATH=/path/to/distinct-target-b \
|
||||
npm run verify:hopper
|
||||
```
|
||||
|
||||
아키텍처 지침, Pull Request 요구 사항, 릴리스 체크리스트는 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요.
|
||||
|
||||
## 라이선스
|
||||
|
||||
[MIT](LICENSE)
|
||||
+230
@@ -0,0 +1,230 @@
|
||||
<div align="center">
|
||||
|
||||
[English](README.md) · **简体中文** · [日本語](README_ja.md) · [한국어](README_ko.md) · [العربية](README_ar.md)
|
||||
|
||||
# REA：逆向工程一切
|
||||
|
||||
### 一个 CLI 与 MCP 服务器，让编程智能体逆向工程任何程序
|
||||
|
||||
**看到喜欢的功能。理解它的原理。按照你的方式实现。**
|
||||
|
||||
[](https://www.npmjs.com/package/@morluto/rea)
|
||||
[](https://github.com/morluto/rea/actions/workflows/ci.yml)
|
||||
[](#42-个工具组成的工作台)
|
||||
[](https://nodejs.org/)
|
||||
[](LICENSE)
|
||||
|
||||
[快速开始](#快速开始) · [从二进制到行为](#从二进制到行为) · [42 个工具](#42-个工具组成的工作台) · [工作原理](#工作原理) · [常见问题](#常见问题)
|
||||
|
||||
<br />
|
||||
|
||||
<code>npx -y @morluto/rea setup --yes</code>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
看到某个应用中想加入自己产品的功能？即使没有源代码，也可以把应用交给编程智能体。借助 REA，智能体能够调查该功能、理解其工作原理，并按照你的技术栈、设计和需求构建适合你产品的版本。
|
||||
|
||||
REA 通过一个 CLI 与 MCP 服务器实现这套流程。智能体可以恢复伪代码、跨函数追踪行为、检查字符串和类型，并把证据直接带入日常编码工作。REA 将逆向工程工具链、分析会话和目标生命周期统一在一个接口背后。
|
||||
|
||||
## 从二进制到行为
|
||||
|
||||
| 反编译 | 理解 | 重建 |
|
||||
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
|
||||
| 打开原生应用或可执行文件，恢复过程、伪代码、汇编、字符串、符号、段和元数据。 | 沿调用者、被调用者、交叉引用和调用图追踪，直到智能体能够解释功能或算法的实际工作方式。 | 将智能体学到的内容变成适合你的技术栈、界面和需求的产品功能。 |
|
||||
|
||||
REA 让调查始终以二进制证据为依据。它不会声称能恢复原始源代码，也不会自动克隆整个应用。
|
||||
|
||||
## 为什么选择 REA
|
||||
|
||||
| | |
|
||||
| ---------------- | -------------------------------------------------------------- |
|
||||
| **为智能体设计** | 直接询问编译后应用的行为，让智能体搜集证据，而不是猜测。 |
|
||||
| **CLI 与 MCP** | 在终端或编程智能体中使用同一套逆向工程能力。 |
|
||||
| **处理复杂流程** | REA 负责工具设置、打开应用、维持调查过程，并在完成后清理资源。 |
|
||||
| **完整工作流** | 从初步概览推进到伪代码、调用关系、类型和实现线索。 |
|
||||
| **本地运行** | 分析在你的 Mac 上运行；REA 不会把二进制上传到托管式分析服务。 |
|
||||
| **保留上下文** | 连续调查多个二进制文件，无需为每个问题重新开始整个分析过程。 |
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 环境要求
|
||||
|
||||
- macOS 12 或更高版本
|
||||
- Node.js 22 或更高版本
|
||||
- [Hopper Disassembler](https://www.hopperapp.com/)
|
||||
|
||||
REA 不捆绑 Hopper。Setup 可以在需要时安装 Homebrew 和 `hopper-disassembler` cask，配置检测到的 Claude Desktop 与 Cursor MCP 客户端，并安装 REA 智能体技能。现有客户端配置会先备份，再原子写入并进行语义回读验证。
|
||||
|
||||
```bash
|
||||
# 1. 安装和配置
|
||||
npx -y @morluto/rea setup --yes
|
||||
|
||||
# 2. 检查集成
|
||||
npx -y @morluto/rea doctor
|
||||
|
||||
# 3. 启动 stdio MCP 服务器
|
||||
npx -y @morluto/rea mcp
|
||||
```
|
||||
|
||||
MCP 命令通过 stdio 通信，因此会静默等待客户端连接。如果 setup 已检测并配置你的客户端，请重启客户端并使用已注册的 `rea` 服务器。
|
||||
|
||||
然后可以这样询问智能体：
|
||||
|
||||
```text
|
||||
打开 /path/to/MyApp，概述该二进制文件，找到身份验证流程，
|
||||
反编译相关过程，并展示支持结论的证据。
|
||||
```
|
||||
|
||||
## 一个提示词，完成一次完整调查
|
||||
|
||||
```text
|
||||
打开 MyApp，找到离线搜索功能的工作方式，解释其控制流，
|
||||
并使用 TypeScript 和 SQLite 为我的项目构建一个版本。
|
||||
```
|
||||
|
||||
| 步骤 | 智能体的操作 | REA 工具 |
|
||||
| ---: | ---------------------- | ---------------------------------------------------------------- |
|
||||
| 1 | 打开并识别二进制文件 | `open_binary`, `binary_overview` |
|
||||
| 2 | 搜索可能的离线搜索线索 | `search_strings`, `search_procedures`, `list_names` |
|
||||
| 3 | 将线索连接到可执行代码 | `find_xrefs_to_name`, `xrefs`, `procedure_callers` |
|
||||
| 4 | 重建相关控制流 | `get_call_graph`, `procedure_callees`, `procedure_info` |
|
||||
| 5 | 恢复实现 | `procedure_pseudo_code`, `procedure_assembly`, `batch_decompile` |
|
||||
| 6 | 在你的项目中构建该功能 | 适合你的技术栈、产品和需求的代码 |
|
||||
|
||||
REA 负责第 1–5 步中的二进制分析。第 6 步由智能体使用其常规文件编辑与测试工具完成。
|
||||
|
||||
## 智能体可以完成什么
|
||||
|
||||
- 在没有源代码时解释某项功能的实现方式。
|
||||
- 重建应用的身份验证、存储、更新或网络流程。
|
||||
- 恢复足够的结构，以记录未公开的格式或接口。
|
||||
- 从字符串或符号追踪到实现可疑行为的代码。
|
||||
- 在一个会话中切换两个应用版本并比较实现路径。
|
||||
- 调查你喜欢的功能，并为自己的产品构建量身定制的版本。
|
||||
- 将恢复的行为转换为产品功能、测试、迁移说明、移植代码或互操作替代品。
|
||||
- 分析 Swift 和 Objective-C 元数据。
|
||||
- 在 Hopper 中留下名称、注释与书签，使人与智能体的分析互相增强。
|
||||
|
||||
## 42 个工具组成的工作台
|
||||
|
||||
| 工具类别 | 数量 | 示例 |
|
||||
| ---------- | ---: | ------------------------------------------------------------------------------------------------ |
|
||||
| 二进制检查 | 31 | 过程、伪代码、汇编、字符串、名称、段、调用者、被调用者、交叉引用、注释 |
|
||||
| 组合分析 | 8 | `binary_overview`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`、Swift 与 ObjC 发现 |
|
||||
| 二进制会话 | 3 | `open_binary`, `binary_session`, `close_binary` |
|
||||
|
||||
公开工具清单通过契约测试和隔离的打包 MCP 客户端验证。真实 Hopper 验证还会使用两个二进制文件检查同一套 42 工具接口。
|
||||
|
||||
## MCP 工作流
|
||||
|
||||
1. 使用 `open_binary` 打开可读的本地二进制文件或 `.hop` 路径。
|
||||
2. 从 `binary_overview` 开始，再通过字符串、符号、反编译、调用者、被调用者和交叉引用缩小范围。
|
||||
3. 再次调用 `open_binary` 切换目标；如果新目标失败，REA 会尝试重新打开之前的目标。
|
||||
4. 完成后调用 `close_binary`。`binary_session` 可随时报告当前状态。
|
||||
|
||||
REA 自动识别 Mach-O/FAT、ELF、PE 和 Hopper 数据库。相对路径以 MCP 服务器工作目录为基准；FAT 二进制会自动选择与宿主兼容的架构。
|
||||
|
||||
### 手动 MCP 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"rea": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@morluto/rea", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Agent["编程智能体"] -->|stdio MCP| REA["REA 服务器<br/>42 个工具"]
|
||||
REA --> Session["二进制会话<br/>打开 · 切换 · 关闭"]
|
||||
Session -->|认证 Unix 套接字| Bridge["Hopper 内部的<br/>REA Python 桥"]
|
||||
Bridge --> API["Hopper 公开<br/>Python API"]
|
||||
```
|
||||
|
||||
CLI 与 MCP 适配器直接调用同一套二进制会话和分析运行时，二者不会互相调用。一次性命令会为每次操作获取并关闭资源；MCP 模式则在多次调用和目标切换之间保持会话。
|
||||
|
||||
## CLI
|
||||
|
||||
```bash
|
||||
npx -y @morluto/rea --help
|
||||
npx -y @morluto/rea doctor --target /path/to/binary
|
||||
npx -y @morluto/rea analyze /path/to/binary
|
||||
npx -y @morluto/rea decompile /path/to/binary 0x100003f20
|
||||
```
|
||||
|
||||
也可以全局安装 `rea` 命令：
|
||||
|
||||
```bash
|
||||
npm install --global @morluto/rea
|
||||
rea --help
|
||||
rea mcp
|
||||
```
|
||||
|
||||
## Hopper 应用行为
|
||||
|
||||
REA 会在需要时启动 Hopper，无需预先运行。Hopper 启动器内部会激活应用，因此打开目标时 Hopper 可能出现在其他窗口前。REA 会请求 macOS 在后台启动 Hopper，但无法保证窗口始终位于后台。
|
||||
|
||||
REA 会推导明确的格式和架构参数，以避免常见的 FAT 与 ARM 选择对话框。其他 Hopper 或 macOS 对话框仍可能需要人工响应。关闭 REA 会话会终止桥并删除私有套接字目录，但不会退出用户正在使用的 Hopper 应用。
|
||||
|
||||
## 安全模型
|
||||
|
||||
每个桥会话都使用随机能力令牌和仅限当前用户的 Unix 套接字。协议消息有大小限制，面向调用者的错误不会暴露启动器 stderr 或内部异常原因。
|
||||
|
||||
这不是沙箱，也无法防御以同一 macOS 用户身份运行的恶意进程。打开不可信二进制文件会让 Hopper 以当前用户权限进行解析和分析。请按照 [SECURITY.md](SECURITY.md) 中的私密流程报告漏洞。
|
||||
|
||||
## 常见问题
|
||||
|
||||
<details><summary><strong>Hopper 是否需要提前运行？</strong></summary>
|
||||
|
||||
不需要。REA 会在操作需要时启动 Hopper，也支持已经运行的 Hopper。
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary><strong>REA 是否包含 Hopper？</strong></summary>
|
||||
|
||||
不包含。Hopper 是独立安装和授权的软件。REA 提供 CLI、MCP 服务器、会话管理、分析工作流和认证桥。
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary><strong>REA 会上传我的二进制文件吗？</strong></summary>
|
||||
|
||||
REA 不提供托管分析服务，而是通过本地 Unix 套接字把操作交给 Hopper。你的智能体或模型服务商可能有自己的数据政策，请单独核查。
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary><strong>REA 能恢复原始源代码吗？</strong></summary>
|
||||
|
||||
不能保证。REA 提供伪代码、汇编、符号、字符串、元数据和关系，智能体可据此解释或兼容地重建观察到的行为。
|
||||
|
||||
</details>
|
||||
|
||||
## 开发
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run check
|
||||
npm run verify:package
|
||||
npm pack --dry-run
|
||||
```
|
||||
|
||||
真实 Hopper 验证需要两个不同的二进制文件：
|
||||
|
||||
```bash
|
||||
HOPPER_TARGET_PATH=/path/to/target-a \
|
||||
HOPPER_SECOND_TARGET_PATH=/path/to/distinct-target-b \
|
||||
npm run verify:hopper
|
||||
```
|
||||
|
||||
架构规范、Pull Request 要求与维护者发布清单请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||||
|
||||
## 许可证
|
||||
|
||||
[MIT](LICENSE)
|
||||
Reference in new issue
Block a user