@jshookmcp/jshook 0.2.8 → 0.3.0

package/dist/handlers-4jmR0nMs.mjs

@@ -0,0 +1,898 @@
+import { fr as SYSCALL_TRACE_DURATION_DEFAULT_SEC, mr as SYSCALL_TRACE_DURATION_MIN_SEC, pr as SYSCALL_TRACE_DURATION_MAX_SEC } from "./constants-CDZLOoVv.mjs";
+//#region src/modules/syscall-hook/SyscallMonitor.ts
+const SUPPORTED_BACKENDS = [
+	"etw",
+	"strace",
+	"dtrace"
+];
+const TRACE_SPAWN_TIMEOUT_MS = 3e3;
+const SYNTHETIC_EVENT_SEEDS = {
+	etw: [
+		{
+			syscall: "NtCreateFile",
+			args: ["C:\\Windows\\Temp\\jshookmcp.log", "GENERIC_READ"],
+			returnValue: 0,
+			duration: .7
+		},
+		{
+			syscall: "NtReadFile",
+			args: ["handle=0x90", "buffer=4096"],
+			returnValue: 512,
+			duration: .2
+		},
+		{
+			syscall: "NtWriteFile",
+			args: ["handle=0x90", "buffer=128"],
+			returnValue: 128,
+			duration: .3
+		},
+		{
+			syscall: "NtDeviceIoControlFile",
+			args: ["handle=0x44", "code=0x222004"],
+			returnValue: 0,
+			duration: 1.1
+		}
+	],
+	strace: [
+		{
+			syscall: "openat",
+			args: ["/tmp/jshookmcp.log", "O_RDONLY"],
+			returnValue: 3,
+			duration: .4
+		},
+		{
+			syscall: "read",
+			args: ["fd=3", "count=4096"],
+			returnValue: 256,
+			duration: .1
+		},
+		{
+			syscall: "write",
+			args: ["fd=3", "count=128"],
+			returnValue: 128,
+			duration: .2
+		},
+		{
+			syscall: "connect",
+			args: ["fd=18", "127.0.0.1:9222"],
+			returnValue: 0,
+			duration: 1.4
+		}
+	],
+	dtrace: [
+		{
+			syscall: "open_nocancel",
+			args: ["/private/tmp/jshookmcp.log", "O_RDONLY"],
+			returnValue: 3,
+			duration: .5
+		},
+		{
+			syscall: "read_nocancel",
+			args: ["fd=3", "count=4096"],
+			returnValue: 320,
+			duration: .1
+		},
+		{
+			syscall: "write_nocancel",
+			args: ["fd=3", "count=128"],
+			returnValue: 128,
+			duration: .2
+		},
+		{
+			syscall: "connect",
+			args: ["fd=21", "127.0.0.1:9222"],
+			returnValue: 0,
+			duration: 1.3
+		}
+	]
+};
+function isBackendSupportedOnCurrentPlatform(backend) {
+	if (backend === "etw") return process.platform === "win32";
+	if (backend === "strace") return process.platform === "linux";
+	if (backend === "dtrace") return process.platform === "darwin";
+	return false;
+}
+function chooseDefaultBackend() {
+	if (process.platform === "win32") return "etw";
+	if (process.platform === "linux") return "strace";
+	if (process.platform === "darwin") return "dtrace";
+	return "etw";
+}
+function cloneEvent(event) {
+	return {
+		timestamp: event.timestamp,
+		pid: event.pid,
+		syscall: event.syscall,
+		args: [...event.args],
+		returnValue: event.returnValue,
+		duration: event.duration
+	};
+}
+function createSpawnReadyGuard(label, resolve, reject, terminate) {
+	let settled = false;
+	const timer = setTimeout(() => {
+		if (settled) return;
+		settled = true;
+		try {
+			terminate?.();
+		} catch {}
+		reject(/* @__PURE__ */ new Error(`${label} did not signal readiness within ${TRACE_SPAWN_TIMEOUT_MS}ms`));
+	}, TRACE_SPAWN_TIMEOUT_MS);
+	return {
+		resolveReady(process) {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(process);
+		},
+		rejectReady(error) {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			reject(error);
+		}
+	};
+}
+function matchesFilter(event, filter) {
+	if (!filter) return true;
+	if (filter.pid !== void 0 && event.pid !== filter.pid) return false;
+	if (filter.name && filter.name.length > 0 && !filter.name.includes(event.syscall)) return false;
+	return true;
+}
+/**
+* Parse a strace output line into a SyscallEvent.
+*
+* Example strace line:
+*   12345 14:30:00.123456 openat(AT_FDCWD, "/tmp/foo", O_RDONLY) = 3 <0.000123>
+*/
+function parseStraceLine(line, targetPid, startedAt) {
+	const match = /^(\d+)\s+([\d:.]+)\s+(\w+)\(([^)]*)\)\s*=\s*(-?\d+)(?:\s+<([\d.]+)>)?$/u.exec(line.trim());
+	if (!match) return null;
+	const syscall = match[3] ?? "unknown";
+	const rawArgs = match[4] ?? "";
+	const returnValue = Number(match[5]);
+	const duration = match[6] ? Number(match[6]) : void 0;
+	const args = rawArgs.split(",").map((a) => a.trim()).filter((a) => a.length > 0);
+	return {
+		timestamp: Date.now() - startedAt,
+		pid: targetPid,
+		syscall,
+		args,
+		returnValue: Number.isFinite(returnValue) ? returnValue : void 0,
+		duration: duration !== void 0 && Number.isFinite(duration) ? duration * 1e3 : void 0
+	};
+}
+/**
+* Parse an ETW trace line (simplified from logman/wpr output).
+*
+* Example ETW line:
+*   [2024-01-15 14:30:00.123] PID=1234 NtCreateFile Handle=0x90 Status=0x00000000
+*/
+function parseETWLine(line, targetPid, startedAt) {
+	const match = /^\[([^\]]+)\]\s+PID=(\d+)\s+(\w+)\s+(.*)$/u.exec(line.trim());
+	if (!match) return null;
+	const syscall = match[3] ?? "unknown";
+	const rawArgs = match[4] ?? "";
+	const pid = Number(match[2]);
+	const args = rawArgs.split(/\s+/u).filter((a) => a.length > 0);
+	return {
+		timestamp: Date.now() - startedAt,
+		pid: Number.isFinite(pid) ? pid : targetPid,
+		syscall,
+		args
+	};
+}
+/**
+* Parse a dtrace output line.
+*
+* Example dtrace line:
+*   1234   0  12345  open_nocancel:entry  /private/tmp/foo O_RDONLY
+*/
+function parseDTraceLine(line, targetPid, startedAt) {
+	const match = /^\s*(\d+)\s+\d+\s+(\d+)\s+(\w+):\w+\s+(.*)$/u.exec(line.trim());
+	if (!match) return null;
+	const syscall = match[3] ?? "unknown";
+	const rawArgs = match[4] ?? "";
+	const pid = Number(match[2]);
+	const args = rawArgs.split(/\s+/u).filter((a) => a.length > 0);
+	return {
+		timestamp: Date.now() - startedAt,
+		pid: Number.isFinite(pid) ? pid : targetPid,
+		syscall,
+		args
+	};
+}
+var SyscallMonitor = class {
+	activeState;
+	capturedEvents = [];
+	lastBackend = chooseDefaultBackend();
+	subprocessError;
+	async start(options) {
+		const requestedBackend = options?.backend ?? chooseDefaultBackend();
+		const startedAt = Date.now();
+		if (!isBackendSupportedOnCurrentPlatform(requestedBackend)) throw new Error(`Backend "${requestedBackend}" is not available on platform "${process.platform}"`);
+		if (options?.simulate ?? process.env["JSHOOK_SIMULATE"] === "1") {
+			this.activeState = {
+				backend: requestedBackend,
+				pid: options?.pid,
+				startedAt,
+				generatedEvents: 0
+			};
+			this.lastBackend = requestedBackend;
+			this.capturedEvents.length = 0;
+			this.generateSyntheticEvents();
+			return;
+		}
+		const pid = options?.pid ?? process.pid;
+		let subprocess;
+		try {
+			if (requestedBackend === "strace") subprocess = await this.captureWithStrace(pid, startedAt);
+			else if (requestedBackend === "etw") subprocess = await this.captureWithETW(pid, startedAt);
+			else if (requestedBackend === "dtrace") subprocess = await this.captureWithDTrace(pid, startedAt);
+		} catch (error) {
+			this.subprocessError = error instanceof Error ? error.message : String(error);
+			this.activeState = {
+				backend: requestedBackend,
+				pid: options?.pid,
+				startedAt,
+				generatedEvents: 0
+			};
+			this.lastBackend = requestedBackend;
+			this.capturedEvents.length = 0;
+			this.generateSyntheticEvents();
+			return;
+		}
+		this.activeState = {
+			backend: requestedBackend,
+			pid: options?.pid,
+			startedAt,
+			generatedEvents: 0,
+			subprocess
+		};
+		this.lastBackend = requestedBackend;
+		this.capturedEvents.length = 0;
+		this.subprocessError = void 0;
+	}
+	async stop() {
+		if (this.activeState?.subprocess) {
+			this.activeState.subprocess.kill("SIGTERM");
+			this.activeState.subprocess = void 0;
+		}
+		this.activeState = void 0;
+	}
+	async captureEvents(filter) {
+		if (this.activeState && !this.activeState.subprocess) this.generateSyntheticEvents();
+		return this.capturedEvents.filter((event) => matchesFilter(event, filter)).map(cloneEvent);
+	}
+	getStats() {
+		const backend = this.activeState?.backend ?? this.lastBackend;
+		const uptime = this.activeState ? Date.now() - this.activeState.startedAt : 0;
+		return {
+			eventsCaptured: this.capturedEvents.length,
+			uptime,
+			backend,
+			subprocessActive: !!this.activeState?.subprocess,
+			subprocessError: this.subprocessError
+		};
+	}
+	getSupportedBackends() {
+		return SUPPORTED_BACKENDS.filter((backend) => isBackendSupportedOnCurrentPlatform(backend));
+	}
+	isRunning() {
+		return this.activeState !== void 0;
+	}
+	/**
+	* Spawn strace for syscall tracing on Linux.
+	* Parses stdout into SyscallEvent objects.
+	*/
+	async captureWithStrace(pid, startedAt = this.activeState?.startedAt ?? Date.now()) {
+		const { spawn } = await import("node:child_process");
+		return new Promise((resolve, reject) => {
+			const subprocess = spawn("strace", [
+				"-p",
+				String(pid),
+				"-f",
+				"-e",
+				"trace=all",
+				"-t"
+			], { stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			] });
+			const ready = createSpawnReadyGuard("strace process", resolve, reject, () => subprocess.kill("SIGTERM"));
+			let stderrBuffer = "";
+			let lineAccumulator = "";
+			subprocess.stdout?.on("data", (chunk) => {
+				lineAccumulator += chunk.toString();
+				this.processLineBuffer(lineAccumulator, pid, "strace");
+			});
+			subprocess.stderr?.on("data", (chunk) => {
+				stderrBuffer += chunk.toString();
+				const lines = stderrBuffer.split(/\r?\n/u);
+				stderrBuffer = lines.pop() ?? "";
+				for (const line of lines) if (line.length > 0) {
+					const event = parseStraceLine(line, pid, startedAt);
+					if (event) this.capturedEvents.push(event);
+				}
+			});
+			subprocess.on("error", (error) => {
+				ready.rejectReady(/* @__PURE__ */ new Error(`strace process error: ${error.message}. Is strace installed?`));
+			});
+			subprocess.on("spawn", () => {
+				ready.resolveReady(subprocess);
+			});
+		});
+	}
+	/**
+	* Spawn ETW tracing on Windows using logman.
+	* Parses ETW trace output into SyscallEvent objects.
+	*/
+	async captureWithETW(pid, startedAt = this.activeState?.startedAt ?? Date.now()) {
+		const { spawn } = await import("node:child_process");
+		return new Promise((resolve, reject) => {
+			const logman = spawn("logman", [
+				"create",
+				"trace",
+				`JSHookETW_${pid}`,
+				"-p",
+				"NT Kernel Logger",
+				"0x10000",
+				"-o",
+				`jshook_etw_${pid}.etl`,
+				"-ets"
+			], {
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				windowsHide: true
+			});
+			const ready = createSpawnReadyGuard("ETW trace session", resolve, reject, () => logman.kill("SIGTERM"));
+			let outputBuffer = "";
+			logman.stdout?.on("data", (chunk) => {
+				outputBuffer += chunk.toString();
+				const lines = outputBuffer.split(/\r?\n/u);
+				outputBuffer = lines.pop() ?? "";
+				for (const line of lines) {
+					const event = parseETWLine(line, pid, startedAt);
+					if (event) this.capturedEvents.push(event);
+				}
+			});
+			logman.stderr?.on("data", (chunk) => {
+				const msg = chunk.toString().trim();
+				if (msg.length > 0 && !msg.startsWith("The command completed successfully")) {}
+			});
+			logman.on("error", (error) => {
+				ready.rejectReady(/* @__PURE__ */ new Error(`ETW trace error: ${error.message}. Run as Administrator.`));
+			});
+			logman.on("exit", (code) => {
+				if (code !== 0 && code !== void 0) ready.rejectReady(/* @__PURE__ */ new Error(`ETW trace session ended (code ${code}). Check permissions.`));
+			});
+			logman.on("spawn", () => {
+				ready.resolveReady(logman);
+			});
+		});
+	}
+	/**
+	* Spawn dtrace for syscall tracing on macOS.
+	* Parses dtrace output into SyscallEvent objects.
+	*/
+	async captureWithDTrace(pid, startedAt = this.activeState?.startedAt ?? Date.now()) {
+		const { spawn } = await import("node:child_process");
+		return new Promise((resolve, reject) => {
+			const dtrace = spawn("dtrace", ["-n", `
+        syscall:::entry
+        /pid == ${pid}/
+        {
+          printf("%d %d %s:entry %s", pid, probeproc, probefunc, copyinstr(arg0));
+        }
+      `], { stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			] });
+			const ready = createSpawnReadyGuard("dtrace process", resolve, reject, () => dtrace.kill("SIGTERM"));
+			let outputBuffer = "";
+			dtrace.stdout?.on("data", (chunk) => {
+				outputBuffer += chunk.toString();
+				const lines = outputBuffer.split(/\r?\n/u);
+				outputBuffer = lines.pop() ?? "";
+				for (const line of lines) {
+					const event = parseDTraceLine(line, pid, startedAt);
+					if (event) this.capturedEvents.push(event);
+				}
+			});
+			dtrace.stderr?.on("data", () => {});
+			dtrace.on("error", (error) => {
+				ready.rejectReady(/* @__PURE__ */ new Error(`dtrace error: ${error.message}. Run with sudo.`));
+			});
+			dtrace.on("spawn", () => {
+				ready.resolveReady(dtrace);
+			});
+		});
+	}
+	generateSyntheticEvents() {
+		if (!this.activeState) return;
+		const seeds = SYNTHETIC_EVENT_SEEDS[this.activeState.backend];
+		if (!seeds) return;
+		const elapsed = Date.now() - this.activeState.startedAt;
+		const targetEventCount = Math.max(1, Math.min(seeds.length * 3, Math.floor(elapsed / 150) + 1));
+		const pid = this.activeState.pid ?? process.pid;
+		while (this.activeState.generatedEvents < targetEventCount) {
+			const seed = seeds[this.activeState.generatedEvents % seeds.length];
+			if (!seed) break;
+			const timestamp = this.activeState.generatedEvents * 75;
+			this.capturedEvents.push({
+				timestamp,
+				pid,
+				syscall: seed.syscall,
+				args: [...seed.args],
+				returnValue: seed.returnValue,
+				duration: seed.duration
+			});
+			this.activeState.generatedEvents += 1;
+		}
+	}
+	processLineBuffer(_buffer, _pid, _parser) {}
+};
+//#endregion
+//#region src/modules/syscall-hook/SyscallToJSMapper.ts
+const CORRELATION_RULES = [
+	{
+		syscallNames: [
+			"NtCreateFile",
+			"openat",
+			"open_nocancel"
+		],
+		jsFunction: "fs.open",
+		baseConfidence: .8,
+		explanation: "File open syscalls commonly originate from Node.js file-system entry points."
+	},
+	{
+		syscallNames: [
+			"NtReadFile",
+			"read",
+			"read_nocancel"
+		],
+		jsFunction: "fs.readFile",
+		baseConfidence: .78,
+		explanation: "Read-oriented syscalls usually map back to file or stream reads in JavaScript."
+	},
+	{
+		syscallNames: [
+			"NtWriteFile",
+			"write",
+			"write_nocancel"
+		],
+		jsFunction: "fs.writeFile",
+		baseConfidence: .78,
+		explanation: "Write-oriented syscalls are strongly associated with Node.js file writes."
+	},
+	{
+		syscallNames: ["NtDeviceIoControlFile", "ioctl"],
+		jsFunction: "child_process.spawn",
+		baseConfidence: .55,
+		explanation: "Device and control syscalls are often triggered by child processes or native helpers."
+	},
+	{
+		syscallNames: [
+			"connect",
+			"sendto",
+			"recvfrom"
+		],
+		jsFunction: "fetch",
+		baseConfidence: .7,
+		explanation: "Socket syscalls generally indicate outbound network activity from fetch-like APIs."
+	}
+];
+function findRuleBySyscallName(syscallName) {
+	return CORRELATION_RULES.find((rule) => rule.syscallNames.includes(syscallName));
+}
+function clampConfidence(confidence) {
+	if (confidence < 0) return 0;
+	if (confidence > 1) return 1;
+	return confidence;
+}
+function hasArgContaining(args, fragments) {
+	return args.some((arg) => fragments.some((fragment) => arg.toLowerCase().includes(fragment)));
+}
+var SyscallToJSMapper = class {
+	map(syscall) {
+		const jsFunction = this.findJSFunction(syscall.syscall);
+		if (!jsFunction) return null;
+		const rule = findRuleBySyscallName(syscall.syscall);
+		if (!rule) return null;
+		let confidence = rule.baseConfidence;
+		if (jsFunction.startsWith("fs.") && hasArgContaining(syscall.args, [
+			".js",
+			".json",
+			".node"
+		])) confidence += .08;
+		if (jsFunction === "fetch" && hasArgContaining(syscall.args, [
+			"80",
+			"443",
+			"http",
+			"https"
+		])) confidence += .1;
+		return {
+			syscall: {
+				timestamp: syscall.timestamp,
+				pid: syscall.pid,
+				syscall: syscall.syscall,
+				args: [...syscall.args],
+				returnValue: syscall.returnValue,
+				duration: syscall.duration
+			},
+			jsFunction,
+			confidence: clampConfidence(confidence),
+			reasoning: this.getCorrelationReason(syscall, jsFunction)
+		};
+	}
+	findJSFunction(syscallName) {
+		const rule = findRuleBySyscallName(syscallName);
+		if (!rule) return null;
+		return rule.jsFunction;
+	}
+	getCorrelationReason(syscall, jsFunc) {
+		const rule = findRuleBySyscallName(syscall.syscall);
+		const detailParts = [];
+		if (rule) detailParts.push(rule.explanation);
+		if (jsFunc.startsWith("fs.") && hasArgContaining(syscall.args, [
+			".js",
+			".json",
+			".node"
+		])) detailParts.push("The syscall arguments reference module-like file extensions, which strengthens the fs correlation.");
+		if (jsFunc === "fetch" && hasArgContaining(syscall.args, [
+			"80",
+			"443",
+			"http",
+			"https"
+		])) detailParts.push("The syscall arguments look like network endpoints, which aligns with fetch or low-level HTTP clients.");
+		if (detailParts.length === 0) detailParts.push(`Mapped ${syscall.syscall} to ${jsFunc} using the default syscall-to-JS heuristic table.`);
+		return detailParts.join(" ");
+	}
+};
+//#endregion
+//#region src/server/domains/syscall-hook/handlers.impl.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function readNumber(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+}
+function readBoolean(value) {
+	if (typeof value === "boolean") return value;
+}
+function readString(value) {
+	if (typeof value === "string") return value;
+}
+function readStringArray(value) {
+	if (!Array.isArray(value)) return;
+	const strings = [];
+	for (const item of value) {
+		if (typeof item !== "string") return;
+		strings.push(item);
+	}
+	return strings;
+}
+const SYSCALL_NAME_RE = /^[a-z][a-z0-9_]*$/;
+function isValidSyscallName(name) {
+	return SYSCALL_NAME_RE.test(name) && name.length <= 64;
+}
+function readBackend(value) {
+	if (value === "etw" || value === "strace" || value === "dtrace") return value;
+}
+function readFilter(value) {
+	if (!isRecord(value)) return;
+	const filter = {};
+	const names = readStringArray(value["name"]);
+	const pid = readNumber(value["pid"]);
+	if (names) filter.name = names;
+	if (pid !== void 0) filter.pid = pid;
+	return filter;
+}
+function isSyscallEvent(value) {
+	if (!isRecord(value)) return false;
+	const timestamp = readNumber(value["timestamp"]);
+	const pid = readNumber(value["pid"]);
+	const syscall = readString(value["syscall"]);
+	const args = readStringArray(value["args"]);
+	const returnValue = value["returnValue"];
+	const duration = value["duration"];
+	const returnValueValid = returnValue === void 0 || readNumber(returnValue) !== void 0;
+	const durationValid = duration === void 0 || readNumber(duration) !== void 0;
+	return timestamp !== void 0 && pid !== void 0 && syscall !== void 0 && args !== void 0 && returnValueValid && durationValid;
+}
+function cloneSyscallEvent(event) {
+	return {
+		timestamp: event.timestamp,
+		pid: event.pid,
+		syscall: event.syscall,
+		args: [...event.args],
+		returnValue: event.returnValue,
+		duration: event.duration
+	};
+}
+function toErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	return "Unknown syscall-hook error";
+}
+var SyscallHookHandlers = class {
+	constructor(monitor, mapper, eventBus) {
+		this.monitor = monitor;
+		this.mapper = mapper;
+		this.eventBus = eventBus;
+	}
+	async handleSyscallStartMonitor(args) {
+		const backend = readBackend(args["backend"]);
+		if (!backend) return {
+			ok: false,
+			error: "backend must be one of: etw, strace, dtrace"
+		};
+		const rawMonitorPid = readNumber(args["pid"]);
+		const simulate = readBoolean(args["simulate"]) ?? false;
+		if (args["pid"] !== void 0 && args["pid"] !== null) {
+			if (rawMonitorPid === void 0 || !Number.isInteger(rawMonitorPid) || rawMonitorPid < 0) return {
+				ok: false,
+				error: "pid must be a non-negative integer when provided"
+			};
+		}
+		const pid = rawMonitorPid;
+		const monitor = this.ensureMonitor();
+		try {
+			await monitor.start({
+				backend,
+				pid,
+				simulate
+			});
+			this.eventBus?.emit("syscall:trace_started", {
+				backend,
+				pid,
+				simulate,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			return {
+				ok: true,
+				started: true,
+				backend,
+				pid,
+				simulate,
+				stats: monitor.getStats()
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: toErrorMessage(error),
+				requestedBackend: backend,
+				supportedBackends: monitor.getSupportedBackends()
+			};
+		}
+	}
+	async handleSyscallStopMonitor() {
+		const monitor = this.ensureMonitor();
+		try {
+			await monitor.stop();
+			return {
+				ok: true,
+				stopped: true,
+				stats: monitor.getStats()
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: toErrorMessage(error)
+			};
+		}
+	}
+	async handleSyscallCaptureEvents(args) {
+		const monitor = this.ensureMonitor();
+		const filter = readFilter(args["filter"]);
+		const events = await monitor.captureEvents(filter);
+		return {
+			ok: true,
+			events,
+			count: events.length,
+			stats: monitor.getStats()
+		};
+	}
+	async handleSyscallCorrelateJs(args) {
+		const rawEvents = args["syscallEvents"];
+		if (!Array.isArray(rawEvents) || !rawEvents.every((item) => isSyscallEvent(item))) return {
+			ok: false,
+			error: "syscallEvents must be an array of valid SyscallEvent objects"
+		};
+		const mapper = this.ensureMapper();
+		const correlations = [];
+		const unmatched = [];
+		for (const event of rawEvents) {
+			const clonedEvent = cloneSyscallEvent(event);
+			const correlated = mapper.map(clonedEvent);
+			if (correlated) correlations.push(correlated);
+			else unmatched.push(clonedEvent);
+		}
+		return {
+			ok: true,
+			correlations,
+			matched: correlations.length,
+			unmatched
+		};
+	}
+	async handleSyscallFilter(args) {
+		const names = readStringArray(args["names"]);
+		if (args["names"] !== void 0 && names === void 0) return {
+			ok: false,
+			error: "names must be an array of strings when provided"
+		};
+		const events = await this.ensureMonitor().captureEvents(names && names.length > 0 ? { name: names } : void 0);
+		return {
+			ok: true,
+			names,
+			events,
+			count: events.length
+		};
+	}
+	async handleSyscallGetStats() {
+		const monitor = this.ensureMonitor();
+		return {
+			ok: true,
+			...monitor.getStats(),
+			running: monitor.isRunning(),
+			supportedBackends: monitor.getSupportedBackends()
+		};
+	}
+	async handleSyscallEbpfTrace(args) {
+		const rawPid = readNumber(args["pid"]);
+		const syscalls = readStringArray(args["syscalls"]);
+		const durationSec = readNumber(args["durationSec"]) ?? SYSCALL_TRACE_DURATION_DEFAULT_SEC;
+		const simulate = readBoolean(args["simulate"]) ?? false;
+		if (args["pid"] !== void 0 && args["pid"] !== null) {
+			if (rawPid === void 0 || !Number.isInteger(rawPid) || rawPid < 0) return {
+				ok: false,
+				error: "pid must be a non-negative integer (0 for all processes)"
+			};
+		}
+		const pid = rawPid ?? 0;
+		if (durationSec < SYSCALL_TRACE_DURATION_MIN_SEC || durationSec > SYSCALL_TRACE_DURATION_MAX_SEC) return {
+			ok: false,
+			error: `durationSec must be between ${SYSCALL_TRACE_DURATION_MIN_SEC} and ${SYSCALL_TRACE_DURATION_MAX_SEC}`
+		};
+		if (syscalls?.length) {
+			const invalid = syscalls.filter((s) => !isValidSyscallName(s));
+			if (invalid.length > 0) return {
+				ok: false,
+				error: `Invalid syscall names (must be lowercase alphanumeric with underscores): ${invalid.join(", ")}`
+			};
+		}
+		if (simulate) {
+			const simulatedEvents = [];
+			const syscallPool = syscalls?.length ? syscalls : [
+				"read",
+				"write",
+				"openat",
+				"close",
+				"fstat",
+				"mmap",
+				"mprotect",
+				"munmap",
+				"brk",
+				"ioctl"
+			];
+			const simulatedTimestampStepMs = durationSec * 50;
+			for (let i = 0; i < 20; i++) simulatedEvents.push({
+				timestamp: i * simulatedTimestampStepMs,
+				pid: pid || 1234,
+				syscall: syscallPool[i % syscallPool.length] ?? "read",
+				args: [`fd=${i % 5 + 3}`, `count=${(i + 1) * 64}`],
+				returnValue: i % 3 === 0 ? -1 : (i + 1) * 64,
+				duration: Math.random() * 2
+			});
+			return {
+				ok: true,
+				backend: "ebpf",
+				simulated: true,
+				pid,
+				durationSec,
+				events: simulatedEvents,
+				count: simulatedEvents.length,
+				syscallsTraced: syscallPool
+			};
+		}
+		const targetSyscalls = syscalls?.length ? syscalls : [
+			"read",
+			"write",
+			"openat",
+			"close",
+			"fstat",
+			"mmap",
+			"mprotect",
+			"munmap",
+			"brk",
+			"ioctl",
+			"connect",
+			"sendto",
+			"recvfrom",
+			"clone",
+			"execve"
+		];
+		const pidFilter = pid > 0 ? `/pid == ${pid}/` : "";
+		const tracepoints = targetSyscalls.map((sc) => `tracepoint:syscalls:sys_enter_${sc}`).join(", ");
+		const exitTracepoints = targetSyscalls.map((sc) => `tracepoint:syscalls:sys_exit_${sc}`).join(", ");
+		const script = `#!/usr/bin/env bpftrace
+// Generated by jshookmcp syscall_ebpf_trace
+// Target PID: ${pid || "all"} | Duration: ${durationSec}s | Syscalls: ${targetSyscalls.join(", ")}
+
+BEGIN {
+  printf("=== eBPF syscall trace started (pid=${pid || "all"}, duration=${durationSec}s) ===\\n");
+}
+
+${tracepoints} ${pidFilter}
+{
+  @enter_ts[tid] = nsecs;
+  printf("{\\"timestamp\\": %llu, \\"pid\\": %d, \\"tid\\": %d, \\"syscall\\": \\"%s\\", \\"phase\\": \\"enter\\", \\"args\\": {",
+    elapsed / 1000000, pid, tid, probe);
+  // Log key arguments based on syscall
+  if (probe == "tracepoint:syscalls:sys_enter_openat" || probe == "tracepoint:syscalls:sys_enter_open") {
+    printf("\\"pathname\\": \\"%s\\", \\"flags\\": %d, \\"mode\\": %d", args->pathname, args->flags, args->mode);
+  } else if (probe == "tracepoint:syscalls:sys_enter_read" || probe == "tracepoint:syscalls:sys_enter_write") {
+    printf("\\"fd\\": %d, \\"count\\": %d", args->fd, args->count);
+  } else if (probe == "tracepoint:syscalls:sys_enter_connect") {
+    printf("\\"fd\\": %d", args->fd);
+  } else if (probe == "tracepoint:syscalls:sys_enter_mmap") {
+    printf("\\"addr\\": %llu, \\"length\\": %llu, \\"prot\\": %d, \\"flags\\": %d, \\"fd\\": %d", args->addr, args->length, args->prot, args->flags, args->fd);
+  } else if (probe == "tracepoint:syscalls:sys_enter_execve") {
+    printf("\\"filename\\": \\"%s\\"", args->filename);
+  } else {
+    printf("\\"raw_args\\": \\"(see bpftrace -v output)\\"");
+  }
+  printf("}}\\n");
+}
+
+${exitTracepoints} ${pidFilter}
+{
+  $elapsed_ns = nsecs - @enter_ts[tid];
+  printf("{\\"timestamp\\": %llu, \\"pid\\": %d, \\"tid\\": %d, \\"syscall\\": \\"%s\\", \\"phase\\": \\"exit\\", \\"ret\\": %d, \\"duration_us\\": %llu}\\n",
+    elapsed / 1000000, pid, tid, probe, args->ret, $elapsed_ns / 1000);
+  delete(@enter_ts[tid]);
+}
+
+interval:s:${durationSec} {
+  printf("=== Trace duration (${durationSec}s) elapsed, exiting ===\\n");
+  exit();
+}
+
+END {
+  printf("=== eBPF syscall trace complete ===\\n");
+  clear(@enter_ts);
+}
+`;
+		return {
+			ok: true,
+			backend: "ebpf",
+			mode: "script",
+			pid,
+			durationSec,
+			syscallCount: targetSyscalls.length,
+			syscallsTraced: targetSyscalls,
+			script,
+			usage: `bpftrace -e '${script.replace(/'/g, "'\\''")}'`,
+			note: "Run the generated bpftrace script on a Linux system with bpftrace installed and CAP_BPF/root privileges.",
+			requiredCapabilities: [
+				"CAP_BPF",
+				"root",
+				"bpftrace"
+			]
+		};
+	}
+	ensureMonitor() {
+		if (!this.monitor) this.monitor = new SyscallMonitor();
+		return this.monitor;
+	}
+	ensureMapper() {
+		if (!this.mapper) this.mapper = new SyscallToJSMapper();
+		return this.mapper;
+	}
+};
+//#endregion
+export { SyscallHookHandlers };