feat(native): admit raw binaries with caller-supplied architecture and entry (#1868)

* feat(native): admit raw binaries with caller-supplied architecture and entry

* fix(native): honor raw-binary preparation and entry identity

* fix(ghidra): stream raw snapshot attestation with cancellation

* fix(native): preserve and validate raw lifecycle entries

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
Matt Van Horn
2026-10-12 00:06:29 +08:00
committed by GitHub
co-authored by morluto
parent d3e83b0899
commit 7c207c7951
57 changed files with 2453 additions and 336 deletions
+22 -66
View File
@@ -8,9 +8,8 @@ import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import type { Logger } from "pino";
import {
directAnalysisOptions,
formatSelectionOption,
providerSelectionOption,
directAnalysisOptionsFromCli,
nativeOpenOptionFields,
} from "./options.js";
import type { CliInstance } from "./types.js";
import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
@@ -43,8 +42,7 @@ const registerOverviewCommands = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
});
cli.command(CLI_COMMANDS.analyze, {
description: "Get an overview of an app",
@@ -75,12 +73,7 @@ const registerOverviewCommands = (
args.path,
"binary_overview",
{},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
);
},
@@ -97,12 +90,7 @@ const registerOverviewCommands = (
args.path,
"binary_overview",
{},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -136,8 +124,7 @@ const registerDecompileCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "decompile", () =>
@@ -152,12 +139,7 @@ const registerDecompileCommand = (
"procedure_pseudo_code",
),
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -168,13 +150,17 @@ const routesToJavaScriptAnalysis = async (
path: string,
options: {
readonly snapshot?: string | undefined;
readonly "target-format"?: "dos-com" | undefined;
readonly "target-format"?: "dos-com" | "raw-binary" | undefined;
readonly architecture?: string | undefined;
readonly "entry-point"?: string | undefined;
readonly provider?: string | undefined;
},
): Promise<boolean> =>
options.provider === undefined &&
options.snapshot === undefined &&
options["target-format"] === undefined &&
options.architecture === undefined &&
options["entry-point"] === undefined &&
(await isJavaScriptApplicationPath(path));
const isJavaScriptApplicationPath = async (path: string): Promise<boolean> => {
@@ -215,8 +201,7 @@ const registerXrefsCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "xrefs", () =>
@@ -231,12 +216,7 @@ const registerXrefsCommand = (
"xrefs",
),
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -270,8 +250,7 @@ const registerTraceCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "trace", () =>
@@ -287,12 +266,7 @@ const registerTraceCommand = (
),
case_sensitive: options.caseSensitive,
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -326,8 +300,7 @@ const registerFunctionCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "function", () =>
@@ -342,12 +315,7 @@ const registerFunctionCommand = (
"analyze_function",
),
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -381,8 +349,7 @@ const registerInstructionsCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.instructions, () =>
@@ -397,12 +364,7 @@ const registerInstructionsCommand = (
"read_function_instructions",
),
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -448,8 +410,7 @@ const registerSearchCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "search", () =>
@@ -468,12 +429,7 @@ const registerSearchCommand = (
mode: options.mode,
case_sensitive: options.caseSensitive,
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
+22 -83
View File
@@ -5,9 +5,8 @@ import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import type { Logger } from "pino";
import {
directAnalysisOptions,
formatSelectionOption,
providerSelectionOption,
directAnalysisOptionsFromCli,
nativeOpenOptionFields,
} from "./options.js";
import type { CliInstance } from "./types.js";
@@ -23,8 +22,7 @@ export const registerCoreNativeCommands = (
"Verify loaded native bytes, source mappings, relocations and entry",
args: z.object({ path: z.string().describe("Local executable path") }),
options: z.object({
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.inspectNativeLoadImage, () =>
@@ -32,12 +30,7 @@ export const registerCoreNativeCommands = (
args.path,
"inspect_native_load_image",
{},
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -54,8 +47,7 @@ export const registerCoreNativeCommands = (
.min(1)
.default(256)
.describe("Requested byte count"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.readBytes, () =>
@@ -63,12 +55,7 @@ export const registerCoreNativeCommands = (
args.path,
"read_bytes",
{ address: args.address, length: options.length },
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -79,8 +66,7 @@ export const registerCoreNativeCommands = (
address: z.string().describe("Exact provider memory address"),
}),
options: z.object({
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.addressToFileOffset, () =>
@@ -88,12 +74,7 @@ export const registerCoreNativeCommands = (
args.path,
"address_to_file_offset",
{ address: args.address },
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -154,8 +135,7 @@ export const registerCoreNativeCommands = (
.max(5000)
.default(1000)
.describe("Maximum nodes on this page"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.traceNativeValues, () =>
@@ -172,12 +152,7 @@ export const registerCoreNativeCommands = (
offset: options.offset,
limit: options.limit,
},
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -189,8 +164,7 @@ export const registerCoreNativeCommands = (
options: z.object({
type: z.string().optional().describe("Exact database type category path"),
address: z.string().optional().describe("Exact native address"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.inspectNativeDataType, () =>
@@ -203,12 +177,7 @@ export const registerCoreNativeCommands = (
? {}
: { address: options.address }),
},
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -226,8 +195,7 @@ export const registerCoreNativeCommands = (
address: z.string().describe("Exact native address"),
}),
options: z.object({
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, command, () =>
@@ -235,12 +203,7 @@ export const registerCoreNativeCommands = (
args.path,
operation,
{ address: args.address },
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -273,8 +236,7 @@ const registerNativeDispatchMetadataCommand = (
.min(1)
.optional()
.describe("Load or update the local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: async ({ args, options }) =>
logCliCommand(logger, "inspect-native-dispatch-metadata", () =>
@@ -282,12 +244,7 @@ const registerNativeDispatchMetadataCommand = (
args.path,
"inspect_native_dispatch_metadata",
{ max_records: options.maxRecords },
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -332,8 +289,7 @@ const registerNativeUiActionCommand = (
.max(5_000)
.default(500)
.describe("Maximum returned graph edges"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: async ({ args, options }) =>
logCliCommand(logger, "trace-native-ui-action", () =>
@@ -346,12 +302,7 @@ const registerNativeUiActionCommand = (
max_nodes: options.maxNodes,
max_edges: options.maxEdges,
},
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -374,8 +325,7 @@ const registerNativeApiCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "inspect-native-api", () =>
@@ -383,12 +333,7 @@ const registerNativeApiCommand = (
args.path,
"inspect_native_api",
{ procedure: args.address },
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -417,8 +362,7 @@ const registerAnnotationCommand = (
.string()
.optional()
.describe("Inline entry comment; empty text clears it"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.annotateNativeFunction, () =>
@@ -435,12 +379,7 @@ const registerAnnotationCommand = (
? {}
: { inline_comment: options["inline-comment"] }),
},
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
+55 -1
View File
@@ -2,6 +2,11 @@ import {
executableFormatHintSchema,
type ExecutableFormatHint,
} from "../domain/dosCom.js";
import type { BinaryArchitecture } from "../domain/binaryTargetTypes.js";
import {
binaryArchitectureSchema,
rawBinaryEntryPointSchema,
} from "../domain/rawBinary.js";
import { analysisProviderSelectorSchema } from "../contracts/providerSelection.js";
import type { AnalysisProviderSelector } from "../contracts/providerSelection.js";
import type { Logger } from "pino";
@@ -15,16 +20,65 @@ export const providerSelectionOption = analysisProviderSelectorSchema
/** Explicit interpretation for headerless native executable formats. */
export const formatSelectionOption = executableFormatHintSchema
.optional()
.describe("Explicit headerless DOS COM interpretation");
.describe(
"Explicit headerless interpretation (dos-com or raw-binary); omission preserves header-based detection",
);
export const architectureSelectionOption = binaryArchitectureSchema
.optional()
.describe(
"Caller-supplied CPU family; required with --target-format raw-binary",
);
export const entryPointSelectionOption = rawBinaryEntryPointSchema
.optional()
.describe(
"Caller-supplied load and entry address (0xhex); required with --target-format raw-binary",
);
/** Shared CLI flags that bind a native target interpretation. */
export const nativeOpenOptionFields = {
"target-format": formatSelectionOption,
architecture: architectureSelectionOption,
"entry-point": entryPointSelectionOption,
provider: providerSelectionOption,
};
/** Native CLI flags consumed when opening a target for one-shot analysis. */
export interface NativeOpenCliFlags {
readonly snapshot?: string | undefined;
readonly provider?: AnalysisProviderSelector | undefined;
readonly "target-format"?: ExecutableFormatHint | undefined;
readonly architecture?: BinaryArchitecture | undefined;
readonly "entry-point"?: string | undefined;
}
export const directAnalysisOptions = (
logger: Logger,
snapshotPath: string | undefined,
providerId: AnalysisProviderSelector | undefined,
formatHint?: ExecutableFormatHint,
architecture?: BinaryArchitecture,
entryPoint?: string,
) => ({
logger,
snapshotPath,
...(formatHint === undefined ? {} : { formatHint }),
...(architecture === undefined ? {} : { architecture }),
...(entryPoint === undefined ? {} : { entryPoint }),
...(providerId === undefined ? {} : { providerId }),
});
/** Map native CLI flags onto the shared one-shot analysis options. */
export const directAnalysisOptionsFromCli = (
logger: Logger,
options: NativeOpenCliFlags,
) =>
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
options.architecture,
options["entry-point"],
);