Files
reverse-engineering-anything/src/cli/fridaCommands.ts
T
morluto 07c5a54fee refactor(cli): import zod directly instead of through incur (#11655)
* refactor(cli): import zod directly instead of through incur

* fix(verify): count incur z imports from declarations, not comment or string text
2026-11-16 10:37:43 +08:00

265 lines
9.4 KiB
TypeScript

import { projectCliAnalysisResult } from "./projectCliAnalysisResult.js";
import { z } from "zod";
import { FridaInstrumentationService } from "../application/frida/FridaInstrumentationService.js";
import type { FridaInstrumentationPort } from "../ports/frida/FridaInstrumentationPort.js";
import { createFridaInstrumentationProvider } from "../composition/frida.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { AnalysisInputError } from "../domain/analysisErrorCore.js";
import { err, ok, type Result } from "../domain/result.js";
import type {
AnalysisError,
AnalysisPartialObservation,
} from "../domain/analysisErrorBase.js";
import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
import {
fridaDeviceSelection,
fridaRemoteConnection,
instrumentWithFrida,
} from "../application/frida/fridaContractRequests.js";
import { contractNamed } from "./contractCliDescription.js";
import { registerContractCommand } from "./contractCommand.js";
import { FRIDA_TOOL_CONTRACTS } from "../contracts/fridaToolContracts.js";
import type { Logger } from "pino";
import type { CliInstance } from "./types.js";
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
/** Script sources stay optional in the options schema; exactly one is required. */
const exactlyOneScriptSource =
"Provide exactly one of --script or --script-file.";
/** The CLI selects the local device when the caller selects none. */
const localUnlessSelected = <
Input extends { readonly device_id?: unknown; readonly remote?: unknown },
>(
input: Input,
): Input =>
input.device_id === undefined && input.remote === undefined
? { ...input, device_id: "local" }
: input;
/** Register Frida discovery and one-shot instrumentation CLI operations. */
export const registerFridaCommands = (
cli: CliInstance,
logger: Logger,
provider: FridaInstrumentationPort = createFridaInstrumentationProvider(),
): void => {
const service = new FridaInstrumentationService(provider);
// CLI calls own a disposable provider; MCP retains its shared provider until
// server shutdown. Await cleanup here, including failed startup resources.
const cleanup = { close: () => provider.closeAll() };
const instrumentContract = contractNamed(
FRIDA_TOOL_CONTRACTS,
"instrument_with_frida",
);
// Discovery commands take each remote member as its own option; any one
// supplies the whole `remote` object, so the contract names a missing
// address.
const remoteMembers = {
address: {
name: "remoteAddress",
description: "Remote Frida host address, optionally with a port",
},
token: { description: "Remote authentication token" },
certificate: { description: "Remote TLS certificate" },
origin: { description: "Remote connection origin" },
keepalive_interval: { name: "keepaliveInterval" },
};
// Discovery admits the request MCP would send, then runs it.
const discover =
<Input, Value extends AnalysisPartialObservation>(
contract: { readonly name: string; readonly inputSchema: z.ZodType },
run: (input: Input) => Promise<Result<Value, AnalysisError>>,
selected: (input: Input) => Input = (input) => input,
) =>
(input: Input, { signal }: { readonly signal: AbortSignal }) =>
finishAnalysisCommand(
async () => {
const candidate = selected(input);
const admitted = contract.inputSchema.safeParse(candidate);
return admitted.success
? run(admitted.data as Input)
: err(
analysisInputErrorFromIssues(
contract.name,
admitted.error.issues,
candidate,
),
);
},
cleanup,
"frida",
contract.name,
signal,
).then(projectCliAnalysisResult);
const listDevices = contractNamed(FRIDA_TOOL_CONTRACTS, "list_frida_devices");
const listProcesses = contractNamed(
FRIDA_TOOL_CONTRACTS,
"list_frida_processes",
);
registerContractCommand(
cli,
logger,
listDevices,
{
description: "List local Frida devices and an optional remote endpoint",
flatten: { remote: remoteMembers },
},
discover(listDevices, (input) =>
service.listDevices(fridaRemoteConnection(input.remote)),
),
);
registerContractCommand(
cli,
logger,
listProcesses,
{
description: "List processes visible through a Frida device",
fields: { device_id: { description: "Frida device identifier" } },
flatten: { remote: remoteMembers },
},
discover(
listProcesses,
(input) => service.listProcesses(fridaDeviceSelection(input)),
localUnlessSelected,
),
);
// One target positional selects the PID or the program by mode, and the
// script option given selects source_kind; the handler fills those
// fields and the contract admits the request MCP would send.
registerContractCommand(
cli,
logger,
instrumentContract,
{
description: `Run one Frida script against a selected process and detach. ${exactlyOneScriptSource}`,
positionals: ["mode"],
cliOptions: {
target: z
.string()
.min(1)
.describe("Process ID for attach or program path for spawn"),
},
cliPositionals: ["target"],
handlerFields: ["pid", "program", "source_kind"],
// The CLI resolves a relative script file against the caller's
// directory; the contract admits only absolute paths.
callerPaths: ["path"],
fields: {
mode: { description: "Attach to a PID or spawn a program" },
device_id: { description: "Frida device identifier" },
source: {
name: "script",
description: `Inline JavaScript to load. ${exactlyOneScriptSource}`,
},
path: {
name: "scriptFile",
description: `Path to JavaScript source file. ${exactlyOneScriptSource}`,
},
argv: {
name: "argument",
description: "Arguments passed to a spawned target",
},
duration_ms: {
description: "Instrumentation duration in milliseconds",
},
},
flatten: {
remote: remoteMembers,
capture_limits: {
session_bytes: {
name: "captureSessionBytes",
description:
"Session retention bytes including encoded payloads; select before starting the experiment",
},
message_text_bytes: {
name: "captureMessageTextBytes",
description: "Retained bytes per Frida error text field",
},
message_type_bytes: {
name: "captureMessageTypeBytes",
description: "Retained bytes per Frida message type",
},
json_nodes: {
name: "captureJsonNodes",
description: "Retained JSON nodes per Frida payload",
},
json_depth: {
name: "captureJsonDepth",
description: "Retained JSON nesting depth per Frida payload",
},
},
},
},
(input, { signal, cliOptions: { target } }) => {
const refused = (
path: string,
message: string,
): Promise<ReturnType<typeof projectAnalysisError>> =>
Promise.resolve(
projectAnalysisError(
new AnalysisInputError(instrumentContract.name, undefined, [
{ path: [path], reason: "invalid_value", message },
]),
),
);
if (input.mode === "attach" && input.argv !== undefined)
return refused(
"argv",
"--argument is only valid in spawn mode; remove it when attaching to a process.",
);
if ((input.source === undefined) === (input.path === undefined))
return refused("source", exactlyOneScriptSource);
if (input.device_id !== undefined && input.remote !== undefined)
return refused(
"device_id",
"Choose either --device-id or --remote-address, not both",
);
const pid =
/^[0-9]+$/u.test(target) &&
Number.isSafeInteger(Number(target)) &&
Number(target) > 0
? Number(target)
: undefined;
if (input.mode === "attach" && pid === undefined)
return refused(
"target",
"attach mode needs a positive integer process ID.",
);
const candidate = localUnlessSelected({
...input,
...(input.mode === "attach" ? { pid } : { program: target }),
source_kind: input.path === undefined ? "inline" : "file",
});
// The contract admits the request MCP would send.
const admitted = instrumentContract.inputSchema.safeParse(candidate);
if (!admitted.success)
return Promise.resolve(
projectAnalysisError(
analysisInputErrorFromIssues(
instrumentContract.name,
admitted.error.issues,
candidate,
),
),
);
return finishAnalysisCommand(
async () => {
const result = await instrumentWithFrida(
service,
admitted.data,
signal,
);
if (!result.ok) return result;
if (result.value.cleanupError !== null) process.exitCode = 1;
return ok(result.value.evidence);
},
cleanup,
"frida",
instrumentContract.name,
signal,
).then(projectCliAnalysisResult);
},
);
};