rea-agents 6.2.0 → 6.4.0

package/bridge/ghidra/ReaGhidraNoReturnFix.java

@@ -0,0 +1,123 @@
+import ghidra.app.cmd.function.CreateFunctionCmd;
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.*;
+import ghidra.program.model.symbol.FlowType;
+import ghidra.program.model.symbol.Reference;
+import ghidra.program.model.pcode.PcodeOp;
+import java.util.ArrayDeque;
+import java.util.Deque;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.TreeSet;
+
+/**
+ * Undo wrong no-return flags from auto-analysis. A function flagged no-return that contains a
+ * real RET is an ordinary function (stream readers, cxa_guard_acquire, ...). Known returning
+ * libc/TLS imports have no body to inspect, so clear their flags by exact external ABI name.
+ * Callers treated the call as a terminator and the decompiler truncated them. Clear the flag, then re-disassemble only
+ * the call sites of the functions that were cleared and refit their owning functions in place.
+ */
+public final class ReaGhidraNoReturnFix extends GhidraScript {
+  private static final Set<String> RETURNING_IMPORTS = Set.of(
+      "malloc", "__tls_get_addr", "memcpy", "memset", "strlen", "__errno_location");
+
+  @Override
+  public void run() throws Exception {
+    // Windows P0 does not admit analysis-database mutation.
+    if (System.getProperty("os.name", "").startsWith("Windows")) return;
+    FunctionManager fm = currentProgram.getFunctionManager();
+    Listing li = currentProgram.getListing();
+    Set<Address> cleared = new HashSet<>();
+    Deque<Address> pending = new ArrayDeque<>();
+    for (Function f : fm.getExternalFunctions()) {
+      monitor.checkCancelled();
+      // Do not apply import-name assumptions to local functions or to arbitrary externals.
+      if (!f.hasNoReturn() || !RETURNING_IMPORTS.contains(externalAbiName(f))) continue;
+      f.setNoReturn(false);
+      enqueueReturning(f, cleared, pending);
+    }
+    for (Function f : fm.getFunctions(true)) {
+      monitor.checkCancelled();
+      if (clearDecodedReturn(f, li)) {
+        enqueueReturning(f, cleared, pending);
+      }
+    }
+    int redone = 0;
+    TreeSet<Address> owners = new TreeSet<>();
+    while (!pending.isEmpty()) {
+      Address target = pending.removeFirst();
+      TreeSet<Address> sites = new TreeSet<>();
+      // References include computed import calls after Ghidra resolves their destination.
+      // Collect before redisassembly mutates the reference table.
+      for (Reference reference : currentProgram.getReferenceManager().getReferencesTo(target)) {
+        monitor.checkCancelled();
+        sites.add(reference.getFromAddress());
+      }
+      for (Address s : sites) {
+        monitor.checkCancelled();
+        Instruction ins = li.getInstructionAt(s);
+        if (ins == null) continue;
+        FlowType ft = ins.getFlowType();
+        if (!(ft.isCall() && ft.isTerminal())) continue;
+        Address[] flows = ins.getFlows();
+        boolean callsTarget = false;
+        for (Address flow : flows) {
+          if (flow.equals(target)) callsTarget = true;
+        }
+        if (!callsTarget) continue;
+        // Do not redisassemble into an independently identified function.
+        Address next = ins.getMaxAddress().add(1);
+        if (fm.getFunctionAt(next) != null || !currentProgram.getMemory().contains(next)) continue;
+        Function owner = fm.getFunctionContaining(s);
+        if (owner != null && !owner.isThunk()) owners.add(owner.getEntryPoint());
+        clearListing(ins.getMinAddress(), ins.getMaxAddress());
+        disassemble(s);
+        redone++;
+        // Refit the body in place so the name, signature and calling convention survive.
+        if (owner != null && !owner.isThunk()) {
+          CreateFunctionCmd.fixupFunctionBody(currentProgram, owner, monitor);
+          // Auto-analysis may have propagated the false flag to this truncated caller.
+          // Its RET becomes visible only now; repair its callers in the same pass.
+          if (clearDecodedReturn(owner, li)) enqueueReturning(owner, cleared, pending);
+        }
+      }
+    }
+    // No analyzeChanges here: on libpl2.so it adds about 70 s, which pushes startup past the 330 s deadline.
+    println(
+        "REA no-return fix: cleared=" + cleared.size() + " sites=" + redone + " refit=" + owners.size());
+  }
+
+  private void enqueueReturning(Function function, Set<Address> cleared, Deque<Address> pending) {
+    if (cleared.add(function.getEntryPoint())) pending.addLast(function.getEntryPoint());
+    // A thunk inherits the flag of the function it forwards to, including through other thunks.
+    Address[] thunks = function.getFunctionThunkAddresses(true);
+    if (thunks == null) return;
+    for (Address thunk : thunks) {
+      if (cleared.add(thunk)) pending.addLast(thunk);
+    }
+  }
+
+  private String externalAbiName(Function function) {
+    String name = function.getName();
+    // Mach-O stores C-linkage symbols with one object-format underscore prefix.
+    if (currentProgram.getExecutableFormat().contains("Mach-O") && name.startsWith("_"))
+      return name.substring(1);
+    return name;
+  }
+
+  private boolean clearDecodedReturn(Function function, Listing listing) throws Exception {
+    if (!function.hasNoReturn() || function.isThunk()) return false;
+    for (Instruction instruction : listing.getInstructions(function.getBody(), true)) {
+      monitor.checkCancelled();
+      FlowType flow = instruction.getFlowType();
+      if (flow.isJump() || flow.isCall()) continue;
+      for (PcodeOp operation : instruction.getPcode()) {
+        if (operation.getOpcode() != PcodeOp.RETURN) continue;
+        function.setNoReturn(false);
+        return true;
+      }
+    }
+    return false;
+  }
+}

package/bridge/hopper_bridge.py

@@ -716,6 +716,8 @@ def _analyze_function(document, params):
         "referenced_strings": referenced_strings,
         "referenced_names": referenced_names,
         "basic_blocks": blocks,
+        "native_api": None,
+        "native_value_flow": None,
         "limitations": [
             "Native CallReference classifications are observed where available; detailed reference flags remain unknown.",
             "Hopper's public Python API does not expose equivalent external or thunk classification in this dossier.",

package/dist/adb/AdbConfiguration.js

@@ -0,0 +1,88 @@
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { isAbsolute } from "node:path";
+import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+/** Environment key selecting the caller's adb binary. */
+export const ADB_BINARY_ENV = "REA_ADB_PATH";
+const VERSION_TIMEOUT_MS = 10_000;
+const VERSION_MAX_OUTPUT_BYTES = 64 * 1024;
+/**
+ * Resolve the caller-supplied adb binary. `REA_ADB_PATH` must be absolute so
+ * the selection stays explicit; without it, adb is resolved from `PATH` by
+ * the platform exec at run time, like any bring-your-own tool.
+ */
+export const resolveAdbBinary = (environment) => {
+    const configured = environment[ADB_BINARY_ENV];
+    if (configured === undefined || configured.trim() === "")
+        return { binary: "adb", pathSource: "path" };
+    if (!isAbsolute(configured))
+        throw new AdbConfigurationFailure("not_absolute", `${ADB_BINARY_ENV} must be an absolute path to the adb binary`, { configured_path: configured });
+    return { binary: configured, pathSource: "environment" };
+};
+export class AdbConfigurationFailure extends Error {
+    code;
+    diagnostics;
+    constructor(code, message, diagnostics = {}, options) {
+        super(message, options);
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}
+/**
+ * Parse `adb version` output. The first line carries the protocol version,
+ * `Version ` the build version (no colon), and `Installed as` the binary path.
+ */
+export const parseAdbVersionOutput = (stdout) => {
+    const build = /^Version\s+(\S.*)$/mu.exec(stdout);
+    const installed = /^Installed as\s+(.+)$/mu.exec(stdout);
+    return {
+        version: build === null ? null : build[1].trim(),
+        installedPath: installed === null ? null : installed[1].trim(),
+    };
+};
+/**
+ * Probe the selected adb binary without contacting devices. `adb version`
+ * never starts the adb server, so this stays a pure client check.
+ */
+export const inspectAdbClient = async (selection, signal) => {
+    try {
+        const { stdout } = await execFileOutput(selection.binary, ["version"], {
+            timeout: VERSION_TIMEOUT_MS,
+            stopSignal: "SIGTERM",
+            maxBuffer: VERSION_MAX_OUTPUT_BYTES,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        return parseAdbVersionOutput(stdout);
+    }
+    catch (cause) {
+        const failure = execFileOutputFailure(cause);
+        if (signal?.aborted || failure?.code === "ABORT_ERR")
+            throw new AnalysisCancelledError("inspect_adb_client", { cause });
+        if (failure?.code === "ENOENT")
+            throw new AdbConfigurationFailure("binary_missing", `The selected adb binary was not found: ${selection.binary}`, {
+                selected_binary: selection.binary,
+                path_source: selection.pathSource,
+                remediation: `Set ${ADB_BINARY_ENV} to an absolute path to an existing adb binary`,
+            }, { cause });
+        throw new AdbConfigurationFailure("version_unresolved", "The selected adb binary did not report a usable version", {
+            selected_binary: selection.binary,
+            ...(failure === undefined
+                ? {}
+                : {
+                    exit_code: failure.code,
+                    stderr_excerpt: failure.stderr.slice(0, 512),
+                }),
+        }, { cause });
+    }
+};
+/** Availability in the shape shared by every provider. */
+const rejectionCodeOf = (code) => code === "binary_missing"
+    ? "executable_missing"
+    : code === "not_absolute"
+        ? "not_configured"
+        : "version_unresolved";
+export const adbConfigurationAvailability = (cause) => ({
+    status: "unavailable",
+    code: rejectionCodeOf(cause.code),
+    reason: cause.message,
+    diagnostics: { ...cause.diagnostics },
+});

package/dist/adb/AdbDeviceOutput.js

@@ -0,0 +1,186 @@
+/**
+ * Parsers for the exact adb and Package Manager output formats REA consumes.
+ *
+ * Each parser preserves what the tool actually printed: unparseable lines are
+ * retained rather than silently dropped, and derived classifications carry
+ * their evidence basis.
+ */
+/**
+ * Device states adb prints after the serial, longest first so two-word
+ * states match before their single-word prefixes. A line whose remainder
+ * starts with none of them is not a device line.
+ */
+const DEVICE_STATES = [
+    "no permissions",
+    "unauthorized",
+    "authorizing",
+    "offline",
+    "recovery",
+    "sideload",
+    "connecting",
+    "bootloader",
+    "device",
+    "unknown",
+    "host",
+];
+const DEVICE_LINE = /^(\S+)\s+(.*)$/u;
+const metadataValue = (remainder, key) => {
+    const match = new RegExp(`(?:^|\\s)${key}:(\\S+)`, "u").exec(remainder);
+    return match === null ? null : match[1];
+};
+/**
+ * Parse `adb devices -l` device lines. The banner, blank lines, and the
+ * daemon startup notices adb prints on first use are recognized separately;
+ * every other unrecognized line is returned for honest reporting.
+ */
+export const parseAdbDevicesOutput = (stdout) => {
+    const devices = [];
+    const unparsedLines = [];
+    let daemonStarted = false;
+    for (const rawLine of stdout.split(/\r?\n/u)) {
+        const line = rawLine.trimEnd();
+        if (line === "" || line.startsWith("List of devices attached"))
+            continue;
+        if (line.startsWith("* daemon")) {
+            if (line.includes("started successfully"))
+                daemonStarted = true;
+            continue;
+        }
+        const match = DEVICE_LINE.exec(line);
+        const state = DEVICE_STATES.find((candidate) => match?.[2]?.startsWith(candidate));
+        if (match === null || state === undefined) {
+            if (line.trim() !== "")
+                unparsedLines.push(line);
+            continue;
+        }
+        const serial = match[1];
+        const remainder = match[2].slice(state.length);
+        const usb = metadataValue(remainder, "usb");
+        const transportIdText = metadataValue(remainder, "transport_id");
+        const parsedTransportId = transportIdText === null || !/^\d+$/u.test(transportIdText)
+            ? null
+            : Number(transportIdText);
+        const isEmulator = /^emulator-\d+$/u.test(serial);
+        const kind = isEmulator
+            ? "emulator"
+            : usb !== null
+                ? "physical"
+                : "unknown";
+        devices.push({
+            serial,
+            state,
+            transport: usb !== null
+                ? "usb"
+                : isEmulator || serial.includes(":")
+                    ? "tcp"
+                    : "unknown",
+            product: metadataValue(remainder, "product"),
+            model: metadataValue(remainder, "model"),
+            device: metadataValue(remainder, "device"),
+            transport_id: parsedTransportId,
+            kind,
+            kind_basis: kind === "emulator"
+                ? "emulator_serial_prefix"
+                : kind === "physical"
+                    ? "usb_transport"
+                    : "none",
+        });
+    }
+    return { devices, unparsedLines, daemonStarted };
+};
+/**
+ * Properties projected from a `getprop` dump. The whitelist keeps device
+ * inspection to build identity facts; a full dump is out of scope.
+ */
+const DEVICE_PROPERTY_WHITELIST = [
+    "ro.build.version.release",
+    "ro.build.version.sdk",
+    "ro.build.version.security_patch",
+    "ro.build.id",
+    "ro.build.fingerprint",
+    "ro.build.characteristics",
+    "ro.debuggable",
+    "ro.kernel.qemu",
+    "ro.product.brand",
+    "ro.product.device",
+    "ro.product.manufacturer",
+    "ro.product.model",
+    "ro.product.cpu.abilist",
+];
+/** Parse a full `getprop` dump into `[name]: [value]` pairs. */
+export const parseGetpropOutput = (stdout) => {
+    const values = new Map();
+    for (const rawLine of stdout.split(/\r?\n/u)) {
+        const match = /^\[([^\]]+)\]:\s*\[(.*)\]$/u.exec(rawLine.trim());
+        if (match === null)
+            continue;
+        values.set(match[1], match[2]);
+    }
+    const properties = DEVICE_PROPERTY_WHITELIST.flatMap((name) => {
+        const value = values.get(name);
+        return value === undefined || value === ""
+            ? []
+            : [{ name, value }];
+    });
+    const qemu = values.get("ro.kernel.qemu");
+    return {
+        properties,
+        emulatorObserved: qemu === undefined ? null : qemu === "1",
+    };
+};
+const PACKAGE_LINE = /^package:(.+)=([^\s=]+)$/u;
+/** Parse `pm list packages -f` lines, retaining unrecognized lines. */
+export const parsePackageListOutput = (stdout) => {
+    const packages = [];
+    const unparsedLines = [];
+    for (const rawLine of stdout.split(/\r?\n/u)) {
+        const line = rawLine.trim();
+        if (line === "")
+            continue;
+        const match = PACKAGE_LINE.exec(line);
+        if (match === null) {
+            unparsedLines.push(line);
+            continue;
+        }
+        packages.push({
+            package_name: match[2],
+            base_apk_device_path: match[1],
+        });
+    }
+    return { packages, unparsedLines };
+};
+const fileNameOf = (devicePath) => {
+    const parts = devicePath.split(/\//u);
+    return parts[parts.length - 1] ?? devicePath;
+};
+/**
+ * Parse `pm path PACKAGE` lines. The base/split role is derived from the file
+ * name (`base.apk`, `split_*.apk`), which is the only signal the output
+ * carries; any other name reports an unknown role.
+ */
+export const parsePmPathOutput = (stdout) => {
+    const paths = [];
+    const unparsedLines = [];
+    for (const rawLine of stdout.split(/\r?\n/u)) {
+        const line = rawLine.trim();
+        if (line === "")
+            continue;
+        const match = /^package:(\S+)$/u.exec(line);
+        if (match === null) {
+            unparsedLines.push(line);
+            continue;
+        }
+        const devicePath = match[1];
+        const fileName = fileNameOf(devicePath);
+        paths.push({
+            device_path: devicePath,
+            file_name: fileName,
+            role: fileName === "base.apk"
+                ? "base"
+                : fileName.startsWith("split_") && fileName.endsWith(".apk")
+                    ? "split"
+                    : "unknown",
+        });
+    }
+    return { paths, unparsedLines };
+};