rea-agents 4.0.1 → 5.0.0

package/dist/ida/IdaMcpConnection.js

@@ -0,0 +1,111 @@
+import { Client, StreamableHTTPClientTransport, } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
+const toolResultSchema = z.object({
+    isError: z.boolean().optional(),
+    structuredContent: z.record(z.string(), z.unknown()).optional(),
+    content: z.array(z.object({ type: z.string(), text: z.string().optional() }).passthrough()),
+    _meta: z
+        .object({
+        ida_mcp: z
+            .object({
+            output_truncated: z.boolean().optional(),
+            download_hint: z.string().optional(),
+        })
+            .passthrough()
+            .optional(),
+    })
+        .passthrough()
+        .optional(),
+});
+/** Decode Python FastMCP's scalar wrapper without dropping structured dictionaries. */
+export const decodeIdaToolResult = (input) => {
+    const result = toolResultSchema.parse(input);
+    const blocks = result.content.flatMap((block) => block.type === "text" && block.text !== undefined ? [block.text] : []);
+    if (result.isError === true)
+        throw new AnalysisProtocolError(`IDA MCP tool failed: ${blocks.join("\n")}`);
+    if (result._meta?.ida_mcp?.output_truncated === true)
+        throw new AnalysisProtocolError(`IDA MCP truncated its output; the preview cannot establish a complete observation. ${result._meta.ida_mcp.download_hint ?? "Use the upstream output download workflow to retrieve the full result."}`);
+    if (result.structuredContent !== undefined) {
+        const value = result.structuredContent;
+        return jsonValueSchema.parse(Object.keys(value).length === 1 && "result" in value
+            ? value.result
+            : value);
+    }
+    if (blocks.length !== 1)
+        throw new AnalysisProtocolError("IDA MCP omitted a single structured or text result; unsupported content cannot establish an empty observation.");
+    const values = blocks.map((text) => {
+        try {
+            return jsonValueSchema.parse(JSON.parse(text));
+        }
+        catch {
+            return text;
+        }
+    });
+    return values[0] ?? null;
+};
+/** Redact configured transport authentication values from SDK diagnostics only. */
+export const redactIdaTransportFailure = (cause, config) => {
+    let message = cause instanceof Error
+        ? cause.message
+        : "Unknown IDA MCP transport failure";
+    if ("headers" in config) {
+        for (const [name, value] of Object.entries(config.headers)) {
+            if (!/^(?:authorization|proxy-authorization|cookie)$/iu.test(name))
+                continue;
+            const credential = value.match(/^(?:Bearer|Basic)\s+([\s\S]+)$/iu)?.[1];
+            for (const secret of [value, credential])
+                if (secret !== undefined && secret.length > 0)
+                    message = message
+                        .split(secret)
+                        .join("[redacted transport credential]");
+        }
+    }
+    return new Error(message, { cause });
+};
+/** Create a standard SDK connection to an existing upstream registration. */
+export const createIdaMcpConnection = (config) => {
+    const client = new Client({ name: "rea-ida-provider", version: "1" });
+    const transportFailure = (cause) => {
+        throw redactIdaTransportFailure(cause, config);
+    };
+    const transport = "command" in config
+        ? new StdioClientTransport({
+            command: config.command,
+            args: config.args,
+            env: {
+                ...Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined)),
+                IDA_MCP_MAX_WORKERS: "1",
+                ...config.env,
+            },
+            stderr: "pipe",
+        })
+        : new StreamableHTTPClientTransport(new URL(config.url), {
+            requestInit: { headers: config.headers, redirect: "error" },
+        });
+    // Drain proxy diagnostics without persisting ambient environment or transport credentials.
+    if (transport instanceof StdioClientTransport)
+        transport.stderr?.on("data", () => undefined);
+    return {
+        async connect() {
+            await client
+                .connect(transport, { timeout: config.timeoutMs })
+                .catch(transportFailure);
+            const catalog = await client
+                .listTools(undefined, {
+                timeout: config.timeoutMs,
+            })
+                .catch(transportFailure);
+            return catalog.tools.map(({ name }) => name);
+        },
+        async call(name, args) {
+            return decodeIdaToolResult(await client
+                .callTool({ name, arguments: args }, { timeout: config.timeoutMs })
+                .catch(transportFailure));
+        },
+        serverInfo: () => jsonValueSchema.parse(client.getServerVersion() ?? null),
+        close: () => client.close().catch(transportFailure),
+    };
+};

package/dist/ida/IdaOperationRunner.js

@@ -0,0 +1,299 @@
+import { z } from "zod";
+import { analysisSearchInput } from "../contracts/analysisSearchContract.js";
+import { AnalysisInputError, AnalysisProtocolError, } from "../domain/analysisErrorCore.js";
+import { functionDossierSchema, functionInstructionWindowSchema, } from "../domain/hopperValues.js";
+import { IDA_LIMITATIONS } from "./IdaProviderCapabilities.js";
+import { disassemblySchema, idaAddressSchema, idaFunctionSchema, legacyCalleesSchema, legacyPageSchema, legacyStringSchema, legacyXrefsSchema, modernCalleesSchema, modernDecompileSchema, modernDisassemblySchema, modernLookupSchema, modernPageSchema, modernStringsSchema, modernXrefsSchema, nextOffset, } from "./IdaProtocolValues.js";
+const unknownBody = {
+    available: false,
+    reason: "IDA MCP does not report complete function body ranges.",
+};
+const identity = (fn) => ({
+    address: fn.address,
+    name: fn.name,
+    classification: null,
+    body: unknownBody,
+});
+const lines = (asm) => asm.lines.map(({ address, instruction }) => `${address}: ${instruction}`);
+/** Translate explicit analyst questions into a closed set of read-only upstream requests. */
+export class IdaOperationRunner {
+    connection;
+    protocol;
+    database;
+    raw = [];
+    locations = [];
+    limitations = [];
+    constructor(connection, protocol, database) {
+        this.connection = connection;
+        this.protocol = protocol;
+        this.database = database;
+    }
+    async call(tool, args) {
+        const scoped = this.database === undefined ? args : { ...args, database: this.database };
+        const result = await this.connection.call(tool, scoped);
+        this.raw.push({ tool, arguments: scoped, result });
+        return result;
+    }
+    async functions() {
+        const result = [];
+        let offset = 0;
+        while (offset !== null) {
+            const current = offset;
+            const value = this.protocol === "legacy"
+                ? legacyPageSchema.parse(await this.call("list_functions", { offset, count: 100 }))
+                : modernPageSchema.parse(await this.call("list_funcs", {
+                    queries: { offset, count: 100 },
+                }))[0];
+            if (value === undefined)
+                throw new AnalysisProtocolError("IDA MCP omitted its function page.");
+            result.push(...value.data.map((fn) => idaFunctionSchema.parse(fn)));
+            offset = value.next_offset;
+            if (offset !== null && offset <= current)
+                throw new AnalysisProtocolError("IDA MCP function pagination did not advance.");
+        }
+        return result;
+    }
+    async resolve(query) {
+        if (this.protocol === "modern") {
+            const item = modernLookupSchema.parse(await this.call("lookup_funcs", { queries: [query] }))[0];
+            if (item?.fn == null || item.error !== null)
+                throw new AnalysisProtocolError(`IDA function lookup failed for ${query}: ${item?.error ?? "missing function"}`);
+            return item.fn;
+        }
+        const address = idaAddressSchema.safeParse(/^0x/iu.test(query) ? query : undefined);
+        const found = idaFunctionSchema.parse(await this.call(address.success ? "get_function_by_address" : "get_function_by_name", address.success ? { address: address.data } : { name: query }));
+        // Legacy producers may echo an interior query or call site in address.
+        // Resolve the reported symbol again to obtain its actual entry, never infer from size.
+        const entry = idaFunctionSchema.parse(await this.call("get_function_by_name", { name: found.name }));
+        if (entry.name !== found.name)
+            throw new AnalysisProtocolError("IDA function identity changed during lookup.");
+        return entry;
+    }
+    async strings() {
+        const result = [];
+        let offset = 0;
+        while (offset !== null) {
+            const current = offset;
+            if (this.protocol === "legacy") {
+                const page = legacyPageSchema.parse(await this.call("list_strings", { offset, count: 100 }));
+                result.push(...page.data.map((item) => {
+                    const s = legacyStringSchema.parse(item);
+                    return { address: s.address, value: s.string };
+                }));
+                offset = page.next_offset;
+            }
+            else {
+                const page = modernStringsSchema.parse(await this.call("find_regex", {
+                    pattern: "(?s).*",
+                    offset,
+                    limit: 100,
+                }));
+                result.push(...page.matches.map((s) => ({ address: s.addr, value: s.string })));
+                offset = nextOffset(page.cursor, current);
+            }
+            if (offset !== null && offset <= current)
+                throw new AnalysisProtocolError("IDA MCP string pagination did not advance.");
+        }
+        return result;
+    }
+    async assembly(fn) {
+        if (this.protocol === "legacy") {
+            const result = disassemblySchema.parse(await this.call("disassemble_function", { start_address: fn.address }));
+            this.verifyAssembly(fn, result);
+            return result;
+        }
+        let result;
+        let offset = 0;
+        while (offset !== null) {
+            const page = modernDisassemblySchema.parse(await this.call("disasm", {
+                addr: fn.address,
+                offset,
+                max_instructions: 100,
+            }));
+            if (page.asm === null || page.error !== undefined)
+                throw new AnalysisProtocolError(`IDA disassembly failed: ${page.error ?? "missing assembly"}`);
+            this.verifyAssembly(fn, page.asm);
+            if (result === undefined)
+                result = page.asm;
+            else
+                result.lines.push(...page.asm.lines);
+            offset = nextOffset(page.cursor, offset);
+        }
+        if (result === undefined)
+            throw new AnalysisProtocolError("IDA omitted assembly.");
+        return result;
+    }
+    verifyAssembly(fn, asm) {
+        if (asm.start_ea !== fn.address || asm.name !== fn.name)
+            throw new AnalysisProtocolError("IDA disassembly identifies a different function than the resolved entry.");
+    }
+    async pseudocode(fn) {
+        if (this.protocol === "legacy")
+            return z
+                .string()
+                .nullable()
+                .parse(await this.call("decompile_function", { address: fn.address }));
+        const result = [];
+        let offset = 0;
+        while (offset !== null) {
+            const page = modernDecompileSchema.parse(await this.call("decompile", {
+                addr: fn.address,
+                offset,
+                max_lines: 100,
+            }));
+            if (page.code === null)
+                throw new AnalysisProtocolError(`IDA decompilation failed: ${page.error ?? "missing code"}`);
+            result.push(page.code);
+            offset = nextOffset(page.cursor, offset);
+        }
+        return result.join("\n");
+    }
+    async xrefs(address) {
+        if (this.protocol === "legacy")
+            return legacyXrefsSchema.parse(await this.call("get_xrefs_to", { address }));
+        const page = modernXrefsSchema.parse(await this.call("xrefs_to", { addrs: [address], limit: 1000 }))[0];
+        if (page?.xrefs == null)
+            throw new AnalysisProtocolError(`IDA xrefs failed: ${page?.error ?? "missing references"}`);
+        if (page.more === true)
+            this.limitations.push("Upstream xrefs_to capped results at 1000 references; additional references remain unknown.");
+        return page.xrefs.map((xref) => ({
+            address: xref.addr,
+            type: xref.type,
+            function: xref.fn,
+        }));
+    }
+    async relationships(fn, direction) {
+        const queries = [];
+        const result = new Map();
+        if (this.protocol === "legacy") {
+            const value = await this.call(direction === "callers" ? "get_callers" : "get_callees", { function_address: fn.address });
+            const items = direction === "callers"
+                ? z.array(idaFunctionSchema).parse(value)
+                : legacyCalleesSchema.parse(value);
+            for (const item of items) {
+                if ("type" in item && item.type === "external")
+                    result.set(item.address, identity({ ...item, size: "unknown" }));
+                else
+                    queries.push(item.name);
+            }
+        }
+        else if (direction === "callers") {
+            this.limitations.push("Modern upstream xrefs classify references as code or data, without proving call edges. Direct callers are unavailable in this profile.");
+            return [];
+        }
+        else {
+            const page = modernCalleesSchema.parse(await this.call("callees", { addrs: [fn.address], limit: 500 }))[0];
+            if (page?.callees == null)
+                throw new AnalysisProtocolError(`IDA callees failed: ${page?.error ?? "missing callees"}`);
+            if (page.more === true)
+                this.limitations.push("Upstream callees capped results at 500; additional callees remain unknown.");
+            for (const item of page.callees) {
+                if ("type" in item && item.type === "external")
+                    result.set(item.addr, identity({ address: item.addr, name: item.name, size: "unknown" }));
+                else
+                    queries.push(item.addr);
+            }
+        }
+        for (const query of new Set(queries)) {
+            const resolved = identity(await this.resolve(query));
+            result.set(resolved.address, resolved);
+        }
+        return [...result.values()];
+    }
+    async run(operation, parameters) {
+        if (operation === "list_procedures" || operation === "search_procedures") {
+            const items = (await this.functions()).map((fn) => ({
+                address: fn.address,
+                value: fn.name,
+            }));
+            return operation === "list_procedures"
+                ? items
+                : this.search(items, parameters);
+        }
+        if (operation === "list_strings" || operation === "search_strings") {
+            const items = await this.strings();
+            return operation === "search_strings"
+                ? this.search(items, parameters)
+                : parameters.address === undefined
+                    ? items
+                    : items.filter(({ address }) => address === idaAddressSchema.parse(parameters.address));
+        }
+        if (operation === "xrefs") {
+            const inspectedAddress = idaAddressSchema.parse(parameters.address);
+            this.locations.push({ kind: "address", address: inspectedAddress });
+            return (await this.xrefs(inspectedAddress)).map(({ address }) => address);
+        }
+        const fn = await this.resolve(z.string().min(1).parse(parameters.procedure));
+        this.locations.push({ kind: "address", address: fn.address });
+        switch (operation) {
+            case "procedure_address":
+                return fn.address;
+            case "procedure_pseudo_code":
+                return this.pseudocode(fn);
+            case "procedure_assembly":
+                return lines(await this.assembly(fn)).join("\n");
+            case "procedure_callers":
+                if (this.protocol === "modern")
+                    throw new AnalysisProtocolError("This IDA MCP profile cannot distinguish direct callers from other code references.");
+                return (await this.relationships(fn, "callers")).map(({ address }) => address);
+            case "procedure_callees":
+                return (await this.relationships(fn, "callees")).map(({ address }) => address);
+            case "read_function_instructions":
+                return functionInstructionWindowSchema.parse({
+                    procedure: identity(fn),
+                    instructions: lines(await this.assembly(fn)),
+                    limitations: IDA_LIMITATIONS,
+                });
+            case "analyze_function":
+                return this.dossier(fn);
+        }
+    }
+    search(items, input) {
+        const query = z.object(analysisSearchInput).parse(input);
+        let matches;
+        if (query.mode === "regex") {
+            try {
+                const regex = new RegExp(query.pattern, query.case_sensitive ? "u" : "iu");
+                matches = (value) => regex.test(value);
+            }
+            catch (cause) {
+                throw new AnalysisInputError("search", { cause });
+            }
+        }
+        else {
+            const needle = query.case_sensitive
+                ? query.pattern
+                : query.pattern.toLowerCase();
+            matches = (value) => (query.case_sensitive ? value : value.toLowerCase()).includes(needle);
+        }
+        return items.filter(({ value }) => matches(value));
+    }
+    async dossier(fn) {
+        const asm = await this.assembly(fn);
+        const pseudocode = await this.pseudocode(fn);
+        const callers = await this.relationships(fn, "callers");
+        const callees = await this.relationships(fn, "callees");
+        const signature = asm.return_type == null || asm.arguments == null
+            ? null
+            : `${asm.return_type} ${fn.name}(${asm.arguments.map((arg) => `${arg.type} ${arg.name}`).join(", ")})`;
+        return functionDossierSchema.parse({
+            procedure: { ...identity(fn), signature, locals: [] },
+            pseudocode: pseudocode ?? "",
+            assembly: lines(asm),
+            comments: [],
+            callers,
+            callees,
+            incoming_references: [],
+            outgoing_references: [],
+            referenced_strings: [],
+            referenced_names: [],
+            basic_blocks: [],
+            limitations: [
+                ...IDA_LIMITATIONS,
+                ...this.limitations,
+                "Stack frame records are not evidence of source locals. Rendered comments do not identify regular versus inline origin.",
+                ...(pseudocode === null ? ["Pseudocode is unavailable."] : []),
+            ],
+        });
+    }
+}

package/dist/ida/IdaProtocolValues.js

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
+/** Normalize an IDA hexadecimal coordinate without passing through a JavaScript number. */
+export const idaAddressSchema = z
+    .string()
+    .regex(/^(?:0x)?[0-9a-f]+$/iu)
+    .transform((value) => `0x${BigInt(value.startsWith("0x") || value.startsWith("0X") ? value : `0x${value}`).toString(16)}`);
+/** A function observation; size is an enclosing span, never a complete body. */
+export const idaFunctionSchema = z.union([
+    z.object({
+        address: idaAddressSchema,
+        name: z.string().min(1),
+        size: z.string(),
+    }),
+    z
+        .object({
+        addr: idaAddressSchema,
+        name: z.string().min(1),
+        size: z.string(),
+    })
+        .transform(({ addr, ...rest }) => ({ address: addr, ...rest })),
+]);
+/** Legacy metadata describes the recorded input, whereas modern health names live paths. */
+export const legacyMetadataSchema = z
+    .object({
+    path: z.string().min(1),
+    module: z.string(),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/iu),
+    base: idaAddressSchema,
+})
+    .passthrough();
+export const modernHealthSchema = z
+    .object({
+    status: z.literal("ok"),
+    input_path: z.string().min(1),
+    idb_path: z.string().nullable(),
+    imagebase: idaAddressSchema,
+    auto_analysis_ready: z.boolean().nullable(),
+    module: z.string(),
+})
+    .passthrough();
+/** An upstream cursor must either finish or advance strictly to avoid replay loops. */
+export const cursorSchema = z.union([
+    z.object({ next: z.number().int().nonnegative() }),
+    z.object({ done: z.literal(true) }),
+]);
+export const nextOffset = (cursor, current) => {
+    if ("done" in cursor)
+        return null;
+    if (cursor.next <= current)
+        throw new AnalysisProtocolError("IDA MCP pagination did not advance its offset.");
+    return cursor.next;
+};
+export const legacyPageSchema = z.object({
+    data: z.array(jsonValueSchema),
+    next_offset: z.number().int().nonnegative().nullable(),
+});
+export const modernPageSchema = z
+    .array(z.object({
+    data: z.array(jsonValueSchema),
+    next_offset: z.number().int().nonnegative().nullable(),
+}))
+    .length(1);
+export const modernLookupSchema = z
+    .array(z.object({
+    query: z.string(),
+    fn: idaFunctionSchema.nullable(),
+    error: z.string().nullable(),
+}))
+    .length(1);
+const instructionSchema = z.union([
+    z.object({
+        address: idaAddressSchema,
+        instruction: z.string(),
+        comments: z.array(z.string()).nullish(),
+    }),
+    z
+        .object({
+        addr: idaAddressSchema,
+        instruction: z.string(),
+        comments: z.array(z.string()).nullish(),
+    })
+        .transform(({ addr, ...rest }) => ({ address: addr, ...rest })),
+]);
+export const disassemblySchema = z.object({
+    name: z.string(),
+    start_ea: idaAddressSchema,
+    lines: z.array(instructionSchema),
+    return_type: z.string().nullish(),
+    arguments: z
+        .array(z.object({ name: z.string(), type: z.string() }))
+        .nullish(),
+});
+export const modernDisassemblySchema = z.object({
+    asm: disassemblySchema.nullable(),
+    error: z.string().optional(),
+    cursor: cursorSchema,
+});
+export const modernDecompileSchema = z.object({
+    code: z.string().nullable(),
+    error: z.string().optional(),
+    cursor: cursorSchema,
+    line_count: z.number().int().nonnegative().optional(),
+    total_lines: z.number().int().nonnegative().optional(),
+});
+export const legacyStringSchema = z.object({
+    address: idaAddressSchema,
+    string: z.string(),
+    length: z.number().int().nonnegative(),
+});
+export const modernStringsSchema = z.object({
+    matches: z.array(z.object({ addr: idaAddressSchema, string: z.string() })),
+    cursor: cursorSchema,
+});
+export const legacyXrefsSchema = z.array(z.object({
+    address: idaAddressSchema,
+    type: z.string(),
+    function: idaFunctionSchema.nullable(),
+}));
+export const modernXrefsSchema = z
+    .array(z.object({
+    xrefs: z
+        .array(z.object({
+        addr: idaAddressSchema,
+        type: z.string(),
+        fn: idaFunctionSchema.nullable(),
+    }))
+        .nullable(),
+    error: z.string().optional(),
+    more: z.boolean().optional(),
+}))
+    .length(1);
+export const modernCalleesSchema = z
+    .array(z.object({
+    callees: z
+        .array(z.object({
+        addr: idaAddressSchema,
+        name: z.string(),
+        type: z.enum(["internal", "external"]),
+    }))
+        .nullable(),
+    error: z.string().optional(),
+    more: z.boolean().optional(),
+}))
+    .length(1);
+export const legacyCalleesSchema = z.array(z.object({ address: idaAddressSchema, name: z.string() }).passthrough());
+/** Parsed database lifecycle observations retain explicit ownership information. */
+export const openDatabaseSchema = z
+    .object({
+    success: z.literal(true),
+    session: z
+        .object({ session_id: z.string().min(1), input_path: z.string().min(1) })
+        .passthrough(),
+})
+    .passthrough();
+export const databaseListSchema = z
+    .object({
+    sessions: z.array(z
+        .object({
+        session_id: z.string(),
+        input_path: z.string(),
+        owned: z.boolean(),
+        backend: z.enum(["worker", "gui"]),
+        is_active: z.boolean(),
+    })
+        .passthrough()),
+})
+    .passthrough();
+export const closeDatabaseSchema = z
+    .object({
+    success: z.literal(true),
+    session_id: z.string(),
+    saved: z.boolean().nullable().optional(),
+    owned: z.boolean(),
+    backend: z.enum(["worker", "gui"]),
+})
+    .passthrough();