rea-agents 1.6.0 → 2.0.0

package/dist/ghidra/GhidraDiagnostics.js

@@ -0,0 +1,43 @@
+/** Preserve actionable runtime coordinates after cleanup and redact bearer data. */
+export const createGhidraDiagnostics = (options) => {
+    if (options.runtimeRoot === undefined &&
+        options.launch === undefined &&
+        Object.keys(options.previous).length > 0)
+        return options.previous;
+    const redacted = (value) => options.token === undefined
+        ? value
+        : value.replaceAll(options.token, "[REDACTED]");
+    return {
+        target_path: options.targetPath,
+        provider_version: options.providerVersion,
+        profile_digest: options.profileDigest,
+        ...(options.runtimeRoot === undefined
+            ? {}
+            : {
+                runtime_root: options.runtimeRoot,
+                socket_path: `${options.runtimeRoot}/bridge.sock`,
+            }),
+        ...(options.launch === undefined
+            ? {}
+            : {
+                project_root: options.launch.projectRoot,
+                ghidra_log_path: options.launch.ghidraLogPath,
+                script_log_path: options.launch.scriptLogPath,
+                process_id: options.launch.process.pid ?? null,
+            }),
+        ...(options.snapshot === undefined
+            ? {}
+            : {
+                exit_code: options.snapshot.exitCode ?? null,
+                exit_signal: options.snapshot.signal ?? null,
+                stdout: boundedStream(options.snapshot.stdout, redacted),
+                stderr: boundedStream(options.snapshot.stderr, redacted),
+            }),
+    };
+};
+const boundedStream = (stream, redact) => ({
+    text: redact(stream.text),
+    bytes: stream.bytes,
+    retained_bytes: stream.retainedBytes,
+    truncated: stream.truncated,
+});

package/dist/ghidra/GhidraDoctor.js

@@ -0,0 +1,59 @@
+import { inspectGhidraInstallation, } from "./GhidraInstallation.js";
+/** Project adapter-owned installation facts into the generic doctor contract. */
+export const projectGhidraDoctorInspection = (inspection) => ({
+    id: "ghidra",
+    configured: inspection.installDir !== null,
+    available: inspection.available,
+    providerVersion: inspection.providerVersion,
+    registrationEnvironment: inspection.available && inspection.installDir !== null
+        ? {
+            GHIDRA_INSTALL_DIR: inspection.installDir,
+            ...(inspection.javaHome === null
+                ? {}
+                : { JAVA_HOME: inspection.javaHome }),
+        }
+        : {},
+    checks: selectedChecks(inspection).map((check) => projectCheck(check, inspection.installDir !== null)),
+});
+/** Inspect the process-configured BYO Ghidra installation for `rea doctor`. */
+export const inspectSystemGhidraProvider = () => Promise.resolve(projectGhidraDoctorInspection(inspectGhidraInstallation({
+    ...(process.env.GHIDRA_INSTALL_DIR === undefined
+        ? {}
+        : { installDir: process.env.GHIDRA_INSTALL_DIR }),
+    ...(process.env.JAVA_HOME === undefined
+        ? {}
+        : { javaHome: process.env.JAVA_HOME }),
+})));
+const selectedChecks = (inspection) => {
+    const byName = new Map(inspection.checks.map((candidate) => [candidate.name, candidate]));
+    const configuration = byName.get("configuration");
+    if (configuration === undefined)
+        return [];
+    if (!configuration.ok)
+        return [configuration];
+    const installation = byName.get("installation");
+    return [
+        configuration,
+        byName.get("platform"),
+        byName.get("architecture"),
+        installation,
+        ...(installation?.ok === true
+            ? [byName.get("version"), byName.get("headless")]
+            : []),
+        byName.get("java"),
+    ].filter((candidate) => Boolean(candidate));
+};
+const projectCheck = (check, configured) => ({
+    name: check.name,
+    ok: check.ok,
+    code: check.code,
+    detail: check.detail,
+    remediation: check.remediation,
+    classification: check.name === "platform" || check.name === "architecture"
+        ? "unsupported_host"
+        : check.name === "java" && check.code === "runtime_missing"
+            ? "missing_dependency"
+            : configured
+                ? "config_drift"
+                : "missing_analysis_engine",
+});

package/dist/ghidra/GhidraFunctionValues.js

@@ -0,0 +1,264 @@
+import { z } from "zod";
+import { AnalysisInputError, AnalysisOutputError } from "../domain/errors.js";
+import { functionDossierSchema, } from "../domain/hopperValues.js";
+import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { ghidraBoundedIdentifierSchema, ghidraCanonicalAddressSchema, } from "./GhidraInventoryValues.js";
+/** Read-only function operations admitted by the Ghidra adapter. */
+export const GHIDRA_FUNCTION_OPERATIONS = [
+    "analyze_function",
+    "procedure_assembly",
+    "procedure_callees",
+    "procedure_callers",
+    "procedure_info",
+    "procedure_pseudo_code",
+    "procedure_references",
+    "xrefs",
+];
+const operationSet = new Set(GHIDRA_FUNCTION_OPERATIONS);
+/** Narrow an application operation to the Ghidra function-analysis surface. */
+export const isGhidraFunctionOperation = (operation) => operationSet.has(operation);
+const document = ghidraBoundedIdentifierSchema.nullable().default(null);
+const procedure = ghidraBoundedIdentifierSchema;
+const directProcedure = { document, procedure };
+const collectionOffsets = z
+    .object({
+    comments: z.number().int().min(0).default(0),
+    callers: z.number().int().min(0).default(0),
+    callees: z.number().int().min(0).default(0),
+    incoming_references: z.number().int().min(0).default(0),
+    outgoing_references: z.number().int().min(0).default(0),
+    referenced_strings: z.number().int().min(0).default(0),
+    referenced_names: z.number().int().min(0).default(0),
+    basic_blocks: z.number().int().min(0).default(0),
+})
+    .strict()
+    .default({
+    comments: 0,
+    callers: 0,
+    callees: 0,
+    incoming_references: 0,
+    outgoing_references: 0,
+    referenced_strings: 0,
+    referenced_names: 0,
+    basic_blocks: 0,
+});
+const inputSchemas = {
+    analyze_function: z
+        .object({
+        procedure,
+        include_assembly: z.boolean().default(false),
+        limit: z.number().int().min(1).max(500).default(100),
+        max_pseudocode_chars: z
+            .number()
+            .int()
+            .min(1)
+            .max(100_000)
+            .default(20_000),
+        max_instructions: z.number().int().min(1).max(5_000).default(500),
+        pseudocode_offset: z.number().int().min(0).default(0),
+        assembly_offset: z.number().int().min(0).default(0),
+        collection_offset: collectionOffsets,
+    })
+        .strict(),
+    procedure_assembly: z.object(directProcedure).strict(),
+    procedure_callees: z.object(directProcedure).strict(),
+    procedure_callers: z.object(directProcedure).strict(),
+    procedure_info: z.object(directProcedure).strict(),
+    procedure_pseudo_code: z.object(directProcedure).strict(),
+    procedure_references: z
+        .object({
+        ...directProcedure,
+        direction: z.enum(["incoming", "outgoing"]).default("outgoing"),
+        offset: z.number().int().min(0).default(0),
+        limit: z.number().int().min(1).max(500).default(100),
+        max_instructions: z.number().int().min(1).max(5_000).default(500),
+    })
+        .strict(),
+    xrefs: z.object({ document, address: ghidraCanonicalAddressSchema }).strict(),
+};
+/** Validate and default one function request before it crosses the socket. */
+export const parseGhidraFunctionInput = (operation, value) => {
+    const parsed = inputSchemas[operation].safeParse(value);
+    return parsed.success
+        ? ok(jsonObjectSchema.parse(parsed.data))
+        : err(new AnalysisInputError(operation, { cause: parsed.error }));
+};
+const classification = z
+    .object({
+    external: z.boolean(),
+    thunk: z.boolean(),
+    thunk_target: ghidraCanonicalAddressSchema.nullable(),
+    provenance: z.literal("ghidra-function-manager"),
+})
+    .strict();
+const procedureIdentity = z
+    .object({
+    address: ghidraCanonicalAddressSchema,
+    name: z.string().min(1),
+    classification,
+})
+    .strict();
+const localVariable = z
+    .object({
+    description: z.string(),
+    provenance: z.literal("ghidra-function-database"),
+})
+    .strict();
+const referenceKind = z
+    .object({
+    available: z.literal(true),
+    provenance: z.literal("ghidra-reference-manager"),
+    type: z.string().min(1),
+    flow: z.boolean(),
+    call: z.boolean(),
+    jump: z.boolean(),
+    data: z.boolean(),
+    read: z.boolean(),
+    write: z.boolean(),
+    indirect: z.boolean(),
+    computed: z.boolean(),
+    conditional: z.boolean(),
+    terminal: z.boolean(),
+    primary: z.boolean(),
+    operand_index: z.number().int(),
+    external: z.boolean(),
+})
+    .strict();
+const referenceEdge = z
+    .object({
+    source_address: ghidraCanonicalAddressSchema,
+    target_address: ghidraCanonicalAddressSchema,
+    source_procedure: procedureIdentity.nullable(),
+    target_procedure: procedureIdentity.nullable(),
+    kind: referenceKind,
+})
+    .strict();
+const boundedReferences = z
+    .object({
+    items: z.array(referenceEdge),
+    total: z.number().int().min(0).nullable(),
+    returned: z.number().int().min(0),
+    truncated: z.boolean(),
+    next_offset: z.number().int().min(0).nullable(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.returned !== value.items.length)
+        context.addIssue({
+            code: "custom",
+            path: ["returned"],
+            message: "returned must equal the number of reference items",
+        });
+    if (value.total !== null && value.total < value.returned)
+        context.addIssue({
+            code: "custom",
+            path: ["total"],
+            message: "total cannot be smaller than returned",
+        });
+    if (value.next_offset !== null && !value.truncated)
+        context.addIssue({
+            code: "custom",
+            path: ["next_offset"],
+            message: "a continuation requires truncated output",
+        });
+});
+const procedureReferences = z
+    .object({
+    procedure: procedureIdentity,
+    direction: z.enum(["incoming", "outgoing"]),
+    references: boundedReferences,
+    instructions_scanned: z.number().int().min(0),
+    instruction_scan_truncated: z.boolean(),
+})
+    .strict();
+const procedureInfo = z
+    .object({
+    name: z.string().min(1),
+    entrypoint: ghidraCanonicalAddressSchema,
+    basicblock_count: z.number().int().min(0),
+    length: z.number().int().min(0),
+    signature: z.string().nullable(),
+    locals: z.array(localVariable),
+    classification,
+})
+    .strict();
+const ghidraFunctionDossier = functionDossierSchema.superRefine((value, context) => {
+    const addresses = [
+        value.procedure.address,
+        ...value.comments.items.map(({ address }) => address),
+        ...value.callers.items.map(({ address }) => address),
+        ...value.callees.items.map(({ address }) => address),
+        ...value.incoming_references.items.flatMap(referenceAddresses),
+        ...value.outgoing_references.items.flatMap(referenceAddresses),
+        ...value.referenced_strings.items.flatMap(({ address, source_address }) => [address, source_address]),
+        ...value.referenced_names.items.flatMap(({ address, source_address }) => [
+            address,
+            source_address,
+        ]),
+        ...value.basic_blocks.items.flatMap(({ start, end, successors }) => [
+            start,
+            end,
+            ...successors,
+        ]),
+    ];
+    if (addresses.some((address) => !ghidraCanonicalAddressSchema.safeParse(address).success))
+        context.addIssue({
+            code: "custom",
+            message: "Ghidra dossier contains a non-canonical address",
+        });
+    const identities = [
+        value.procedure,
+        ...value.callers.items,
+        ...value.callees.items,
+        ...value.incoming_references.items.flatMap(referenceProcedures),
+        ...value.outgoing_references.items.flatMap(referenceProcedures),
+    ];
+    if (identities.some(({ classification: facts }) => !classification.safeParse(facts).success))
+        context.addIssue({
+            code: "custom",
+            message: "Ghidra dossier omitted function classification",
+        });
+    if (value.procedure.locals.some((variable) => !localVariable.safeParse(variable).success) ||
+        [
+            ...value.incoming_references.items,
+            ...value.outgoing_references.items,
+        ].some(({ kind }) => !referenceKind.safeParse(kind).success))
+        context.addIssue({
+            code: "custom",
+            message: "Ghidra dossier contains invalid provenance",
+        });
+    if (!value.limitations.some((item) => /indirect|computed/u.test(item)) ||
+        !value.limitations.some((item) => /provider|Ghidra|Hopper/u.test(item)))
+        context.addIssue({
+            code: "custom",
+            message: "Ghidra dossier omitted required uncertainty limitations",
+        });
+});
+const resultSchemas = {
+    analyze_function: ghidraFunctionDossier,
+    procedure_assembly: z.string(),
+    procedure_callees: z.array(ghidraCanonicalAddressSchema),
+    procedure_callers: z.array(ghidraCanonicalAddressSchema),
+    procedure_info: procedureInfo,
+    procedure_pseudo_code: z.string().nullable(),
+    procedure_references: procedureReferences,
+    xrefs: z.array(ghidraCanonicalAddressSchema),
+};
+/** Require exact, bounded Java-bridge function output before creating Evidence. */
+export const parseGhidraFunctionResult = (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 function-analysis contract", { cause: parsed.error }));
+};
+const referenceAddresses = (edge) => [
+    edge.source_address,
+    edge.target_address,
+    ...(edge.source_procedure === null ? [] : [edge.source_procedure.address]),
+    ...(edge.target_procedure === null ? [] : [edge.target_procedure.address]),
+];
+const referenceProcedures = (edge) => [
+    ...(edge.source_procedure === null ? [] : [edge.source_procedure]),
+    ...(edge.target_procedure === null ? [] : [edge.target_procedure]),
+];

package/dist/ghidra/GhidraInstallation.js

@@ -0,0 +1,239 @@
+import { spawnSync } from "node:child_process";
+import { constants } from "node:fs";
+import { accessSync, readFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+/** Exact Ghidra build whose Java bridge contract this REA release supports. */
+export const SUPPORTED_GHIDRA_VERSION = "12.1.2";
+/** Exact JDK major documented by the supported Ghidra release. */
+export const SUPPORTED_GHIDRA_JAVA_MAJOR = 21;
+/** Inspect an installation without importing a target or modifying Ghidra. */
+export const inspectGhidraInstallation = (options, host = systemGhidraInstallationHost()) => {
+    const platform = options.platform ?? process.platform;
+    const architecture = options.architecture ?? process.arch;
+    const coordinates = installationCoordinates(options, host);
+    const checks = installationChecks({
+        coordinates,
+        platform,
+        architecture,
+        javaHome: options.javaHome,
+        host,
+    });
+    const failed = checks.find(({ ok }) => !ok);
+    return {
+        available: failed === undefined,
+        platform,
+        architecture,
+        installDir: coordinates.installDir,
+        analyzeHeadlessPath: coordinates.analyzeHeadlessPath,
+        applicationPropertiesPath: coordinates.applicationPropertiesPath,
+        providerVersion: coordinates.providerVersion,
+        javaCommand: coordinates.javaCommand,
+        javaHome: coordinates.java?.home ?? options.javaHome ?? null,
+        javaVersion: coordinates.java?.version ?? null,
+        checks,
+        rejectionCode: failed?.code ?? null,
+        reason: failed?.remediation ?? null,
+    };
+};
+const installationCoordinates = (options, host) => {
+    const installDir = options.installDir ?? null;
+    const applicationPropertiesPath = installDir === null
+        ? null
+        : join(installDir, "Ghidra", "application.properties");
+    const analyzeHeadlessPath = installDir === null ? null : join(installDir, "support", "analyzeHeadless");
+    const properties = applicationPropertiesPath === null
+        ? undefined
+        : host.readText(applicationPropertiesPath);
+    const javaCommand = options.javaHome === undefined
+        ? "java"
+        : join(options.javaHome, "bin", "java");
+    return {
+        installDir,
+        applicationPropertiesPath,
+        analyzeHeadlessPath,
+        propertiesAvailable: properties !== undefined,
+        providerVersion: properties === undefined
+            ? null
+            : propertyValue(properties, "application.version"),
+        javaCommand,
+        java: host.probeJava(javaCommand, ghidraJavaEnvironment(options.javaHome)),
+    };
+};
+const installationChecks = ({ coordinates, platform, architecture, javaHome, host, }) => [
+    installationCheck({
+        name: "configuration",
+        ok: coordinates.installDir !== null,
+        code: "not_configured",
+        detail: coordinates.installDir ?? "GHIDRA_INSTALL_DIR is not set",
+        remediation: "Set GHIDRA_INSTALL_DIR to an extracted Ghidra 12.1.2 release directory.",
+    }),
+    installationCheck({
+        name: "platform",
+        ok: platform === "linux",
+        code: "unsupported_host",
+        detail: platform,
+        remediation: "REA's Ghidra v1 adapter currently supports Linux only.",
+    }),
+    installationCheck({
+        name: "architecture",
+        ok: architecture === "x64",
+        code: "unsupported_host",
+        detail: architecture,
+        remediation: "Use the official Linux x86-64 Ghidra distribution on an x64 host.",
+    }),
+    installationCheck({
+        name: "installation",
+        ok: coordinates.propertiesAvailable,
+        code: "executable_missing",
+        detail: coordinates.applicationPropertiesPath ??
+            "Ghidra application properties unavailable",
+        remediation: "Point GHIDRA_INSTALL_DIR at the root of an extracted official Ghidra release.",
+    }),
+    installationCheck({
+        name: "version",
+        ok: coordinates.providerVersion === SUPPORTED_GHIDRA_VERSION,
+        code: coordinates.providerVersion === null
+            ? "version_unresolved"
+            : "unsupported_version",
+        detail: coordinates.providerVersion ?? "unknown",
+        remediation: `Install Ghidra ${SUPPORTED_GHIDRA_VERSION}, or update REA for a different Ghidra build.`,
+    }),
+    installationCheck({
+        name: "headless",
+        ok: coordinates.analyzeHeadlessPath !== null &&
+            host.executable(coordinates.analyzeHeadlessPath),
+        code: "executable_missing",
+        detail: coordinates.analyzeHeadlessPath ?? "analyzeHeadless unavailable",
+        remediation: "Restore the executable support/analyzeHeadless script from the official Ghidra release.",
+    }),
+    javaCheck(coordinates.java, coordinates.javaCommand, javaHome),
+];
+/** Project an installation probe into caller-visible, secret-free diagnostics. */
+export const ghidraInstallationDiagnostics = (inspection) => ({
+    install_dir: inspection.installDir,
+    analyze_headless_path: inspection.analyzeHeadlessPath,
+    application_properties_path: inspection.applicationPropertiesPath,
+    provider_version: inspection.providerVersion,
+    java_command: inspection.javaCommand,
+    java_home: inspection.javaHome,
+    java_version: inspection.javaVersion,
+    platform: inspection.platform,
+    architecture: inspection.architecture,
+    checks: inspection.checks.map((check) => ({
+        name: check.name,
+        ok: check.ok,
+        code: check.code,
+        detail: check.detail,
+    })),
+});
+/** Environment that makes an explicitly selected JDK win over PATH discovery. */
+export const ghidraJavaEnvironment = (javaHome, environment = process.env) => {
+    const boundedEnvironment = {
+        ...environment,
+        _JAVA_OPTIONS: "",
+        JAVA_TOOL_OPTIONS: "",
+        JDK_JAVA_OPTIONS: "",
+        GHIDRA_JAVA_OPTIONS: "",
+    };
+    return javaHome === undefined
+        ? boundedEnvironment
+        : {
+            ...boundedEnvironment,
+            JAVA_HOME: javaHome,
+            PATH: `${join(javaHome, "bin")}${delimiter}${environment.PATH ?? ""}`,
+        };
+};
+const installationCheck = (options) => ({
+    name: options.name,
+    ok: options.ok,
+    code: options.ok ? null : options.code,
+    detail: options.detail,
+    remediation: options.ok ? null : options.remediation,
+});
+const javaCheck = (observation, command, configuredHome) => {
+    const supported = observation !== undefined &&
+        observation.major === SUPPORTED_GHIDRA_JAVA_MAJOR &&
+        observation.bits === 64 &&
+        observation.jdk;
+    const detail = observation === undefined
+        ? command
+        : `${observation.version}; ${String(observation.bits)}-bit; ${observation.jdk ? "JDK" : "runtime only"}; ${observation.home}`;
+    return installationCheck({
+        name: "java",
+        ok: supported,
+        code: observation === undefined ? "runtime_missing" : "unsupported_version",
+        detail,
+        remediation: configuredHome === undefined
+            ? "Install a 64-bit JDK 21 or set JAVA_HOME before starting REA."
+            : "Update JAVA_HOME to the root of a 64-bit JDK 21 installation.",
+    });
+};
+const propertyValue = (content, name) => {
+    for (const line of content.split(/\r?\n/u)) {
+        const separator = line.indexOf("=");
+        if (separator < 0 || line.slice(0, separator).trim() !== name)
+            continue;
+        const value = line.slice(separator + 1).trim();
+        return value.length === 0 ? null : value;
+    }
+    return null;
+};
+const systemGhidraInstallationHost = () => ({
+    readText(path) {
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    },
+    executable(path) {
+        try {
+            accessSync(path, constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    probeJava(command, environment) {
+        const observed = spawnSync(command, ["-XshowSettings:properties", "-version"], {
+            encoding: "utf8",
+            env: environment,
+            timeout: 5_000,
+            maxBuffer: 128 * 1024,
+            windowsHide: true,
+        });
+        if (observed.error !== undefined || observed.status !== 0)
+            return undefined;
+        const output = `${observed.stdout ?? ""}\n${observed.stderr ?? ""}`;
+        const version = javaProperty(output, "java.version");
+        const home = javaProperty(output, "java.home");
+        const bits = Number.parseInt(javaProperty(output, "sun.arch.data.model") ?? "0", 10);
+        if (version === null || home === null)
+            return undefined;
+        return {
+            version,
+            major: javaMajor(version),
+            home,
+            bits,
+            jdk: executablePath(join(home, "bin", "javac")),
+        };
+    },
+});
+const executablePath = (path) => {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const javaProperty = (output, name) => new RegExp(`^\\s*${name.replaceAll(".", "\\.")}\\s*=\\s*(.+?)\\s*$`, "mu").exec(output)?.[1] ?? null;
+const javaMajor = (version) => {
+    const first = Number.parseInt(version.split(".")[0] ?? "0", 10);
+    if (first !== 1)
+        return first;
+    return Number.parseInt(version.split(".")[1] ?? "0", 10);
+};