Files
reverse-engineering-anything/src/cli/reverseEngineeringCommands.ts
T
morluto f14e9a1d28 refactor(cli): register every command in an REA-owned command table (#11680)
* refactor(cli): register every command in an REA-owned command table

* fix(cli): flag grouped fields and named selectors in each command's input binding
2026-11-16 11:39:07 +08:00

386 lines
13 KiB
TypeScript

import { z } from "zod";
import { localPathStringSchema } from "../domain/localPath.js";
import type { Logger } from "pino";
import { OBJDUMP_PROVIDER_IDENTITY } from "../objdump/ObjdumpProviderIdentity.js";
import { RIZIN_PROVIDER_IDENTITY } from "../rizin/RizinProviderIdentity.js";
import { createReverseEngineeringService } from "../composition/reverseEngineering.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import {
AnalysisInputError,
AnalysisOutputError,
} from "../domain/analysisErrorCore.js";
import type { Evidence } from "../domain/evidence.js";
import { recognizeEvidence } from "../domain/evidenceValidation.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { Result } from "../domain/result.js";
import { ok } from "../domain/result.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { OBJDUMP_ARTIFACT_OPERATIONS } from "../domain/reverseEngineering.js";
import { logCliCommand } from "../cliLogging.js";
import { registerCliCommand } from "./commandRegistry.js";
import type { CliInstance } from "./types.js";
import { withCommandCancellation } from "./commandCancellation.js";
import { CLI_COMMANDS } from "../contracts/cliCommandNames.js";
import { REVERSE_ENGINEERING_TOOL_CONTRACTS } from "../contracts/reverseEngineeringToolContracts.js";
import { contractNamed } from "./contractCliDescription.js";
import {
registerContractCommand,
type ContractCommandContext,
} from "./contractCommand.js";
import type { ReverseEngineeringService } from "../application/reverse/ReverseEngineeringService.js";
import { gdbOneShotCommandMayInvalidateDetachProof } from "../gdb/GdbSessionManager.js";
import {
createGdbSessionManager,
createRizinDebugSessionManager,
} from "../composition/debuggerSessions.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import {
retainedDebuggerDiagnostics,
retainedDebuggerProcessIds,
retainedDebuggerRemediation,
} from "../process/ownedDebuggerCleanupError.js";
import {
analysisEvidenceDeliveryOptions,
cliEvidenceDeliveryInputError,
deliverCliAnalysisEvidence,
publishCliAnalysisEvidence,
} from "./analysisEvidenceDelivery.js";
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
import { projectCliAnalysisResult } from "./projectCliAnalysisResult.js";
import { errorMessage } from "../kernel/errorMessage.js";
import { isRecord } from "../kernel/isRecord.js";
const executeWithCleanup = async (
service: ReverseEngineeringService,
signal: AbortSignal,
execute: () => Promise<Result<Evidence, AnalysisError>>,
operation: "inspect_with_objdump" | "execute_rizin_command",
) =>
finishAnalysisCommand(
execute,
service,
operation === "inspect_with_objdump"
? OBJDUMP_PROVIDER_IDENTITY.id
: RIZIN_PROVIDER_IDENTITY.id,
operation,
signal,
undefined,
{ recoverResolvedCleanup: cleanupOnlyCompleteEvidence },
);
const cleanupOnlyCompleteEvidence = (
error: AnalysisError,
): Evidence | undefined => {
if (
!(error instanceof AnalysisOutputError) ||
!error.cleanupOnly ||
error.partialObservation === undefined
)
return undefined;
// Only authenticated Evidence is recovered; otherwise the error stands.
const parsed = recognizeEvidence(error.partialObservation);
if (!parsed.ok || parsed.value === undefined) return undefined;
const normalized = parsed.value.normalized_result;
return isRecord(normalized) && normalized.completion_status !== "unknown"
? parsed.value
: undefined;
};
/** One-shot debugger cleanup: the retained owner's closeAll decides whether cleanup remains incomplete. */
const closeDebuggerCommandSession = async (
manager: {
close(sessionId: string): Promise<Result<unknown, AnalysisError>>;
closeAll(): Promise<void>;
},
sessionId: string | undefined,
providerId: string,
operation: string,
log: (cleanup: JsonValue | string) => void,
): Promise<void> => {
if (sessionId !== undefined) {
try {
const closed = await manager.close(sessionId);
if (!closed.ok) log(projectAnalysisError(closed.error));
} catch (cause) {
log(cause instanceof Error ? cause.message : "Unknown cleanup failure");
}
}
try {
await manager.closeAll();
} catch (cause) {
// This process is the only owner, so a caller gets the debugger to check
// rather than a retry that no later command could perform.
const retainedPids = retainedDebuggerProcessIds(cause);
throw new ProviderCleanupError(
providerId,
sessionId === undefined ? [] : [sessionId],
{
reason:
cause instanceof AggregateError
? cause.errors
.map((error: unknown) => errorMessage(error))
.join("; ")
: errorMessage(cause),
...retainedDebuggerDiagnostics(cause),
},
{
cause,
operation,
...(retainedPids.length === 0
? {}
: { remediationAction: retainedDebuggerRemediation(retainedPids) }),
},
);
}
};
/** Add one-shot reverse-engineering commands using the shared service layer. */
export const registerReverseEngineeringCommands = (
cli: CliInstance,
logger: Logger,
environment: Readonly<NodeJS.ProcessEnv>,
createGdbManager: (
environment: Readonly<NodeJS.ProcessEnv>,
) => ReturnType<typeof createGdbSessionManager> = createGdbSessionManager,
createService: typeof createReverseEngineeringService = createReverseEngineeringService,
): void => {
const service = createService(environment);
const objdump = contractNamed(
REVERSE_ENGINEERING_TOOL_CONTRACTS,
"inspect_with_objdump",
);
const inspectWithObjdump = async (
input: unknown,
{ signal, delivery }: ContractCommandContext,
) => {
if (delivery === undefined)
throw new Error("inspect_with_objdump delivers Evidence");
const result = await executeWithCleanup(
service,
signal,
() => service.inspectWithObjdump(input, { signal }),
"inspect_with_objdump",
);
return result.ok
? publishCliAnalysisEvidence(result, {
operation: "inspect_with_objdump",
signal,
detail: delivery.detail,
evidenceOutput: delivery.evidenceOutput,
})
: result.error;
};
registerContractCommand(
cli,
logger,
objdump,
{
description:
"Inspect a local artifact using GNU-style objdump arguments and retain the selected command output as Evidence",
inputBranches: {
field: "operation",
values: OBJDUMP_ARTIFACT_OPERATIONS,
},
positionals: ["path", "operation"],
evidenceDelivery: true,
fields: {
path: { description: "Path to the local artifact to inspect." },
operation: { description: "GNU-style objdump operation to run." },
symbol: {
description:
"Native symbol to select with the disassemble operation; the selected executable controls matching and boundaries.",
},
follow_debug_links: {
description:
"Follow local DWARF debug links. External debug-file identity is not bound to Evidence.",
},
},
},
inspectWithObjdump,
);
registerContractCommand(
cli,
logger,
objdump,
{
command: CLI_COMMANDS.listObjdumpArchitectures,
description: "Capture the selected objdump command response to -i",
inputBranches: { field: "operation", values: ["architectures"] },
evidenceDelivery: true,
},
inspectWithObjdump,
);
registerContractCommand(
cli,
logger,
contractNamed(REVERSE_ENGINEERING_TOOL_CONTRACTS, "execute_rizin_command"),
{
description: "Execute one Rizin command against a local artifact",
positionals: ["path", "command"],
fields: {
path: { description: "Path to the local artifact to analyze." },
command: { description: "One caller-selected Rizin command." },
},
},
async (input, { signal }) =>
projectCliAnalysisResult(
await executeWithCleanup(
service,
signal,
() => service.executeRizinCommand(input, { signal }),
"execute_rizin_command",
),
),
);
registerCliCommand(cli, CLI_COMMANDS.debugWithGdb, {
description:
"Run one unrestricted GDB console command in an ephemeral MI session; provide an inferior TTY so a live target can be safely detached",
args: z.object({
command: z
.string()
.min(1)
.describe("One unrestricted GDB console command."),
}),
options: z.object({
inferiorTty: z
.string()
.min(1)
.describe(
"Caller-selected durable TTY for output from a live GDB inferior.",
),
...analysisEvidenceDeliveryOptions,
}),
run: ({ args, options }) =>
withCommandCancellation((signal) =>
logCliCommand(logger, CLI_COMMANDS.debugWithGdb, async () => {
const delivery = {
providerId: "gdb",
operation: "gdb_console",
signal,
detail: options.detail,
evidenceOutput: options.evidence_output,
};
const inputError = cliEvidenceDeliveryInputError(delivery);
if (inputError !== undefined) return projectAnalysisError(inputError);
if (gdbOneShotCommandMayInvalidateDetachProof(args.command))
return projectAnalysisError(
new AnalysisInputError("gdb_console", undefined, [
{
path: ["command"],
reason: "invalid_value",
message:
"This command can invalidate the verified inferior output route; use the persistent GDB session workflow.",
},
]),
);
const manager = createGdbManager(environment);
let sessionId: string | undefined;
return deliverCliAnalysisEvidence({
...delivery,
run: async () => {
const started = await manager.start(signal, {
inferiorTty: options.inferiorTty,
});
if (!started.ok) return started;
sessionId = started.value.session_id;
const executed = await manager.execute(
sessionId,
args.command,
signal,
);
return executed.ok ? ok(executed.value.evidence) : executed;
},
service: {
close: () =>
closeDebuggerCommandSession(
manager,
sessionId,
"gdb",
"gdb_console",
(cleanup) =>
logger.error(
{ command: CLI_COMMANDS.debugWithGdb, cleanup },
"GDB cleanup failed after collecting command output",
),
),
},
});
}),
),
});
registerCliCommand(cli, CLI_COMMANDS.debugWithRizin, {
description:
"Run one unrestricted Rizin debugger command in an ephemeral session",
args: z.object({
path: localPathStringSchema.describe(
"Path to the local artifact to debug.",
),
command: z
.string()
.min(1)
.describe("One unrestricted Rizin debugger command.")
.refine((value) => !/[\r\n]/u.test(value)),
}),
options: z.object({
inferiorTty: z
.string()
.min(1)
.describe(
"Caller-selected Linux TTY for inferior stdin, stdout and stderr.",
),
backend: z
.string()
.min(1)
.optional()
.describe("Optional Rizin IO debugger backend name."),
}),
run: ({ args, options }) =>
withCommandCancellation((signal) =>
logCliCommand(logger, CLI_COMMANDS.debugWithRizin, async () => {
const manager = createRizinDebugSessionManager(environment);
let sessionId: string | undefined;
return finishAnalysisCommand(
async () => {
const started = await manager.start(
{
...args,
inferior_tty: options.inferiorTty,
...(options.backend === undefined
? {}
: { backend: options.backend }),
},
signal,
);
if (!started.ok) return started;
sessionId = started.value.session_id;
const executed = await manager.execute(
sessionId,
args.command,
signal,
);
return executed.ok ? ok(executed.value.evidence) : executed;
},
{
close: () =>
closeDebuggerCommandSession(
manager,
sessionId,
"rizin",
"rizin_debug_command",
(cleanup) =>
logger.error(
{ command: CLI_COMMANDS.debugWithRizin, cleanup },
"Rizin cleanup failed after collecting command output",
),
),
},
"rizin",
"rizin_debug_command",
signal,
).then(projectCliAnalysisResult);
}),
),
});
};