@jshookmcp/jshook 0.2.9 → 0.3.0

package/dist/{handlers-C67ktuRN.mjs → handlers-4jmR0nMs.mjs}

@@ -1,9 +1,11 @@
+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: [
 		{
@@ -106,6 +108,31 @@ function cloneEvent(event) {
 		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;
@@ -118,7 +145,7 @@ function matchesFilter(event, filter) {
 * Example strace line:
 *   12345 14:30:00.123456 openat(AT_FDCWD, "/tmp/foo", O_RDONLY) = 3 <0.000123>
 */
-function parseStraceLine(line, targetPid) {
+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";
@@ -127,7 +154,7 @@ function parseStraceLine(line, targetPid) {
 	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(),
+		timestamp: Date.now() - startedAt,
 		pid: targetPid,
 		syscall,
 		args,
@@ -141,7 +168,7 @@ function parseStraceLine(line, targetPid) {
 * Example ETW line:
 *   [2024-01-15 14:30:00.123] PID=1234 NtCreateFile Handle=0x90 Status=0x00000000
 */
-function parseETWLine(line, targetPid) {
+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";
@@ -149,7 +176,7 @@ function parseETWLine(line, targetPid) {
 	const pid = Number(match[2]);
 	const args = rawArgs.split(/\s+/u).filter((a) => a.length > 0);
 	return {
-		timestamp: Date.now(),
+		timestamp: Date.now() - startedAt,
 		pid: Number.isFinite(pid) ? pid : targetPid,
 		syscall,
 		args
@@ -161,7 +188,7 @@ function parseETWLine(line, targetPid) {
 * Example dtrace line:
 *   1234   0  12345  open_nocancel:entry  /private/tmp/foo O_RDONLY
 */
-function parseDTraceLine(line, targetPid) {
+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";
@@ -169,7 +196,7 @@ function parseDTraceLine(line, targetPid) {
 	const pid = Number(match[2]);
 	const args = rawArgs.split(/\s+/u).filter((a) => a.length > 0);
 	return {
-		timestamp: Date.now(),
+		timestamp: Date.now() - startedAt,
 		pid: Number.isFinite(pid) ? pid : targetPid,
 		syscall,
 		args
@@ -182,12 +209,13 @@ var SyscallMonitor = class {
 	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: Date.now(),
+				startedAt,
 				generatedEvents: 0
 			};
 			this.lastBackend = requestedBackend;
@@ -198,15 +226,15 @@ var SyscallMonitor = class {
 		const pid = options?.pid ?? process.pid;
 		let subprocess;
 		try {
-			if (requestedBackend === "strace") subprocess = await this.captureWithStrace(pid);
-			else if (requestedBackend === "etw") subprocess = await this.captureWithETW(pid);
-			else if (requestedBackend === "dtrace") subprocess = await this.captureWithDTrace(pid);
+			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: Date.now(),
+				startedAt,
 				generatedEvents: 0
 			};
 			this.lastBackend = requestedBackend;
@@ -217,7 +245,7 @@ var SyscallMonitor = class {
 		this.activeState = {
 			backend: requestedBackend,
 			pid: options?.pid,
-			startedAt: Date.now(),
+			startedAt,
 			generatedEvents: 0,
 			subprocess
 		};
@@ -257,7 +285,7 @@ var SyscallMonitor = class {
 	* Spawn strace for syscall tracing on Linux.
 	* Parses stdout into SyscallEvent objects.
 	*/
-	async captureWithStrace(pid) {
+	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", [
@@ -272,6 +300,7 @@ var SyscallMonitor = class {
 				"pipe",
 				"pipe"
 			] });
+			const ready = createSpawnReadyGuard("strace process", resolve, reject, () => subprocess.kill("SIGTERM"));
 			let stderrBuffer = "";
 			let lineAccumulator = "";
 			subprocess.stdout?.on("data", (chunk) => {
@@ -283,15 +312,15 @@ var SyscallMonitor = class {
 				const lines = stderrBuffer.split(/\r?\n/u);
 				stderrBuffer = lines.pop() ?? "";
 				for (const line of lines) if (line.length > 0) {
-					const event = parseStraceLine(line, pid);
+					const event = parseStraceLine(line, pid, startedAt);
 					if (event) this.capturedEvents.push(event);
 				}
 			});
 			subprocess.on("error", (error) => {
-				reject(/* @__PURE__ */ new Error(`strace process error: ${error.message}. Is strace installed?`));
+				ready.rejectReady(/* @__PURE__ */ new Error(`strace process error: ${error.message}. Is strace installed?`));
 			});
 			subprocess.on("spawn", () => {
-				resolve(subprocess);
+				ready.resolveReady(subprocess);
 			});
 		});
 	}
@@ -299,7 +328,7 @@ var SyscallMonitor = class {
 	* Spawn ETW tracing on Windows using logman.
 	* Parses ETW trace output into SyscallEvent objects.
 	*/
-	async captureWithETW(pid) {
+	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", [
@@ -320,13 +349,14 @@ var SyscallMonitor = class {
 				],
 				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);
+					const event = parseETWLine(line, pid, startedAt);
 					if (event) this.capturedEvents.push(event);
 				}
 			});
@@ -335,13 +365,13 @@ var SyscallMonitor = class {
 				if (msg.length > 0 && !msg.startsWith("The command completed successfully")) {}
 			});
 			logman.on("error", (error) => {
-				reject(/* @__PURE__ */ new Error(`ETW trace error: ${error.message}. Run as Administrator.`));
+				ready.rejectReady(/* @__PURE__ */ new Error(`ETW trace error: ${error.message}. Run as Administrator.`));
 			});
 			logman.on("exit", (code) => {
-				if (code !== 0 && code !== void 0) reject(/* @__PURE__ */ new Error(`ETW trace session ended (code ${code}). Check permissions.`));
+				if (code !== 0 && code !== void 0) ready.rejectReady(/* @__PURE__ */ new Error(`ETW trace session ended (code ${code}). Check permissions.`));
 			});
 			logman.on("spawn", () => {
-				resolve(logman);
+				ready.resolveReady(logman);
 			});
 		});
 	}
@@ -349,7 +379,7 @@ var SyscallMonitor = class {
 	* Spawn dtrace for syscall tracing on macOS.
 	* Parses dtrace output into SyscallEvent objects.
 	*/
-	async captureWithDTrace(pid) {
+	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", `
@@ -363,22 +393,23 @@ var SyscallMonitor = class {
 				"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);
+					const event = parseDTraceLine(line, pid, startedAt);
 					if (event) this.capturedEvents.push(event);
 				}
 			});
 			dtrace.stderr?.on("data", () => {});
 			dtrace.on("error", (error) => {
-				reject(/* @__PURE__ */ new Error(`dtrace error: ${error.message}. Run with sudo.`));
+				ready.rejectReady(/* @__PURE__ */ new Error(`dtrace error: ${error.message}. Run with sudo.`));
 			});
 			dtrace.on("spawn", () => {
-				resolve(dtrace);
+				ready.resolveReady(dtrace);
 			});
 		});
 	}
@@ -392,7 +423,7 @@ var SyscallMonitor = class {
 		while (this.activeState.generatedEvents < targetEventCount) {
 			const seed = seeds[this.activeState.generatedEvents % seeds.length];
 			if (!seed) break;
-			const timestamp = this.activeState.startedAt + this.activeState.generatedEvents * 75;
+			const timestamp = this.activeState.generatedEvents * 75;
 			this.capturedEvents.push({
 				timestamp,
 				pid,
@@ -531,6 +562,9 @@ function isRecord(value) {
 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;
 }
@@ -543,6 +577,10 @@ function readStringArray(value) {
 	}
 	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;
 }
@@ -593,20 +631,26 @@ var SyscallHookHandlers = class {
 			ok: false,
 			error: "backend must be one of: etw, strace, dtrace"
 		};
-		const pid = readNumber(args["pid"]);
-		if (args["pid"] !== void 0 && pid === void 0) return {
-			ok: false,
-			error: "pid must be a finite number when provided"
-		};
+		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
+				pid,
+				simulate
 			});
 			this.eventBus?.emit("syscall:trace_started", {
 				backend,
 				pid,
+				simulate,
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			return {
@@ -614,6 +658,7 @@ var SyscallHookHandlers = class {
 				started: true,
 				backend,
 				pid,
+				simulate,
 				stats: monitor.getStats()
 			};
 		} catch (error) {
@@ -697,6 +742,149 @@ var SyscallHookHandlers = class {
 			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;