mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 21:23:45 +00:00
* 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
159 lines
6.5 KiB
TypeScript
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[];
|