summaryrefslogtreecommitdiff
path: root/src/agent/hook.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:44:48 -0300
committerGabriel Schneider <[email protected]>2026-11-10 12:09:34 -0300
commitce7c0abf14e7ab056d5479adc3f05df9976e94e4 (patch)
tree8931de9a55b3d7c2ec2d52d3b3817c6f7eb5db5a /src/agent/hook.zig
parente7aa7801c10ed34194b7fe3f5ca8722a72404e65 (diff)
downloadcomputeranim-ce7c0abf14e7ab056d5479adc3f05df9976e94e4.tar.gz
computeranim-ce7c0abf14e7ab056d5479adc3f05df9976e94e4.zip
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 <[email protected]>
Diffstat (limited to 'src/agent/hook.zig')
-rw-r--r--src/agent/hook.zig150
1 files changed, 150 insertions, 0 deletions
diff --git a/src/agent/hook.zig b/src/agent/hook.zig
new file mode 100644
index 0000000..d11ddbd
--- /dev/null
+++ b/src/agent/hook.zig
@@ -0,0 +1,150 @@
+//! Function hooks: `call` and `ret` events for chosen functions, with the
+//! registers at entry (the first six integer arguments among them) and the
+//! return value.
+//!
+//! Entry is a breakpoint: the function's first byte becomes int3, and the
+//! SIGTRAP handler runs here, in the target, with every register in hand. It
+//! needs no instruction decoding, so it works on any function, whatever its
+//! prologue. The handler then lets the replaced instruction run: emulated
+//! when it is `push %rbp` or `endbr64` (how compiled functions start), else
+//! the byte is put back for a single step. Return needs no trap: the entry
+//! handler swaps the return address on the stack for `returned`, which emits
+//! the event and jumps to the real one.
+//!
+//! shortcut: a signal per call, about a microsecond. For hooks on hot
+//! functions, copy the prologue to a trampoline and patch a jump in (this
+//! needs an x86-64 instruction-length decoder, to move whole instructions and
+//! fix their rip-relative operands).
+const std = @import("std");
+const linux = std.os.linux;
+const agent = @import("agent.zig");
+const signal = @import("signal.zig");
+const sud = @import("sud.zig");
+const watch = @import("watch.zig");
+
+const Hook = struct { addr: usize, first: [4]u8 };
+var hooks: [64]Hook = undefined;
+var count: usize = 0;
+
+/// A hooked call that has not returned: where its return address lives, and
+/// the real one.
+const Frame = struct { slot: usize, ret: usize, callee: usize };
+// shortcut: calls nested deeper than this are not reported; grow the stack on demand if a target recurses further.
+threadlocal var frames: [1024]Frame = @splat(.{ .slot = 0, .ret = 0, .callee = 0 });
+threadlocal var depth: u32 = 0;
+
+/// Hooked calls the calling thread has open.
+pub fn open() u32 {
+ return depth;
+}
+
+/// `addr` must be a function's first instruction, and nothing may jump back
+/// to it from inside the function.
+pub fn add(addr: usize) void {
+ if (count == hooks.len) return;
+ for (hooks[0..count]) |h| {
+ if (h.addr == addr) return;
+ }
+ listen();
+ // Left writable: a single step puts the first byte back for a moment.
+ const page = addr & ~@as(usize, 4095);
+ if (linux.errno(linux.mprotect(@ptrFromInt(page), 4096, .{ .READ = true, .WRITE = true, .EXEC = true })) != .SUCCESS) return;
+ const code: *[4]u8 = @ptrFromInt(addr);
+ hooks[count] = .{ .addr = addr, .first = code.* };
+ count += 1;
+ code[0] = 0xcc;
+}
+
+var listening = false;
+
+/// SIGTRAP is the agent's from here on: breakpoints, and single steps (its own and sud.zig's).
+pub fn listen() void {
+ if (!listening) signal.install(.TRAP, onTrap);
+ listening = true;
+}
+
+fn onTrap(_: i32, info: *const linux.siginfo_t, uc: *signal.Ucontext) callconv(.c) void {
+ const TRAP_TRACE = 2;
+ if (info.code == TRAP_TRACE) {
+ // A single step ended: over a hooked function's first instruction,
+ // or over a syscall the dispatcher let through.
+ for (hooks[0..count]) |h| @as(*u8, @ptrFromInt(h.addr)).* = 0xcc;
+ uc.eflags &= ~@as(u64, signal.trap_flag);
+ sud.stepped(uc);
+ return;
+ }
+ const hook = for (hooks[0..count]) |*h| {
+ if (h.addr == uc.rip - 1) break h;
+ } else {
+ // A breakpoint of the target's own: again, without us.
+ signal.install(.TRAP, null);
+ uc.rip -= 1;
+ return;
+ };
+ uc.rip = hook.addr;
+ if (depth < frames.len) {
+ const slot: *usize = @ptrFromInt(uc.rsp);
+ agent.emit(.call, 0, .{ hook.addr, slot.*, uc.rsp, 0, 0, 0 }, std.mem.asBytes(&uc.regs()));
+ frames[depth] = .{ .slot = uc.rsp, .ret = slot.*, .callee = hook.addr };
+ depth += 1;
+ slot.* = @intFromPtr(&returned);
+ }
+ if (hook.first[0] == 0x55) {
+ // push %rbp
+ uc.rsp -= 8;
+ @as(*u64, @ptrFromInt(uc.rsp)).* = uc.rbp;
+ uc.rip += 1;
+ } else if (std.mem.eql(u8, &hook.first, &.{ 0xf3, 0x0f, 0x1e, 0xfa })) {
+ // endbr64: nothing to do while indirect-branch tracking is off, as it is in user space.
+ uc.rip += 4;
+ } else {
+ // shortcut: while the byte is back another thread can enter unseen; a relocated copy of the instruction would close that.
+ @as(*u8, @ptrFromInt(hook.addr)).* = hook.first[0];
+ uc.eflags |= signal.trap_flag;
+ }
+}
+
+/// Where a hooked function returns to, in place of its caller. rax and rdx
+/// and xmm0 and xmm1 hold what it returns: kept. (A 256-bit return value
+/// would lose its upper half to the code called here.)
+fn returned() callconv(.naked) void {
+ asm volatile (
+ \\ pushq %%rax
+ \\ pushq %%rax
+ \\ pushq %%rdx
+ \\ subq $40, %%rsp
+ \\ movdqu %%xmm0, (%%rsp)
+ \\ movdqu %%xmm1, 16(%%rsp)
+ \\ movq %%rax, %%rdi
+ \\ leaq 64(%%rsp), %%rsi
+ \\ callq %[onReturn:P]
+ \\ movq %%rax, 56(%%rsp)
+ \\ movdqu (%%rsp), %%xmm0
+ \\ movdqu 16(%%rsp), %%xmm1
+ \\ addq $40, %%rsp
+ \\ popq %%rdx
+ \\ popq %%rax
+ \\ retq
+ :
+ : [onReturn] "X" (&onReturn),
+ );
+}
+
+/// `sp` is the stack pointer the function returned with. Returns where it
+/// meant to return to.
+fn onReturn(value: u64, sp: usize) callconv(.c) usize {
+ const was = sud.selector;
+ sud.selector = sud.allow;
+ defer sud.selector = was;
+ while (true) {
+ depth -= 1;
+ const frame = frames[depth];
+ // Frames below `sp` were left without returning (longjmp): they end here too.
+ const ours = frame.slot + 8 == sp or depth == 0;
+ agent.emit(.ret, 0, .{ frame.callee, if (ours) value else 0, 0, 0, 0, 0 }, "");
+ if (ours) {
+ watch.drop(agent.threadId(), depth);
+ return frame.ret;
+ }
+ }
+}