rea-agents 4.0.0 → 4.1.0

package/dist/ghidra/GhidraLauncher.js

@@ -1,11 +1,13 @@
 import { mkdir } from "node:fs/promises";
 import { basename, dirname, join, win32 } from "node:path";
 import writeFileAtomic from "write-file-atomic";
-import { AnalysisCancelledError } from "../domain/errors.js";
+import { windowsPrivateRuntime } from "../windows/WindowsPrivateRuntime.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
 import { cleanupOwnedProcessGroup, cleanupWindowsProcessTree, } from "../process/ProcessOwnership.js";
 import { spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
 import { ghidraJavaEnvironment } from "./GhidraInstallation.js";
+import { snapshotGhidraExtensions, } from "./extensions/GhidraExtensions.js";
 /** Local launch failure retained as the cause of a provider-neutral error. */
 export class GhidraLaunchError extends Error {
     constructor(message, options) {
@@ -26,15 +28,9 @@ export class GhidraHeadlessLauncher {
         const platform = this.options.platform ?? process.platform;
         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({
+            await createGhidraRuntimeDirectories(paths, platform);
+            const extensions = await snapshotGhidraExtensions(this.options.analysisExtensions ?? [], session.runtimeRoot);
+            await writeGhidraRuntimeFile(paths.descriptorPath, `${JSON.stringify({
                 transport: session.transport,
                 endpoint_path: session.endpointPath,
                 token: session.token,
@@ -42,7 +38,10 @@ export class GhidraHeadlessLauncher {
                 target_sha256: session.targetSha256,
                 provider_version: session.providerVersion,
                 profile_digest: session.profileDigest,
-            })}\n`, { encoding: "utf8", mode: 0o600 });
+                ...(extensions.length === 0
+                    ? {}
+                    : { analysis_extensions: extensions }),
+            })}\n`, platform);
             if (isAborted(options.signal))
                 return err(new AnalysisCancelledError("open_binary"));
             const headlessArguments = ghidraHeadlessArguments({
@@ -52,6 +51,9 @@ export class GhidraHeadlessLauncher {
                 descriptorPath: paths.descriptorPath,
                 ghidraLogPath: paths.ghidraLogPath,
                 scriptLogPath: paths.scriptLogPath,
+                ...(this.options.dosCom === undefined
+                    ? {}
+                    : { dosCom: this.options.dosCom }),
                 ...(this.options.dosMz === undefined
                     ? {}
                     : { dosMz: this.options.dosMz }),
@@ -75,17 +77,15 @@ export class GhidraHeadlessLauncher {
                 platform,
                 env: ghidraLaunchEnvironment(paths, this.options.javaHome, platform),
             });
-            await writeFileAtomic(paths.ownershipPath, `${JSON.stringify({
+            await writeGhidraRuntimeFile(paths.ownershipPath, `${JSON.stringify({
                 run_id: session.runId,
                 pid: started.ownership.leaderPid,
                 process_group_id: started.ownership.processGroupId,
                 parent_pid: process.pid,
-                ownership_kind: platform === "win32"
-                    ? "windows-process-tree-p0"
-                    : "posix-process-group",
+                ownership_kind: platform === "win32" ? "windows-job-object" : "posix-process-group",
                 launcher: this.options.analyzeHeadlessPath,
                 created_at: new Date().toISOString(),
-            })}\n`, { encoding: "utf8", mode: 0o600 });
+            })}\n`, platform);
             if (isAborted(options.signal)) {
                 await cleanupStartedProcess(started, platform);
                 return err(new AnalysisCancelledError("open_binary"));
@@ -100,7 +100,10 @@ export class GhidraHeadlessLauncher {
         }
         catch (cause) {
             if (started !== undefined)
-                await cleanupStartedProcess(started, platform).catch(() => undefined);
+                await cleanupStartedProcess(started, platform).catch((cause) => {
+                    // best-effort cleanup: started-process cleanup must not mask the launch failure.
+                    void cause;
+                });
             return isAborted(options.signal)
                 ? err(new AnalysisCancelledError("open_binary"))
                 : err(new GhidraLaunchError("Ghidra headless launch failed", { cause }));
@@ -146,9 +149,11 @@ const quoteWindowsBatchToken = (value) => {
         throw new GhidraLaunchError("Windows Ghidra P0 paths cannot contain command-interpreter metacharacters");
     return `"${value}"`;
 };
-const cleanupStartedProcess = (started, platform) => platform === "win32"
-    ? cleanupWindowsProcessTree(started.ownership.leaderPid)
-    : cleanupOwnedProcessGroup(started.ownership);
+const cleanupStartedProcess = (started, platform) => started.cleanup !== undefined
+    ? started.cleanup()
+    : platform === "win32"
+        ? cleanupWindowsProcessTree(started.ownership.leaderPid)
+        : cleanupOwnedProcessGroup(started.ownership);
 /** Build the complete read-only headless invocation in deterministic order. */
 export const ghidraHeadlessArguments = (options) => [
     options.projectRoot,
@@ -164,7 +169,18 @@ export const ghidraHeadlessArguments = (options) => [
             "-cspec",
             "default",
         ]
-        : []),
+        : options.dosCom === true
+            ? [
+                "-loader",
+                "BinaryLoader",
+                "-loader-baseAddr",
+                "1000:0100",
+                "-processor",
+                "x86:LE:16:Real Mode",
+                "-cspec",
+                "default",
+            ]
+            : []),
     "-readOnly",
     "-deleteProject",
     "-log",
@@ -173,6 +189,9 @@ export const ghidraHeadlessArguments = (options) => [
     options.scriptLogPath,
     "-scriptPath",
     dirname(options.bridgeScriptPath),
+    ...(options.dosCom === true
+        ? ["-preScript", "ReaGhidraPrepareCom.java"]
+        : []),
     "-postScript",
     basename(options.bridgeScriptPath),
     options.descriptorPath,
@@ -189,18 +208,47 @@ const ghidraRuntimePaths = (runtimeRoot) => ({
     ghidraLogPath: join(runtimeRoot, "ghidra.log"),
     scriptLogPath: join(runtimeRoot, "script.log"),
 });
+const createGhidraRuntimeDirectories = async (paths, platform) => {
+    if (platform === "win32") {
+        const runtime = windowsPrivateRuntime(dirname(paths.projectRoot));
+        for (const path of [
+            paths.projectRoot,
+            paths.homeRoot,
+            paths.tempRoot,
+            paths.cacheRoot,
+            paths.configRoot,
+            paths.dataRoot,
+        ])
+            runtime.mkdir(basename(path));
+        return;
+    }
+    await Promise.all([
+        paths.projectRoot,
+        paths.homeRoot,
+        paths.tempRoot,
+        paths.cacheRoot,
+        paths.configRoot,
+        paths.dataRoot,
+    ].map((path) => mkdir(path, { recursive: true, mode: 0o700 })));
+};
+const writeGhidraRuntimeFile = async (path, content, platform) => {
+    if (platform === "win32") {
+        windowsPrivateRuntime(dirname(path)).writeFile(basename(path), content);
+        return;
+    }
+    await writeFileAtomic(path, content, { encoding: "utf8", mode: 0o600 });
+};
 const ghidraLaunchEnvironment = (paths, javaHome, platform) => {
-    // analyzeHeadless.bat wraps GHIDRA_HEADLESS_JAVA_OPTIONS in its own quotes
-    // when it builds VMARG_LIST. Nested quotes break cmd.exe tokenization before
-    // Ghidra starts, so keep this option list unquoted on every platform.
-    const javaOptions = `-Duser.home=${paths.homeRoot} -Djava.io.tmpdir=${paths.tempRoot}`;
     return {
         ...ghidraJavaEnvironment(javaHome, process.env, platform),
+        ...ghidraHeadlessJavaOptions(paths.homeRoot, paths.tempRoot, platform),
         HOME: paths.homeRoot,
         TMPDIR: paths.tempRoot,
         ...(platform === "win32"
             ? {
                 USERPROFILE: paths.homeRoot,
+                APPDATA: paths.configRoot,
+                LOCALAPPDATA: paths.cacheRoot,
                 TEMP: paths.tempRoot,
                 TMP: paths.tempRoot,
             }
@@ -208,7 +256,24 @@ const ghidraLaunchEnvironment = (paths, javaHome, platform) => {
         XDG_CACHE_HOME: paths.cacheRoot,
         XDG_CONFIG_HOME: paths.configRoot,
         XDG_DATA_HOME: paths.dataRoot,
-        GHIDRA_HEADLESS_JAVA_OPTIONS: javaOptions,
     };
 };
+/** Encode provider-owned JVM paths for the parser that actually consumes them. */
+export const ghidraHeadlessJavaOptions = (homeRoot, tempRoot, platform) => {
+    const options = [`-Duser.home=${homeRoot}`, `-Djava.io.tmpdir=${tempRoot}`];
+    // analyzeHeadless.bat quotes VMARG_LIST, then launch.bat expands it again.
+    // Inner quotes fail in cmd.exe; unquoted paths with spaces split at the JVM.
+    // JDK_JAVA_OPTIONS is parsed by Java itself, outside that batch expansion.
+    return platform === "win32"
+        ? {
+            JDK_JAVA_OPTIONS: [...options, "-XX:-UsePerfData"]
+                .map(quoteWindowsBatchToken)
+                .join(" "),
+            GHIDRA_HEADLESS_JAVA_OPTIONS: "",
+        }
+        : {
+            JDK_JAVA_OPTIONS: "",
+            GHIDRA_HEADLESS_JAVA_OPTIONS: options.join(" "),
+        };
+};
 const isAborted = (signal) => signal?.aborted === true;

package/dist/ghidra/GhidraLoadImageValues.js

@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import { nativeLoadImageSchema, } from "../domain/nativeLoadImage.js";
+import { parseDosMzHeader } from "../domain/dosMz.js";
+import { validateDosComLength } from "../domain/dosCom.js";
+import { err, ok } from "../domain/result.js";
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const address = (offset) => `0x${offset.toString(16)}`;
+const limitations = [
+    "Verification covers original/modified FileBytes, every initialized target-backed header/module mapping, relocation records and the external entry point. Mapping ends are inclusive.",
+    "Appended overlay bytes are identified by file extent and included in FileBytes identity; they must not be mapped as initialized header/module memory. Uninitialized allocations are reported but their contents and DOS runtime behavior are not verified.",
+    "The fixed load segment 0x1000 describes Ghidra's analysis image, not a running DOS process. Verified import does not establish original source ownership or recovered program behavior.",
+    "A mismatching memory digest identifies the reported source range; it does not locate the first differing byte inside that range.",
+];
+/** Verify measured MZ import state against the session's immutable snapshot. */
+export const attestGhidraDosLoadImage = (bytes, targetSha256, observations) => {
+    if (sha256(bytes) !== targetSha256)
+        return err("Ghidra load-image snapshot digest does not match the admitted target");
+    const parsed = parseDosMzHeader(bytes);
+    if (!parsed.ok)
+        return parsed;
+    const header = parsed.value;
+    const loadSegment = 0x1000;
+    const modified = Buffer.from(bytes);
+    const expectedRelocations = [];
+    for (let index = 0; index < header.relocationCount; index += 1) {
+        const table = header.relocationTableOffset + index * 4;
+        const offset = bytes.readUInt16LE(table);
+        const segment = bytes.readUInt16LE(table + 2);
+        const fileOffset = header.headerBytes + segment * 16 + offset;
+        const original = modified
+            .subarray(fileOffset, fileOffset + 2)
+            .toString("hex");
+        const relocated = (modified.readUInt16LE(fileOffset) + loadSegment) & 0xffff;
+        modified.writeUInt16LE(relocated, fileOffset);
+        expectedRelocations.push({
+            address: address(loadSegment * 16 + segment * 16 + offset),
+            segment: (loadSegment + segment) & 0xffff,
+            offset,
+            status: "APPLIED",
+            type: 0,
+            values: [segment, offset, relocated],
+            original_bytes_hex: original,
+            memory_bytes_hex: modified
+                .subarray(fileOffset, fileOffset + 2)
+                .toString("hex"),
+        });
+    }
+    const checks = [];
+    const check = (name, expected, observed, fileOffset = null, location = null) => {
+        checks.push({
+            name,
+            matched: JSON.stringify(expected) === JSON.stringify(observed),
+            expected,
+            observed,
+            file_offset: fileOffset,
+            address: location,
+        });
+    };
+    check("executable_format", "Old-style DOS Executable (MZ)", observations.executable_format);
+    check("language_id", "x86:LE:16:Real Mode", observations.language_id);
+    check("compiler_spec_id", "default", observations.compiler_spec_id);
+    check("image_base", "0x0", observations.image_base);
+    check("default_address_space", "ram", observations.default_address_space);
+    check("source_file_count", 1, observations.source_files.length);
+    const source = observations.source_files[0];
+    check("source_file_size", bytes.length, source?.size ?? null);
+    check("original_file_sha256", targetSha256, source?.original_sha256 ?? null);
+    check("modified_file_sha256", sha256(modified), source?.modified_sha256 ?? null);
+    const entryAddress = address(((loadSegment + header.entrySegment) & 0xffff) * 16 + header.entryOffset);
+    check("entry_points", [entryAddress], [...observations.entry_points].sort());
+    // A multiset preserves duplicate relocations and aliases; iteration order is not semantic.
+    const rows = (values) => values
+        .map(({ segment: _segment, offset: _offset, ...value }) => JSON.stringify(value))
+        .sort();
+    check("relocation_address_aliases", [], observations.relocations.filter((row) => row.segment === null ||
+        row.offset === null ||
+        address(row.segment * 16 + row.offset) !== row.address));
+    check("relocation_records", rows(expectedRelocations), rows(observations.relocations));
+    checkMappings(header, loadSegment * 16, bytes, modified, observations, check);
+    return ok(nativeLoadImageSchema.parse({
+        status: checks.every((item) => item.matched) ? "verified" : "mismatch",
+        format: "dos-mz",
+        target_sha256: targetSha256,
+        load_segment: loadSegment,
+        header_bytes: header.headerBytes,
+        module_bytes: header.moduleBytes,
+        overlay_bytes: header.overlayBytes,
+        entry: {
+            relative_segment: header.entrySegment,
+            offset: header.entryOffset,
+            linear_address: entryAddress,
+        },
+        observations,
+        checks,
+        limitations,
+    }));
+};
+const checkMappings = (header, loadBase, bytes, modified, observations, check) => {
+    const backed = observations.mappings.filter((mapping) => mapping.source_file_index !== null);
+    const sorted = [...backed].sort((left, right) => (left.file_offset ?? -1) - (right.file_offset ?? -1));
+    let covered = 0;
+    for (let index = 0; index < sorted.length; index += 1) {
+        const mapping = sorted[index];
+        if (mapping === undefined)
+            continue;
+        const start = mapping.file_offset;
+        const end = start === null ? null : start + mapping.length;
+        const headerMapping = start !== null && end !== null && start >= 0 && end <= header.headerBytes;
+        const moduleMapping = start !== null &&
+            end !== null &&
+            start >= header.headerBytes &&
+            end <= header.imageBytes;
+        const at = `mapping[${index}]`;
+        check(`${at}.source_file_index`, 0, mapping.source_file_index, start, mapping.start);
+        check(`${at}.file_coverage_start`, covered, start, start, mapping.start);
+        check(`${at}.partition`, true, headerMapping || moduleMapping, start, mapping.start);
+        check(`${at}.initialized`, true, mapping.initialized, start, mapping.start);
+        check(`${at}.loaded`, moduleMapping, mapping.loaded, start, mapping.start);
+        check(`${at}.overlay`, headerMapping, mapping.overlay, start, mapping.start);
+        check(`${at}.address_space`, headerMapping ? "HEADER" : observations.default_address_space, mapping.address_space, start, mapping.start);
+        const expectedStart = start === null
+            ? null
+            : headerMapping
+                ? `HEADER:${address(start)}`
+                : address(loadBase + start - header.headerBytes);
+        const expectedEnd = start === null
+            ? null
+            : headerMapping
+                ? `HEADER:${address(start + mapping.length - 1)}`
+                : address(loadBase + start - header.headerBytes + mapping.length - 1);
+        check(`${at}.start`, expectedStart, mapping.start, start, mapping.start);
+        check(`${at}.end`, expectedEnd, mapping.end, start, mapping.end);
+        check(`${at}.memory_sha256`, start !== null && end !== null && end <= bytes.length
+            ? sha256(modified.subarray(start, end))
+            : null, mapping.sha256, start, mapping.start);
+        covered = end ?? covered;
+    }
+    check("initialized_file_coverage_end", header.imageBytes, covered);
+    check("initialized_unbacked_mappings", [], observations.mappings.filter((mapping) => mapping.initialized && mapping.source_file_index === null));
+};
+/** Verify the explicit DOS COM interpretation against measured bytes and context. */
+export const attestGhidraDosComLoadImage = (bytes, targetSha256, observations) => {
+    if (sha256(bytes) !== targetSha256)
+        return err("Ghidra COM snapshot digest does not match the admitted target");
+    const length = validateDosComLength(bytes.length);
+    if (!length.ok)
+        return length;
+    const checks = [];
+    const check = (name, expected, observed, fileOffset = null, location = null) => {
+        checks.push({
+            name,
+            matched: JSON.stringify(expected) === JSON.stringify(observed),
+            expected,
+            observed,
+            file_offset: fileOffset,
+            address: location,
+        });
+    };
+    const source = observations.source_files[0];
+    check("executable_format", "Raw Binary", observations.executable_format);
+    check("language_id", "x86:LE:16:Real Mode", observations.language_id);
+    check("compiler_spec_id", "default", observations.compiler_spec_id);
+    check("image_base", "0x0", observations.image_base);
+    check("default_address_space", "ram", observations.default_address_space);
+    check("source_file_count", 1, observations.source_files.length);
+    check("source_file_size", bytes.length, source?.size ?? null);
+    check("original_file_sha256", targetSha256, source?.original_sha256 ?? null);
+    check("modified_file_sha256", targetSha256, source?.modified_sha256 ?? null);
+    check("entry_points", ["0x10100"], [...observations.entry_points].sort());
+    check("entry_context", [
+        {
+            address: "0x10100",
+            registers: ["CS", "DS", "ES", "SS"].map((name) => ({
+                name,
+                value_hex: "0x1000",
+            })),
+        },
+    ], observations.entry_context);
+    check("relocation_records", [], observations.relocations);
+    checkMappings({ headerBytes: 0, imageBytes: bytes.length }, 0x10100, bytes, bytes, observations, check);
+    return ok(nativeLoadImageSchema.parse({
+        status: checks.every((item) => item.matched) ? "verified" : "mismatch",
+        format: "dos-com",
+        target_sha256: targetSha256,
+        load_segment: 0x1000,
+        header_bytes: 0,
+        module_bytes: bytes.length,
+        overlay_bytes: 0,
+        entry: { relative_segment: 0, offset: 0x100, linear_address: "0x10100" },
+        observations,
+        checks,
+        limitations: [
+            "DOS COM is a headerless interpretation explicitly selected by the caller, not format identification from file bytes.",
+            "Verification covers complete original/modified source identity, mapped file bytes, entry and measured CS/DS/ES/SS entry context. Context 0x1000 is imposed for analysis; it is not an observed running process.",
+            "The PSP, initial stack contents/registers, DOS interrupts, PC-98 devices and runtime behavior are not modeled or verified. No original executable bytes are changed.",
+            "Mapping ends are inclusive; a mismatching digest identifies its source range, not the first differing byte.",
+        ],
+    }));
+};