mirror of
https://github.com/morluto/rea.git
synced 2026-11-21 14:05:49 +00:00
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:
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.
|
||||
|
||||
|
||||
@@ -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");
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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"),
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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" },
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -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.");
|
||||
};
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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);
|
||||
},
|
||||
);
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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",
|
||||
})),
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
};
|
||||
@@ -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
|
||||
? {
|
||||
|
||||
@@ -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));
|
||||
};
|
||||
@@ -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",
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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,
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -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",
|
||||
};
|
||||
};
|
||||
Reference in new issue
Block a user