Files
reverse-engineering-anything/src/cli/binaryDiagnosticsCommands.ts
T
Matt Van Hornandgensokyo-dev e9c72dbd1f feat(elf): inspect dynamic dependencies and required symbol versions
Add offline ELF dependency, search-path, symbol-version and import inspection with retained Evidence summaries and pages. Bound GNU-hash work and preserve cancellation, stable identity and caller-selected parameters across CLI/MCP.

Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning)
Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2026-11-17 08:19:52 +00:00

376 lines
12 KiB
TypeScript

import {
createByteEntropyService,
createRecordedCrashService,
createBinaryLayoutService,
createElfNotesService,
createNativeInitializersService,
createElfUnwindRangesService,
createAppleIpsService,
createDevicetreeService,
createKernelModuleService,
createKernelBuildConfigService,
createPeLoadConfigService,
createBinaryHardeningService,
createPeResourcesService,
createPeCertificatesService,
createPeImportsService,
createWindowsShortcutService,
createNativeExportsService,
createElfDependenciesService,
} from "../composition/binaryDiagnostics.js";
import type { Logger } from "pino";
import type { CliInstance } from "./types.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { withEvidenceCallerInputPath } from "../domain/evidence.js";
import { BYTE_ENTROPY_PROVIDER } from "../domain/investigationProviders.js";
import { BINARY_DIAGNOSTICS_TOOL_CONTRACTS } from "../contracts/native/binaryDiagnosticsToolContracts.js";
import { contractNamed } from "./contractCliDescription.js";
import {
callerTargetPath,
deliverWithService,
inspectWithService,
registerContractCommand,
} from "./contractCommand.js";
import { PRODUCER_LIMITS_HELP } from "./producerLimitsOption.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 = (
cli: CliInstance,
logger: Logger,
environment: Readonly<NodeJS.ProcessEnv>,
): void => {
registerContractCommand(
cli,
logger,
contract("inspect_elf_notes"),
{
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"),
{
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"),
{
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"),
{
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"),
{
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"),
{
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"),
{
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"),
{
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();
registerContractCommand(
cli,
logger,
contract("inspect_byte_entropy"),
{
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"),
{
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"),
{
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"),
{
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"),
{
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"),
);
registerContractCommand(
cli,
logger,
contract("inspect_devicetree"),
{
description: "Inspect a flattened devicetree blob without executing it",
positionals: ["path"],
callerPaths: ["path"],
evidenceDelivery: true,
fields: {
path: { description: "Local flattened devicetree image" },
max_file_bytes: { description: "Maximum FDT file size in bytes" },
max_nodes: { description: "Maximum number of device-tree nodes" },
max_properties: {
description: "Maximum number of device-tree properties",
},
max_depth: { description: "Maximum device-tree nesting depth" },
},
},
deliverWithService(createDevicetreeService, "rea-devicetree"),
);
registerContractCommand(
cli,
logger,
contract("inspect_native_exports"),
{
description:
"Inspect a PE or ELF image's export table without executing it",
positionals: ["path"],
callerPaths: ["path"],
evidenceDelivery: true,
fields: { path: { description: "Local PE or ELF image" } },
},
deliverWithService(createNativeExportsService, "rea-native-exports"),
);
registerContractCommand(
cli,
logger,
contract("inspect_elf_dependencies"),
{
description:
"Inspect ELF needed libraries and required symbol versions without executing the image",
positionals: ["path"],
callerPaths: ["path"],
evidenceDelivery: true,
fields: {
path: { description: "Local ELF32/ELF64 ET_EXEC or ET_DYN image" },
},
},
deliverWithService(createElfDependenciesService, "rea-elf-dependencies"),
);
const layout = createBinaryLayoutService(environment);
registerContractCommand(
cli,
logger,
contract("inspect_binary_layout"),
{
description:
"Inspect binary file/linked layout without executing the selected object",
positionals: ["path"],
callerPaths: ["path"],
jsonText: ["producer_limits"],
fields: {
path: { description: "Local ELF binary or relocatable object" },
producer_limits: { description: PRODUCER_LIMITS_HELP },
},
omit: {
detail:
"One-shot output is complete Evidence; this command has no summary delivery",
},
},
async (input, context) => {
const result = await layout.inspectAndClose(input, {
signal: context.signal,
});
return result.ok
? withEvidenceCallerInputPath(result.value, callerTargetPath(context))
: projectAnalysisError(result.error);
},
);
const recorded = createRecordedCrashService(environment);
registerContractCommand(
cli,
logger,
contract("inspect_recorded_crash"),
{
description:
"Inspect supplied core registers/signals and optional debugger mapping evidence",
positionals: ["path"],
callerPaths: ["path"],
jsonText: ["producer_limits"],
fields: {
path: {
description: "Local Linux ELF64 amd64 or AArch64 little-endian core",
},
producer_limits: { description: PRODUCER_LIMITS_HELP },
include_debugger_context: {
name: "debuggerContext",
description: "Add BYO core-only GDB/pwndbg mapping candidates",
},
},
},
async (input, context) => {
const result = await recorded.inspectAndClose(input, {
signal: context.signal,
});
return result.ok
? withEvidenceCallerInputPath(result.value, callerTargetPath(context))
: projectAnalysisError(result.error);
},
);
};