mirror of
https://github.com/morluto/rea.git
synced 2026-11-18 04:34:13 +00:00
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>
376 lines
12 KiB
TypeScript
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);
|
|
},
|
|
);
|
|
};
|