Files
reverse-engineering-anything/src/contracts/rizinDebugToolContracts.ts
T
morluto 2234a7db57 fix(mcp)!: require absolute local paths for pcap capture and debugger sessions (#11508)
* fix(mcp)!: require absolute local paths for pcap capture and debugger sessions

The MCP server's working directory is not the caller's, so sibling local
file contracts refuse a relative path. inspect_pcap_capture (path),
start_rizin_debug_session (path, inferior_tty) and start_gdb_session
(inferior_tty) admitted one and resolved it against the server's
directory. They now use absoluteLocalPathStringSchema.

The inspect-pcap-capture CLI command declares path as a caller path, so
a relative CLI argument is still resolved against the caller's working
directory before the contract sees it. debug-with-rizin and
debug-with-gdb call their managers directly and are unchanged.

BREAKING CHANGE: MCP calls to inspect_pcap_capture,
start_rizin_debug_session and start_gdb_session with a relative path or
inferior_tty are refused with invalid_request. Pass absolute paths.

Fixes #11079

* test(mcp): call the debugger session tools with absolute paths

* fix(cli): describe the inspect-pcap-capture path without the MCP absolute requirement

The CLI resolves a relative capture path, so its help keeps the
caller-path description instead of inheriting the contract's absolute
wording.

* test(pcap): expect the absolute-path format issue beside the empty-path bound
2026-11-16 09:48:52 +08:00

159 lines
6.5 KiB
TypeScript

import { z } from "zod";
import { DEBUGGER_SESSION_STOP_CODES } from "../domain/debuggerSessionErrors.js";
import { absoluteLocalPathStringSchema } from "../domain/localPath.js";
import type { ToolContract } from "./toolContractTypes.js";
import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
import { toolContractMetadata, toolEffects } from "./toolEffects.js";
const sessionId = z.string().uuid();
const commandResult = z.strictObject({
command: z.string(),
output: z.string(),
output_scope: z.literal("command_and_interleaved_session_output"),
output_truncated: z.boolean(),
output_invalid_utf8: z.literal(true).optional(),
// lifecycle-state: whether the debugger command finished, not coverage of its output.
completion_status: z.enum(["complete", "unknown"]),
backend: z.string().nullable(),
});
/** Persistent Rizin debugger session contracts. */
export const RIZIN_DEBUG_TOOL_CONTRACTS = [
{
name: "start_rizin_debug_session",
availability: { host: "persistentDebugger" },
...toolContractMetadata(
"start_rizin_debug_session",
toolEffects({
mutatesTarget: true,
mutatesSession: true,
launchesProcess: true,
accessesNetwork: true,
executesForeignCode: true,
idempotent: false,
}),
),
kind: "native-provider",
description:
"Start a persistent Rizin debugger for one selected target/backend. Linux and a caller-selected TTY for inferior stdin/stdout/stderr are required; the target may use that terminal after detach. Startup suppresses user settings/scripts while retaining plugins. Detach requires verified output sinks, no target access to the debugger command stream, and dbg.exitkills=false. Capabilities depend on the installed backend. This shared-server operation retires binary analysis: close Ghidra explicitly first, then reopen the binary after effects settle.",
inputSchema: z.strictObject({
path: absoluteLocalPathStringSchema,
inferior_tty: absoluteLocalPathStringSchema,
backend: z.string().min(1).optional(),
}),
outputSchema: z.strictObject({
session_id: sessionId,
backend: z.string().nullable(),
}),
examples: [
{
title: "Start Rizin debugger",
input: { path: "/tmp/program", inferior_tty: "/dev/pts/7" },
},
],
},
{
name: "rizin_debug_command",
...toolContractMetadata(
"rizin_debug_command",
toolEffects({
mutatesTarget: true,
mutatesSession: true,
executesForeignCode: true,
writesFilesystem: true,
launchesProcess: true,
accessesNetwork: true,
changesUiState: true,
mayDiscardData: true,
idempotent: false,
}),
),
kind: "native-provider",
description:
"Run one unrestricted command in a persistent Rizin debugger; it can access target state, plugins, shell, files and network. Returns raw/interleaved session output as Evidence. Output/frame limits stop the owned debugger and retain partial output with output_truncated and unknown completion. Prequeued unsolicited frames refuse the call because correlation is ambiguous. This shared-server operation retires binary analysis: close Ghidra explicitly first, then reopen the binary after effects settle.",
inputSchema: z.strictObject({
session_id: sessionId,
command: z
.string()
.min(1)
.refine(
(value) => !/[\r\n]/u.test(value),
"A single command line is required",
),
}),
outputSchema: evidenceResultOf(commandResult),
examples: [
{
title: "Inspect debugger state",
input: {
session_id: "00000000-0000-4000-8000-000000000001",
command: "dr",
},
},
],
},
{
name: "rizin_debug_session_status",
...toolContractMetadata(
"rizin_debug_session_status",
toolEffects({ mutatesSession: true }),
),
kind: "native-provider",
description:
"Return observed lifecycle state and bounded recent NUL-framed output and process diagnostics for one Rizin debugger session; closed_reason says why a closed session stopped, truncation fields report discarded data, and output_invalid_utf8 reports whether invalid UTF-8 has been observed in session frame bytes; recent output may contain replacement characters.",
inputSchema: z.strictObject({ session_id: sessionId }),
outputSchema: z.strictObject({
session_id: sessionId,
state: z.enum(["ready", "closed"]),
inferior_tty: z.string(),
recent_output: z.array(z.string()),
recent_output_truncated: z.boolean(),
diagnostics_truncated: z.boolean(),
output_invalid_utf8: z.boolean(),
closed_reason: z
.string()
.exactOptional()
.describe(
"Present when state is closed: why the session stopped accepting commands. Close it and start a new session to continue.",
),
closed_reason_code: z
.enum(DEBUGGER_SESSION_STOP_CODES)
.exactOptional()
.describe(
"Present with closed_reason: input-stream-failure, output-correlation-failure, command-deadline, command-cancelled, server-shutdown, close-requested, process-exited, or stopped.",
),
}),
examples: [
{
title: "Check Rizin session",
input: { session_id: "00000000-0000-4000-8000-000000000001" },
},
],
},
{
name: "close_rizin_debug_session",
...toolContractMetadata(
"close_rizin_debug_session",
toolEffects({
mutatesSession: true,
launchesProcess: true,
accessesNetwork: true,
mutatesTarget: true,
executesForeignCode: true,
}),
),
kind: "native-provider",
description:
"Close the REA-owned Rizin debugger only after verifying no inferior remains or detaching one with a verified caller-selected TTY output sink. A detached target may continue running, read from and write to that TTY; target state is otherwise reported as unknown. REA never signals an inferior based on PID or path. In a shared MCP server, this admitted close retires any active binary-analysis session; after target effects have settled, call open_binary before further analysis. Close an active Ghidra session explicitly first.",
inputSchema: z.strictObject({ session_id: sessionId }),
outputSchema: z.strictObject({ target_state: z.literal("unknown") }),
examples: [
{
title: "Close Rizin debugger",
input: { session_id: "00000000-0000-4000-8000-000000000001" },
},
],
},
] as const satisfies readonly ToolContract[];