rea-agents 6.2.0 → 6.4.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-**English** · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md)
+**English** · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
 
 # REA: Reverse Engineer Anything
 
@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#what-you-can-analyze)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA launching its analysis bridge inside Hopper while inspecting a native binary" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="REA community">
 <tr>
@@ -52,7 +52,7 @@ See a feature in an app that you want in your own product? Ask your agent to inv
 
 REA connects your agent to tools for inspecting native binaries, JavaScript and Electron apps, .NET assemblies, and websites. You can also use the same tools from your terminal. Analysis runs locally, and results include the evidence and limitations behind each conclusion.
 
-Setup registers REA with your agent and installs matching workflow instructions. Native analysis can use an existing Hopper or Ghidra installation; setup can optionally install Hopper with approval. Static JavaScript analysis needs neither engine.
+Setup registers REA with your agent and installs matching workflow instructions. Native analysis can use an existing Hopper, Ghidra, or IDA installation; setup can optionally install Hopper with approval. Static JavaScript analysis needs no native analysis engine.
 
 > **[Visit the REA website](https://rea.tools/)** for setup instructions, illustrated guides, and real case studies.
 
@@ -151,13 +151,16 @@ Additional tools and host support depend on the target:
 | ---------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
 | Native binaries        | Pseudocode, assembly, strings, symbols, calls and references                         | Hopper, Ghidra or IDA; [native analysis](https://rea.tools/guides/native/)                                                            |
 | Offline ELF layout     | Sections, segments, original symbols/relocations and static mitigation candidates    | Caller-supplied pwntools on Linux x64; [binary diagnostics](docs/binary-diagnostics.md)                                               |
-| EVM bytecode           | Dispatch selectors, byte offsets, inferred arguments and mutability                  | Local raw/hex carrier; [offline EVM guide](docs/evm-bytecode.md)                                                                      |
-| Recorded Linux crashes | Raw notes, every recorded thread's registers/signals and optional mapping candidates | Caller-supplied pwntools; optional GDB/pwndbg; [recorded crashes](docs/recorded-crashes.md)                                           |
+| EVM bytecode           | Dispatch selectors, byte offsets, inferred arguments and mutability                  | Local raw/hex carrier on Linux x64; [offline EVM guide](docs/evm-bytecode.md)                                                         |
+| Recorded Linux crashes | Raw notes, every recorded thread's registers/signals and optional mapping candidates | Caller-supplied pwntools on Linux x64; optional GDB/pwndbg; [recorded crashes](docs/recorded-crashes.md)                              |
 | JavaScript / Electron  | Modules, imports, source maps, routes, IPC and native add-on relationships           | Node.js and npm; [application analysis](https://rea.tools/guides/javascript/)                                                         |
 | Websites               | Page structure, scripts, network observations and requested screenshots              | A Chrome-family browser; [browser analysis](https://rea.tools/guides/browser/)                                                        |
 | Saved network captures | Requests, responses, exposed payloads and source locations                           | HAR; mitmdump on Linux for native mitmproxy captures; [capture guide](docs/web-network-captures.md)                                   |
-| .NET assemblies        | Metadata, CIL instructions, declared native dependencies and build comparisons       | Static inspection; [managed-code guide](docs/managed-code-analysis.md)                                                                |
+| .NET assemblies        | Metadata, CIL instructions, declared native dependencies and build comparisons       | None (static only); [managed-code guide](docs/managed-code-analysis.md)                                                               |
 | Android APKs           | Manifest declarations, classes, decompiled methods and references                    | Headless JADX and a full JDK on Linux/macOS/Windows x64; [Android guide](docs/android-analysis.md)                                    |
+| Android devices        | Devices, packages, processes, logs, dumps, screen captures, and APK/file transfers   | Caller-supplied adb (emulator or hardware); [ADB guide](docs/adb-device-analysis.md)                                                  |
+| JEB projects           | Engine-backed project units, artifact digests and type/method pseudo-code            | A caller-started JEB client serving MCP, selected with REA_JEB_MCP_URL; [JEB guide](docs/jeb-analysis.md)                             |
+| Android resources      | Decoded manifest, string tables, locales and version facts                           | Caller-supplied Apktool launcher; [resource guide](docs/apktool-resource-analysis.md)                                                 |
 | Firmware               | Regions, extraction results and native-analysis handoffs                             | Binwalk / Unblob on Linux; [firmware guide](docs/firmware-analysis.md)                                                                |
 | Packages and resources | File inventories, digests, plists, Apple bundle anatomy and extracted resources      | [Artifact and JavaScript guide](docs/javascript-artifact-reconstruction.md), [Apple applications](docs/apple-application-analysis.md) |
 | Process behavior       | Terminal output, interactions, exit and filesystem observations, and run comparisons | Linux/macOS with a native PTY; [process capture](docs/process-capture.md)                                                             |
@@ -181,6 +184,8 @@ for features added since the latest npm release.
 
 ## Showcases
 
+[![Illustrations of the DX-Ball sound-pan, Notion clipboard-bridge, and TH04 bullet-ring showcases](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: reconstruct a sound-pan calculation
 
 Follow a sound call into its position-to-pan helper, inspect the instructions,
@@ -243,7 +248,7 @@ ask you to choose demo mode or activate your license. See
 <details>
 <summary><strong>What does installing the skill from skills.sh do?</strong></summary>
 
-The skill supplies investigation instructions for your agent. Use `rea setup`
+The skill supplies investigation instructions for your agent. Use `npx rea-agents setup`
 to register REA's MCP server and install the matching instructions, then restart
 your agent. See [skill-only installation](docs/installation.md#skill-only-installation).
 
@@ -303,23 +308,9 @@ For exact options, prerequisites and result contracts:
 
 Report vulnerabilities through [SECURITY.md](SECURITY.md).
 
-## Contributing
-
-We'd love your help with REA! [Open an issue](https://github.com/morluto/rea/issues) to
-report a bug or suggest a feature, or [send a pull request](https://github.com/morluto/rea/pulls)
-to improve the code or docs.
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks,
-[testing](docs/testing.md) for verification lanes, and the
-[architecture map](docs/architecture.mermaid) for the project structure.
-
-## Project links
-
-[Website](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [Security](SECURITY.md)
-
 ## Star history
 
-🎉 **30,000 GitHub stars — thank you!**
+🎉 **60,000 GitHub stars — thank you!**
 
 Thanks to everyone using REA, reporting bugs, requesting features, testing builds, and contributing fixes.
 
@@ -337,6 +328,16 @@ REA provides tools for lawful reverse-engineering research, analysis, and recons
 
 REA is an open-source software project. We have not issued or endorsed any cryptocurrency or token. Tokens using the REA name are not affiliated with the project.
 
+## Contributing
+
+We'd love your help with REA! [Open an issue](https://github.com/morluto/rea/issues) to
+report a bug or suggest a feature, or [send a pull request](https://github.com/morluto/rea/pulls)
+to improve the code or docs.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks,
+[testing](docs/testing.md) for verification lanes, and the
+[architecture map](docs/architecture.mermaid) for the project structure.
+
 ## License
 
 [MIT](LICENSE)

package/bridge/ghidra/ReaGhidraApplySeeds.java

@@ -0,0 +1,151 @@
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.address.AddressSpace;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.Program;
+import ghidra.program.model.mem.MemoryBlock;
+import ghidra.program.model.symbol.SourceType;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.LinkOption;
+import java.nio.file.Path;
+import java.security.MessageDigest;
+import java.util.ArrayList;
+import java.util.HexFormat;
+import java.util.List;
+
+/**
+ * Apply caller-declared analysis seeds before default auto-analysis.
+ *
+ * The single argument is REA's canonical seed snapshot: one
+ * {@code 0x<hex>\t(function|code|label)[\tname]} line per seed. Code seeds are
+ * applied after functions (highest address first), then labels. The outcome is stored as a
+ * program property that the bridge reports during its handshake.
+ */
+public final class ReaGhidraApplySeeds extends GhidraScript {
+    static final String REPORT_OPTION = "REA analysis seeds";
+
+    private record Seed(Address address, String kind, String name) {}
+
+    @Override
+    public void run() throws Exception {
+        String[] args = getScriptArgs();
+        if (args.length != 1) {
+            throw new IllegalArgumentException("REA seed script requires exactly one seed file");
+        }
+        Path path = Path.of(args[0]);
+        if (!Files.isRegularFile(path, LinkOption.NOFOLLOW_LINKS)) {
+            throw new IllegalArgumentException("REA seed file is not a regular file");
+        }
+        byte[] bytes = Files.readAllBytes(path);
+        String sha256 = HexFormat.of().formatHex(
+            MessageDigest.getInstance("SHA-256").digest(bytes)
+        );
+        AddressSpace space = currentProgram.getAddressFactory().getDefaultAddressSpace();
+        List<Seed> seeds = new ArrayList<>();
+        for (String line : new String(bytes, StandardCharsets.UTF_8).split("\n")) {
+            if (line.isEmpty()) continue;
+            String[] fields = line.split("\t", -1);
+            if (fields.length < 2 || fields.length > 3 || !fields[0].startsWith("0x")) {
+                throw new IllegalArgumentException("REA seed snapshot is malformed");
+            }
+            Address address;
+            try {
+                address = space.getAddress(Long.parseUnsignedLong(fields[0].substring(2), 16));
+            } catch (ghidra.program.model.address.AddressOutOfBoundsException e) {
+                address = null;
+            }
+            seeds.add(new Seed(address, fields[1], fields.length == 3 ? fields[2] : null));
+        }
+
+        // Highest address first: a function body computed before analysis stops at
+        // an existing function entry, so later creations cannot swallow earlier ones.
+        seeds.sort((left, right) -> {
+            if (left.address() == null) return right.address() == null ? 0 : 1;
+            if (right.address() == null) return -1;
+            return right.address().compareTo(left.address());
+        });
+        int unmapped = 0;
+        int logged = 0;
+        int codeDecoded = 0, codeFailed = 0;
+        int functionCreated = 0, functionExisting = 0, functionFailed = 0;
+        int labelApplied = 0, labelFailed = 0;
+        for (String pass : new String[] { "function", "code", "label" }) {
+            for (Seed seed : seeds) {
+                if (!seed.kind().equals(pass)) continue;
+                monitor.checkCancelled();
+                MemoryBlock block = seed.address() == null
+                    ? null
+                    : currentProgram.getMemory().getBlock(seed.address());
+                if (block == null || (!pass.equals("label") && !block.isInitialized())) {
+                    unmapped++;
+                    continue;
+                }
+                switch (pass) {
+                    case "code" -> {
+                        if (decoded(seed.address())) codeDecoded++;
+                        else {
+                            codeFailed++;
+                            if (logged++ < 20) println("REA seed failed: code " + seed.address() + " " + why(seed.address()));
+                        }
+                    }
+                    case "function" -> {
+                        Function existing = getFunctionAt(seed.address());
+                        if (existing != null) {
+                            functionExisting++;
+                            if (seed.name() != null) {
+                                existing.setName(seed.name(), SourceType.USER_DEFINED);
+                            }
+                        } else if (decoded(seed.address()) &&
+                            createFunction(seed.address(), seed.name()) != null) {
+                            functionCreated++;
+                        } else {
+                            functionFailed++;
+                            if (logged++ < 20) println("REA seed failed: function " + seed.address() + " " + why(seed.address()));
+                        }
+                    }
+                    default -> {
+                        try {
+                            createLabel(seed.address(), seed.name(), true, SourceType.USER_DEFINED);
+                            labelApplied++;
+                        } catch (Exception e) {
+                            labelFailed++;
+                        }
+                    }
+                }
+            }
+        }
+        String report = "{\"format\":\"rea-ghidra-seeds-v1\",\"sha256\":\"" + sha256 + "\"" +
+            ",\"entries\":" + seeds.size() +
+            ",\"function_created\":" + functionCreated +
+            ",\"function_existing\":" + functionExisting +
+            ",\"function_failed\":" + functionFailed +
+            ",\"code_decoded\":" + codeDecoded +
+            ",\"code_failed\":" + codeFailed +
+            ",\"label_applied\":" + labelApplied +
+            ",\"label_failed\":" + labelFailed +
+            ",\"unmapped\":" + unmapped + "}";
+        currentProgram.getOptions(Program.PROGRAM_INFO).setString(REPORT_OPTION, report);
+        println("REA seeds applied: " + report);
+    }
+
+    private String why(Address address) {
+        if (getDataAt(address) != null) return "defined data " + getDataAt(address).getDataType().getName();
+        var containing = getInstructionContaining(address);
+        if (containing != null && !containing.getAddress().equals(address))
+            return "inside instruction at " + containing.getAddress();
+        Function owner = getFunctionContaining(address);
+        if (owner != null) return "inside function " + owner.getEntryPoint();
+        return getInstructionAt(address) == null ? "undecodable" : "function creation refused";
+    }
+
+    /** Decode one instruction flow at an address, keeping an existing decode. */
+    private boolean decoded(Address address) {
+        if (getInstructionAt(address) != null) return true;
+        if (getDataAt(address) != null || getInstructionContaining(address) != null) {
+            return false;
+        }
+        disassemble(address);
+        return getInstructionAt(address) != null;
+    }
+}