rea-agents 6.3.0 → 6.5.0

package/dist/generatedPackageMetadata.js

@@ -1,9 +1,9 @@
 /** Generated from package.json and package-lock.json; do not edit. */
 export const PACKAGE_METADATA = {
     name: "rea-agents",
-    version: "6.3.0", // x-release-please-version
+    version: "6.5.0", // x-release-please-version
     serverSdkVersion: "2.3.1",
     clientSdkVersion: "2.3.1",
     coreSdkVersion: "2.3.1",
-    skillVersion: "34",
+    skillVersion: "42",
 };

package/dist/ghidra/GhidraAnalysisProfile.js

@@ -1,35 +1,148 @@
 import { createAnalysisProfile } from "../domain/analysisProfile.js";
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
-import {} from "../domain/analysisErrorBase.js";
 import { err, ok } from "../domain/result.js";
+import { ghidraMipsProfileParameters, ghidraMipsLanguageOverride, } from "./GhidraMipsProfile.js";
+import { ghidraRiscvLanguageOverride, ghidraRiscvProfileParameters, } from "./GhidraRiscvProfile.js";
+import { ghidraPowerPcLanguage, ghidraPowerPcProfileParameters, } from "./GhidraPowerPcProfile.js";
+import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js";
+import { ghidraProcessorUnsupportedReason, isGhidraPspTarget, } from "./GhidraPspProfile.js";
+import { resolveGhidraPspExtension } from "./GhidraPspExtension.js";
+import { NATIVE_AOT_MAX_REPORT_BYTES, NATIVE_AOT_MAX_SOURCE_BYTES, NATIVE_AOT_MAX_WORKING_MEMORY_BYTES, NATIVE_AOT_MAX_WORK_UNITS, NATIVE_AOT_PROFILE_CONTRACT_REVISION, } from "../domain/native/nativeAotPe.js";
+const callRelationshipCoverage = "function-body-call-coverage-v5";
+/**
+ * The processor language REA pins for this target, or undefined when Ghidra may
+ * select from the header. The committed profile and the session readback both
+ * compare against this single owner rather than re-deriving a lane.
+ */
+export const ghidraPinnedLanguage = (target) => ghidraMipsLanguageOverride(target) ??
+    ghidraRiscvLanguageOverride(target) ??
+    ghidraPowerPcLanguage(target);
 /** Resolve version-bound, deterministic semantics before Ghidra imports a target. */
-export const resolveGhidraAnalysisProfile = (target, identity, installation, signal) => {
+export const resolveGhidraAnalysisProfile = async (target, identity, installation, signal, languageOverride, disabledAnalyzers) => {
     if (signal?.aborted === true)
         return Promise.resolve(err(new AnalysisCancelledError("open_binary")));
     if (target.kind !== "executable")
         return Promise.resolve(ok({ profile: null }));
     if (installation.status === "unavailable")
         return Promise.resolve(err(new ProviderAdapterError(identity.id, "resolve_analysis_profile")));
+    const mipsReason = ghidraProcessorUnsupportedReason(target);
+    if (mipsReason !== null)
+        return Promise.resolve(err(new AnalysisUnsupportedTargetError("resolve_analysis_profile", target.path, mipsReason)));
+    // A caller-selected generic processor cannot override this verified PSP loader.
+    if (isGhidraPspTarget(target) && languageOverride !== undefined)
+        return err(new AnalysisUnsupportedTargetError("resolve_analysis_profile", target.path, "The bounded PSP Allegrex profile does not accept REA_GHIDRA_LANGUAGE_ID overrides."));
+    const pspExtension = isGhidraPspTarget(target)
+        ? await resolveGhidraPspExtension(installation, signal)
+        : null;
+    if (pspExtension !== null && !pspExtension.ok)
+        return pspExtension;
     const provider = { ...identity, version: installation.providerVersion };
+    const analyzerParameters = disabledAnalyzers === undefined || disabledAnalyzers.length === 0
+        ? { analyzer_preset: "ghidra-default" }
+        : {
+            analyzer_preset: `ghidra-default+disabled:${disabledAnalyzers.join(",")}`,
+            analysis_options: { disabled_analyzers: [...disabledAnalyzers] },
+        };
+    if (target.format === "raw-binary") {
+        if (languageOverride !== undefined)
+            return Promise.resolve(err(new AnalysisUnsupportedTargetError("resolve_analysis_profile", target.path, "REA_GHIDRA_LANGUAGE_ID cannot override the admitted raw-binary import.")));
+        const language = ghidraRawBinaryLanguage(target.architecture);
+        return Promise.resolve(ok({
+            profile: createAnalysisProfile(provider, {
+                target_kind: target.kind,
+                target_format: target.format,
+                architecture: target.architecture,
+                available_architectures: [...target.availableArchitectures].sort(),
+                import_mode: "ephemeral-source-immutable",
+                annotation_policy: "atomic-function-entry-metadata-v1",
+                load_image_observations: "source-mappings-entry-context-v2",
+                function_body_evidence: "complete-inclusive-ranges-v1",
+                function_references: "complete-body-and-entry-reference-manager-v2",
+                call_relationship_coverage: callRelationshipCoverage,
+                function_dossier_coverage: "observed-facets-and-call-relationships-v1",
+                string_inventory_evidence: "defined-data-coverage-v1",
+                location_resolution: "explicit-address-exact-entry-symbol-first-v3",
+                procedure_file_offset_resolution: "address-first-unique-target-source-mapping-v2",
+                instruction_flow_evidence: "decoded-return-pcode-v1",
+                instruction_references: "exact-address-incoming-v1",
+                function_boundary_observations: "ghidra-function-boundary-limitations-v3",
+                no_return_repair: installation.platform === "win32"
+                    ? "disabled-windows-p0"
+                    : "returning-imports-decoded-return-v2",
+                process_launch: installation.platform === "win32"
+                    ? "official-headless-script-v1"
+                    : "inspected-jvm-launch-support-v1",
+                load_image_evidence: "independent-raw-mapping-context-v4",
+                jump_table_evidence: "typed-case-default-blocks-v1",
+                decompiler_jump_loads: true,
+                loader: "BinaryLoader",
+                language_id: language.languageId,
+                compiler_spec_id: language.compilerSpecId,
+                language_selection: "caller-supplied-v1",
+                entry_point: target.entryPoint,
+                entry_seed: "external-entry-and-function-before-analysis-v1",
+                ...analyzerParameters,
+            }),
+        }));
+    }
     const dosMz = target.format === "dos-mz";
     const dosCom = target.format === "dos-com";
     const dos = dosMz || dosCom;
+    const pinnedLanguage = ghidraPinnedLanguage(target);
+    if (pinnedLanguage !== undefined &&
+        target.architecture !== "powerpc" &&
+        languageOverride !== undefined &&
+        (languageOverride.languageId !== pinnedLanguage.languageId ||
+            (languageOverride.compilerSpecId !== undefined &&
+                languageOverride.compilerSpecId !== pinnedLanguage.compilerSpecId)))
+        return err(new AnalysisUnsupportedTargetError("resolve_analysis_profile", target.path, `The caller-selected processor or compiler specification is outside the verified ${target.architecture === "riscv"
+            ? "generic little-endian RISC-V"
+            : "endian-matched MIPS32"} profile. The requested override has not been changed.`));
+    const selectedLanguage = languageOverride ?? pinnedLanguage;
+    // DOS imports already force an admitted loader, language, and context.
+    if (dos && languageOverride !== undefined)
+        return Promise.resolve(err(new AnalysisUnsupportedTargetError("resolve_analysis_profile", target.path, "REA_GHIDRA_LANGUAGE_ID cannot override the admitted DOS real-mode import.")));
     return Promise.resolve(ok({
         profile: createAnalysisProfile(provider, {
             target_kind: target.kind,
             target_format: target.format,
+            ...(target.format === "pe"
+                ? {
+                    executable_role: target.executableRole ?? null,
+                    managed: target.managed ?? null,
+                    native_aot_metadata: {
+                        contract_revision: NATIVE_AOT_PROFILE_CONTRACT_REVISION,
+                        source_bytes: NATIVE_AOT_MAX_SOURCE_BYTES,
+                        work_units: NATIVE_AOT_MAX_WORK_UNITS,
+                        working_memory_bytes: NATIVE_AOT_MAX_WORKING_MEMORY_BYTES,
+                        report_bytes: NATIVE_AOT_MAX_REPORT_BYTES,
+                    },
+                }
+                : {}),
             architecture: target.architecture ?? null,
             available_architectures: [
                 ...(target.availableArchitectures ?? []),
             ].sort(),
             import_mode: "ephemeral-source-immutable",
+            ...(target.format === "pe"
+                ? { pdb_observations: "program-info-v1" }
+                : {}),
             annotation_policy: "atomic-function-entry-metadata-v1",
             load_image_observations: "source-mappings-entry-context-v2",
             function_body_evidence: "complete-inclusive-ranges-v1",
             function_references: "complete-body-and-entry-reference-manager-v2",
+            call_relationship_coverage: callRelationshipCoverage,
+            function_dossier_coverage: "observed-facets-and-call-relationships-v1",
+            string_inventory_evidence: "defined-data-coverage-v1",
             location_resolution: "explicit-address-exact-entry-symbol-first-v3",
+            procedure_file_offset_resolution: "address-first-unique-target-source-mapping-v2",
             instruction_flow_evidence: "decoded-return-pcode-v1",
+            instruction_references: "exact-address-incoming-v1",
+            function_boundary_observations: "ghidra-function-boundary-limitations-v3",
+            no_return_repair: installation.platform === "win32"
+                ? "disabled-windows-p0"
+                : "returning-imports-decoded-return-v2",
             process_launch: installation.platform === "win32"
                 ? "official-headless-script-v1"
                 : "inspected-jvm-launch-support-v1",
@@ -47,8 +160,19 @@ export const resolveGhidraAnalysisProfile = (target, identity, installation, sig
                 : dosCom
                     ? "BinaryLoader"
                     : "auto-from-header",
-            language_id: dos ? "x86:LE:16:Real Mode" : "auto-from-header",
-            compiler_spec_id: dos ? "default" : "auto-default",
+            language_id: dos
+                ? "x86:LE:16:Real Mode"
+                : (selectedLanguage?.languageId ?? "auto-from-header"),
+            compiler_spec_id: dos
+                ? "default"
+                : selectedLanguage === undefined
+                    ? "auto-default"
+                    : (selectedLanguage.compilerSpecId ?? "language-default"),
+            ...(languageOverride === undefined
+                ? pinnedLanguage === undefined
+                    ? {}
+                    : { language_selection: "provider-pinned-v1" }
+                : { language_selection: "configured-v1" }),
             ...(dos
                 ? {
                     load_segment: "0x1000",
@@ -67,7 +191,52 @@ export const resolveGhidraAnalysisProfile = (target, identity, installation, sig
                     entry_seed: "external-entry-and-function-before-analysis-v1",
                 }
                 : {}),
-            analyzer_preset: "ghidra-default",
+            ...analyzerParameters,
+            ...ghidraMipsProfileParameters(target, languageOverride),
+            ...ghidraRiscvProfileParameters(target),
+            ...ghidraPowerPcProfileParameters(target),
+            ...(pspExtension?.ok === true
+                ? {
+                    mips_support_lane: "psp-elf32-exec-eabi32-allegrex-v2",
+                    loader: "PspElfLoader",
+                    language_id: "Allegrex:LE:32:default",
+                    compiler_spec_id: "default",
+                    psp_extension: { ...pspExtension.value },
+                }
+                : {}),
         }),
     }));
 };
+/** Read the import-language commitment back from a resolved profile. */
+export const ghidraProfileLanguageOverride = (parameters) => {
+    if (parameters.language_selection !== "configured-v1" &&
+        parameters.language_selection !== "provider-pinned-v1")
+        return undefined;
+    const languageId = parameters.language_id;
+    const compilerSpecId = parameters.compiler_spec_id;
+    if (typeof languageId !== "string" || typeof compilerSpecId !== "string")
+        return undefined;
+    return compilerSpecId === "language-default"
+        ? { languageId }
+        : { languageId, compilerSpecId };
+};
+/** Whether a committed profile and the active configuration select the same language. */
+export const sameGhidraLanguageOverride = (left, right) => left?.languageId === right?.languageId &&
+    left?.compilerSpecId === right?.compilerSpecId;
+/** Read the analyzer-option commitment back from a resolved profile. */
+export const ghidraProfileDisabledAnalyzers = (parameters) => {
+    const options = parameters.analysis_options;
+    if (typeof options !== "object" || options === null)
+        return undefined;
+    const disabled = options.disabled_analyzers;
+    if (!Array.isArray(disabled))
+        return undefined;
+    return disabled.every((name) => typeof name === "string")
+        ? disabled
+        : undefined;
+};
+/** Whether a committed profile and the active configuration disable the same analyzers. */
+export const sameGhidraDisabledAnalyzers = (left, right) => left === undefined || right === undefined
+    ? left === right
+    : left.length === right.length &&
+        left.every((name, index) => name === right[index]);

package/dist/ghidra/GhidraAnalysisSeeds.js

@@ -0,0 +1,211 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, realpath, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { z } from "zod";
+import { ConfigurationError } from "../domain/configurationErrors.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { err, ok } from "../domain/result.js";
+/** Seed file format admitted by this adapter. */
+export const GHIDRA_SEED_FORMAT = "rea-ghidra-seeds-v1";
+export const GHIDRA_SEED_SCRIPT = "ReaGhidraApplySeeds.java";
+export const MAX_GHIDRA_SEED_BYTES = 32 * 1024 * 1024;
+export const MAX_GHIDRA_SEED_ENTRIES = 1_000_000;
+const MAX_SEED_NAME_LENGTH = 2000;
+const digest = z.string().regex(/^[a-f0-9]{64}$/u);
+const count = z.number().int().nonnegative();
+/** Caller-declared seeds committed into the analysis profile before import. */
+export const ghidraSeedCommitmentSchema = z.strictObject({
+    format: z.literal(GHIDRA_SEED_FORMAT),
+    path: z.string().refine(isAbsolute, "Seed path must be absolute"),
+    configured_path: z.string().refine(isAbsolute, "Seed path must be absolute"),
+    sha256: digest,
+    entries: z.strictObject({ function: count, code: count, label: count }),
+});
+/** What the pre-analysis script applied, as reported by the bridge handshake. */
+export const ghidraSeedReportSchema = z.strictObject({
+    format: z.literal(GHIDRA_SEED_FORMAT),
+    sha256: digest,
+    entries: count,
+    function_created: count,
+    function_existing: count,
+    function_failed: count,
+    code_decoded: count,
+    code_failed: count,
+    label_applied: count,
+    label_failed: count,
+    unmapped: count,
+});
+const seedLineError = (line, constraint) => new ConfigurationError("Invalid REA environment configuration", {
+    settings: [
+        {
+            setting: "REA_GHIDRA_SEED_FILE",
+            constraint: `line ${line}: ${constraint}`,
+        },
+    ],
+});
+/**
+ * Parse `address<TAB>kind[<TAB>name]` lines. Blank lines and `#` comments are
+ * ignored. Addresses are hexadecimal offsets in the default address space.
+ */
+export const parseGhidraSeeds = (text) => {
+    const entries = [];
+    const seen = new Set();
+    const lines = text.split("\n");
+    for (const [index, raw] of lines.entries()) {
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (line.trim() === "" || line.startsWith("#"))
+            continue;
+        const number = index + 1;
+        const fields = line.split("\t");
+        if (fields.length < 2 || fields.length > 3)
+            return err(seedLineError(number, "expected address<TAB>kind[<TAB>name]"));
+        const [address, kind, name] = fields;
+        if (address === undefined || !/^0x[0-9a-fA-F]{1,16}$/u.test(address))
+            return err(seedLineError(number, "address must be 0x-prefixed hex"));
+        if (kind !== "function" && kind !== "code" && kind !== "label")
+            return err(seedLineError(number, "kind must be function, code or label"));
+        if (name !== undefined &&
+            (name.length === 0 ||
+                name.length > MAX_SEED_NAME_LENGTH ||
+                /[\s\0]/u.test(name)))
+            return err(seedLineError(number, `name must be 1..${MAX_SEED_NAME_LENGTH} characters without whitespace`));
+        if (kind === "label" && name === undefined)
+            return err(seedLineError(number, "a label seed requires a name"));
+        if (kind === "code" && name !== undefined)
+            return err(seedLineError(number, "a code seed takes no name; add a label seed"));
+        const value = BigInt(address);
+        const key = `${value.toString(16)}:${kind}`;
+        if (seen.has(key))
+            return err(seedLineError(number, `duplicate ${kind} seed at ${address}`));
+        seen.add(key);
+        entries.push({
+            address: value,
+            kind,
+            ...(name === undefined ? {} : { name }),
+        });
+        if (entries.length > MAX_GHIDRA_SEED_ENTRIES)
+            return err(seedLineError(number, `more than ${MAX_GHIDRA_SEED_ENTRIES} seed entries`));
+    }
+    return ok(entries);
+};
+/** Canonical script input: lowercase addresses, fixed field order, LF endings. */
+const normalizedSeeds = (entries) => entries
+    .map((entry) => `0x${entry.address.toString(16)}\t${entry.kind}${entry.name === undefined ? "" : `\t${entry.name}`}\n`)
+    .join("");
+/** Read a bounded regular file through one handle without following links. */
+const readSeedFile = async (path) => {
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > MAX_GHIDRA_SEED_BYTES)
+            throw new Error(`Ghidra seed file must be a regular file of at most ${MAX_GHIDRA_SEED_BYTES} bytes: ${path}`);
+        const bytes = Buffer.alloc(stat.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const read = await file.read(bytes, offset, bytes.length - offset, offset);
+            if (read.bytesRead === 0)
+                throw new Error(`Incomplete Ghidra seed file read: ${path}`);
+            offset += read.bytesRead;
+        }
+        return bytes;
+    }
+    finally {
+        await file.close();
+    }
+};
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const decodeSeeds = (bytes) => {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return parseGhidraSeeds(text);
+};
+/** Resolve the configured seed file into an immutable profile commitment. */
+export const resolveGhidraAnalysisSeeds = async (configured) => {
+    if (configured === undefined)
+        return ok(undefined);
+    let bytes;
+    let path;
+    try {
+        path = await realpath(configured);
+        bytes = await readSeedFile(path);
+    }
+    catch (cause) {
+        return err(new ProviderAdapterError("ghidra", "resolve_analysis_profile", {
+            cause,
+            diagnostics: {
+                setting: "REA_GHIDRA_SEED_FILE",
+                path: configured,
+                reason: cause instanceof Error ? cause.message : String(cause),
+            },
+        }));
+    }
+    let parsed;
+    try {
+        parsed = decodeSeeds(bytes);
+    }
+    catch {
+        return err(seedLineError(0, "file is not valid UTF-8"));
+    }
+    if (!parsed.ok)
+        return parsed;
+    const normalized = normalizedSeeds(parsed.value);
+    const tally = { function: 0, code: 0, label: 0 };
+    for (const entry of parsed.value)
+        tally[entry.kind] += 1;
+    return ok({
+        format: GHIDRA_SEED_FORMAT,
+        path,
+        configured_path: configured,
+        sha256: sha256(normalized),
+        entries: tally,
+    });
+};
+/** Re-read the committed seeds and write the canonical copy the script applies. */
+export const snapshotGhidraAnalysisSeeds = async (commitment, runtimeRoot) => {
+    ghidraSeedCommitmentSchema.parse(commitment);
+    if ((await realpath(commitment.configured_path)) !== commitment.path)
+        throw new Error("Ghidra seed file resolved path differs from explicit configuration");
+    const parsed = decodeSeeds(await readSeedFile(commitment.path));
+    if (!parsed.ok)
+        throw parsed.error;
+    const normalized = normalizedSeeds(parsed.value);
+    if (sha256(normalized) !== commitment.sha256)
+        throw new Error(`Ghidra seed file changed after the analysis profile was committed: ${commitment.path}`);
+    const directory = join(runtimeRoot, "seeds");
+    await mkdir(directory, { mode: 0o700 });
+    const path = join(directory, "seeds.tsv");
+    await writeFile(path, normalized, { flag: "wx", mode: 0o600 });
+    return path;
+};
+const totalEntries = (commitment) => commitment.entries.function +
+    commitment.entries.code +
+    commitment.entries.label;
+/** Fail closed when the session did not apply exactly the committed seeds. */
+export const ghidraSeedFailure = (commitment, report, operation) => {
+    if (commitment === undefined && report === undefined)
+        return undefined;
+    const reason = commitment === undefined
+        ? "The Ghidra session reported analysis seeds that the profile did not commit."
+        : report === undefined
+            ? "The Ghidra session did not report the committed analysis seeds."
+            : report.sha256 !== commitment.sha256 ||
+                report.entries !== totalEntries(commitment)
+                ? "The Ghidra session applied analysis seeds that differ from the committed profile."
+                : undefined;
+    return reason === undefined
+        ? undefined
+        : new ProviderAdapterError("ghidra", operation, {
+            diagnostics: { reason },
+        });
+};
+/** Session limitations that keep seeded facts distinct from Ghidra discoveries. */
+export const ghidraSeedLimitations = (commitment, report) => commitment === undefined
+    ? []
+    : [
+        `Ghidra analysis was seeded before auto-analysis from ${commitment.path} (sha256 ${commitment.sha256}: ${commitment.entries.function} function, ${commitment.entries.code} code, ${commitment.entries.label} label entries). Seeded functions, code and names are caller assertions, not Ghidra discoveries.`,
+        ...(report === undefined
+            ? []
+            : [
+                `Seed outcome: ${report.function_created} functions created, ${report.function_existing} already present, ${report.function_failed} failed; ${report.code_decoded} code seeds decoded, ${report.code_failed} failed; ${report.label_applied} labels applied, ${report.label_failed} failed; ${report.unmapped} seeds outside initialized memory.`,
+            ]),
+    ];