rea-agents 1.6.0 → 2.0.0

package/dist/ghidra/GhidraInventoryValues.js

@@ -0,0 +1,217 @@
+import { z } from "zod";
+import { AnalysisInputError, AnalysisOutputError } from "../domain/errors.js";
+import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+/** Read-only direct operations admitted by the Ghidra v1 adapter. */
+export const GHIDRA_INVENTORY_OPERATIONS = [
+    "address_name",
+    "list_documents",
+    "list_names",
+    "list_procedures",
+    "list_segments",
+    "list_strings",
+    "procedure_address",
+    "resolve_containing_procedure",
+    "search_procedures",
+    "search_strings",
+];
+const operationSet = new Set(GHIDRA_INVENTORY_OPERATIONS);
+/** Narrow an application operation to the Ghidra inventory surface. */
+export const isGhidraInventoryOperation = (operation) => operationSet.has(operation);
+export const ghidraBoundedIdentifierSchema = z.string().min(1).max(4096);
+const boundedIdentifier = ghidraBoundedIdentifierSchema;
+const document = boundedIdentifier.nullable().default(null);
+const explicitAddress = boundedIdentifier;
+const filteredAddress = explicitAddress.nullable().default(null);
+const pagination = {
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(500).default(100),
+};
+const searchInput = {
+    pattern: z.string().min(1).max(256),
+    mode: z.enum(["literal", "regex"]).default("literal"),
+    case_sensitive: z.boolean().default(false),
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(100).default(100),
+    document,
+};
+const inputSchemas = {
+    address_name: z.object({ document, address: explicitAddress }).strict(),
+    list_documents: z.object({}).strict(),
+    list_names: z
+        .object({ document, address: filteredAddress, ...pagination })
+        .strict(),
+    list_procedures: z.object({ document, ...pagination }).strict(),
+    list_segments: z.object({ document }).strict(),
+    list_strings: z
+        .object({ document, address: filteredAddress, ...pagination })
+        .strict(),
+    procedure_address: z
+        .object({ document, procedure: boundedIdentifier })
+        .strict(),
+    resolve_containing_procedure: z
+        .object({ document, address: explicitAddress })
+        .strict(),
+    search_procedures: z.object(searchInput).strict(),
+    search_strings: z.object(searchInput).strict(),
+};
+/** Validate and default one provider request before it crosses the socket. */
+export const parseGhidraInventoryInput = (operation, value) => {
+    const parsed = inputSchemas[operation].safeParse(value);
+    if (!parsed.success)
+        return err(new AnalysisInputError(operation, { cause: parsed.error }));
+    return ok(jsonObjectSchema.parse(parsed.data));
+};
+export const ghidraCanonicalAddressSchema = z
+    .string()
+    .regex(/^(?:0x[0-9a-f]+|(?:[A-Za-z0-9._~-]|%[0-9A-F]{2})+:0x[0-9a-f]+)$/u);
+const canonicalAddress = ghidraCanonicalAddressSchema;
+const valueTruncation = { value_truncated: z.boolean() };
+const symbolFacts = z
+    .object({
+    primary: z.boolean(),
+    dynamic: z.boolean(),
+    external: z.boolean(),
+    type: z.string().min(1),
+    source: z.enum(["default", "analysis", "ai", "imported", "user_defined"]),
+})
+    .strict();
+const procedureFacts = z
+    .object({
+    external: z.boolean(),
+    thunk: z.boolean(),
+    thunk_target: canonicalAddress.nullable(),
+})
+    .strict();
+const functionClassification = procedureFacts
+    .extend({ provenance: z.literal("ghidra-function-manager") })
+    .strict();
+const stringFacts = z
+    .object({
+    encoding: z.string().min(1),
+    termination: z.enum(["missing", "present_or_not_required"]),
+    byte_length: z.number().int().min(0),
+})
+    .strict();
+const baseItem = {
+    address: canonicalAddress,
+    value: z.string(),
+    ...valueTruncation,
+};
+const symbolItem = z.object({ ...baseItem, symbol: symbolFacts }).strict();
+const procedureItem = z
+    .object({ ...baseItem, procedure: procedureFacts })
+    .strict();
+const stringItem = z.object({ ...baseItem, string: stringFacts }).strict();
+const searchItem = z.object(baseItem).strict();
+const pageSchema = (item, maximumLimit) => z
+    .object({
+    items: z.array(item),
+    offset: z.number().int().min(0),
+    limit: z.number().int().min(1).max(maximumLimit),
+    total: z.number().int().min(0),
+    next_offset: z.number().int().min(0).nullable(),
+    has_more: z.boolean(),
+})
+    .strict()
+    .superRefine((page, context) => {
+    const next = page.offset + page.items.length;
+    const hasMore = next < page.total;
+    if (page.items.length > page.limit)
+        context.addIssue({
+            code: "custom",
+            path: ["items"],
+            message: "page exceeds its declared limit",
+        });
+    if (page.items.length > 0 && next > page.total)
+        context.addIssue({
+            code: "custom",
+            path: ["total"],
+            message: "page items exceed its exact total",
+        });
+    if (hasMore && page.items.length === 0)
+        context.addIssue({
+            code: "custom",
+            path: ["items"],
+            message: "page continuation must advance its offset",
+        });
+    if (page.has_more !== hasMore)
+        context.addIssue({
+            code: "custom",
+            path: ["has_more"],
+            message: "page continuation does not match its exact total",
+        });
+    if (page.next_offset !== (hasMore ? next : null))
+        context.addIssue({
+            code: "custom",
+            path: ["next_offset"],
+            message: "page continuation offset is inconsistent",
+        });
+});
+const availablePermissions = z
+    .object({
+    available: z.literal(true),
+    source: z.literal("ghidra-memory-block"),
+})
+    .strict();
+const memoryRegion = z
+    .object({
+    name: z.string(),
+    start: canonicalAddress,
+    end: canonicalAddress,
+    readable: z.boolean(),
+    writable: z.boolean(),
+    executable: z.boolean(),
+    permissions: availablePermissions,
+    provenance: z.literal("ghidra-memory-block"),
+    address_space: z.string().min(1),
+    image_base: canonicalAddress,
+    initialized: z.boolean(),
+    overlay: z.boolean(),
+})
+    .strict();
+const segment = memoryRegion
+    .extend({ sections: z.array(memoryRegion) })
+    .strict();
+const containingProcedure = z.discriminatedUnion("found", [
+    z
+        .object({
+        query_address: canonicalAddress,
+        found: z.literal(true),
+        procedure: z
+            .object({
+            address: canonicalAddress,
+            name: z.string().min(1),
+            classification: functionClassification,
+        })
+            .strict(),
+    })
+        .strict(),
+    z
+        .object({
+        query_address: canonicalAddress,
+        found: z.literal(false),
+        procedure: z.null(),
+        reason: z.enum(["outside_segments", "not_in_procedure"]),
+    })
+        .strict(),
+]);
+const resultSchemas = {
+    address_name: z.string().nullable(),
+    list_documents: z.array(z.string().min(1)).length(1),
+    list_names: pageSchema(symbolItem, 500),
+    list_procedures: pageSchema(procedureItem, 500),
+    list_segments: z.array(segment),
+    list_strings: pageSchema(stringItem, 500),
+    procedure_address: canonicalAddress,
+    resolve_containing_procedure: containingProcedure,
+    search_procedures: pageSchema(searchItem, 100),
+    search_strings: pageSchema(searchItem, 100),
+};
+/** Require exact, bounded Java-bridge output before creating Evidence. */
+export const parseGhidraInventoryResult = (operation, value) => {
+    const parsed = resultSchemas[operation].safeParse(value);
+    return parsed.success
+        ? ok(jsonValueSchema.parse(parsed.data))
+        : err(new AnalysisOutputError(operation, "Ghidra bridge output did not match the inventory contract", { cause: parsed.error }));
+};

package/dist/ghidra/GhidraLauncher.js

@@ -0,0 +1,139 @@
+import { mkdir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { AnalysisCancelledError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
+import { spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
+import { GHIDRA_ANALYSIS_TIMEOUT_SECONDS, GHIDRA_MAX_CPU, GHIDRA_MAX_HEAP, } from "./GhidraDefaults.js";
+import { ghidraJavaEnvironment } from "./GhidraInstallation.js";
+/** Local launch failure retained as the cause of a provider-neutral error. */
+export class GhidraLaunchError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "GhidraLaunchError";
+    }
+}
+/** Launch Ghidra without copying scripts into or modifying its installation. */
+export class GhidraHeadlessLauncher {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async launch(session, options = {}) {
+        if (isAborted(options.signal))
+            return err(new AnalysisCancelledError("open_binary"));
+        const paths = ghidraRuntimePaths(session.runtimeRoot);
+        let started;
+        try {
+            await Promise.all([
+                paths.projectRoot,
+                paths.homeRoot,
+                paths.tempRoot,
+                paths.cacheRoot,
+                paths.configRoot,
+                paths.dataRoot,
+            ].map((path) => mkdir(path, { recursive: true, mode: 0o700 })));
+            await writeFileAtomic(paths.descriptorPath, `${JSON.stringify({
+                schema_version: 1,
+                socket_path: session.socketPath,
+                token: session.token,
+                run_id: session.runId,
+                provider_version: session.providerVersion,
+                profile_digest: session.profileDigest,
+            })}\n`, { encoding: "utf8", mode: 0o600 });
+            if (isAborted(options.signal))
+                return err(new AnalysisCancelledError("open_binary"));
+            started = await spawnOwnedProviderProcess({
+                command: this.options.analyzeHeadlessPath,
+                arguments: ghidraHeadlessArguments({
+                    projectRoot: paths.projectRoot,
+                    targetPath: session.targetPath,
+                    bridgeScriptPath: this.options.bridgeScriptPath,
+                    descriptorPath: paths.descriptorPath,
+                    ghidraLogPath: paths.ghidraLogPath,
+                    scriptLogPath: paths.scriptLogPath,
+                }),
+                runId: session.runId,
+                // analyzeHeadless is an interpreter-driven script. Parent identity and
+                // the per-process run token remain the cleanup authority.
+                expectedCommand: null,
+                env: ghidraLaunchEnvironment(paths, this.options.javaHome),
+            });
+            await writeFileAtomic(paths.ownershipPath, `${JSON.stringify({
+                schema_version: 1,
+                run_id: session.runId,
+                pid: started.ownership.leaderPid,
+                process_group_id: started.ownership.processGroupId,
+                parent_pid: process.pid,
+                launcher: this.options.analyzeHeadlessPath,
+                created_at: new Date().toISOString(),
+            })}\n`, { encoding: "utf8", mode: 0o600 });
+            if (isAborted(options.signal)) {
+                await cleanupOwnedProcessGroup(started.ownership);
+                return err(new AnalysisCancelledError("open_binary"));
+            }
+            const ownership = started.ownership;
+            return ok({
+                process: started.process,
+                ownsProcessLifetime: true,
+                cleanup: () => cleanupOwnedProcessGroup(ownership),
+                projectRoot: paths.projectRoot,
+                ghidraLogPath: paths.ghidraLogPath,
+                scriptLogPath: paths.scriptLogPath,
+            });
+        }
+        catch (cause) {
+            if (started !== undefined)
+                await cleanupOwnedProcessGroup(started.ownership).catch(() => undefined);
+            return isAborted(options.signal)
+                ? err(new AnalysisCancelledError("open_binary"))
+                : err(new GhidraLaunchError("Ghidra headless launch failed", { cause }));
+        }
+    }
+}
+/** Build the complete read-only headless invocation in deterministic order. */
+export const ghidraHeadlessArguments = (options) => [
+    options.projectRoot,
+    "rea-project",
+    "-import",
+    options.targetPath,
+    "-readOnly",
+    "-deleteProject",
+    "-analysisTimeoutPerFile",
+    String(GHIDRA_ANALYSIS_TIMEOUT_SECONDS),
+    "-max-cpu",
+    String(GHIDRA_MAX_CPU),
+    "-log",
+    options.ghidraLogPath,
+    "-scriptlog",
+    options.scriptLogPath,
+    "-scriptPath",
+    dirname(options.bridgeScriptPath),
+    "-postScript",
+    basename(options.bridgeScriptPath),
+    options.descriptorPath,
+];
+const ghidraRuntimePaths = (runtimeRoot) => ({
+    projectRoot: join(runtimeRoot, "project"),
+    homeRoot: join(runtimeRoot, "home"),
+    tempRoot: join(runtimeRoot, "tmp"),
+    cacheRoot: join(runtimeRoot, "cache"),
+    configRoot: join(runtimeRoot, "config"),
+    dataRoot: join(runtimeRoot, "data"),
+    descriptorPath: join(runtimeRoot, "session.json"),
+    ownershipPath: join(runtimeRoot, "ownership.json"),
+    ghidraLogPath: join(runtimeRoot, "ghidra.log"),
+    scriptLogPath: join(runtimeRoot, "script.log"),
+});
+const ghidraLaunchEnvironment = (paths, javaHome) => ({
+    ...ghidraJavaEnvironment(javaHome),
+    HOME: paths.homeRoot,
+    TMPDIR: paths.tempRoot,
+    XDG_CACHE_HOME: paths.cacheRoot,
+    XDG_CONFIG_HOME: paths.configRoot,
+    XDG_DATA_HOME: paths.dataRoot,
+    GHIDRA_HEADLESS_MAXMEM: GHIDRA_MAX_HEAP,
+    GHIDRA_HEADLESS_JAVA_OPTIONS: `-Duser.home=${paths.homeRoot} -Djava.io.tmpdir=${paths.tempRoot}`,
+});
+const isAborted = (signal) => signal?.aborted === true;