From 86cf8942dea23cca4d84b2e359631e49affce616 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 05:40:18 +0800 Subject: [PATCH] feat(ghidra)!: import recognized DOS COM files with ComLoader (#12086) * feat(ghidra)!: import recognized DOS COM files with ComLoader Select Ghidra 12.2 ComLoader for an admitted .com image and do not pass a base address, so the file stays at 0000:0100. Images ComLoader rejects use the explicit BinaryLoader import at 1000:0100 and record the typed reason. BREAKING CHANGE: A DOS COM file that ComLoader accepts now loads at linear 0x100 instead of 0x10100. Read load_address. The BinaryLoader fallback remains at 1000:0100. * fix(ghidra): score COM dollar-strings in one pass ComLoader's printable-run walk restarts at every offset, so a 64 KiB image of printable bytes blocked profile resolution. The same capped count now skips a run once an earlier start has seen every later dollar sign. Co-authored-by: morluto * fix(ghidra): align COM import facts with the image Ghidra receives Mismatch load-image coordinates follow the measured loader and address. A dotfile named .com keeps that suffix on the snapshot, and selection uses that snapshot name. The COM fallback verifier owns its MCP connection before connect. Co-authored-by: morluto * style(ghidra): format COM snapshot and verifier files Co-authored-by: morluto * fix(ghidra): keep measured COM facts and required MZ coordinates DOS MZ and a verified COM image keep load_segment and entry required. A COM mismatch emits a known loader or load address on its own, and omits the segment and entry only when that pair is not a known layout. Co-authored-by: morluto * fix(ghidra): require the verified COM layout and document both entries A verified COM image is either ComLoader at 0000:0100 or BinaryLoader at 1000:0100 with a fallback reason. The DOS guide queries 0x100 only for the ComLoader entry and 0x10100 for the fallback. Co-authored-by: morluto * fix(ghidra): attest COM imports against the committed loader --------- Co-authored-by: Cursor Agent Co-authored-by: morluto --- .../references/native-and-artifacts.md | 10 +- .../references/native-and-artifacts.md | 10 +- bridge/ghidra/ReaGhidraBridge.java | 5 + bridge/ghidra/ReaGhidraPrepareCom.java | 59 +++- docs/providers/ghidra-dos.md | 48 +++- docs/testing-lanes.md | 8 +- scripts/verify-real-ghidra-com.mjs | 125 ++++++++- .../analysisView/nativeLoadImageView.ts | 22 +- src/domain/native/nativeLoadImage.ts | 81 +++++- src/ghidra/GhidraAnalysisProfile.ts | 34 ++- src/ghidra/GhidraComImport.test.ts | 256 ++++++++++++++++++ src/ghidra/GhidraComImport.ts | 237 ++++++++++++++++ src/ghidra/GhidraDosComLoadImage.test.ts | 160 ++++++++++- src/ghidra/GhidraLanguageOverride.test.ts | 17 +- src/ghidra/GhidraLauncher.ts | 32 ++- src/ghidra/GhidraLoadImage.fixture.ts | 85 +++++- src/ghidra/GhidraLoadImageAttest.test.ts | 5 + src/ghidra/GhidraLoadImageAttest.ts | 10 + src/ghidra/GhidraLoadImageValues.ts | 196 ++++++++++++-- src/ghidra/GhidraProvider.behavior.test.ts | 62 +++++ src/ghidra/GhidraProviderClient.ts | 13 +- src/ghidra/GhidraTargetSnapshot.ts | 31 ++- .../providers/ghidra/ghidraLauncher.test.ts | 39 ++- .../ghidra/ghidraTargetSnapshot.test.ts | 14 + tests/conformance/ghidra/dos-com-fixture.mjs | 25 +- 25 files changed, 1449 insertions(+), 135 deletions(-) create mode 100644 src/ghidra/GhidraComImport.test.ts create mode 100644 src/ghidra/GhidraComImport.ts diff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md index d807ea1fd4..671e10747a 100644 --- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -817,9 +817,13 @@ and detach the mount you created when finished. REA's inspection mount is temporary, not a retained export of the image's contents. For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI -`--target-format dos-com`). Inspect the load image before trusting function -analysis: the entry is `0x10100`, file offset zero, with imposed real-mode segment -context. PSP/stack/device state remains unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/providers/ghidra-dos.md). +`--target-format dos-com`). Do not pass a loader or base. Inspect the load +image before trusting function analysis. A Ghidra ComLoader import records +`loader: "ComLoader"` and `load_address: "0000:0100"` (linear entry `0x100`, +file offset zero) plus a zero-filled PSP placeholder at `0000:0000`. An image +ComLoader rejects records `loader: "BinaryLoader"`, `load_address: "1000:0100"` +(linear `0x10100`), and `loader_fallback.reason`. Segment context is imposed for +analysis. PSP contents, stack, and device state remain unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/providers/ghidra-dos.md). Use `inspect_byte_entropy` to triage high- and low-entropy ranges before extraction. diff --git a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md index d807ea1fd4..671e10747a 100644 --- a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -817,9 +817,13 @@ and detach the mount you created when finished. REA's inspection mount is temporary, not a retained export of the image's contents. For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI -`--target-format dos-com`). Inspect the load image before trusting function -analysis: the entry is `0x10100`, file offset zero, with imposed real-mode segment -context. PSP/stack/device state remains unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/providers/ghidra-dos.md). +`--target-format dos-com`). Do not pass a loader or base. Inspect the load +image before trusting function analysis. A Ghidra ComLoader import records +`loader: "ComLoader"` and `load_address: "0000:0100"` (linear entry `0x100`, +file offset zero) plus a zero-filled PSP placeholder at `0000:0000`. An image +ComLoader rejects records `loader: "BinaryLoader"`, `load_address: "1000:0100"` +(linear `0x10100`), and `loader_fallback.reason`. Segment context is imposed for +analysis. PSP contents, stack, and device state remain unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/providers/ghidra-dos.md). Use `inspect_byte_entropy` to triage high- and low-entropy ranges before extraction. diff --git a/bridge/ghidra/ReaGhidraBridge.java b/bridge/ghidra/ReaGhidraBridge.java index a7d3852744..03b8511abd 100644 --- a/bridge/ghidra/ReaGhidraBridge.java +++ b/bridge/ghidra/ReaGhidraBridge.java @@ -225,6 +225,11 @@ public final class ReaGhidraBridge extends HeadlessScript { } sessionDefaultAddressSpace = currentProgram.getAddressFactory().getDefaultAddressSpace(); + if (currentProgram.getExecutableFormat().equals("Old-style DOS Executable (COM)") && + !currentProgram.getOptions(ghidra.program.model.listing.Program.PROGRAM_INFO) + .getBoolean("REA DOS COM prepared", false)) { + throw new IllegalStateException("REA DOS COM entry/context preparation failed"); + } if (currentProgram.getExecutableFormat().equals("Raw Binary")) { boolean dosCom = currentProgram.getLanguageID().getIdAsString() .equals("x86:LE:16:Real Mode"); diff --git a/bridge/ghidra/ReaGhidraPrepareCom.java b/bridge/ghidra/ReaGhidraPrepareCom.java index d5d5c8e2d1..096c30c87c 100644 --- a/bridge/ghidra/ReaGhidraPrepareCom.java +++ b/bridge/ghidra/ReaGhidraPrepareCom.java @@ -1,32 +1,77 @@ import ghidra.app.script.GhidraScript; import ghidra.program.model.address.Address; +import ghidra.program.model.address.AddressSpace; import ghidra.program.model.listing.Program; +import ghidra.program.model.mem.MemoryBlock; import java.math.BigInteger; -/** Seed the declared DOS COM analysis context before default auto-analysis. */ +/** + * Seed the declared DOS COM analysis context before default auto-analysis. + * + * ComLoader ("Old-style DOS Executable (COM)") maps a 256-byte placeholder at + * 0000:0000 and the file at 0000:0100. The explicit BinaryLoader fallback maps + * the file alone at 1000:0100. Both stay on x86:LE:16:Real Mode. Segment + * registers match the load segment so later instructions use that coordinate. + */ public final class ReaGhidraPrepareCom extends GhidraScript { + private static final String COM_FORMAT = "Old-style DOS Executable (COM)"; + private static final String RAW_FORMAT = "Raw Binary"; + @Override public void run() throws Exception { - if (!currentProgram.getLanguageID().getIdAsString().equals("x86:LE:16:Real Mode") || - !currentProgram.getExecutableFormat().equals("Raw Binary")) { - throw new IllegalArgumentException("DOS COM preparation requires raw x86 real-mode import"); + if (!currentProgram.getLanguageID().getIdAsString().equals("x86:LE:16:Real Mode")) { + throw new IllegalArgumentException("DOS COM preparation requires x86 real-mode import"); } - Address entry = currentProgram.getAddressFactory().getDefaultAddressSpace().getAddress("1000:0100"); + String format = currentProgram.getExecutableFormat(); + AddressSpace space = currentProgram.getAddressFactory().getDefaultAddressSpace(); + if (format.equals(COM_FORMAT)) prepareComLoader(space); + else if (format.equals(RAW_FORMAT)) prepareBinaryLoader(space); + else { + throw new IllegalArgumentException( + "DOS COM preparation requires the ComLoader or raw BinaryLoader import" + ); + } + currentProgram.getOptions(Program.PROGRAM_INFO).setBoolean("REA DOS COM prepared", true); + } + + /** ComLoader's PSP placeholder and file image, with segment registers at 0. */ + private void prepareComLoader(AddressSpace space) throws Exception { + Address psp = space.getAddress("0000:0000"); + Address entry = space.getAddress("0000:0100"); + MemoryBlock placeholder = currentProgram.getMemory().getBlock("PSP"); + MemoryBlock code = currentProgram.getMemory().getBlock("CODE"); + if (placeholder == null || code == null || + !placeholder.getStart().equals(psp) || placeholder.getSize() != 0x100 || + !code.getStart().equals(entry) || code.getSize() < 1 || code.getSize() > 0xff00 || + !currentProgram.getMaxAddress().equals(code.getEnd())) { + throw new IllegalArgumentException( + "DOS COM ComLoader import must map a 256-byte PSP at 0000:0000 and 1..65280 code bytes at 0000:0100" + ); + } + seed(entry, psp, code.getEnd(), BigInteger.ZERO); + } + + /** Explicit raw fallback: file bytes only, at the fixed real-mode segment. */ + private void prepareBinaryLoader(AddressSpace space) throws Exception { + Address entry = space.getAddress("1000:0100"); Address start = currentProgram.getMinAddress(); Address end = currentProgram.getMaxAddress(); if (!entry.equals(start) || end.subtract(start) + 1 > 0xff00) { throw new IllegalArgumentException("DOS COM import must map 1..65280 bytes at 1000:0100"); } + seed(entry, start, end, BigInteger.valueOf(0x1000)); + } + + private void seed(Address entry, Address start, Address end, BigInteger segment) throws Exception { for (String name : new String[] { "CS", "DS", "ES", "SS" }) { monitor.checkCancelled(); currentProgram.getProgramContext().setValue( - currentProgram.getRegister(name), start, end, BigInteger.valueOf(0x1000) + currentProgram.getRegister(name), start, end, segment ); } addEntryPoint(entry); if (!disassemble(entry) || createFunction(entry, "entry") == null) { throw new IllegalStateException("DOS COM entry cannot be decoded as a function"); } - currentProgram.getOptions(Program.PROGRAM_INFO).setBoolean("REA DOS COM prepared", true); } } diff --git a/docs/providers/ghidra-dos.md b/docs/providers/ghidra-dos.md index 3734a555d6..492f86277d 100644 --- a/docs/providers/ghidra-dos.md +++ b/docs/providers/ghidra-dos.md @@ -59,10 +59,15 @@ COM has no identifying header. Select its interpretation explicitly; neither the ```bash rea inspect /absolute/path/to/legacy.com --target-format dos-com --provider ghidra --json -rea function /absolute/path/to/legacy.com 0x10100 --target-format dos-com --provider ghidra --json rea inspect-native-load-image /absolute/path/to/legacy.com --target-format dos-com --provider ghidra --json +rea function /absolute/path/to/recognized.com 0x100 --target-format dos-com --provider ghidra --json +rea function /absolute/path/to/rejected.com 0x10100 --target-format dos-com --provider ghidra --json ``` +Use `entry.linear_address` from the load image for later lookups. A ComLoader +import is `0x100`. A BinaryLoader fallback is `0x10100`; `0x100` is not mapped +on that image. + ```json { "name": "open_binary", @@ -76,18 +81,34 @@ rea inspect-native-load-image /absolute/path/to/legacy.com --target-format dos-c The caller's interpretation applies to the complete file, even if its filename suggests another format. Files must contain 1..65280 bytes: the 64 KiB COM segment -minus the 256-byte PSP prefix. Ghidra uses `BinaryLoader` with real-mode language -and maps file offset zero at `1000:0100` (linear `0x10100`). A packaged pre-analysis -script seeds the entry function and CS/DS/ES/SS context `0x1000`. These settings -and the preparation policy are committed in the analysis profile; a failed +minus the 256-byte PSP prefix. REA does not ask the caller for a loader or a base +address. + +When Ghidra 12.2 ComLoader accepts the image, REA imports it with `-loader +ComLoader` and no base address. ComLoader requires a provider name ending in +`.com`, rejects an `MZ` prefix, and requires its recognition score of DOS `INT` +opcodes and `$`-terminated strings to reach 12. It maps a 256-byte zero-filled +PSP placeholder at `0000:0000` and the file at `0000:0100` (linear `0x100`), with +language `x86:LE:16:Real Mode`. The placeholder is not file-backed and is not an +observed DOS PSP. The pre-analysis script accepts that format, keeps real mode, +requires that segment:offset, and sets CS/DS/ES/SS to `0x0`. + +Images ComLoader rejects use an explicit `BinaryLoader` fallback at `1000:0100` +(linear `0x10100`) with CS/DS/ES/SS `0x1000`. The analysis profile and the +verified load image record the loader actually used, the segment:offset +`load_address`, and, for the fallback, `loader_fallback.reason`: +`filename_extension`, `mz_signature`, or `recognition_score`. A failed preparation prevents the resident bridge from serving results. Load-image verification checks all original and modified file bytes, complete -source mapping/memory digests, absence of relocations, entry and measured register -context. The context is imposed for analysis, not observed from execution. PSP -memory, initial stack contents/SP, DOS interrupts and PC-98 devices are not -modeled. COM has no MZ header, relocation table or appended-overlay model; all -selected bytes belong to its analysis module. The original file stays unchanged. +source mapping/memory digests, absence of relocations, the loader and load +address, entry and measured register context. The context is imposed for +analysis, not observed from execution. ComLoader's zero-filled PSP placeholder +is measured as unbacked initialized bytes; it is not DOS PSP contents. Initial +stack contents/SP, DOS interrupts and PC-98 devices are not modeled. COM has no +MZ header, relocation table or appended-overlay model; all selected file bytes +belong to its analysis module. The original file stays unchanged. A fallback +image has no PSP mapping: reads at the old `0x10000` placeholder stay unmapped. ## Addresses and function extent @@ -201,7 +222,7 @@ observations rather than asserting cross-process identity of raw p-code. ```json { - "procedure": "0x10100", + "procedure": "0x100", "name": "entry", "comment": "Recovered startup role", "inline_comment": "Inspect segment setup" @@ -209,7 +230,10 @@ observations rather than asserting cross-process identity of raw p-code. ``` ```bash -rea annotate-native-function /local/program.com 0x10100 --target-format dos-com --provider ghidra --name entry --comment 'Recovered startup role' --json +rea annotate-native-function /local/recognized.com 0x100 --target-format dos-com --provider ghidra --name entry --comment 'Recovered startup role' --json +rea annotate-native-function /local/rejected.com 0x10100 --target-format dos-com --provider ghidra --name entry --comment 'Recovered startup role' --json ``` +`0x100` is the ComLoader entry. A fallback image is annotated at `0x10100`. + The CLI returns the updated analysis before closing its isolated session. MCP edits remain visible to later reads until `close_binary`. Original bytes remain unchanged, database edits are discarded on close, and immutable analysis snapshots are invalidated after edits. This operation does not save a Ghidra project, change ABI/types/body ranges, patch instructions, or emulate a DOS runtime. Windows P0 does not admit it. diff --git a/docs/testing-lanes.md b/docs/testing-lanes.md index c23f5a54a1..6fd1de4ec2 100644 --- a/docs/testing-lanes.md +++ b/docs/testing-lanes.md @@ -507,9 +507,11 @@ annotation edits are refused instead of exercising them. This lane is separate f verification. See [DOS analysis](providers/ghidra-dos.md). `npm run verify:ghidra:com` uses a generated headerless fixture with no compiler, -DOS emulator or game data. It exercises explicit admission, BinaryLoader entry -preparation, measured register context, whole-file byte readback, source offsets, -unmapped PSP/partial reads, actual decompilation, CLI/MCP parity and owned cleanup. +DOS emulator or game data. It exercises explicit admission, ComLoader import at +`0000:0100` without a caller-supplied loader or base, the raw BinaryLoader +fallback at `1000:0100` with its typed rejection, measured register context, +whole-file byte readback, source offsets, the zero PSP placeholder and partial +reads, actual decompilation, CLI/MCP parity and owned cleanup. Both segmented-address lanes reject oversized default, explicit-space and encoded-space coordinates through real reads, function queries and annotation attempts. Rejected annotations must preserve the live function dossier; CLI and MCP must report the diff --git a/scripts/verify-real-ghidra-com.mjs b/scripts/verify-real-ghidra-com.mjs index 73a0160676..f584bbb7c2 100644 --- a/scripts/verify-real-ghidra-com.mjs +++ b/scripts/verify-real-ghidra-com.mjs @@ -20,13 +20,20 @@ import { parseEvidence } from "../dist/domain/evidence.js"; import { functionDossierSchema } from "../dist/domain/native/functionDossier.js"; import { nativeInstructionSchema } from "../dist/domain/native/nativeInstruction.js"; import { inspectVerifierGhidraInstallation } from "./lib/ghidra-installation-inspection.mjs"; -import { buildDosComFixture } from "../tests/conformance/ghidra/dos-com-fixture.mjs"; +import { + buildDosComFixture, + buildRejectedDosComFixture, +} from "../tests/conformance/ghidra/dos-com-fixture.mjs"; import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs"; import { verifyGhidraAddressBoundaries } from "./lib/real-ghidra-address-boundaries.mjs"; import { VerifierFixture, withVerifierFixture, } from "./lib/verifier-fixture.mjs"; +import { + createVerifierMcpOwner, + VerifierStdioTransport, +} from "./lib/verifier-mcp-owner.mjs"; // This lane intentionally has no game paths, binary seeds or compiler dependency. if (process.argv.length !== 2) @@ -124,6 +131,7 @@ await withVerifierFixture(workspaceFixture, async () => { try { await client.connect(transport); connected = true; + const fallbackImport = await verifyRejectedCom(); const untyped = await client.callTool({ name: "open_binary", @@ -151,9 +159,18 @@ await withVerifierFixture(workspaceFixture, async () => { assert.equal(image.format, "dos-com"); assert.equal(image.header_bytes, 0); assert.equal(image.module_bytes, fixture.bytes.length); + assert.equal(image.loader, fixture.loader); + assert.equal(image.load_address, fixture.load_address); + assert.equal(image.loader_fallback, undefined); assert.equal(image.entry.linear_address, fixture.entry); assert.equal(image.entry.offset, 256); - assert.equal(image.observations.entry_context[0].registers.length, 4); + assert.deepEqual( + image.observations.entry_context[0].registers.map((register) => [ + register.name, + register.value_hex, + ]), + ["CS", "DS", "ES", "SS"].map((name) => [name, "0x0"]), + ); const memory = await call("read_bytes", { address: fixture.entry, length: fixture.bytes.length, @@ -164,10 +181,16 @@ await withVerifierFixture(workspaceFixture, async () => { address: fixture.near, }); assert.equal(mapping.file_offset, 32); - const psp = await call("read_bytes", { address: "0x10000", length: 16 }); - assert.equal(psp.returned_bytes, 0); - assert.equal(psp.complete, false); - const tail = await call("read_bytes", { address: "0x1013e", length: 8 }); + const psp = await call("read_bytes", { address: "0x0", length: 16 }); + assert.equal(psp.bytes_hex, "00".repeat(16)); + assert.equal(psp.complete, true); + const oldSegment = await call("read_bytes", { + address: "0x10000", + length: 16, + }); + assert.equal(oldSegment.returned_bytes, 0); + assert.equal(oldSegment.complete, false); + const tail = await call("read_bytes", { address: fixture.tail, length: 8 }); assert.equal(tail.returned_bytes, 2); assert.equal(tail.complete, false); const procedures = await call("list_procedures"); @@ -190,7 +213,7 @@ await withVerifierFixture(workspaceFixture, async () => { ); // This NOP follows the entry's terminating INT 20h and is not reached by // either function. It remains valid instruction bytes outside the listing. - const unlistedAddress = "0x1013f"; + const unlistedAddress = fixture.unlisted; const unlistedBytes = await call("read_bytes", { address: unlistedAddress, length: 1, @@ -471,14 +494,18 @@ await withVerifierFixture(workspaceFixture, async () => { load_image: { status: image.status, checks: image.checks.length, + loader: image.loader, + load_address: image.load_address, entry: fixture.entry, entry_context: image.observations.entry_context, }, + loader_fallback: fallbackImport, transport: { cli: true, stdio_mcp: true }, memory_evidence: { complete_file_read: true, source_offset: 32, - psp_unmapped: true, + placeholder_psp_zero: true, + old_segment_unmapped: true, partial_read_bytes: 2, }, functions: { entry: true, near: true, pseudocode_nonempty: true }, @@ -511,6 +538,81 @@ process.stdout.write( cleanup: "complete", }) + "\n", ); +async function verifyRejectedCom() { + const rejectedFixture = buildRejectedDosComFixture(); + const rejectedPath = join(workspace, "rejected.com"); + await writeFile(rejectedPath, rejectedFixture.bytes, { mode: 0o600 }); + const fallbackOwner = createVerifierMcpOwner(); + workspaceFixture.releaseAfter(() => fallbackOwner.close()); + const rejectedClient = new Client({ + name: "rea-real-com-fallback", + version: "1", + }); + const rejectedTransport = new VerifierStdioTransport({ + command: process.execPath, + args: [entrypoint, "mcp"], + env, + stderr: "pipe", + }); + const connection = await fallbackOwner.open( + rejectedClient, + rejectedTransport, + ); + try { + const opened = await rejectedClient.callTool( + { + name: "open_binary", + arguments: { + path: rejectedPath, + provider_id: "ghidra", + format: "dos-com", + }, + }, + { timeout: 240000 }, + ); + const session = requireMcpLifecycleResult(opened, "open_binary"); + assert.equal(session.format, "dos-com"); + const response = await rejectedClient.callTool( + { name: "inspect_native_load_image", arguments: {} }, + { timeout: 240000 }, + ); + const evidence = parseEvidence( + requireMcpOutput(response, "inspect_native_load_image"), + ); + const image = evidence.normalized_result; + assert.equal(image.status, "verified"); + assert.equal(image.loader, rejectedFixture.loader); + assert.equal(image.load_address, rejectedFixture.load_address); + assert.deepEqual(image.loader_fallback, { + loader: "ComLoader", + reason: rejectedFixture.fallback_reason, + }); + assert.equal(image.entry.linear_address, rejectedFixture.entry); + assert.equal( + evidence.analysis_profile.parameters.loader, + rejectedFixture.loader, + ); + assert.equal( + evidence.analysis_profile.parameters.load_address, + rejectedFixture.load_address, + ); + assert.deepEqual(evidence.analysis_profile.parameters.loader_fallback, { + loader: "ComLoader", + reason: rejectedFixture.fallback_reason, + }); + return { + loader: image.loader, + load_address: image.load_address, + reason: image.loader_fallback.reason, + entry: image.entry.linear_address, + }; + } finally { + await rejectedClient + .callTool({ name: "close_binary", arguments: {} }, { timeout: 240000 }) + .catch(() => undefined); + await fallbackOwner.closeConnection(connection); + } +} function digest(bytes) { return createHash("sha256").update(bytes).digest("hex"); } @@ -545,7 +647,12 @@ async function cli(command, address, options = []) { const evidence = parseEvidence(JSON.parse(stdout)); assert.equal(evidence.subject.identity.sha256, sha256); assert.equal(evidence.subject.identity.format, "dos-com"); - assert.equal(evidence.analysis_profile.parameters.loader, "BinaryLoader"); + assert.equal(evidence.analysis_profile.parameters.loader, fixture.loader); + assert.equal( + evidence.analysis_profile.parameters.load_address, + fixture.load_address, + ); + assert.equal(evidence.analysis_profile.parameters.loader_fallback, undefined); assert.equal( evidence.analysis_profile.parameters.language_id, "x86:LE:16:Real Mode", diff --git a/src/domain/analysisView/nativeLoadImageView.ts b/src/domain/analysisView/nativeLoadImageView.ts index 09f3cc2ab0..c52b33d173 100644 --- a/src/domain/analysisView/nativeLoadImageView.ts +++ b/src/domain/analysisView/nativeLoadImageView.ts @@ -4,7 +4,10 @@ import { nativeLoadImageObservationSchema, nativeLoadImageSchema, nativeUnsupportedLoadImageSchema, - nativeDosLoadImageSchema, + nativeDosMzLoadImageSchema, + nativeDosComVerifiedComLoaderLoadImageSchema, + nativeDosComVerifiedBinaryLoaderLoadImageSchema, + nativeDosComMismatchLoadImageSchema, nativeRawLoadImageSchema, nativeDolLoadImageSchema, } from "../native/nativeLoadImage.js"; @@ -121,7 +124,22 @@ export const nativeLoadImageSummarySchema = z.strictObject({ observations: true, limitations: true, }), - nativeDosLoadImageSchema.omit({ + nativeDosMzLoadImageSchema.omit({ + observations: true, + limitations: true, + checks: true, + }), + nativeDosComVerifiedComLoaderLoadImageSchema.omit({ + observations: true, + limitations: true, + checks: true, + }), + nativeDosComVerifiedBinaryLoaderLoadImageSchema.omit({ + observations: true, + limitations: true, + checks: true, + }), + nativeDosComMismatchLoadImageSchema.omit({ observations: true, limitations: true, checks: true, diff --git a/src/domain/native/nativeLoadImage.ts b/src/domain/native/nativeLoadImage.ts index b723089756..357b5747b8 100644 --- a/src/domain/native/nativeLoadImage.ts +++ b/src/domain/native/nativeLoadImage.ts @@ -92,23 +92,86 @@ export const nativeUnsupportedLoadImageSchema = z.strictObject({ observations: nativeLoadImageObservationSchema, limitations: z.array(z.string().min(1)), }); -export const nativeDosLoadImageSchema = z.strictObject({ - status: z.enum(["verified", "mismatch"]), - format: z.enum(["dos-mz", "dos-com"]), +const dosLoadImageEntrySchema = z.strictObject({ + relative_segment: integer.max(0xffff), + offset: integer.max(0xffff), + linear_address: nativeAddressObservationSchema, +}); +const dosLoadImageFacts = { target_sha256: digest, - load_segment: integer.max(0xffff), header_bytes: integer, module_bytes: integer, overlay_bytes: integer, - entry: z.strictObject({ - relative_segment: integer.max(0xffff), - offset: integer.max(0xffff), - linear_address: nativeAddressObservationSchema, - }), observations: nativeLoadImageObservationSchema, checks: z.array(nativeLoadImageCheckSchema), limitations: z.array(z.string().min(1)), +}; +const comLoadAddressSchema = z.string().regex(/^[0-9a-f]{4}:[0-9a-f]{4}$/u); +const comLoaderFallbackSchema = z.strictObject({ + loader: z.literal("ComLoader"), + reason: z.enum(["filename_extension", "mz_signature", "recognition_score"]), }); +/** Measured COM identity. Each field is present only when that fact was observed. */ +const comMeasuredIdentity = { + format: z.literal("dos-com"), + loader: z.enum(["ComLoader", "BinaryLoader"]).optional(), + load_address: comLoadAddressSchema.optional(), + loader_fallback: comLoaderFallbackSchema.optional(), +}; + +/** DOS MZ always names its load segment and entry. */ +export const nativeDosMzLoadImageSchema = z.strictObject({ + status: z.enum(["verified", "mismatch"]), + format: z.literal("dos-mz"), + load_segment: integer.max(0xffff), + entry: dosLoadImageEntrySchema, + ...dosLoadImageFacts, +}); +const comVerifiedFacts = { + status: z.literal("verified"), + format: z.literal("dos-com"), + ...dosLoadImageFacts, +}; +const comVerifiedEntry = (linearAddress: "0x100" | "0x10100") => + z.strictObject({ + relative_segment: z.literal(0), + offset: z.literal(0x100), + linear_address: z.literal(linearAddress), + }); +/** Verified ComLoader: file at 0000:0100, no fallback record. */ +export const nativeDosComVerifiedComLoaderLoadImageSchema = z.strictObject({ + ...comVerifiedFacts, + loader: z.literal("ComLoader"), + load_address: z.literal("0000:0100"), + load_segment: z.literal(0), + entry: comVerifiedEntry("0x100"), +}); +/** Verified BinaryLoader fallback: file at 1000:0100 with a typed reason. */ +export const nativeDosComVerifiedBinaryLoaderLoadImageSchema = z.strictObject({ + ...comVerifiedFacts, + loader: z.literal("BinaryLoader"), + load_address: z.literal("1000:0100"), + loader_fallback: comLoaderFallbackSchema, + load_segment: z.literal(0x1000), + entry: comVerifiedEntry("0x10100"), +}); +/** + * A COM mismatch may omit the segment and entry when the measured loader and + * address are not one known layout. Loader and load address stay independent. + */ +export const nativeDosComMismatchLoadImageSchema = z.strictObject({ + status: z.literal("mismatch"), + ...comMeasuredIdentity, + load_segment: integer.max(0xffff).optional(), + entry: dosLoadImageEntrySchema.optional(), + ...dosLoadImageFacts, +}); +export const nativeDosLoadImageSchema = z.union([ + nativeDosMzLoadImageSchema, + nativeDosComVerifiedComLoaderLoadImageSchema, + nativeDosComVerifiedBinaryLoaderLoadImageSchema, + nativeDosComMismatchLoadImageSchema, +]); export const nativeRawLoadImageSchema = z.strictObject({ status: z.enum(["verified", "mismatch"]), format: z.literal("raw-binary"), diff --git a/src/ghidra/GhidraAnalysisProfile.ts b/src/ghidra/GhidraAnalysisProfile.ts index bf2411864d..1c6c43ae62 100644 --- a/src/ghidra/GhidraAnalysisProfile.ts +++ b/src/ghidra/GhidraAnalysisProfile.ts @@ -12,6 +12,7 @@ import { AnalysisUnsupportedTargetError, cancelledBy, } from "../domain/analysisErrorCore.js"; +import { resolveGhidraComImport } from "./GhidraComImport.js"; import { ConfigurationError } from "../domain/configurationErrors.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; @@ -267,6 +268,13 @@ export const resolveGhidraAnalysisProfile = async ( ), ), ); + // ComLoader's acceptance depends on the provider name and the image bytes. + // Read them once here; the launcher uses this committed selection. + const comImport = dosCom + ? await resolveGhidraComImport(target, resources, signal) + : undefined; + if (comImport !== undefined && !comImport.ok) return comImport; + const com = comImport?.ok === true ? comImport.value : undefined; return Promise.resolve( ok({ profile: createProfile({ @@ -319,8 +327,8 @@ export const resolveGhidraAnalysisProfile = async ( decompiler_jump_loads: true, loader: dosMz ? "MzLoader" - : dosCom - ? "BinaryLoader" + : com !== undefined + ? com.loader : "auto-from-header", language_id: dos ? "x86:LE:16:Real Mode" @@ -337,21 +345,25 @@ export const resolveGhidraAnalysisProfile = async ( : { language_selection: "configured" }), ...(dos ? { - load_segment: "0x1000", + load_segment: com?.loadSegment ?? "0x1000", address_coordinates: "linear-byte-offset", + ...(com === undefined ? {} : { load_address: com.loadAddress }), } : {}), - ...(dosCom - ? { + ...(com === undefined + ? {} + : { entry_offset: "0x100", register_context: { - CS: "0x1000", - DS: "0x1000", - ES: "0x1000", - SS: "0x1000", + CS: com.segmentRegister, + DS: com.segmentRegister, + ES: com.segmentRegister, + SS: com.segmentRegister, }, - } - : {}), + ...(com.fallback === undefined + ? {} + : { loader_fallback: com.fallback }), + }), ...analyzerParameters, ...ghidraMipsProfileParameters(target, languageOverride), ...ghidraRiscvProfileParameters(target), diff --git a/src/ghidra/GhidraComImport.test.ts b/src/ghidra/GhidraComImport.test.ts new file mode 100644 index 0000000000..1cb0c87d5b --- /dev/null +++ b/src/ghidra/GhidraComImport.test.ts @@ -0,0 +1,256 @@ +import { createHash } from "node:crypto"; +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; +import { parseConfig } from "../config/parseConfig.js"; +import type { BinaryTarget } from "../domain/binaryTargetTypes.js"; +import { silentLogger } from "../logger.js"; +import { + createSimulatedInstallDirectory, + ghidraProfileInstallationHost as host, +} from "./GhidraInstallation.fixture.js"; +import { GhidraProvider } from "./GhidraProvider.js"; +import { + ghidraComRecognitionScore, + selectGhidraComImport, +} from "./GhidraComImport.js"; +import { ghidraSnapshotFileName } from "./GhidraTargetSnapshot.js"; + +// ComLoader scans only while i < length - 2, so the terminating INT must not +// sit in the last two bytes. Sixteen bytes keeps both INT 21h opcodes in range. +const recognized = Buffer.alloc(16, 0x90); +recognized.set(Buffer.from("b409cd21b409cd21", "hex")); + +describe("Ghidra COM import selection", () => { + it("scores one MOV AH / INT 21h the way ComLoader double-counts it", () => { + expect(ghidraComRecognitionScore(Buffer.from("b409cd210000", "hex"))).toBe( + 7, + ); + expect(ghidraComRecognitionScore(recognized)).toBe(12); + expect(ghidraComRecognitionScore(Buffer.from("b83412c3", "hex"))).toBe(0); + expect( + ghidraComRecognitionScore(Buffer.from("abcd$abcd$abcd$", "ascii")), + ).toBe(5); + expect(ghidraComRecognitionScore(Buffer.from("aaa$", "ascii"))).toBe(0); + expect(ghidraComRecognitionScore(Buffer.from("abc$defgh$", "ascii"))).toBe( + 3, + ); + }); + + it("matches ComLoader's dollar-string walk on mixed buffers", () => { + const reference = (data: Uint8Array): number => { + let score = 0; + for (let index = 0; index < data.length - 2 && score < 12; index++) { + if (data[index] !== 0xcd) continue; + if (data[index + 1] === 0x21) { + score += 2; + if ( + index >= 2 && + (data[index - 2] === 0xb4 || data[index - 2] === 0xb0) + ) + score += 3; + if (index >= 3 && data[index - 3] === 0xb8) score += 2; + if (score >= 12) return score; + } else if (data[index + 1] === 0x20) { + score += 2; + if (score >= 12) return score; + } + if (index > 1 && (data[index - 2] === 0xb4 || data[index - 2] === 0xb0)) + score += 2; + if (index > 2 && data[index - 3] === 0xb8) score += 2; + if (score >= 12) return score; + } + let count = 0; + for (let index = 0; index < data.length - 4 && count < 3; index++) { + let length = 0; + while ( + index + length < data.length && + data[index + length]! >= 0x20 && + data[index + length]! <= 0x7e + ) { + length += 1; + if ( + index + length < data.length && + data[index + length] === 0x24 && + length >= 4 + ) { + count += 1; + index += length; + break; + } + } + } + if (count > 0) score += 3; + if (count > 2) score += 2; + return score; + }; + const samples = [ + Buffer.alloc(300, 0x41), + Buffer.from("abc$defgh$abcd$abcd$abcd$"), + Buffer.from("\x00abcd$\x01$$$$abcd$"), + recognized, + ]; + for (let seed = 0; seed < 20; seed++) { + const bytes = Buffer.alloc(180); + for (let index = 0; index < bytes.length; index++) + bytes[index] = (seed * 17 + index * 13) & 0xff; + samples.push(bytes); + } + for (const sample of samples) + expect(ghidraComRecognitionScore(sample)).toBe(reference(sample)); + }); + + it("scores a full-size printable image without rescanning each suffix", () => { + const bytes = Buffer.alloc(0xff00, 0x41); + const started = Date.now(); + expect(ghidraComRecognitionScore(bytes)).toBe(0); + expect(Date.now() - started).toBeLessThan(250); + bytes.set(Buffer.from("abcd$abcd$abcd$"), bytes.length - 15); + expect(ghidraComRecognitionScore(bytes)).toBe(5); + }); + + it("keeps a dotfile named .com visible to ComLoader as a .com snapshot", () => { + const sha256 = "ab".repeat(32); + const imported = ghidraSnapshotFileName("/hidden/.com", sha256); + expect(imported).toBe(`target-${sha256.slice(0, 12)}.com`); + expect(selectGhidraComImport(imported, recognized).loader).toBe( + "ComLoader", + ); + }); + + it("selects ComLoader for a recognized .com image and records no fallback", () => { + expect(selectGhidraComImport("fixture.com", recognized)).toEqual({ + loader: "ComLoader", + loadAddress: "0000:0100", + loadSegment: "0x0", + linearAddress: "0x100", + segmentRegister: "0x0", + executableFormat: "Old-style DOS Executable (COM)", + }); + }); + + it.each([ + ["fixture.bin", recognized, "filename_extension"], + ["mz.com", Buffer.from("MZ"), "mz_signature"], + ["low.com", Buffer.from("b83412c3", "hex"), "recognition_score"], + ] as const)( + "falls back to BinaryLoader at 1000:0100 for %s", + (filename, bytes, reason) => { + expect(selectGhidraComImport(filename, bytes)).toMatchObject({ + loader: "BinaryLoader", + loadAddress: "1000:0100", + loadSegment: "0x1000", + linearAddress: "0x10100", + segmentRegister: "0x1000", + executableFormat: "Raw Binary", + fallback: { loader: "ComLoader", reason }, + }); + }, + ); +}); + +describe("Ghidra COM analysis profile", () => { + let installDir = ""; + let dispose: (() => Promise) | undefined; + beforeAll(async () => { + const directory = await createSimulatedInstallDirectory("rea-com-import-"); + installDir = directory.path; + dispose = directory.dispose; + }); + afterAll(async () => { + await dispose?.(); + }); + + it("commits the ComLoader selection for a recognized file", async () => { + const directory = await createTestTempDirectory("rea-com-recognized-"); + const path = join(directory, "program.com"); + await writeFile(path, recognized); + const parsed = parseConfig({ GHIDRA_INSTALL_DIR: installDir }); + if (!parsed.ok) throw parsed.error; + const provider = new GhidraProvider(parsed.value, silentLogger, {}, host); + const target: BinaryTarget = { + path, + sha256: createHash("sha256").update(recognized).digest("hex"), + kind: "executable", + format: "dos-com", + architecture: "x86", + availableArchitectures: ["x86"], + }; + const resolved = await provider.resolveAnalysisProfile(target); + if (!resolved.ok || resolved.value.profile === null) + throw new Error("Expected a COM analysis profile"); + expect(resolved.value.profile.parameters).toMatchObject({ + loader: "ComLoader", + load_address: "0000:0100", + load_segment: "0x0", + entry_offset: "0x100", + language_id: "x86:LE:16:Real Mode", + register_context: { CS: "0x0", DS: "0x0", ES: "0x0", SS: "0x0" }, + }); + expect(resolved.value.profile.parameters).not.toHaveProperty( + "loader_fallback", + ); + }); + + it("selects ComLoader when the admitted file is a dotfile named .com", async () => { + const directory = await createTestTempDirectory("rea-com-dotfile-"); + const path = join(directory, ".com"); + await writeFile(path, recognized); + const sha256 = createHash("sha256").update(recognized).digest("hex"); + const parsed = parseConfig({ GHIDRA_INSTALL_DIR: installDir }); + if (!parsed.ok) throw parsed.error; + const resolved = await new GhidraProvider( + parsed.value, + silentLogger, + {}, + host, + ).resolveAnalysisProfile({ + path, + sha256, + kind: "executable", + format: "dos-com", + architecture: "x86", + availableArchitectures: ["x86"], + }); + if (!resolved.ok || resolved.value.profile === null) + throw new Error("Expected a COM analysis profile"); + expect(ghidraSnapshotFileName(path, sha256).endsWith(".com")).toBe(true); + expect(resolved.value.profile.parameters).toMatchObject({ + loader: "ComLoader", + load_address: "0000:0100", + }); + }); + + it("records the typed BinaryLoader fallback when ComLoader rejects the image", async () => { + const directory = await createTestTempDirectory("rea-com-rejected-"); + const path = join(directory, "program.com"); + const bytes = Buffer.from("b83412c3", "hex"); + await writeFile(path, bytes); + const parsed = parseConfig({ GHIDRA_INSTALL_DIR: installDir }); + if (!parsed.ok) throw parsed.error; + const provider = new GhidraProvider(parsed.value, silentLogger, {}, host); + const resolved = await provider.resolveAnalysisProfile({ + path, + sha256: createHash("sha256").update(bytes).digest("hex"), + kind: "executable", + format: "dos-com", + architecture: "x86", + availableArchitectures: ["x86"], + }); + if (!resolved.ok || resolved.value.profile === null) + throw new Error("Expected a COM analysis profile"); + expect(resolved.value.profile.parameters).toMatchObject({ + loader: "BinaryLoader", + load_address: "1000:0100", + load_segment: "0x1000", + register_context: { + CS: "0x1000", + DS: "0x1000", + ES: "0x1000", + SS: "0x1000", + }, + loader_fallback: { loader: "ComLoader", reason: "recognition_score" }, + }); + }); +}); diff --git a/src/ghidra/GhidraComImport.ts b/src/ghidra/GhidraComImport.ts new file mode 100644 index 0000000000..7f2a19b2d0 --- /dev/null +++ b/src/ghidra/GhidraComImport.ts @@ -0,0 +1,237 @@ +import { sha256Hex } from "../kernel/sha256Hex.js"; +import type { ArtifactResourceScope } from "../resources/index.js"; +import { AnalysisArtifactChangedError } from "../domain/analysisErrorCore.js"; +import type { AnalysisError } from "../domain/analysisErrorBase.js"; +import { err, ok, type Result } from "../domain/result.js"; +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; +import { + ghidraFileDialect, + readGhidraProfileArtifact, +} from "./GhidraFileArtifacts.js"; +import { ghidraSnapshotFileName } from "./GhidraTargetSnapshot.js"; + +/** + * Ghidra 12.2 ComLoader acceptance, used to commit the import selection. The + * prepare script still requires the program Ghidra actually created. + * + * ComLoader (`ghidra.app.util.opinion.ComLoader` in 12.2) returns no load spec + * unless the provider name ends in `.com`, the bytes are not an MZ image, and + * its recognition score reaches 12. The score counts DOS `INT` opcodes and + * `$`-terminated strings the same way that class does, including the extra + * points it adds after an `INT 21h` or `INT 20h` that already matched. + */ +const COM_SCORE_THRESHOLD = 12; + +export const GHIDRA_COM_EXECUTABLE_FORMAT = "Old-style DOS Executable (COM)"; +export const GHIDRA_COM_LOADER = "ComLoader"; +export const GHIDRA_COM_BINARY_LOADER = "BinaryLoader"; +export const GHIDRA_COM_LOAD_ADDRESS = "0000:0100"; +export const GHIDRA_COM_LINEAR_ADDRESS = "0x100"; +export const GHIDRA_COM_LOAD_SEGMENT = "0x0"; +export const GHIDRA_COM_SEGMENT_REGISTER = "0x0"; +export const GHIDRA_COM_BINARY_LOAD_ADDRESS = "1000:0100"; +export const GHIDRA_COM_BINARY_LINEAR_ADDRESS = "0x10100"; +export const GHIDRA_COM_BINARY_LOAD_SEGMENT = "0x1000"; +export const GHIDRA_COM_BINARY_SEGMENT_REGISTER = "0x1000"; +export const GHIDRA_COM_ENTRY_OFFSET = "0x100"; + +export const GHIDRA_COM_LOADER_REJECTIONS = [ + "filename_extension", + "mz_signature", + "recognition_score", +] as const; + +/** Why Ghidra 12.2 ComLoader returns no load spec for an admitted COM image. */ +export type GhidraComLoaderRejection = + (typeof GHIDRA_COM_LOADER_REJECTIONS)[number]; + +/** The import REA asks Ghidra to perform for one explicit DOS COM target. */ +export interface GhidraComImportSelection { + readonly loader: typeof GHIDRA_COM_LOADER | typeof GHIDRA_COM_BINARY_LOADER; + readonly loadAddress: + | typeof GHIDRA_COM_LOAD_ADDRESS + | typeof GHIDRA_COM_BINARY_LOAD_ADDRESS; + readonly loadSegment: + | typeof GHIDRA_COM_LOAD_SEGMENT + | typeof GHIDRA_COM_BINARY_LOAD_SEGMENT; + readonly linearAddress: + | typeof GHIDRA_COM_LINEAR_ADDRESS + | typeof GHIDRA_COM_BINARY_LINEAR_ADDRESS; + readonly segmentRegister: + | typeof GHIDRA_COM_SEGMENT_REGISTER + | typeof GHIDRA_COM_BINARY_SEGMENT_REGISTER; + readonly executableFormat: typeof GHIDRA_COM_EXECUTABLE_FORMAT | "Raw Binary"; + readonly fallback?: { + readonly loader: typeof GHIDRA_COM_LOADER; + readonly reason: GhidraComLoaderRejection; + }; +} + +const binaryFallback = ( + reason: GhidraComLoaderRejection, +): GhidraComImportSelection => ({ + loader: GHIDRA_COM_BINARY_LOADER, + loadAddress: GHIDRA_COM_BINARY_LOAD_ADDRESS, + loadSegment: GHIDRA_COM_BINARY_LOAD_SEGMENT, + linearAddress: GHIDRA_COM_BINARY_LINEAR_ADDRESS, + segmentRegister: GHIDRA_COM_BINARY_SEGMENT_REGISTER, + executableFormat: "Raw Binary", + fallback: { loader: GHIDRA_COM_LOADER, reason }, +}); + +const comLoaderSelection = (): GhidraComImportSelection => ({ + loader: GHIDRA_COM_LOADER, + loadAddress: GHIDRA_COM_LOAD_ADDRESS, + loadSegment: GHIDRA_COM_LOAD_SEGMENT, + linearAddress: GHIDRA_COM_LINEAR_ADDRESS, + segmentRegister: GHIDRA_COM_SEGMENT_REGISTER, + executableFormat: GHIDRA_COM_EXECUTABLE_FORMAT, +}); + +const isPrintable = (value: number): boolean => value >= 0x20 && value <= 0x7e; + +/** + * Count `$`-terminated printable runs the way ComLoader.countDollarStrings does. + * + * That loop restarts inside a printable run that has no `$`, so a 64 KiB image + * of printable bytes is quadratic and blocks profile resolution. Inside one + * printable run an earlier start sees every `$` a later start could use, so a + * miss skips the rest of the run. A hit resumes at the byte after that `$`, + * the same index ComLoader's `for` increment reaches after `i += len`. + */ +const countDollarStrings = (data: Uint8Array): number => { + let count = 0; + const minLength = 4; + const limit = data.length - minLength; + let index = 0; + while (index < limit && count < 3) { + if (!isPrintable(data[index]!)) { + index += 1; + continue; + } + let end = index + 1; + while (end < data.length && isPrintable(data[end]!)) end += 1; + let start = index; + while (start < limit && start < end && count < 3) { + let dollar = start + minLength; + while (dollar < end && data[dollar] !== 0x24) dollar += 1; + if (dollar >= end) break; + count += 1; + start = dollar + 1; + } + index = end; + } + return count; +}; + +/** ComLoader.calculateScore for one image that already passed the length gate. */ +export const ghidraComRecognitionScore = (data: Uint8Array): number => { + let score = 0; + for ( + let index = 0; + index < data.length - 2 && score < COM_SCORE_THRESHOLD; + index++ + ) { + if (data[index] !== 0xcd) continue; + if (data[index + 1] === 0x21) { + score += 2; + if (index >= 2 && (data[index - 2] === 0xb4 || data[index - 2] === 0xb0)) + score += 3; + if (index >= 3 && data[index - 3] === 0xb8) score += 2; + if (score >= COM_SCORE_THRESHOLD) return score; + } else if (data[index + 1] === 0x20) { + score += 2; + if (score >= COM_SCORE_THRESHOLD) return score; + } + if (index > 1 && (data[index - 2] === 0xb4 || data[index - 2] === 0xb0)) + score += 2; + if (index > 2 && data[index - 3] === 0xb8) score += 2; + if (score >= COM_SCORE_THRESHOLD) return score; + } + const dollarStrings = countDollarStrings(data); + if (dollarStrings > 0) score += 3; + if (dollarStrings > 2) score += 2; + return score; +}; + +/** + * Choose ComLoader, or the explicit BinaryLoader fallback, for one admitted + * DOS COM image. `filename` is the provider name Ghidra will see. + */ +export const selectGhidraComImport = ( + filename: string, + bytes: Uint8Array, +): GhidraComImportSelection => { + if (!filename.toLowerCase().endsWith(".com")) + return binaryFallback("filename_extension"); + if (bytes.length > 1 && bytes[0] === 0x4d && bytes[1] === 0x5a) + return binaryFallback("mz_signature"); + if (ghidraComRecognitionScore(bytes) < COM_SCORE_THRESHOLD) + return binaryFallback("recognition_score"); + return comLoaderSelection(); +}; + +/** Read the admitted COM image once and select its Ghidra loader. */ +export const resolveGhidraComImport = async ( + target: { readonly path: string; readonly sha256: string }, + resources: ArtifactResourceScope, + signal?: AbortSignal, +): Promise> => { + let bytes: Buffer; + try { + bytes = await readGhidraProfileArtifact( + target.path, + 0xff00, + resources, + signal, + (value) => value, + ); + } catch (cause: unknown) { + return err( + classifyProviderFailure( + cause, + ghidraFileDialect("resolve_analysis_profile", { path: target.path }), + ), + ); + } + if (sha256Hex(bytes) !== target.sha256) + return err( + new AnalysisArtifactChangedError( + "resolve_analysis_profile", + target.path, + "DOS COM bytes changed before import selection", + ), + ); + // ComLoader's name gate reads the imported snapshot, not the caller's path. + return ok( + selectGhidraComImport( + ghidraSnapshotFileName(target.path, target.sha256), + bytes, + ), + ); +}; + +/** Read the selected import once for launch and independent attestation. */ +export const ghidraProfileComImport = ( + parameters: Readonly>, +): Result => { + const loader = parameters.loader; + if (loader === GHIDRA_COM_LOADER && parameters.loader_fallback === undefined) + return ok(comLoaderSelection()); + if (loader === GHIDRA_COM_BINARY_LOADER) { + const fallback = parameters.loader_fallback; + if ( + typeof fallback === "object" && + fallback !== null && + "loader" in fallback && + fallback.loader === GHIDRA_COM_LOADER && + "reason" in fallback + ) { + const reason = GHIDRA_COM_LOADER_REJECTIONS.find( + (candidate) => candidate === fallback.reason, + ); + if (reason !== undefined) return ok(binaryFallback(reason)); + } + } + return err("The DOS COM analysis profile has no valid loader selection."); +}; diff --git a/src/ghidra/GhidraDosComLoadImage.test.ts b/src/ghidra/GhidraDosComLoadImage.test.ts index d241227850..e2a276effd 100644 --- a/src/ghidra/GhidraDosComLoadImage.test.ts +++ b/src/ghidra/GhidraDosComLoadImage.test.ts @@ -1,12 +1,30 @@ import { describe, expect, it } from "vitest"; +import { selectGhidraComImport } from "./GhidraComImport.js"; import { attestGhidraDosComLoadImage } from "./GhidraLoadImageValues.js"; -import { fixtureDosComLoadImage } from "./GhidraLoadImage.fixture.js"; +import { + compareDosFixture, + fixtureDosComLoadImage, + fixtureDosComLoaderLoadImage, + fixtureDosLoadImage, +} from "./GhidraLoadImage.fixture.js"; import { nativeLoadImageObservationSchema, nativeLoadImageSchema, type NativeLoadImageObservation, } from "../domain/native/nativeLoadImage.js"; +const attestComFixture = ({ + bytes, + sha256, + observation, +}: ReturnType) => + attestGhidraDosComLoadImage( + bytes, + sha256, + observation, + selectGhidraComImport("fixture.com", bytes), + ); + const mutations: ReadonlyArray< readonly [string, (o: NativeLoadImageObservation) => void] > = [ @@ -91,11 +109,7 @@ const mutations: ReadonlyArray< describe("COM independent load-image checks", () => { it("verifies all bytes and the imposed entry context without a PSP claim", () => { const f = fixtureDosComLoadImage(); - const result = attestGhidraDosComLoadImage( - f.bytes, - f.sha256, - f.observation, - ); + const result = attestComFixture(f); expect(result).toMatchObject({ ok: true, value: { @@ -104,6 +118,9 @@ describe("COM independent load-image checks", () => { header_bytes: 0, module_bytes: 4, overlay_bytes: 0, + loader: "BinaryLoader", + load_address: "1000:0100", + loader_fallback: { loader: "ComLoader", reason: "recognition_score" }, entry: { relative_segment: 0, offset: 0x100, @@ -112,14 +129,67 @@ describe("COM independent load-image checks", () => { }, }); }); + it("verifies a ComLoader image at 0000:0100 including the zero PSP placeholder", () => { + const f = fixtureDosComLoaderLoadImage(); + const result = attestComFixture(f); + expect(result).toMatchObject({ + ok: true, + value: { + status: "verified", + format: "dos-com", + loader: "ComLoader", + load_address: "0000:0100", + load_segment: 0, + header_bytes: 0, + module_bytes: f.bytes.length, + entry: { + relative_segment: 0, + offset: 0x100, + linear_address: "0x100", + }, + }, + }); + expect(result.ok && result.value).not.toHaveProperty("loader_fallback"); + }); + it("reports mismatch coordinates from the measured import", () => { + const f = fixtureDosComLoadImage(); + f.observation.executable_format = "Old-style DOS Executable (COM)"; + if (f.observation.mappings[0]) f.observation.mappings[0].start = "0x100"; + const result = attestComFixture(f); + expect(result).toMatchObject({ + ok: true, + value: { + status: "mismatch", + loader: "ComLoader", + load_address: "0000:0100", + load_segment: 0, + entry: { linear_address: "0x100" }, + }, + }); + }); + it("omits load segment and entry when the measured import is not a known COM layout", () => { + const f = fixtureDosComLoadImage(); + if (f.observation.mappings[0]) f.observation.mappings[0].start = "0x200"; + const result = attestComFixture(f); + if (!result.ok || !("checks" in result.value)) + throw new Error("Expected a retained mismatch"); + expect(result.value.status).toBe("mismatch"); + expect(result.value).toMatchObject({ loader: "BinaryLoader" }); + expect(result.value).not.toHaveProperty("load_address"); + expect(result.value).not.toHaveProperty("load_segment"); + expect(result.value).not.toHaveProperty("entry"); + expect( + result.value.checks.find((item) => item.name === "load_address"), + ).toMatchObject({ + matched: false, + expected: "1000:0100", + observed: null, + }); + }); it.each(mutations)("retains mismatch evidence for %s", (_name, damage) => { const f = fixtureDosComLoadImage(); damage(f.observation); - const result = attestGhidraDosComLoadImage( - f.bytes, - f.sha256, - f.observation, - ); + const result = attestComFixture(f); expect(result).toMatchObject({ ok: true, value: { status: "mismatch", observations: f.observation }, @@ -162,8 +232,70 @@ describe("COM independent load-image checks", () => { it("rejects stale snapshot identity", () => { const f = fixtureDosComLoadImage(); - expect( - attestGhidraDosComLoadImage(f.bytes, "f".repeat(64), f.observation).ok, - ).toBe(false); + expect(attestComFixture({ ...f, sha256: "f".repeat(64) }).ok).toBe(false); + }); +}); + +describe("COM load-image field contracts", () => { + it("keeps a measured load address when the executable format is unknown", () => { + const f = fixtureDosComLoadImage(); + f.observation.executable_format = "not-a-loader"; + const result = attestComFixture(f); + if (!result.ok || !("checks" in result.value)) + throw new Error("Expected a retained mismatch"); + expect(result.value).toMatchObject({ + status: "mismatch", + load_address: "1000:0100", + }); + expect(result.value).not.toHaveProperty("loader"); + expect(result.value).not.toHaveProperty("load_segment"); + expect(result.value).not.toHaveProperty("entry"); + }); + it("rejects a DOS MZ result that omits its load segment or entry", () => { + const f = fixtureDosLoadImage(); + const attested = compareDosFixture(f.bytes, f.sha256, f.observation); + if ( + !attested.ok || + attested.value.status === "unsupported" || + attested.value.format !== "dos-mz" + ) { + throw new Error(attested.ok ? "expected DOS MZ" : attested.error); + } + expect(nativeLoadImageSchema.safeParse(attested.value).success).toBe(true); + const { load_segment: _segment, ...withoutSegment } = attested.value; + expect(nativeLoadImageSchema.safeParse(withoutSegment).success).toBe(false); + const { entry: _entry, ...withoutEntry } = attested.value; + expect(nativeLoadImageSchema.safeParse(withoutEntry).success).toBe(false); + }); + it("rejects a verified COM result that omits its loader or mixes layouts", () => { + const recognized = attestComFixture(fixtureDosComLoaderLoadImage()); + if ( + !recognized.ok || + recognized.value.status !== "verified" || + recognized.value.format !== "dos-com" || + recognized.value.loader !== "ComLoader" + ) + throw new Error("expected a verified ComLoader image"); + expect(nativeLoadImageSchema.safeParse(recognized.value).success).toBe( + true, + ); + const { loader: _loader, ...withoutLoader } = recognized.value; + expect(nativeLoadImageSchema.safeParse(withoutLoader).success).toBe(false); + expect( + nativeLoadImageSchema.safeParse({ + ...recognized.value, + load_address: "1000:0100", + }).success, + ).toBe(false); + const fallback = attestComFixture(fixtureDosComLoadImage()); + if ( + !fallback.ok || + fallback.value.status !== "verified" || + fallback.value.format !== "dos-com" || + fallback.value.loader !== "BinaryLoader" + ) + throw new Error("expected a verified fallback image"); + const { loader_fallback: _fallback, ...withoutReason } = fallback.value; + expect(nativeLoadImageSchema.safeParse(withoutReason).success).toBe(false); }); }); diff --git a/src/ghidra/GhidraLanguageOverride.test.ts b/src/ghidra/GhidraLanguageOverride.test.ts index 1b9baeeb24..480fbea1b2 100644 --- a/src/ghidra/GhidraLanguageOverride.test.ts +++ b/src/ghidra/GhidraLanguageOverride.test.ts @@ -1,3 +1,4 @@ +import { createHash } from "node:crypto"; import { chmod, mkdir, readdir, rm, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { afterAll, beforeAll, describe, expect, it } from "vitest"; @@ -116,6 +117,18 @@ afterAll(async () => { await disposeInstallDir?.(); }); +const lowScoreDosCom = async (target: BinaryTarget): Promise => { + const directory = await createTestTempDirectory("rea-com-profile-"); + const path = join(directory, "fixture.com"); + const bytes = Buffer.from("b83412c3", "hex"); + await writeFile(path, bytes); + return { + ...target, + path, + sha256: createHash("sha256").update(bytes).digest("hex"), + }; +}; + const provider = (environment: Record) => { const parsed = parseConfig({ GHIDRA_INSTALL_DIR: installDir, @@ -447,7 +460,9 @@ describe("Ghidra language override profile", () => { ], }, }); - const automatic = await provider({}).resolveAnalysisProfile(target); + const admitted = + format === "dos-com" ? await lowScoreDosCom(target) : target; + const automatic = await provider({}).resolveAnalysisProfile(admitted); expect(automatic.ok).toBe(true); }, ); diff --git a/src/ghidra/GhidraLauncher.ts b/src/ghidra/GhidraLauncher.ts index 358982c782..7e4ccf93f8 100644 --- a/src/ghidra/GhidraLauncher.ts +++ b/src/ghidra/GhidraLauncher.ts @@ -240,7 +240,8 @@ export interface GhidraHeadlessLauncherOptions { readonly comSpec?: string; /** Select the admitted 16-bit real-mode MZ import instead of auto-detection. */ readonly dosMz?: true; - readonly dosCom?: true; + /** DOS COM import selected from the committed analysis profile. */ + readonly dosCom?: { readonly loader: "ComLoader" | "BinaryLoader" }; readonly rawBinary?: { readonly languageId: string; readonly compilerSpecId: string; @@ -794,7 +795,7 @@ export interface GhidraHeadlessArgumentOptions { readonly mipsSoftFloat?: true; readonly riscvCallingConvention?: GhidraRiscvCallingConvention; readonly dosMz?: true; - readonly dosCom?: true; + readonly dosCom?: { readonly loader: "ComLoader" | "BinaryLoader" }; readonly rawBinary?: { readonly languageId: string; readonly compilerSpecId: string; @@ -843,7 +844,7 @@ const validateExistingProjectOptions = ( throw new GhidraAdmissionError("existing_project_program_name"); if (options.psp === true) throw new GhidraAdmissionError("existing_project_psp"); - if (options.dosMz === true || options.dosCom === true) + if (options.dosMz === true || options.dosCom !== undefined) throw new GhidraAdmissionError("existing_project_dos"); if (rawBinary !== undefined) throw new GhidraAdmissionError("existing_project_raw_binary"); @@ -882,7 +883,7 @@ export const ghidraHeadlessArguments = ( gamecubeDol !== undefined && (options.psp === true || options.dosMz === true || - options.dosCom === true || + options.dosCom !== undefined || options.mipsSoftFloat === true || options.riscvCallingConvention !== undefined || rawBinary !== undefined || @@ -892,7 +893,7 @@ export const ghidraHeadlessArguments = ( if ( options.psp === true && (options.dosMz === true || - options.dosCom === true || + options.dosCom !== undefined || override !== undefined) ) throw new GhidraAdmissionError("psp_combined"); @@ -902,7 +903,7 @@ export const ghidraHeadlessArguments = ( options.mipsSoftFloat === true && (options.psp === true || options.dosMz === true || - options.dosCom === true || + options.dosCom !== undefined || rawBinary !== undefined) ) throw new GhidraAdmissionError("mips_soft_float_scope"); @@ -911,20 +912,20 @@ export const ghidraHeadlessArguments = ( (options.psp === true || options.mipsSoftFloat === true || options.dosMz === true || - options.dosCom === true || + options.dosCom !== undefined || rawBinary !== undefined) ) throw new GhidraAdmissionError("riscv_calling_convention_scope"); if ( override !== undefined && - (options.dosMz === true || options.dosCom === true) + (options.dosMz === true || options.dosCom !== undefined) ) throw new GhidraAdmissionError("language_override_dos"); if (override !== undefined && rawBinary !== undefined) throw new GhidraAdmissionError("language_override_raw_binary"); if ( rawBinary !== undefined && - (options.dosMz === true || options.dosCom === true) + (options.dosMz === true || options.dosCom !== undefined) ) throw new GhidraAdmissionError("raw_binary_dos"); return [ @@ -956,12 +957,15 @@ export const ghidraHeadlessArguments = ( "-cspec", "default", ] - : options.dosCom === true + : options.dosCom !== undefined ? [ "-loader", - "BinaryLoader", - "-loader-baseAddr", - "1000:0100", + options.dosCom.loader, + // ComLoader owns 0000:0100. BinaryLoader is the explicit + // fallback and still needs the real-mode segment base. + ...(options.dosCom.loader === "BinaryLoader" + ? ["-loader-baseAddr", "1000:0100"] + : []), "-processor", "x86:LE:16:Real Mode", "-cspec", @@ -1013,7 +1017,7 @@ export const ghidraHeadlessArguments = ( options.scriptLogPath, "-scriptPath", bridgeDirectory, - ...(options.dosCom === true + ...(options.dosCom !== undefined ? [ "-preScript", scriptPath.join(bridgeDirectory, GHIDRA_BRIDGE_SOURCES.prepareCom), diff --git a/src/ghidra/GhidraLoadImage.fixture.ts b/src/ghidra/GhidraLoadImage.fixture.ts index cf07e61847..86789acfec 100644 --- a/src/ghidra/GhidraLoadImage.fixture.ts +++ b/src/ghidra/GhidraLoadImage.fixture.ts @@ -221,13 +221,14 @@ export const fixtureDosOverlapLoadImage = () => { return { bytes, sha256: hash(bytes), observation }; }; -/** Source-owned headerless COM image and measured real-mode import facts. */ -export const fixtureDosComLoadImage = (): { +/** Source-owned COM image ComLoader rejects, imported by the raw fallback. */ +export const fixtureDosComLoadImage = ( + bytes: Buffer = Buffer.from("b83412c3", "hex"), +): { bytes: Buffer; sha256: string; observation: NativeLoadImageObservation; } => { - const bytes = Buffer.from("b83412c3", "hex"); const digest = hash(bytes); return { bytes, @@ -250,7 +251,7 @@ export const fixtureDosComLoadImage = (): { { block: "ram", start: "0x10100", - end: "0x10103", + end: `0x${(0x10100 + bytes.length - 1).toString(16)}`, address_space: "ram", initialized: true, loaded: true, @@ -278,3 +279,79 @@ export const fixtureDosComLoadImage = (): { }, }; }; + +/** Source-owned COM image Ghidra 12.2 ComLoader accepts, at 0000:0100. */ +export const fixtureDosComLoaderLoadImage = (): { + bytes: Buffer; + sha256: string; + observation: NativeLoadImageObservation; +} => { + const bytes = Buffer.alloc(16, 0x90); + bytes.set(Buffer.from("b409cd21b409cd21", "hex")); + const digest = hash(bytes); + const psp = Buffer.alloc(0x100); + return { + bytes, + sha256: digest, + observation: { + executable_format: "Old-style DOS Executable (COM)", + language_id: "x86:LE:16:Real Mode", + compiler_spec_id: "default", + image_base: "0x0", + default_address_space: "ram", + source_files: [ + { + name: "fixture.com", + size: bytes.length, + original_sha256: digest, + modified_sha256: digest, + }, + ], + mappings: [ + { + block: "PSP", + start: "0x0", + end: "0xff", + address_space: "ram", + initialized: true, + loaded: true, + overlay: false, + readable: true, + writable: true, + executable: false, + length: psp.length, + source_file_index: null, + file_offset: null, + sha256: hash(psp), + }, + { + block: "CODE", + start: "0x100", + end: "0x10f", + address_space: "ram", + initialized: true, + loaded: true, + overlay: false, + readable: true, + writable: true, + executable: false, + length: bytes.length, + source_file_index: 0, + file_offset: 0, + sha256: digest, + }, + ], + relocations: [], + entry_points: ["0x100"], + entry_context: [ + { + address: "0x100", + registers: ["CS", "DS", "ES", "SS"].map((name) => ({ + name, + value_hex: "0x0", + })), + }, + ], + }, + }; +}; diff --git a/src/ghidra/GhidraLoadImageAttest.test.ts b/src/ghidra/GhidraLoadImageAttest.test.ts index 44abe6fb34..00b1650ce2 100644 --- a/src/ghidra/GhidraLoadImageAttest.test.ts +++ b/src/ghidra/GhidraLoadImageAttest.test.ts @@ -20,6 +20,7 @@ import { fixtureDosComLoadImage, } from "./GhidraLoadImage.fixture.js"; import { fixtureRawBinaryLoadImage } from "./GhidraRawBinaryLoadImage.fixture.js"; +import { selectGhidraComImport } from "./GhidraComImport.js"; import { attestGhidraNativeLoadImage } from "./GhidraLoadImageAttest.js"; import { limitationsFor } from "./GhidraProviderCapabilities.js"; import { @@ -56,6 +57,10 @@ it.each(["dos-mz", "dos-com", "raw-binary"] as const)( operation: "inspect_native_load_image", target: fixture.target, measured: fixture.observation, + comSelection: + format === "dos-com" && "bytes" in fixture + ? selectGhidraComImport("fixture.com", fixture.bytes) + : undefined, client: format === "dos-mz" && "bytes" in fixture ? { diff --git a/src/ghidra/GhidraLoadImageAttest.ts b/src/ghidra/GhidraLoadImageAttest.ts index 11ad6c0b91..6a269fad69 100644 --- a/src/ghidra/GhidraLoadImageAttest.ts +++ b/src/ghidra/GhidraLoadImageAttest.ts @@ -21,6 +21,7 @@ import { } from "./GhidraVerifiedLoadImageFormats.js"; import type { GhidraLanguageOverride } from "../config/ghidraLanguageOverride.js"; import type { NativeAotPeResult } from "../domain/native/nativeAotPe.js"; +import type { GhidraComImportSelection } from "./GhidraComImport.js"; import type { GhidraClient } from "./GhidraClient.js"; import type { GhidraSessionError } from "./GhidraSessionError.js"; @@ -41,6 +42,7 @@ type NativeLoadImageAttestationInput = { readonly nativeAotResult?: NativeAotPeResult | undefined; /** Import language committed by the profile; DOL attestation expects it. */ readonly languageOverride?: GhidraLanguageOverride | undefined; + readonly comSelection?: GhidraComImportSelection | undefined; readonly signal?: AbortSignal | undefined; }; @@ -208,6 +210,13 @@ const compareLoadImage = async ( const compared = await client.attestDosTargetSnapshot(observations, signal); return compared.ok ? compared : err(sourceFailure(compared.error)); } + if (input.comSelection === undefined) + return err( + comparisonFailure( + input, + "The DOS COM import selection was not committed.", + ), + ); if (client.readTargetSnapshot === undefined) return err( comparisonFailure( @@ -228,6 +237,7 @@ const compareLoadImage = async ( snapshot.value.bytes, target.sha256, observations, + input.comSelection, ); return attested.ok ? attested : err(comparisonFailure(input, attested.error)); }; diff --git a/src/ghidra/GhidraLoadImageValues.ts b/src/ghidra/GhidraLoadImageValues.ts index 6f49fcfe99..3d6b7e802d 100644 --- a/src/ghidra/GhidraLoadImageValues.ts +++ b/src/ghidra/GhidraLoadImageValues.ts @@ -10,6 +10,10 @@ import { validateDosComLength } from "../domain/dosCom.js"; import { err, ok, type Result } from "../domain/result.js"; import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js"; import { sha256Hex } from "../kernel/sha256Hex.js"; +import { + GHIDRA_COM_EXECUTABLE_FORMAT, + type GhidraComImportSelection, +} from "./GhidraComImport.js"; const address = (offset: number): string => `0x${offset.toString(16)}`; const GHIDRA_DOS_LOAD_VERIFICATION_LIMITATION = @@ -282,11 +286,71 @@ const checkMappings = ( ); }; +const ZERO_PSP_SHA256 = sha256Hex(Buffer.alloc(0x100)); + +const observedComLoader = ( + format: string, +): GhidraComImportSelection["loader"] | null => + format === GHIDRA_COM_EXECUTABLE_FORMAT + ? "ComLoader" + : format === "Raw Binary" + ? "BinaryLoader" + : null; + +const observedComLoadAddress = ( + start: string | null, +): GhidraComImportSelection["loadAddress"] | null => + start === "0x100" ? "0000:0100" : start === "0x10100" ? "1000:0100" : null; + +const COM_HEADERLESS_LIMITATION = + "DOS COM is a headerless interpretation explicitly selected by the caller, not format identification from file bytes."; +const COM_UNVERIFIED_RUNTIME_LIMITATION = + "The initial stack contents/registers, DOS interrupts, PC-98 devices and runtime behavior are not modeled or verified. No original executable bytes are changed."; +const COM_MAPPING_END_LIMITATION = + "Mapping ends are inclusive; a mismatching digest identifies its source range, not the first differing byte."; + +/** Coordinates and limitations for one measured COM layout, not the selector. */ +const appliedComLayout = ( + loader: GhidraComImportSelection["loader"] | null, + loadAddress: GhidraComImportSelection["loadAddress"] | null, +): { + readonly loadSegment: number; + readonly linearAddress: "0x100" | "0x10100"; + readonly limitations: readonly string[]; +} | null => { + if (loader === "ComLoader" && loadAddress === "0000:0100") + return { + loadSegment: 0, + linearAddress: "0x100", + limitations: [ + COM_HEADERLESS_LIMITATION, + "Ghidra ComLoader mapped a 256-byte zero-filled PSP placeholder at 0000:0000 and the file at 0000:0100 (linear 0x100). The placeholder is not file-backed and is not an observed DOS PSP.", + "Verification covers complete original/modified source identity, the placeholder and mapped file bytes, entry and measured CS/DS/ES/SS entry context. Context 0x0 is imposed for analysis; it is not an observed running process.", + COM_UNVERIFIED_RUNTIME_LIMITATION, + COM_MAPPING_END_LIMITATION, + ], + }; + if (loader === "BinaryLoader" && loadAddress === "1000:0100") + return { + loadSegment: 0x1000, + linearAddress: "0x10100", + limitations: [ + COM_HEADERLESS_LIMITATION, + "The measured BinaryLoader layout places the file at 1000:0100 (linear 0x10100).", + "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.", + COM_MAPPING_END_LIMITATION, + ], + }; + return null; +}; + /** Verify the explicit DOS COM interpretation against measured bytes and context. */ export const attestGhidraDosComLoadImage = ( bytes: Buffer, targetSha256: string, observations: NativeLoadImageObservation, + selection: GhidraComImportSelection, ): Result => { if (sha256Hex(bytes) !== targetSha256) return err("Ghidra COM snapshot digest does not match the admitted target"); @@ -294,7 +358,20 @@ export const attestGhidraDosComLoadImage = ( if (!length.ok) return length; const { checks, check } = createLoadImageChecks(); const source = observations.source_files[0]; - check("executable_format", "Raw Binary", observations.executable_format); + const observedLoader = observedComLoader(observations.executable_format); + const fileMapping = observations.mappings.find( + (mapping) => mapping.file_offset === 0 && mapping.source_file_index === 0, + ); + const observedLoadAddress = observedComLoadAddress( + fileMapping?.start ?? null, + ); + check( + "executable_format", + selection.executableFormat, + observations.executable_format, + ); + check("loader", selection.loader, observedLoader); + check("load_address", selection.loadAddress, observedLoadAddress); 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); @@ -303,50 +380,129 @@ export const attestGhidraDosComLoadImage = ( 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_points", + [selection.linearAddress], + [...observations.entry_points].sort(), + ); check( "entry_context", [ { - address: "0x10100", + address: selection.linearAddress, registers: ["CS", "DS", "ES", "SS"].map((name) => ({ name, - value_hex: "0x1000", + value_hex: selection.segmentRegister, })), }, ], observations.entry_context, ); check("relocation_records", [], observations.relocations); - checkMappings( - { headerBytes: 0, imageBytes: bytes.length }, - 0x10100, - bytes, - observations, - check, - ); + if (selection.loader === "ComLoader") + checkComLoaderMappings(bytes, observations, check); + else + checkMappings( + { headerBytes: 0, imageBytes: bytes.length }, + 0x10100, + bytes, + observations, + check, + ); + const matched = checks.every((item) => item.matched); + const applied = appliedComLayout(observedLoader, observedLoadAddress); return ok( nativeLoadImageSchema.parse({ - status: checks.every((item) => item.matched) ? "verified" : "mismatch", + status: matched ? "verified" : "mismatch", format: "dos-com", + ...(observedLoader === null ? {} : { loader: observedLoader }), + ...(observedLoadAddress === null + ? {} + : { load_address: observedLoadAddress }), + ...(selection.fallback === undefined || observedLoader !== "BinaryLoader" + ? {} + : { loader_fallback: selection.fallback }), target_sha256: targetSha256, - load_segment: 0x1000, + ...(applied === null + ? {} + : { + load_segment: applied.loadSegment, + entry: { + relative_segment: 0, + offset: 0x100, + linear_address: applied.linearAddress, + }, + }), 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.", - ], + limitations: + applied === null + ? [ + COM_HEADERLESS_LIMITATION, + "The measured loader and load address are not a known COM import. checks retain the expected and observed values. No load segment or entry was derived.", + COM_MAPPING_END_LIMITATION, + ] + : [...applied.limitations], }), ); }; +const checkComLoaderMappings = ( + bytes: Buffer, + observations: NativeLoadImageObservation, + check: ReturnType["check"], +): void => { + const psp = observations.mappings.find((mapping) => mapping.start === "0x0"); + const code = observations.mappings.find( + (mapping) => mapping.start === "0x100", + ); + check("mapping_count", 2, observations.mappings.length); + check("psp.block", "PSP", psp?.block ?? null); + check("psp.end", "0xff", psp?.end ?? null, null, psp?.end ?? null); + check("psp.length", 0x100, psp?.length ?? null); + check("psp.initialized", true, psp?.initialized ?? null); + check("psp.loaded", true, psp?.loaded ?? null); + check("psp.overlay", false, psp?.overlay ?? null); + check("psp.readable", true, psp?.readable ?? null); + check("psp.writable", true, psp?.writable ?? null); + check("psp.executable", false, psp?.executable ?? null); + check("psp.source_file_index", null, psp?.source_file_index ?? null); + check("psp.file_offset", null, psp?.file_offset ?? null); + check("psp.memory_sha256", ZERO_PSP_SHA256, psp?.sha256 ?? null, null, "0x0"); + check("code.block", "CODE", code?.block ?? null); + check( + "code.end", + address(0x100 + bytes.length - 1), + code?.end ?? null, + 0, + code?.end ?? null, + ); + check("code.length", bytes.length, code?.length ?? null, 0, "0x100"); + check("code.initialized", true, code?.initialized ?? null); + check("code.loaded", true, code?.loaded ?? null); + check("code.overlay", false, code?.overlay ?? null); + check("code.readable", true, code?.readable ?? null); + check("code.writable", true, code?.writable ?? null); + check("code.executable", false, code?.executable ?? null); + check("code.source_file_index", 0, code?.source_file_index ?? null); + check("code.file_offset", 0, code?.file_offset ?? null, 0, "0x100"); + check( + "code.memory_sha256", + sha256Hex(bytes), + code?.sha256 ?? null, + 0, + "0x100", + ); + check( + "code.address_space", + observations.default_address_space, + code?.address_space ?? null, + ); +}; + const hexAddress = (value: bigint): string => `0x${value.toString(16)}`; /** Verify a caller-supplied raw-binary mapping against measured Ghidra import facts. */ diff --git a/src/ghidra/GhidraProvider.behavior.test.ts b/src/ghidra/GhidraProvider.behavior.test.ts index 2d44162120..d72f71ae3d 100644 --- a/src/ghidra/GhidraProvider.behavior.test.ts +++ b/src/ghidra/GhidraProvider.behavior.test.ts @@ -65,6 +65,8 @@ import { import * as nativeLoader from "../windows/WindowsNativeLoader.js"; import { fixtureDosLoadImage, + fixtureDosComLoadImage, + fixtureDosComLoaderLoadImage, compareDosClientFixture, } from "./GhidraLoadImage.fixture.js"; import { fixtureRawBinaryLoadImage } from "./GhidraRawBinaryLoadImage.fixture.js"; @@ -2731,6 +2733,66 @@ describe("Ghidra measured raw load-image projection", () => { ); }); +it("compares measured COM import evidence against the loader committed at admission", async () => { + const { bytes, sha256 } = fixtureDosComLoaderLoadImage(); + const { observation } = fixtureDosComLoadImage(bytes); + observation.source_files[0]!.name = "fixture.bin"; + const root = await mkdtemp(join(tmpdir(), "rea-ghidra-com-selection-")); + onTestFinished(() => rm(root, { recursive: true, force: true })); + const path = join(root, "fixture.com"); + await writeFile(path, bytes); + const ghidra = provider(installationHost(), () => ({ + start: async () => ok(sessionInfo()), + callTool: async () => ok(jsonValueSchema.parse(observation)), + readTargetSnapshot: async () => ok({ kind: "captured", bytes }), + close: async () => ok(null), + })); + onTestFinished(async () => { + await ghidra.closeOwnedResources(); + }); + const target: BinaryTarget = { + path, + sha256, + kind: "executable", + format: "dos-com", + architecture: "x86", + availableArchitectures: ["x86"], + }; + const profile = await ghidra.resolveAnalysisProfile(target); + if (!profile.ok) throw profile.error; + if (profile.value.profile === null) + throw new Error("Expected a DOS COM profile"); + expect(profile.value.profile.parameters.loader).toBe("ComLoader"); + const client = ghidra.createClient(target, profile.value.profile); + try { + const result = await client.execute("inspect_native_load_image", {}); + if (!result.ok) throw result.error; + expect(result.value.result).toMatchObject({ + status: "mismatch", + loader: "BinaryLoader", + load_address: "1000:0100", + observations: observation, + checks: expect.arrayContaining([ + expect.objectContaining({ + name: "loader", + expected: "ComLoader", + observed: "BinaryLoader", + matched: false, + }), + expect.objectContaining({ + name: "load_address", + expected: "0000:0100", + observed: "1000:0100", + matched: false, + }), + ]), + }); + expect(result.value.result).not.toHaveProperty("loader_fallback"); + } finally { + await client.close(); + } +}); + describe("Ghidra measured DOS load-image projection", () => { it.each([ "verified", diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.ts index a09f6e7639..287a1a33aa 100644 --- a/src/ghidra/GhidraProviderClient.ts +++ b/src/ghidra/GhidraProviderClient.ts @@ -24,6 +24,7 @@ import { analysisErrorWithCleanupDependencies } from "../domain/analysisErrorCle import { artifactFilePrimaryFacts } from "../resources/index.js"; import { fileURLToPath } from "node:url"; import { GHIDRA_BRIDGE_SOURCES } from "./GhidraBridgeSources.js"; +import { ghidraProfileComImport } from "./GhidraComImport.js"; import { GhidraAdmissionError } from "./GhidraAdmissionError.js"; import { GHIDRA_RESTRICTED_TEMP_REMEDIATION } from "./GhidraTemporaryDirectory.js"; import { @@ -358,6 +359,13 @@ export const createGhidraProviderClient = (input: { const prerequisites = ghidraClientPrerequisites(profile, installation); if (!prerequisites.ok) return prerequisites; const committedProfile = prerequisites.value.profile; + const comImport = + target.format === "dos-com" + ? ghidraProfileComImport(committedProfile.parameters) + : undefined; + if (comImport?.ok === false) + return err(ghidraProfileConflict("open_binary", comImport.error)); + const comSelection = comImport?.value; const checkpoint = ghidraCheckpointSelectionSchema .optional() .safeParse(committedProfile.parameters.owned_checkpoint); @@ -669,7 +677,9 @@ export const createGhidraProviderClient = (input: { ? {} : { riscvCallingConvention }), ...(target.format === "dos-mz" ? { dosMz: true } : {}), - ...(target.format === "dos-com" ? { dosCom: true } : {}), + ...(comSelection === undefined + ? {} + : { dosCom: { loader: comSelection.loader } }), ...(rawLanguage === undefined || target.format !== "raw-binary" ? {} : { @@ -980,6 +990,7 @@ export const createGhidraProviderClient = (input: { measured: observed, client, languageOverride: importLanguage, + comSelection, mapSessionError: (failure) => projectSessionError( operation, diff --git a/src/ghidra/GhidraTargetSnapshot.ts b/src/ghidra/GhidraTargetSnapshot.ts index 735ef32516..69b5e29545 100644 --- a/src/ghidra/GhidraTargetSnapshot.ts +++ b/src/ghidra/GhidraTargetSnapshot.ts @@ -1,7 +1,7 @@ import { createHash } from "node:crypto"; import { HOST_PLATFORM } from "../platform/HostPlatform.js"; import { open } from "node:fs/promises"; -import { extname, join } from "node:path"; +import { basename, extname, join } from "node:path"; import { withArtifactRegularFile, withArtifactFileHandle, @@ -46,18 +46,11 @@ export const createGhidraTargetSnapshot = async ( ): Promise => { if (!/^[a-f0-9]{64}$/u.test(expectedSha256)) throw new TypeError("Ghidra target SHA-256 commitment is invalid"); - const suffix = safeExtension(sourcePath); - const snapshotPath = join( - runtimeRoot, - `target-${expectedSha256.slice(0, 12)}${suffix}`, - ); + const snapshotFileName = ghidraSnapshotFileName(sourcePath, expectedSha256); + const snapshotPath = join(runtimeRoot, snapshotFileName); if ((options.platform ?? HOST_PLATFORM.platform) === "win32") { const observed = await windowsPrivateRuntime(runtimeRoot) - .snapshot( - sourcePath, - `target-${expectedSha256.slice(0, 12)}${suffix}`, - options.signal, - ) + .snapshot(sourcePath, snapshotFileName, options.signal) .catch((cause: unknown) => { if (cause instanceof WindowsSnapshotCancelledError) throw new ArtifactReaderFailure("cancelled", cause.message, { @@ -168,6 +161,22 @@ const classifySnapshotFailure = (cause: unknown): unknown => { return cause; }; +/** + * Filename Ghidra's loader receives for one immutable snapshot. + * + * ComLoader accepts a provider name only when it ends in `.com`. Node's + * `extname` treats a basename of `.com` as a dotfile with no extension, so + * that name is preserved explicitly. Selection uses this same filename. + */ +export const ghidraSnapshotFileName = ( + sourcePath: string, + sha256: string, +): string => + `target-${sha256.slice(0, 12)}${ghidraSnapshotExtension(sourcePath)}`; + +const ghidraSnapshotExtension = (sourcePath: string): string => + /^\.com$/iu.test(basename(sourcePath)) ? ".com" : safeExtension(sourcePath); + const safeExtension = (path: string): string => { const extension = extname(path); return /^\.[A-Za-z0-9]{1,12}$/u.test(extension) ? extension : ".bin"; diff --git a/tests/boundary/providers/ghidra/ghidraLauncher.test.ts b/tests/boundary/providers/ghidra/ghidraLauncher.test.ts index 35f9fb32f6..3df34aade3 100644 --- a/tests/boundary/providers/ghidra/ghidraLauncher.test.ts +++ b/tests/boundary/providers/ghidra/ghidraLauncher.test.ts @@ -112,14 +112,14 @@ describe("Ghidra COM loader", () => { descriptorPath: "/tmp/session.json", ghidraLogPath: "/tmp/ghidra.log", scriptLogPath: "/tmp/script.log", - dosCom: true, + dosCom: { loader: "ComLoader" }, }); expectOptions(arguments_, [ - ["-loader", "BinaryLoader"], - ["-loader-baseAddr", "1000:0100"], + ["-loader", "ComLoader"], ["-processor", "x86:LE:16:Real Mode"], ["-cspec", "default"], ]); + expect(arguments_).not.toContain("-loader-baseAddr"); const prepare = arguments_.indexOf("-preScript"); expect(arguments_[prepare + 1]).toBe( join("/package/bridge", "ReaGhidraPrepareCom.java"), @@ -128,6 +128,27 @@ describe("Ghidra COM loader", () => { expect(arguments_).toContain("-readOnly"); expect(arguments_).toContain("-deleteProject"); }); + + it("keeps BinaryLoader at 1000:0100 when ComLoader is not selected", () => { + const arguments_ = ghidraHeadlessArguments({ + projectRoot: "/tmp/project", + targetPath: "/tmp/target.bin", + bridgeScriptPath: "/package/bridge/ReaGhidraBridge.java", + descriptorPath: "/tmp/session.json", + ghidraLogPath: "/tmp/ghidra.log", + scriptLogPath: "/tmp/script.log", + dosCom: { loader: "BinaryLoader" }, + }); + expectOptions(arguments_, [ + ["-loader", "BinaryLoader"], + ["-loader-baseAddr", "1000:0100"], + ["-processor", "x86:LE:16:Real Mode"], + ["-cspec", "default"], + ]); + expect(arguments_).toContain( + join("/package/bridge", "ReaGhidraPrepareCom.java"), + ); + }); }); describe("Ghidra raw-binary loader", () => { @@ -236,7 +257,7 @@ describe("Ghidra GameCube DOL loader", () => { it.each([ ["PSP", { psp: true }], ["DOS MZ", { dosMz: true }], - ["DOS COM", { dosCom: true }], + ["DOS COM", { dosCom: { loader: "ComLoader" } }], ["MIPS soft-float", { mipsSoftFloat: true }], [ "RISC-V calling convention", @@ -346,7 +367,7 @@ describe("Ghidra headless launcher", () => { for (const conflict of [ { psp: true as const }, { dosMz: true as const }, - { dosCom: true as const }, + { dosCom: { loader: "ComLoader" } as const }, { rawBinary: { languageId: "x86:LE:32:default", @@ -403,7 +424,7 @@ describe("Ghidra headless launcher", () => { { psp: true as const }, { mipsSoftFloat: true as const }, { dosMz: true as const }, - { dosCom: true as const }, + { dosCom: { loader: "ComLoader" } as const }, { rawBinary: { languageId: "x86:LE:32:default", @@ -509,7 +530,7 @@ describe("Ghidra configured import language and seeds", () => { ...base, platform, bridgeScriptPath: path.join(bridgeDirectory, "ReaGhidraBridge.java"), - dosCom: true, + dosCom: { loader: "ComLoader" }, seedPath, }); const prepare = arguments_.indexOf( @@ -547,7 +568,7 @@ describe("Ghidra disabled analyzers", () => { it("applies the analyzer options after seeds and before analysis scripts", () => { const arguments_ = ghidraHeadlessArguments({ ...base, - dosCom: true, + dosCom: { loader: "ComLoader" }, seedPath: posix.join("/tmp/runtime/seeds", "seeds.tsv"), disabledAnalyzers: [ "Objective-C Message Analyzer", @@ -667,7 +688,7 @@ describe("Ghidra existing project", () => { it.each([ [{ dosMz: true as const }, "existing_project_dos"], - [{ dosCom: true as const }, "existing_project_dos"], + [{ dosCom: { loader: "ComLoader" } as const }, "existing_project_dos"], [ { rawBinary: { diff --git a/tests/boundary/providers/ghidra/ghidraTargetSnapshot.test.ts b/tests/boundary/providers/ghidra/ghidraTargetSnapshot.test.ts index 19e2574bae..52bd223a1e 100644 --- a/tests/boundary/providers/ghidra/ghidraTargetSnapshot.test.ts +++ b/tests/boundary/providers/ghidra/ghidraTargetSnapshot.test.ts @@ -28,4 +28,18 @@ describe("Ghidra target snapshot", () => { createGhidraTargetSnapshot(source, root, sha256, { platform: "win32" }), ).rejects.toThrow(/No native private runtime owns/u); }); + + it("preserves a dotfile named .com so ComLoader sees that extension", async () => { + const root = await createTestTempDirectory("rea-ghidra-hidden-com-"); + const source = join(root, ".com"); + const bytes = Buffer.from("hidden com"); + const sha256 = createHash("sha256").update(bytes).digest("hex"); + await writeFile(source, bytes); + const snapshot = await createGhidraTargetSnapshot(source, root, sha256, { + platform: "linux", + }); + expect(snapshot.path.endsWith(`target-${sha256.slice(0, 12)}.com`)).toBe( + true, + ); + }); }); diff --git a/tests/conformance/ghidra/dos-com-fixture.mjs b/tests/conformance/ghidra/dos-com-fixture.mjs index fef1d24803..3afb960bf3 100644 --- a/tests/conformance/ghidra/dos-com-fixture.mjs +++ b/tests/conformance/ghidra/dos-com-fixture.mjs @@ -1,5 +1,25 @@ /** Generate a public source-owned COM fixture; no external compiler or game input. */ export const buildDosComFixture = () => { + const bytes = Buffer.alloc(64, 0x90); + // Two MOV AH,imm8 / INT 21h instructions reach ComLoader's score of 12. + // The near call targets file offset 0x20; INT 20h terminates the entry. + bytes.set(Buffer.from("b409cd21b409cd21e81500cd20", "hex")); + bytes.set(Buffer.from("40c3", "hex"), 0x20); + return { + bytes, + entry: "0x100", + near: "0x120", + entry_hex: "b409", + load_segment: "0x0", + load_address: "0000:0100", + loader: "ComLoader", + unlisted: "0x13f", + tail: "0x13e", + }; +}; + +/** A .com image ComLoader's recognition score rejects. */ +export const buildRejectedDosComFixture = () => { const bytes = Buffer.alloc(64, 0x90); bytes.set(Buffer.from("b83412e81a00cd20", "hex")); bytes.set(Buffer.from("40c3", "hex"), 32); @@ -7,7 +27,8 @@ export const buildDosComFixture = () => { bytes, entry: "0x10100", near: "0x10120", - entry_hex: "b83412", - load_segment: "0x1000", + load_address: "1000:0100", + loader: "BinaryLoader", + fallback_reason: "recognition_score", }; };