mirror of
https://github.com/morluto/rea.git
synced 2026-11-18 04:34:13 +00:00
refactor(cli): derive contract-backed command options from the tool contract (#10571)
* refactor(cli): derive contract-backed command options from the tool contract Each contract-backed CLI command restated its contract's input fields as hand-written incur options and mapped them back to snake_case input with conditional spreads. Nothing checked that the two schemas agreed. Add registerContractCommand: a per-command projection names only what the CLI spells differently (positionals, caller-relative path fields, option renames, CLI help wording, omitted optional fields with a reason). Option schemas, decimal argv tokens and the contract's cross-field rules are derived from the contract input schema, and parsed options map back to the contract input mechanically. Migrate inspect-sqlite-database and the thirteen flat binary-diagnostics inspectors. Their --schema output is unchanged apart from property order, and help lists options in contract order. Delete the SQLite superRefine that mirrored the contract and the per-command spreads. Add a parity test: every projected command exposes each contract field or declares its omission, and each field admits exactly what the contract admits for empty, NUL, relative-path, bound and numeric-spelling probes. * refactor(cli): refuse unprojected contract input forms at registration Address review findings on the contract projection: - Bind inspect-sqlite-database to its contract by name instead of catalog position. - Accept only field forms argv can carry (string, number, boolean, enum, and arrays of strings or enums) instead of rejecting a short list, so arrays of objects, tuples and other forms fail at registration. - Refuse root input keywords other than the projected object constraints and presentation annotations, so a contract rule such as `not` cannot disappear from --schema. * refactor(cli): describe contract commands independently of the CLI framework Split the contract projection into a framework-neutral description and a thin Incur adapter, so a later REA-owned CLI layer (#10583) can render the same description. - contractCliDescription.ts derives each positional and option from the contract and projection: key and short flag, help, argv admission schema, boolean-flag/repeatable/decimal/caller-path facts, object constraints renamed to CLI keys, the optional argv-time cross-field check, and the mapping back to contract input. - contractCommand.ts only renders that description as Incur args and options and runs the handler. Cross-field rules now refuse at argv parsing only when a projection asks (inspect-sqlite-database does, keeping its behavior); otherwise the service's contract parse refuses them as before. Exact-optional fields are projected as optional because argv cannot carry an explicit undefined and Incur's help reads flag and choice types only through optional. The parity guard reads the descriptions, and also checks that boolean fields parse as bare flags and that no projected field stays exact-optional.
This commit is contained in:
1 parent
29fb608559
commit
f3b697da5a
6 files changed
+1145
-731
No files matched your search
@@ -1,8 +1,4 @@
|
||||
import { projectCliAnalysisResult } from "./projectCliAnalysisResult.js";
|
||||
import { inspectDevicetreeInputSchema } from "../domain/firmware/devicetree.js";
|
||||
import { inspectPeLoadConfigInputSchema } from "../domain/native/peLoadConfig.js";
|
||||
import { inspectBinaryHardeningInputSchema } from "../domain/native/binaryHardening.js";
|
||||
import { inspectByteEntropyInputSchema } from "../domain/native/byteEntropy.js";
|
||||
import { z } from "incur";
|
||||
import { cliDecimalField } from "./options.js";
|
||||
import { producerLimitsOption } from "./producerLimitsOption.js";
|
||||
@@ -33,20 +29,8 @@ import type { CliInstance } from "./types.js";
|
||||
import { withCommandCancellation } from "./commandCancellation.js";
|
||||
import { inspectBinaryLayoutInputSchema } from "../domain/native/binaryLayout.js";
|
||||
import { inspectRecordedCrashInputSchema } from "../domain/native/recordedCrash.js";
|
||||
import { inspectPeResourcesInputSchema } from "../domain/native/peResources.js";
|
||||
import { inspectPeCertificatesInputSchema } from "../domain/native/peCertificates.js";
|
||||
import { inspectPeImportsInputSchema } from "../domain/native/peImports.js";
|
||||
import { inspectWindowsShortcutInputSchema } from "../domain/native/windowsShortcut.js";
|
||||
import { inspectNativeExportsInputSchema } from "../domain/native/nativeExports.js";
|
||||
import { inspectElfNotesInputSchema } from "../domain/native/elfNotes.js";
|
||||
import { inspectNativeInitializersInputSchema } from "../domain/native/nativeInitializers.js";
|
||||
import { machoSliceArchitectureSchema } from "../domain/apple/machoTargetSelection.js";
|
||||
import { inspectElfUnwindRangesInputSchema } from "../domain/native/elfUnwindRanges.js";
|
||||
import { inspectAppleIpsInputSchema } from "../domain/native/appleIps.js";
|
||||
import { inspectKernelModuleInputSchema } from "../domain/native/kernelModule.js";
|
||||
import { inspectKernelBuildConfigInputSchema } from "../domain/native/kernelBuildConfig.js";
|
||||
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
|
||||
import { finishCliEvidenceCommand } from "./cliEvidenceCallerPath.js";
|
||||
import { withEvidenceCallerInputPath } from "../domain/evidence.js";
|
||||
import { BYTE_ENTROPY_PROVIDER } from "../domain/investigationProviders.js";
|
||||
import { localPathStringSchema } from "../domain/localPath.js";
|
||||
@@ -55,6 +39,18 @@ import {
|
||||
analysisEvidenceDeliveryOptions,
|
||||
deliverCliAnalysisEvidence,
|
||||
} from "./analysisEvidenceDelivery.js";
|
||||
import { BINARY_DIAGNOSTICS_TOOL_CONTRACTS } from "../contracts/native/binaryDiagnosticsToolContracts.js";
|
||||
import { contractNamed } from "./contractCliDescription.js";
|
||||
import {
|
||||
inspectWithService,
|
||||
registerContractCommand,
|
||||
} from "./contractCommand.js";
|
||||
|
||||
type BinaryDiagnosticsOperation =
|
||||
(typeof BINARY_DIAGNOSTICS_TOOL_CONTRACTS)[number]["name"];
|
||||
|
||||
const contract = <Name extends BinaryDiagnosticsOperation>(name: Name) =>
|
||||
contractNamed(BINARY_DIAGNOSTICS_TOOL_CONTRACTS, name);
|
||||
|
||||
/** Inspect operator-selected files through the same shared workflow as MCP. */
|
||||
export const registerBinaryDiagnosticsCommands = (
|
||||
@@ -62,600 +58,235 @@ export const registerBinaryDiagnosticsCommands = (
|
||||
logger: Logger,
|
||||
environment: Readonly<NodeJS.ProcessEnv>,
|
||||
): void => {
|
||||
cli.command(CLI_COMMANDS.inspectElfNotes, {
|
||||
description:
|
||||
"Inspect ELF PT_NOTE and SHT_NOTE identities without executing the image",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe("Local ELF32/ELF64 image"),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectElfNotesInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
maxEntries: cliDecimalField(inspectElfNotesInputSchema.shape.max_entries),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const elf = createElfNotesService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectElfNotes,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
elf.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
max_entries: options.maxEntries,
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
elf,
|
||||
"rea-elf-notes",
|
||||
"inspect_elf_notes",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectNativeInitializers, {
|
||||
description:
|
||||
"List ELF and Mach-O initializer and finalizer functions without executing the image",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe(
|
||||
"Local ELF32/ELF64, thin Mach-O or universal Mach-O image",
|
||||
),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectNativeInitializersInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
offset: cliDecimalField(
|
||||
inspectNativeInitializersInputSchema.shape.offset,
|
||||
),
|
||||
limit: cliDecimalField(inspectNativeInitializersInputSchema.shape.limit),
|
||||
architecture: machoSliceArchitectureSchema
|
||||
.optional()
|
||||
.describe(
|
||||
"Slice to read from a universal Mach-O, by CPU family; when several slices share a family, arm64 (arm64 or arm64v8), arm64e (arm64e or arm64e.x1) or x86_64 names the subtype, and a value matching several slices is refused; required for universal files",
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const initializers = createNativeInitializersService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectNativeInitializers,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
initializers.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
offset: options.offset,
|
||||
limit: options.limit,
|
||||
...(options.architecture === undefined
|
||||
? {}
|
||||
: { architecture: options.architecture }),
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
initializers,
|
||||
"rea-native-initializers",
|
||||
"inspect_native_initializers",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
|
||||
cli.command(CLI_COMMANDS.inspectElfUnwindRanges, {
|
||||
description:
|
||||
"Inspect ELF unwind function ranges without executing the image",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe("Local ELF32/ELF64 image"),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectElfUnwindRangesInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
maxRanges: cliDecimalField(
|
||||
inspectElfUnwindRangesInputSchema.shape.max_ranges,
|
||||
),
|
||||
offset: cliDecimalField(inspectElfUnwindRangesInputSchema.shape.offset),
|
||||
limit: cliDecimalField(inspectElfUnwindRangesInputSchema.shape.limit),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const unwind = createElfUnwindRangesService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectElfUnwindRanges,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
unwind.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
max_ranges: options.maxRanges,
|
||||
offset: options.offset,
|
||||
limit: options.limit,
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
unwind,
|
||||
"rea-elf-unwind-ranges",
|
||||
"inspect_elf_unwind_ranges",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectAppleIps, {
|
||||
description:
|
||||
"Inspect an Apple .ips crash report without executing a target",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe("Local Apple .ips crash report"),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectAppleIpsInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
maxThreads: cliDecimalField(inspectAppleIpsInputSchema.shape.max_threads),
|
||||
maxFrames: cliDecimalField(inspectAppleIpsInputSchema.shape.max_frames),
|
||||
maxImages: cliDecimalField(inspectAppleIpsInputSchema.shape.max_images),
|
||||
maxRegisters: cliDecimalField(
|
||||
inspectAppleIpsInputSchema.shape.max_registers,
|
||||
),
|
||||
maxIntegerTextBytes: cliDecimalField(
|
||||
inspectAppleIpsInputSchema.shape.max_integer_text_bytes,
|
||||
),
|
||||
joinPath: localPathStringSchema
|
||||
.optional()
|
||||
.describe(
|
||||
"Optional local Mach-O executable or dSYM whose slice LC_UUID matches report images",
|
||||
),
|
||||
maxJoinBytes: cliDecimalField(
|
||||
inspectAppleIpsInputSchema.shape.max_join_bytes,
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const ips = createAppleIpsService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectAppleIps,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
ips.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
max_threads: options.maxThreads,
|
||||
max_frames: options.maxFrames,
|
||||
max_images: options.maxImages,
|
||||
max_registers: options.maxRegisters,
|
||||
max_integer_text_bytes: options.maxIntegerTextBytes,
|
||||
...(options.joinPath === undefined
|
||||
? {}
|
||||
: { join_path: absoluteCallerPath(options.joinPath) }),
|
||||
max_join_bytes: options.maxJoinBytes,
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
ips,
|
||||
"rea-apple-ips",
|
||||
"inspect_apple_ips",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectKernelModule, {
|
||||
description:
|
||||
"Inspect Linux kernel module metadata without executing the module",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe(
|
||||
"Local ELF32/ELF64 kernel module or compressed .ko container",
|
||||
),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectKernelModuleInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
maxEntries: cliDecimalField(
|
||||
inspectKernelModuleInputSchema.shape.max_entries,
|
||||
),
|
||||
maxModinfoKeyBytes: cliDecimalField(
|
||||
inspectKernelModuleInputSchema.shape.max_modinfo_key_bytes,
|
||||
),
|
||||
maxModinfoValueBytes: cliDecimalField(
|
||||
inspectKernelModuleInputSchema.shape.max_modinfo_value_bytes,
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const kernelModule = createKernelModuleService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectKernelModule,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
kernelModule.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
max_entries: options.maxEntries,
|
||||
max_modinfo_key_bytes: options.maxModinfoKeyBytes,
|
||||
max_modinfo_value_bytes: options.maxModinfoValueBytes,
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
kernelModule,
|
||||
"rea-kernel-module",
|
||||
"inspect_kernel_module",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectKernelBuildConfig, {
|
||||
description:
|
||||
"Inspect a Linux kernel image's version banner and embedded build config without executing it",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe(
|
||||
"Local vmlinux ELF, raw Image, x86 bzImage/zImage, or configs.ko",
|
||||
),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectKernelBuildConfigInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
maxEntries: cliDecimalField(
|
||||
inspectKernelBuildConfigInputSchema.shape.max_entries,
|
||||
),
|
||||
maxConfigBytes: cliDecimalField(
|
||||
inspectKernelBuildConfigInputSchema.shape.max_config_bytes,
|
||||
),
|
||||
maxPayloadBytes: cliDecimalField(
|
||||
inspectKernelBuildConfigInputSchema.shape.max_payload_bytes,
|
||||
),
|
||||
offset: cliDecimalField(inspectKernelBuildConfigInputSchema.shape.offset),
|
||||
limit: cliDecimalField(inspectKernelBuildConfigInputSchema.shape.limit),
|
||||
name: inspectKernelBuildConfigInputSchema.shape.name,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const kernelBuildConfig = createKernelBuildConfigService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectKernelBuildConfig,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
kernelBuildConfig.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
max_entries: options.maxEntries,
|
||||
max_config_bytes: options.maxConfigBytes,
|
||||
max_payload_bytes: options.maxPayloadBytes,
|
||||
offset: options.offset,
|
||||
limit: options.limit,
|
||||
...(options.name === undefined
|
||||
? {}
|
||||
: { name: options.name }),
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
kernelBuildConfig,
|
||||
"rea-kernel-build-config",
|
||||
"inspect_kernel_build_config",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectPeLoadConfig, {
|
||||
description:
|
||||
"Inspect PE TLS callbacks and load configuration without executing the image",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe("Local PE32/PE32+ image"),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectPeLoadConfigInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
maxCallbacks: cliDecimalField(
|
||||
inspectPeLoadConfigInputSchema.shape.max_callbacks,
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const elf = createPeLoadConfigService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectPeLoadConfig,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
elf.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
max_callbacks: options.maxCallbacks,
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
elf,
|
||||
"rea-pe-load-config",
|
||||
"inspect_pe_load_config",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectBinaryHardening, {
|
||||
description:
|
||||
"Inspect ELF, PE, and Mach-O hardening without executing the image",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe("Local ELF, PE, or Mach-O image"),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectBinaryHardeningInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const hardening = createBinaryHardeningService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectBinaryHardening,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
hardening.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
hardening,
|
||||
"rea-binary-hardening",
|
||||
"inspect_binary_hardening",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_elf_notes"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectElfNotes,
|
||||
description:
|
||||
"Inspect ELF PT_NOTE and SHT_NOTE identities without executing the image",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: { path: { description: "Local ELF32/ELF64 image" } },
|
||||
},
|
||||
inspectWithService(createElfNotesService, "rea-elf-notes"),
|
||||
);
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_native_initializers"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectNativeInitializers,
|
||||
description:
|
||||
"List ELF and Mach-O initializer and finalizer functions without executing the image",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: {
|
||||
path: {
|
||||
description:
|
||||
"Local ELF32/ELF64, thin Mach-O or universal Mach-O image",
|
||||
},
|
||||
architecture: {
|
||||
description:
|
||||
"Slice to read from a universal Mach-O, by CPU family; when several slices share a family, arm64 (arm64 or arm64v8), arm64e (arm64e or arm64e.x1) or x86_64 names the subtype, and a value matching several slices is refused; required for universal files",
|
||||
},
|
||||
},
|
||||
},
|
||||
inspectWithService(
|
||||
createNativeInitializersService,
|
||||
"rea-native-initializers",
|
||||
),
|
||||
);
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_elf_unwind_ranges"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectElfUnwindRanges,
|
||||
description:
|
||||
"Inspect ELF unwind function ranges without executing the image",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: { path: { description: "Local ELF32/ELF64 image" } },
|
||||
},
|
||||
inspectWithService(createElfUnwindRangesService, "rea-elf-unwind-ranges"),
|
||||
);
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_apple_ips"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectAppleIps,
|
||||
description:
|
||||
"Inspect an Apple .ips crash report without executing a target",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path", "join_path"],
|
||||
fields: {
|
||||
path: { description: "Local Apple .ips crash report" },
|
||||
join_path: {
|
||||
description:
|
||||
"Optional local Mach-O executable or dSYM whose slice LC_UUID matches report images",
|
||||
},
|
||||
},
|
||||
},
|
||||
inspectWithService(createAppleIpsService, "rea-apple-ips"),
|
||||
);
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_kernel_module"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectKernelModule,
|
||||
description:
|
||||
"Inspect Linux kernel module metadata without executing the module",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: {
|
||||
path: {
|
||||
description:
|
||||
"Local ELF32/ELF64 kernel module or compressed .ko container",
|
||||
},
|
||||
},
|
||||
},
|
||||
inspectWithService(createKernelModuleService, "rea-kernel-module"),
|
||||
);
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_kernel_build_config"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectKernelBuildConfig,
|
||||
description:
|
||||
"Inspect a Linux kernel image's version banner and embedded build config without executing it",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: {
|
||||
path: {
|
||||
description:
|
||||
"Local vmlinux ELF, raw Image, x86 bzImage/zImage, or configs.ko",
|
||||
},
|
||||
},
|
||||
},
|
||||
inspectWithService(
|
||||
createKernelBuildConfigService,
|
||||
"rea-kernel-build-config",
|
||||
),
|
||||
);
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_pe_load_config"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectPeLoadConfig,
|
||||
description:
|
||||
"Inspect PE TLS callbacks and load configuration without executing the image",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: { path: { description: "Local PE32/PE32+ image" } },
|
||||
},
|
||||
inspectWithService(createPeLoadConfigService, "rea-pe-load-config"),
|
||||
);
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_binary_hardening"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectBinaryHardening,
|
||||
description:
|
||||
"Inspect ELF, PE, and Mach-O hardening without executing the image",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: { path: { description: "Local ELF, PE, or Mach-O image" } },
|
||||
},
|
||||
inspectWithService(createBinaryHardeningService, "rea-binary-hardening"),
|
||||
);
|
||||
const entropy = createByteEntropyService();
|
||||
cli.command(CLI_COMMANDS.inspectByteEntropy, {
|
||||
description:
|
||||
"Inspect file-wide and block byte entropy without executing the file",
|
||||
args: z.object({ path: localPathStringSchema.describe("Local file") }),
|
||||
options: z.object({
|
||||
// Decimal tokens only: numeric coercion would read "" as 0 and accept
|
||||
// "0x10" or "1e2".
|
||||
blockSize: cliDecimalField(
|
||||
inspectByteEntropyInputSchema.shape.block_size,
|
||||
).describe("Power-of-two block size from 256 to 65536 bytes"),
|
||||
offset: cliDecimalField(
|
||||
inspectByteEntropyInputSchema.shape.offset,
|
||||
).describe("Window start as a decimal file byte offset"),
|
||||
length: cliDecimalField(
|
||||
inspectByteEntropyInputSchema.shape.length,
|
||||
).describe("Window length in bytes; omit to extend through EOF"),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation((signal) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.inspectByteEntropy, async () => {
|
||||
return await finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
entropy.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
block_size: options.blockSize,
|
||||
offset: options.offset,
|
||||
length: options.length,
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
entropy,
|
||||
BYTE_ENTROPY_PROVIDER.id,
|
||||
"inspect_byte_entropy",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult);
|
||||
}),
|
||||
),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectPeCertificates, {
|
||||
description:
|
||||
"Inspect PE Authenticode certificate table identities without verifying signatures",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe("Local PE32/PE32+ image"),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectPeCertificatesInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
maxEntries: cliDecimalField(
|
||||
inspectPeCertificatesInputSchema.shape.max_entries,
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const pe = createPeCertificatesService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectPeCertificates,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
pe.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
max_entries: options.maxEntries,
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
pe,
|
||||
"rea-pe-certificates",
|
||||
"inspect_pe_certificates",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectPeImports, {
|
||||
description:
|
||||
"Inspect PE import and delay-load table identities without executing the image",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe("Local PE32/PE32+ image"),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectPeImportsInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
maxDlls: cliDecimalField(inspectPeImportsInputSchema.shape.max_dlls),
|
||||
maxFunctions: cliDecimalField(
|
||||
inspectPeImportsInputSchema.shape.max_functions,
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const pe = createPeImportsService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectPeImports,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
pe.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
max_dlls: options.maxDlls,
|
||||
max_functions: options.maxFunctions,
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
pe,
|
||||
"rea-pe-imports",
|
||||
"inspect_pe_imports",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectWindowsShortcut, {
|
||||
description:
|
||||
"Inspect a Windows Shell Link (.lnk) without resolving or executing the target",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe(
|
||||
"Local Windows Shell Link (.lnk) file",
|
||||
),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectWindowsShortcutInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
maxIdListItems: cliDecimalField(
|
||||
inspectWindowsShortcutInputSchema.shape.max_id_list_items,
|
||||
),
|
||||
maxExtraDataBlocks: cliDecimalField(
|
||||
inspectWindowsShortcutInputSchema.shape.max_extra_data_blocks,
|
||||
),
|
||||
maxStringBytes: cliDecimalField(
|
||||
inspectWindowsShortcutInputSchema.shape.max_string_bytes,
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const shortcut = createWindowsShortcutService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectWindowsShortcut,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
shortcut.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
max_id_list_items: options.maxIdListItems,
|
||||
max_extra_data_blocks: options.maxExtraDataBlocks,
|
||||
max_string_bytes: options.maxStringBytes,
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
shortcut,
|
||||
"rea-windows-shortcut",
|
||||
"inspect_windows_shortcut",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectPeResources, {
|
||||
description:
|
||||
"Inspect PE resource identities, payload ranges, hashes and icon-group relationships",
|
||||
args: z.object({
|
||||
path: localPathStringSchema.describe("Local PE32/PE32+ image"),
|
||||
}),
|
||||
options: z.object({
|
||||
maxFileBytes: cliDecimalField(
|
||||
inspectPeResourcesInputSchema.shape.max_file_bytes,
|
||||
),
|
||||
maxEntries: cliDecimalField(
|
||||
inspectPeResourcesInputSchema.shape.max_entries,
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation(async (signal) => {
|
||||
const pe = createPeResourcesService();
|
||||
return await logCliCommand(
|
||||
logger,
|
||||
CLI_COMMANDS.inspectPeResources,
|
||||
async () =>
|
||||
finishCliEvidenceCommand(
|
||||
args.path,
|
||||
() =>
|
||||
pe.inspect(
|
||||
{
|
||||
path: absoluteCallerPath(args.path),
|
||||
max_file_bytes: options.maxFileBytes,
|
||||
max_entries: options.maxEntries,
|
||||
},
|
||||
{ signal },
|
||||
),
|
||||
pe,
|
||||
"rea-pe-resources",
|
||||
"inspect_pe_resources",
|
||||
signal,
|
||||
).then(projectCliAnalysisResult),
|
||||
);
|
||||
}),
|
||||
});
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_byte_entropy"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectByteEntropy,
|
||||
description:
|
||||
"Inspect file-wide and block byte entropy without executing the file",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: {
|
||||
path: { description: "Local file" },
|
||||
block_size: {
|
||||
description: "Power-of-two block size from 256 to 65536 bytes",
|
||||
},
|
||||
offset: { description: "Window start as a decimal file byte offset" },
|
||||
length: {
|
||||
description: "Window length in bytes; omit to extend through EOF",
|
||||
},
|
||||
},
|
||||
omit: {
|
||||
detail:
|
||||
"One-shot output is complete Evidence; this command has no summary delivery",
|
||||
},
|
||||
},
|
||||
inspectWithService(() => entropy, BYTE_ENTROPY_PROVIDER.id),
|
||||
);
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_pe_certificates"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectPeCertificates,
|
||||
description:
|
||||
"Inspect PE Authenticode certificate table identities without verifying signatures",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: { path: { description: "Local PE32/PE32+ image" } },
|
||||
},
|
||||
inspectWithService(createPeCertificatesService, "rea-pe-certificates"),
|
||||
);
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_pe_imports"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectPeImports,
|
||||
description:
|
||||
"Inspect PE import and delay-load table identities without executing the image",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: { path: { description: "Local PE32/PE32+ image" } },
|
||||
},
|
||||
inspectWithService(createPeImportsService, "rea-pe-imports"),
|
||||
);
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_windows_shortcut"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectWindowsShortcut,
|
||||
description:
|
||||
"Inspect a Windows Shell Link (.lnk) without resolving or executing the target",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: {
|
||||
path: { description: "Local Windows Shell Link (.lnk) file" },
|
||||
},
|
||||
},
|
||||
inspectWithService(createWindowsShortcutService, "rea-windows-shortcut"),
|
||||
);
|
||||
registerContractCommand(
|
||||
cli,
|
||||
logger,
|
||||
contract("inspect_pe_resources"),
|
||||
{
|
||||
command: CLI_COMMANDS.inspectPeResources,
|
||||
description:
|
||||
"Inspect PE resource identities, payload ranges, hashes and icon-group relationships",
|
||||
positionals: ["path"],
|
||||
callerPaths: ["path"],
|
||||
fields: { path: { description: "Local PE32/PE32+ image" } },
|
||||
},
|
||||
inspectWithService(createPeResourcesService, "rea-pe-resources"),
|
||||
);
|
||||
cli.command(CLI_COMMANDS.inspectDevicetree, {
|
||||
description: "Inspect a flattened devicetree blob without executing it",
|
||||
args: z.object({
|
||||
|
||||
Reference in new issue
Block a user