feat(ghidra): admit explicit DOS COM analysis (#702)
* feat(ghidra): admit explicit DOS COM analysis Carry caller-selected COM interpretation through CLI, MCP and target identity, seed real-mode entry/context before Ghidra analysis, and verify complete loaded bytes, source mappings and measured register context. Keep original binaries unchanged and PSP/runtime coverage explicit. Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering) * fix(verification): validate COM package selection before allocating fixtures
This commit is contained in:
+134
-21
@@ -6,7 +6,11 @@ import { runDirectAnalysis } from "../application/DirectAnalysis.js";
|
||||
import { CLI_COMMANDS } from "../cliCommandNames.js";
|
||||
import { logCliCommand } from "../cliLogging.js";
|
||||
import type { Logger } from "../logger.js";
|
||||
import { directAnalysisOptions, providerSelectionOption } from "./options.js";
|
||||
import {
|
||||
directAnalysisOptions,
|
||||
formatSelectionOption,
|
||||
providerSelectionOption,
|
||||
} from "./options.js";
|
||||
import type { CliInstance } from "./types.js";
|
||||
import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
|
||||
|
||||
@@ -19,14 +23,22 @@ export const registerCoreAnalysisCommands = (
|
||||
description:
|
||||
"Verify loaded native bytes, source mappings, relocations and entry",
|
||||
args: z.object({ path: z.string().describe("Local executable path") }),
|
||||
options: z.object({ provider: providerSelectionOption }),
|
||||
options: z.object({
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.inspectNativeLoadImage, () =>
|
||||
runDirectAnalysis(
|
||||
args.path,
|
||||
"inspect_native_load_image",
|
||||
{},
|
||||
directAnalysisOptions(logger, undefined, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
undefined,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -43,6 +55,7 @@ export const registerCoreAnalysisCommands = (
|
||||
.min(1)
|
||||
.default(256)
|
||||
.describe("Requested byte count"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
@@ -51,7 +64,12 @@ export const registerCoreAnalysisCommands = (
|
||||
args.path,
|
||||
"read_bytes",
|
||||
{ address: args.address, length: options.length },
|
||||
directAnalysisOptions(logger, undefined, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
undefined,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -61,14 +79,22 @@ export const registerCoreAnalysisCommands = (
|
||||
path: z.string().describe("Local executable path"),
|
||||
address: z.string().describe("Exact provider memory address"),
|
||||
}),
|
||||
options: z.object({ provider: providerSelectionOption }),
|
||||
options: z.object({
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.addressToFileOffset, () =>
|
||||
runDirectAnalysis(
|
||||
args.path,
|
||||
"address_to_file_offset",
|
||||
{ address: args.address },
|
||||
directAnalysisOptions(logger, undefined, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
undefined,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -129,6 +155,7 @@ export const registerCoreAnalysisCommands = (
|
||||
.max(5000)
|
||||
.default(1000)
|
||||
.describe("Maximum nodes on this page"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
alias: {
|
||||
@@ -153,7 +180,12 @@ export const registerCoreAnalysisCommands = (
|
||||
offset: options.offset,
|
||||
limit: options.limit,
|
||||
},
|
||||
directAnalysisOptions(logger, undefined, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
undefined,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -165,6 +197,7 @@ export const registerCoreAnalysisCommands = (
|
||||
options: z.object({
|
||||
type: z.string().optional().describe("Exact database type category path"),
|
||||
address: z.string().describe("Exact native address").optional(),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
@@ -178,7 +211,12 @@ export const registerCoreAnalysisCommands = (
|
||||
? {}
|
||||
: { address: options.address }),
|
||||
},
|
||||
directAnalysisOptions(logger, undefined, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
undefined,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -195,14 +233,22 @@ export const registerCoreAnalysisCommands = (
|
||||
path: z.string().describe("Local native executable or app path"),
|
||||
address: z.string().describe("Exact native address"),
|
||||
}),
|
||||
options: z.object({ provider: providerSelectionOption }),
|
||||
options: z.object({
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, command, () =>
|
||||
runDirectAnalysis(
|
||||
args.path,
|
||||
operation,
|
||||
{ address: args.address },
|
||||
directAnalysisOptions(logger, undefined, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
undefined,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -239,6 +285,7 @@ const registerNativeDispatchMetadataCommand = (
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Load or update the local analysis snapshot"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
alias: { maxRecords: "max-records" },
|
||||
@@ -248,7 +295,12 @@ const registerNativeDispatchMetadataCommand = (
|
||||
args.path,
|
||||
"inspect_native_dispatch_metadata",
|
||||
{ max_records: options.maxRecords },
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
options.snapshot,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -292,6 +344,7 @@ const registerNativeUiActionCommand = (
|
||||
.max(5_000)
|
||||
.default(500)
|
||||
.describe("Maximum returned graph edges"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
alias: {
|
||||
@@ -310,7 +363,12 @@ const registerNativeUiActionCommand = (
|
||||
max_nodes: options.maxNodes,
|
||||
max_edges: options.maxEdges,
|
||||
},
|
||||
directAnalysisOptions(logger, undefined, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
undefined,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -323,6 +381,7 @@ const registerCoreCommands = (cli: CliInstance, logger: Logger): void => {
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Load and update a local analysis snapshot"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
});
|
||||
cli.command(CLI_COMMANDS.analyze, {
|
||||
@@ -348,7 +407,12 @@ const registerCoreCommands = (cli: CliInstance, logger: Logger): void => {
|
||||
args.path,
|
||||
"binary_overview",
|
||||
{},
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
options.snapshot,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -364,6 +428,7 @@ const registerCoreCommands = (cli: CliInstance, logger: Logger): void => {
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Load and update a local analysis snapshot"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
@@ -372,7 +437,12 @@ const registerCoreCommands = (cli: CliInstance, logger: Logger): void => {
|
||||
args.path,
|
||||
"procedure_pseudo_code",
|
||||
{ procedure: args.address },
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
options.snapshot,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -382,6 +452,7 @@ const runRoutedOverview = async (
|
||||
path: string,
|
||||
options: {
|
||||
readonly snapshot?: string | undefined;
|
||||
readonly "target-format"?: "dos-com" | undefined;
|
||||
readonly provider?: string | undefined;
|
||||
},
|
||||
logger: Logger,
|
||||
@@ -389,6 +460,7 @@ const runRoutedOverview = async (
|
||||
if (
|
||||
options.provider === undefined &&
|
||||
options.snapshot === undefined &&
|
||||
options["target-format"] === undefined &&
|
||||
(await isJavaScriptApplicationPath(path))
|
||||
)
|
||||
return runCliJavaScriptApplicationAnalysis({
|
||||
@@ -398,7 +470,12 @@ const runRoutedOverview = async (
|
||||
path,
|
||||
"binary_overview",
|
||||
{},
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
options.snapshot,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
);
|
||||
};
|
||||
|
||||
@@ -429,6 +506,7 @@ const registerXrefsCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Load and update a local analysis snapshot"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
@@ -437,7 +515,12 @@ const registerXrefsCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
args.path,
|
||||
"xrefs",
|
||||
{ address: args.address },
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
options.snapshot,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -460,6 +543,7 @@ const registerTraceCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Load and update a local analysis snapshot"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
alias: {
|
||||
@@ -474,7 +558,12 @@ const registerTraceCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
query: args.query,
|
||||
case_sensitive: options.caseSensitive,
|
||||
},
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
options.snapshot,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -493,6 +582,7 @@ const registerFunctionCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Load and update a local analysis snapshot"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
@@ -501,7 +591,12 @@ const registerFunctionCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
args.path,
|
||||
"analyze_function",
|
||||
{ procedure: args.address },
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
options.snapshot,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -520,6 +615,7 @@ const registerNativeApiCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Load and update a local analysis snapshot"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
@@ -528,7 +624,12 @@ const registerNativeApiCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
args.path,
|
||||
"inspect_native_api",
|
||||
{ procedure: args.address },
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
options.snapshot,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -550,6 +651,7 @@ const registerInstructionsCommand = (
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Load and update a local analysis snapshot"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
@@ -560,7 +662,12 @@ const registerInstructionsCommand = (
|
||||
{
|
||||
procedure: args.address,
|
||||
},
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
options.snapshot,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
@@ -591,6 +698,7 @@ const registerSearchCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Load and update a local analysis snapshot"),
|
||||
"target-format": formatSelectionOption,
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
alias: { caseSensitive: "case-sensitive" },
|
||||
@@ -604,7 +712,12 @@ const registerSearchCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
mode: options.mode,
|
||||
case_sensitive: options.caseSensitive,
|
||||
},
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
directAnalysisOptions(
|
||||
logger,
|
||||
options.snapshot,
|
||||
options.provider,
|
||||
options["target-format"],
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
import {
|
||||
executableFormatHintSchema,
|
||||
type ExecutableFormatHint,
|
||||
} from "../domain/dosCom.js";
|
||||
import { analysisProviderSelectorSchema } from "../contracts/providerSelection.js";
|
||||
import type { AnalysisProviderSelector } from "../contracts/providerSelection.js";
|
||||
import type { Logger } from "../logger.js";
|
||||
@@ -8,12 +12,19 @@ export const providerSelectionOption = analysisProviderSelectorSchema
|
||||
"Bind deep analysis to a provider ID or use deterministic auto selection",
|
||||
);
|
||||
|
||||
/** Explicit interpretation for headerless native executable formats. */
|
||||
export const formatSelectionOption = executableFormatHintSchema
|
||||
.optional()
|
||||
.describe("Explicit headerless DOS COM interpretation");
|
||||
|
||||
export const directAnalysisOptions = (
|
||||
logger: Logger,
|
||||
snapshotPath: string | undefined,
|
||||
providerId: AnalysisProviderSelector | undefined,
|
||||
formatHint?: ExecutableFormatHint,
|
||||
) => ({
|
||||
logger,
|
||||
snapshotPath,
|
||||
...(formatHint === undefined ? {} : { formatHint }),
|
||||
...(providerId === undefined ? {} : { providerId }),
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user