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 <morluto@users.noreply.github.com>

* 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 <morluto@users.noreply.github.com>

* style(ghidra): format COM snapshot and verifier files

Co-authored-by: morluto <morluto@users.noreply.github.com>

* 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 <morluto@users.noreply.github.com>

* 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 <morluto@users.noreply.github.com>

* fix(ghidra): attest COM imports against the committed loader

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <morluto@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-11-18 16:40:18 -05:00
1 parent 1920525900
commit 86cf8942de
25 files changed
+1449 -135

No files matched your search

@@ -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.
@@ -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.
+5
View File
@@ -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");
+52 -7
View File
@@ -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);
}
}
+36 -12
View File
@@ -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.
+5 -3
View File
@@ -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
+116 -9
View File
@@ -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",
+20 -2
View File
@@ -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,
+72 -9
View File
@@ -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"),
+23 -11
View File
@@ -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),
+256
View File
@@ -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<void>) | 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" },
});
});
});
+237
View File
@@ -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<Result<GhidraComImportSelection, AnalysisError>> => {
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<Record<string, unknown>>,
): Result<GhidraComImportSelection, string> => {
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.");
};
+146 -14
View File
@@ -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<typeof fixtureDosComLoadImage>) =>
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);
});
});
+16 -1
View File
@@ -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<BinaryTarget> => {
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<string, string>) => {
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);
},
);
+18 -14
View File
@@ -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),
+81 -4
View File
@@ -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",
})),
},
],
},
};
};
+5
View File
@@ -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
? {
+10
View File
@@ -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));
};
+176 -20
View File
@@ -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<NativeLoadImage, string> => {
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<typeof createLoadImageChecks>["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. */
@@ -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",
+12 -1
View File
@@ -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,
+20 -11
View File
@@ -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<GhidraTargetSnapshot> => {
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";
@@ -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: {
@@ -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,
);
});
});
+23 -2
View File
@@ -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",
};
};