From ce7c0abf14e7ab056d5479adc3f05df9976e94e4 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 11:44:48 -0300 Subject: agent: the in-process backend, and ztrace run's options for it libztrace-agent.so (preloaded) and libztrace-agent.a (linked in), one source: map and thread_start at startup; alloc/free from the interposed allocator; syscall_enter/exit through Syscall User Dispatch; call/ret from int3 hooks; mem_write from watched regions diffed in-process; the target-side API (include/ztrace.h, and the ztrace-agent module for Zig). ztrace run turns each on (--alloc --syscalls --hook --watch), chooses the moments (--cut), and stops the target at event kinds without ptrace (--stop-at, --read, -i). test-agent records real targets and checks the recordings. Co-Authored-By: Claude Fable 5.2 --- src/agent/sud.zig | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 src/agent/sud.zig (limited to 'src/agent/sud.zig') diff --git a/src/agent/sud.zig b/src/agent/sud.zig new file mode 100644 index 0000000..e556df3 --- /dev/null +++ b/src/agent/sud.zig @@ -0,0 +1,129 @@ +//! Syscalls without ptrace: Syscall User Dispatch. The kernel turns every +//! syscall the thread makes into SIGSYS; the handler runs here, in the +//! target, emits `syscall_enter` (with the path or the bytes written, read +//! straight from memory), makes the syscall itself, emits `syscall_exit` +//! and returns the result. No context switch to a tracer: two signal frames +//! a syscall. +//! +//! The agent's own syscalls pass because the selector byte says so while its +//! code runs. The target's syscall itself is made with the selector back on +//! `block`, through the gate (signal.zig), the range of code the kernel +//! always lets through: a signal that interrupts it runs the target's handler +//! as the target's code, its syscalls seen like any other. +const std = @import("std"); +const linux = std.os.linux; +const zt = @import("ztrace"); +const agent = @import("agent.zig"); +const signal = @import("signal.zig"); + +pub const allow: u8 = 0; +pub const block: u8 = 1; +/// The kernel reads this at each of the thread's syscalls: `block` while the +/// target's code runs, `allow` while the agent's does. +pub threadlocal var selector: u8 = allow; +/// What the target's code runs with: `block` once syscalls are traced. +pub var resting: u8 = allow; +/// 1 + the syscall this thread is making natively, under a single step. +threadlocal var passing: u64 = 0; + +/// Signals the target may neither block nor take over: the kernel kills a +/// process whose forced signal is blocked. +const ours = signal.bit(.SYS) | signal.bit(.TRAP); + +fn nr(comptime name: linux.SYS) u64 { + return @intFromEnum(name); +} + +pub fn enable() void { + signal.install(.SYS, onSyscall); + // Syscalls let through natively are stepped over: hook.zig's handler calls `stepped`. + @import("hook.zig").listen(); + resting = block; + arm(); +} + +/// Dispatch on for the calling thread: the kernel keeps it per thread, and a +/// clone starts without it. +pub fn arm() void { + if (resting == allow) return; + const PR_SET_SYSCALL_USER_DISPATCH = 59; + const PR_SYS_DISPATCH_ON = 1; + const gate = signal.gate(); + _ = linux.prctl(PR_SET_SYSCALL_USER_DISPATCH, PR_SYS_DISPATCH_ON, gate[0], gate[1], @intFromPtr(&selector)); +} + +fn onSyscall(_: i32, _: *const linux.siginfo_t, uc: *signal.Ucontext) callconv(.c) void { + selector = allow; + const number = uc.rax; + var a = [6]u64{ uc.rdi, uc.rsi, uc.rdx, uc.r10, uc.r8, uc.r9 }; + if (number == nr(.rt_sigreturn)) { + // The target leaves a handler of its own: its frame is where its + // stack pointer is, and ours, pushed below, goes with it. + selector = block; + signal.ztrace_gate_sigreturn(uc.rsp); + } + agent.emit(.syscall_enter, @truncate(number), a, argument(number, a)); + if (number == nr(.clone3) or number == nr(.vfork) or (number == nr(.clone) and a[0] & linux.CLONE.VM != 0)) { + // The child starts on another stack, or shares this one: not from + // inside a handler. Back onto the syscall instruction with dispatch + // off and one step to go; `stepped` turns it on again. + passing = number + 1; + uc.rip -= 2; + uc.eflags |= signal.trap_flag; + return; + } + var act: linux.k_sigaction = undefined; + var faked = false; + if (number == nr(.rt_sigaction) and a[1] != 0) { + // shortcut: the target is told its handler for one of our signals is installed, and it is not; chain to it when a target needs SIGTRAP or SIGSYS itself. + faked = a[0] == @intFromEnum(linux.SIG.SYS) or a[0] == @intFromEnum(linux.SIG.TRAP); + act = @as(*const linux.k_sigaction, @ptrFromInt(a[1])).*; + act.mask[0] &= ~ours; + a[1] = @intFromPtr(&act); + } + selector = block; + const result = if (faked) 0 else signal.ztrace_gate_syscall(number, a[0], a[1], a[2], a[3], a[4], a[5]); + selector = allow; + if (number == nr(.rt_sigprocmask)) { + // The mask it set is this handler's; the target's is the one the frame restores. + _ = linux.sigprocmask(linux.SIG.BLOCK, null, @ptrCast(&uc.sigmask)); + uc.sigmask &= ~ours; + } + // A forked child. + if (result == 0 and (number == nr(.fork) or number == nr(.clone))) agent.forked(); + agent.emit(.syscall_exit, @truncate(number), .{ result, 0, 0, 0, 0, 0 }, ""); + uc.rax = result; + selector = block; +} + +/// A single step ended (hook.zig's SIGTRAP handler): if it was over a syscall +/// let through, here is its exit, in the parent and in a new thread both. +pub fn stepped(uc: *const signal.Ucontext) void { + if (resting == allow) return; + agent.threadStart(); + if (passing != 0) { + // shortcut: the step may end one instruction after the syscall, which could have changed rax; none of libc's do. + agent.emit(.syscall_exit, @truncate(passing - 1), .{ uc.rax, 0, 0, 0, 0, 0 }, ""); + passing = 0; + } + selector = block; +} + +/// What a syscall's pointer argument points at, for the event's payload. +// shortcut: read without checking; a pointer the kernel would refuse with EFAULT faults here instead. +fn argument(number: u64, a: [6]u64) []const u8 { + return switch (number) { + nr(.open), nr(.stat), nr(.lstat), nr(.access), nr(.execve), nr(.chdir), nr(.unlink), nr(.readlink), nr(.mkdir), nr(.rmdir), nr(.truncate), nr(.chmod) => string(a[0]), + nr(.openat), nr(.newfstatat), nr(.unlinkat), nr(.readlinkat), nr(.faccessat), nr(.faccessat2), nr(.statx), nr(.mkdirat), nr(.execveat) => string(a[1]), + nr(.write), nr(.pwrite64), nr(.sendto) => if (a[1] == 0) "" else agent.text(@as([*]const u8, @ptrFromInt(a[1]))[0..a[2]]), + else => "", + }; +} + +fn string(addr: u64) []const u8 { + if (addr == 0) return ""; + const s: [*]const u8 = @ptrFromInt(addr); + var len: usize = 0; + while (len < agent.max_payload and s[len] != 0) len += 1; + return agent.text(s[0..len]); +} -- cgit v1.3