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:
morluto authored and GitHub committed 2026-11-15 04:30:18 +08:00
1 parent 29fb608559
commit f3b697da5a
6 files changed
+1145 -731

No files matched your search

+240 -609
View File
@@ -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({