Learn Zig Series):Exercise 1: Configurable sandbox launcher reading a JSON profile
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const BpfInsn = extern struct { code: u16, jt: u8, jf: u8, k: u32 };
const SockFprog = extern struct { len: u16, filter: [*]const BpfInsn };
const Rlimit = extern struct { cur: u64, max: u64 };
const SECCOMP_RET_ALLOW: u32 = 0x7fff0000;
const SECCOMP_RET_ERRNO: u32 = 0x00050000;
const SECCOMP_RET_KILL: u32 = 0x00000000;
const AUDIT_ARCH_X86_64: u32 = 0xc000003e;
fn bpfS(code: u16, k: u32) BpfInsn { return .{ .code = code, .jt = 0, .jf = 0, .k = k }; }
fn bpfJ(code: u16, k: u32, jt: u8, jf: u8) BpfInsn { return .{ .code = code, .jt = jt, .jf = jf, .k = k }; }
const stdio_sc = [_]u32{ 0, 1, 3, 9, 10, 11, 12, 13, 14, 15, 16, 35, 39, 60, 96, 158, 228, 231, 302, 318, 334 };
const fread_sc = [_]u32{ 4, 5, 6, 21, 79, 257, 262 };
const fwrite_sc = [_]u32{ 76, 82, 87, 90, 83, 84, 85, 86, 88 };
const net_sc = [_]u32{ 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51 };
const proc_sc = [_]u32{ 56, 57, 58, 59, 61, 62 };
const Profile = struct {
stdio: bool = false, file_read: bool = false, file_write: bool = false,
network: bool = false, process: bool = false,
max_memory_mb: u64 = 256, max_files: u64 = 32, max_cpu_seconds: u64 = 30,
};
fn parseProfile(alloc: std.mem.Allocator, path: []const u8) !Profile {
const file = try std.fs.cwd().openFile(path, .{});
defer file.close();
const data = try file.readToEndAlloc(alloc, 8192);
defer alloc.free(data);
var p = Profile{};
const parsed = try std.json.parseFromSlice(std.json.Value, alloc, data, .{});
defer parsed.deinit();
const root = parsed.value.object;
if (root.get("stdio")) |v| p.stdio = v.bool;
if (root.get("file_read")) |v| p.file_read = v.bool;
if (root.get("file_write")) |v| p.file_write = v.bool;
if (root.get("network")) |v| p.network = v.bool;
if (root.get("process")) |v| p.process = v.bool;
if (root.get("max_memory_mb")) |v| p.max_memory_mb = @intCast(v.integer);
if (root.get("max_files")) |v| p.max_files = @intCast(v.integer);
if (root.get("max_cpu_seconds")) |v| p.max_cpu_seconds = @intCast(v.integer);
return p;
}
fn applySandbox(p: Profile) !void {
_ = linux.syscall5(.prctl, 38, 1, 0, 0, 0);
const mem = p.max_memory_mb * 1024 * 1024;
var rl = Rlimit{ .cur = mem, .max = mem };
_ = linux.syscall2(.setrlimit, 9, @intFromPtr(&rl));
rl = .{ .cur = p.max_files, .max = p.max_files };
_ = linux.syscall2(.setrlimit, 7, @intFromPtr(&rl));
rl = .{ .cur = p.max_cpu_seconds, .max = p.max_cpu_seconds };
_ = linux.syscall2(.setrlimit, 0, @intFromPtr(&rl));
var all: [128]u32 = undefined;
var n: usize = 0;
if (p.stdio) for (stdio_sc) |s| { all[n] = s; n += 1; };
if (p.file_read) for (fread_sc) |s| { all[n] = s; n += 1; };
if (p.file_write) for (fwrite_sc) |s| { all[n] = s; n += 1; };
if (p.network) for (net_sc) |s| { all[n] = s; n += 1; };
if (p.process) for (proc_sc) |s| { all[n] = s; n += 1; };
if (n == 0) return error.EmptyProfile;
var filter: [192]BpfInsn = undefined;
var fi: u16 = 0;
filter[fi] = bpfS(0x20, 4); fi += 1;
filter[fi] = bpfJ(0x15, AUDIT_ARCH_X86_64, 1, 0); fi += 1;
filter[fi] = bpfS(0x06, SECCOMP_RET_KILL); fi += 1;
filter[fi] = bpfS(0x20, 0); fi += 1;
const alen: u8 = @intCast(n);
for (all[0..n], 0..) |sc, idx| {
filter[fi] = bpfJ(0x15, sc, alen - @as(u8, @intCast(idx)) - 1, 0); fi += 1;
}
filter[fi] = bpfS(0x06, SECCOMP_RET_ERRNO | 1); fi += 1;
filter[fi] = bpfS(0x06, SECCOMP_RET_ALLOW); fi += 1;
const prog = SockFprog{ .len = fi, .filter = &filter };
const r: isize = @bitCast(linux.syscall3(.seccomp, 1, 0, @intFromPtr(&prog)));
if (r < 0) return error.SeccompFailed;
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
var args = std.process.args();
_ = args.next();
const prof_path = args.next() orelse { try stdout.print("Usage: sandbox \n", .{}); return; };
const program = args.next() orelse { try stdout.print("Missing program\n", .{}); return; };
const profile = parseProfile(std.heap.page_allocator, prof_path) catch |e| {
try stdout.print("Profile error: {s}\n", .{@errorName(e)}); return;
};
const pid = try posix.fork();
if (pid == 0) {
applySandbox(profile) catch { posix.exit(1); };
const argv = [_]?[*:0]const u8{ @ptrCast(program.ptr), null };
const envp = [_]?[*:0]const u8{ null };
_ = linux.syscall3(.execve, @intFromPtr(argv[0].?), @intFromPtr(&argv), @intFromPtr(&envp));
posix.exit(127);
}
const result = posix.waitpid(pid, 0);
if (result.status.signal()) |sig| try stdout.print("Killed: signal {d}\n", .{@intFromEnum(sig)})
else try stdout.print("Exited: {d}\n", .{result.status.exit_status().?});
}
The JSON profile maps human-readable categories to syscall number arrays. The launcher applies rlimits first (they work without seccomp), then installs the BPF filter. If process is false but the target needs execve, it gets EPERM immediately.
Exercise 2: Seccomp audit logger using SECCOMP_RET_LOG
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const UserRegs = extern struct {
r15: u64, r14: u64, r13: u64, r12: u64, rbp: u64, rbx: u64,
r11: u64, r10: u64, r9: u64, r8: u64, rax: u64, rcx: u64,
rdx: u64, rsi: u64, rdi: u64, orig_rax: u64, rip: u64, cs: u64,
eflags: u64, rsp: u64, ss: u64, fs_base: u64, gs_base: u64,
ds: u64, es: u64, fs: u64, gs: u64,
};
fn pt(req: u32, pid: i32, addr: usize, data: usize) isize {
return @bitCast(linux.syscall4(.ptrace, req, @as(usize, @bitCast(@as(isize, pid))), addr, data));
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
var args = std.process.args();
_ = args.next();
const target = args.next() orelse "/bin/ls";
try stdout.print("Profiling: {s}\n\n", .{target});
const pid = try posix.fork();
if (pid == 0) {
_ = pt(0, 0, 0, 0); // TRACEME
_ = linux.syscall2(.kill, linux.syscall0(.getpid), 19);
const argv = [_]?[*:0]const u8{ @ptrCast(target.ptr), null };
const envp = [_]?[*:0]const u8{ null };
_ = linux.syscall3(.execve, @intFromPtr(argv[0].?), @intFromPtr(&argv), @intFromPtr(&envp));
posix.exit(1);
}
_ = posix.waitpid(pid, 0);
var seen = std.AutoHashMap(u64, u32).init(std.heap.page_allocator);
defer seen.deinit();
var entering = true;
while (true) {
_ = pt(24, pid, 0, 0); // SYSCALL
const wr = posix.waitpid(pid, 0);
if (wr.status.signal()) |_| break;
if (wr.status.exit_status() != null) break;
if (entering) {
var regs: UserRegs = undefined;
_ = pt(12, pid, 0, @intFromPtr(®s)); // GETREGS
const entry = try seen.getOrPut(regs.orig_rax);
if (!entry.found_existing) entry.value_ptr.* = 0;
entry.value_ptr.* += 1;
}
entering = !entering;
}
try stdout.print("const allowed = [_]u32{{ ", .{});
var it = seen.iterator();
var first = true;
while (it.next()) |entry| {
if (!first) try stdout.print(", ", .{});
try stdout.print("{d}", .{entry.key_ptr.*});
first = false;
}
try stdout.print(" }};\n", .{});
}
The "learn then enforce" pattern -- profile a known-good execution, then generate the minimal whitelist. The ptrace approach gives you structured data immediately, and the output is valid Zig you can paste directly into a seccomp filter.
Exercise 3: Pledge-like API with narrowing via stacked filters
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const BpfInsn = extern struct { code: u16, jt: u8, jf: u8, k: u32 };
const SockFprog = extern struct { len: u16, filter: [*]const BpfInsn };
const SECCOMP_RET_ALLOW: u32 = 0x7fff0000;
const SECCOMP_RET_ERRNO: u32 = 0x00050000;
const SECCOMP_RET_KILL: u32 = 0x00000000;
const AUDIT_ARCH_X86_64: u32 = 0xc000003e;
fn bpfS(code: u16, k: u32) BpfInsn { return .{ .code = code, .jt = 0, .jf = 0, .k = k }; }
fn bpfJ(code: u16, k: u32, jt: u8, jf: u8) BpfInsn { return .{ .code = code, .jt = jt, .jf = jf, .k = k }; }
const Flags = packed struct { stdio: bool = false, rpath: bool = false, inet: bool = false, _pad: u13 = 0 };
const stdio_sc = [_]u32{ 0, 1, 3, 9, 10, 11, 12, 13, 14, 15, 16, 35, 39, 60, 158, 228, 231, 302, 318, 334 };
const rpath_sc = [_]u32{ 4, 5, 6, 21, 79, 257, 262 };
const inet_sc = [_]u32{ 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51 };
fn pledgeNarrow(flags: Flags) !void {
var calls: [128]u32 = undefined;
var n: usize = 0;
if (flags.stdio) for (stdio_sc) |s| { calls[n] = s; n += 1; };
if (flags.rpath) for (rpath_sc) |s| { calls[n] = s; n += 1; };
if (flags.inet) for (inet_sc) |s| { calls[n] = s; n += 1; };
if (n == 0) return error.EmptyPledge;
var filter: [192]BpfInsn = undefined;
var fi: u16 = 0;
filter[fi] = bpfS(0x20, 4); fi += 1;
filter[fi] = bpfJ(0x15, AUDIT_ARCH_X86_64, 1, 0); fi += 1;
filter[fi] = bpfS(0x06, SECCOMP_RET_KILL); fi += 1;
filter[fi] = bpfS(0x20, 0); fi += 1;
const alen: u8 = @intCast(n);
for (calls[0..n], 0..) |sc, idx| {
filter[fi] = bpfJ(0x15, sc, alen - @as(u8, @intCast(idx)) - 1, 0); fi += 1;
}
filter[fi] = bpfS(0x06, SECCOMP_RET_ERRNO | 1); fi += 1;
filter[fi] = bpfS(0x06, SECCOMP_RET_ALLOW); fi += 1;
_ = linux.syscall5(.prctl, 38, 1, 0, 0, 0);
const prog = SockFprog{ .len = fi, .filter = &filter };
const r: isize = @bitCast(linux.syscall3(.seccomp, 1, 0, @intFromPtr(&prog)));
if (r < 0) return error.SeccompFailed;
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
try pledgeNarrow(.{ .stdio = true, .rpath = true, .inet = true });
try stdout.print("Phase 1: stdio+rpath+inet\n", .{});
const s1: isize = @bitCast(linux.syscall3(.socket, 2, 1, 0));
try stdout.print(" socket() = {d} (works)\n", .{s1});
if (s1 >= 0) posix.close(@intCast(s1));
try pledgeNarrow(.{ .stdio = true, .rpath = true }); // drop inet
try stdout.print("Phase 2: stdio+rpath (inet dropped)\n", .{});
const s2: isize = @bitCast(linux.syscall3(.socket, 2, 1, 0));
try stdout.print(" socket() = {d} (blocked)\n", .{s2});
try stdout.print("\nFilters stack: kernel takes the most restrictive result.\n", .{});
}
Seccomp filters stack -- each new filter is added to a chain and the kernel runs ALL of them, taking the most restrictive result. You can never widen permissions, only narrow. Each pledgeNarrow call can only remove permissions, never grant new ones.
Last episode we built seccomp sandboxes that restrict WHICH syscalls a process can make. But seccomp operates from the perspective of the process restricting itself -- the process installs its own filter. What if you want to observe and control ANOTHER process from the outside? What if you want to watch every syscall it makes, inspect its memory, or pause it mid-execution to examine its state?
That's what ptrace does, and it's the foundation of every debugger you've ever used. GDB, strace, ltrace, LLDB -- they all rely on ptrace under the hood. And honestly, once you understand how ptrace works, debuggers stop feeling like magic and start feeling like (somewhat clunky) API clients ;-)
The ptrace syscall is Linux-specific (BSDs have their own variants) and it gives one process -- the tracer -- almost complete control over another process -- the tracee. The tracer can read and write the tracee's memory, inspect and modify its CPU registers, single-step through instructions, intercept syscalls, and inject signals. It's the most powerful debugging primitive the kernel exposes.
The basic ptrace workflow is: fork a child, have the child call PTRACE_TRACEME before exec, then the parent uses various ptrace requests to control execution. Alternatively, you can attach to an already-running process with PTRACE_ATTACH (requires the same UID or CAP_SYS_PTRACE).
Here's the minimal attach-and-trace pattern:
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const PTRACE_TRACEME: u32 = 0;
const PTRACE_PEEKTEXT: u32 = 1;
const PTRACE_PEEKDATA: u32 = 2;
const PTRACE_CONT: u32 = 7;
const PTRACE_SINGLESTEP: u32 = 9;
const PTRACE_GETREGS: u32 = 12;
const PTRACE_SETREGS: u32 = 13;
const PTRACE_ATTACH: u32 = 16;
const PTRACE_DETACH: u32 = 17;
const PTRACE_SYSCALL: u32 = 24;
const PTRACE_POKEDATA: u32 = 5;
const UserRegs = extern struct {
r15: u64, r14: u64, r13: u64, r12: u64,
rbp: u64, rbx: u64, r11: u64, r10: u64,
r9: u64, r8: u64, rax: u64, rcx: u64,
rdx: u64, rsi: u64, rdi: u64, orig_rax: u64,
rip: u64, cs: u64, eflags: u64, rsp: u64,
ss: u64, fs_base: u64, gs_base: u64,
ds: u64, es: u64, fs: u64, gs: u64,
};
fn ptrace(request: u32, pid: i32, addr: usize, data: usize) isize {
return @bitCast(linux.syscall4(
.ptrace,
request,
@as(usize, @bitCast(@as(isize, pid))),
addr,
data,
));
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
const pid = try posix.fork();
if (pid == 0) {
// child: request to be traced
_ = ptrace(PTRACE_TRACEME, 0, 0, 0);
// stop ourselves so the parent gets a notification
_ = linux.syscall2(.kill, linux.syscall0(.getpid), 19); // SIGSTOP
// after the parent continues us, do some work
const w = std.io.getStdOut().writer();
w.print("Child: running after parent continued us\n", .{}) catch {};
w.print("Child: PID = {d}\n", .{linux.syscall0(.getpid)}) catch {};
posix.exit(42);
}
// parent: wait for child to stop
try stdout.print("Tracer: waiting for tracee (pid {d}) to stop...\n", .{pid});
_ = posix.waitpid(pid, 0);
// read the child's registers
var regs: UserRegs = undefined;
_ = ptrace(PTRACE_GETREGS, pid, 0, @intFromPtr(®s));
try stdout.print("Tracer: tracee stopped at RIP=0x{x}\n", .{regs.rip});
try stdout.print("Tracer: RSP=0x{x}, RBP=0x{x}\n", .{ regs.rsp, regs.rbp });
// continue the child
try stdout.print("Tracer: continuing tracee...\n", .{});
_ = ptrace(PTRACE_CONT, pid, 0, 0);
// wait for exit
const result = posix.waitpid(pid, 0);
if (result.status.exit_status()) |code| {
try stdout.print("Tracer: tracee exited with code {d}\n", .{code});
}
}
The PTRACE_TRACEME call in the child tells the kernel "my parent is my tracer." After that, any signal delivered to the child (including the SIGSTOP we send ourselves) causes the child to stop and the parent's waitpid to return. The parent can then inspect registers, memory, and decide whether to continue, single-step, or do something else entirely.
Notice we use a raw kill syscall instead of posix.raise() or similar -- when you're doing ptrace work, you want to be very explicit about which syscalls you're invoking. The less magic between you and the kernel, the better.
Once you have a stopped tracee, you can read its memory word-by-word with PTRACE_PEEKDATA and write it with PTRACE_POKEDATA. These operate on aligned usize values (8 bytes on x86-64). For registers, PTRACE_GETREGS fills a UserRegs struct and PTRACE_SETREGS applies changes:
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const PTRACE_TRACEME: u32 = 0;
const PTRACE_PEEKDATA: u32 = 2;
const PTRACE_POKEDATA: u32 = 5;
const PTRACE_CONT: u32 = 7;
const PTRACE_GETREGS: u32 = 12;
const PTRACE_SETREGS: u32 = 13;
const UserRegs = extern struct {
r15: u64, r14: u64, r13: u64, r12: u64,
rbp: u64, rbx: u64, r11: u64, r10: u64,
r9: u64, r8: u64, rax: u64, rcx: u64,
rdx: u64, rsi: u64, rdi: u64, orig_rax: u64,
rip: u64, cs: u64, eflags: u64, rsp: u64,
ss: u64, fs_base: u64, gs_base: u64,
ds: u64, es: u64, fs: u64, gs: u64,
};
fn ptrace(request: u32, pid: i32, addr: usize, data: usize) isize {
return @bitCast(linux.syscall4(
.ptrace, request,
@as(usize, @bitCast(@as(isize, pid))), addr, data,
));
}
// read a block of memory from the tracee
fn readTraceeMemory(pid: i32, addr: usize, buf: []u8) void {
var offset: usize = 0;
while (offset < buf.len) {
const word: usize = @bitCast(ptrace(PTRACE_PEEKDATA, pid, addr + offset, 0));
const bytes: [8]u8 = @bitCast(word);
const remaining = buf.len - offset;
const to_copy = @min(remaining, 8);
@memcpy(buf[offset..][0..to_copy], bytes[0..to_copy]);
offset += 8;
}
}
// write a block of memory to the tracee
fn writeTraceeMemory(pid: i32, addr: usize, data: []const u8) void {
var offset: usize = 0;
while (offset < data.len) {
if (data.len - offset >= 8) {
const word: usize = @bitCast(data[offset..][0..8].*);
_ = ptrace(PTRACE_POKEDATA, pid, addr + offset, word);
} else {
// partial word: read-modify-write
const existing: usize = @bitCast(ptrace(PTRACE_PEEKDATA, pid, addr + offset, 0));
var bytes: [8]u8 = @bitCast(existing);
const remaining = data.len - offset;
@memcpy(bytes[0..remaining], data[offset..][0..remaining]);
const word: usize = @bitCast(bytes);
_ = ptrace(PTRACE_POKEDATA, pid, addr + offset, word);
}
offset += 8;
}
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
// we'll put a message on the stack, fork, and read it from the parent
var message: [32]u8 = undefined;
@memcpy(message[0..13], "Hello ptrace!");
message[13] = 0;
const pid = try posix.fork();
if (pid == 0) {
_ = ptrace(PTRACE_TRACEME, 0, 0, 0);
_ = linux.syscall2(.kill, linux.syscall0(.getpid), 19);
// after parent modifies our memory, print the message
const w = std.io.getStdOut().writer();
const len = std.mem.indexOfScalar(u8, &message, 0) orelse message.len;
w.print("Child sees: \"{s}\"\n", .{message[0..len]}) catch {};
posix.exit(0);
}
_ = posix.waitpid(pid, 0);
// read the child's registers to find the stack
var regs: UserRegs = undefined;
_ = ptrace(PTRACE_GETREGS, pid, 0, @intFromPtr(®s));
try stdout.print("Child RSP: 0x{x}\n", .{regs.rsp});
// read some bytes from the child's stack
var stack_peek: [64]u8 = undefined;
readTraceeMemory(pid, regs.rsp, &stack_peek);
try stdout.print("Stack bytes: ", .{});
for (stack_peek[0..16]) |b| try stdout.print("{x:0>2} ", .{b});
try stdout.print("\n", .{});
// find and modify the message in the child's address space
// in a real debugger you'd search or use symbols, but we know
// the child inherited our memory layout (copy-on-write)
const msg_addr = @intFromPtr(&message);
var remote_msg: [32]u8 = undefined;
readTraceeMemory(pid, msg_addr, &remote_msg);
const len = std.mem.indexOfScalar(u8, &remote_msg, 0) orelse remote_msg.len;
try stdout.print("Original message: \"{s}\"\n", .{remote_msg[0..len]});
// overwrite it
const new_msg = "MODIFIED by tracer!";
writeTraceeMemory(pid, msg_addr, new_msg);
try stdout.print("Wrote new message, continuing child...\n", .{});
_ = ptrace(PTRACE_CONT, pid, 0, 0);
_ = posix.waitpid(pid, 0);
}
The readTraceeMemory and writeTraceeMemory helpers handle the fact that PTRACE_PEEKDATA only reads one machine word at a time. For partial words at the end of a buffer, we do a read-modify-write to avoid corrupting adjacent memory. This is a pain, but that's ptrace for you -- it was designed in the 1970s and the API hasn't exactly been modernized since.
Having said that, on modern Linux there's also process_vm_readv / process_vm_writev which can read/write arbitrary-length buffers in one syscall without the word-at-a-time limitation. But those require specific permissions and don't work in all contexts where ptrace does.
PTRACE_SINGLESTEP is the simplest (and slowest) way to trace execution. It executes exactly one machine instruction, then stops the tracee. The tracer gets a SIGTRAP notification and can inspect registers to see what happened:
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const PTRACE_TRACEME: u32 = 0;
const PTRACE_SINGLESTEP: u32 = 9;
const PTRACE_GETREGS: u32 = 12;
const PTRACE_PEEKDATA: u32 = 2;
const UserRegs = extern struct {
r15: u64, r14: u64, r13: u64, r12: u64,
rbp: u64, rbx: u64, r11: u64, r10: u64,
r9: u64, r8: u64, rax: u64, rcx: u64,
rdx: u64, rsi: u64, rdi: u64, orig_rax: u64,
rip: u64, cs: u64, eflags: u64, rsp: u64,
ss: u64, fs_base: u64, gs_base: u64,
ds: u64, es: u64, fs: u64, gs: u64,
};
fn ptrace(request: u32, pid: i32, addr: usize, data: usize) isize {
return @bitCast(linux.syscall4(
.ptrace, request,
@as(usize, @bitCast(@as(isize, pid))), addr, data,
));
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
const pid = try posix.fork();
if (pid == 0) {
_ = ptrace(PTRACE_TRACEME, 0, 0, 0);
_ = linux.syscall2(.kill, linux.syscall0(.getpid), 19);
// do a few simple things so we can watch the instructions
var x: u64 = 0;
x += 10;
x *= 3;
_ = x;
posix.exit(0);
}
_ = posix.waitpid(pid, 0);
try stdout.print("Single-stepping tracee (pid {d})...\n\n", .{pid});
try stdout.print("Step | RIP | Instruction bytes\n", .{});
try stdout.print("-----|------------------|------------------\n", .{});
var step_count: u32 = 0;
const max_steps: u32 = 40; // don't go forever
while (step_count < max_steps) {
_ = ptrace(PTRACE_SINGLESTEP, pid, 0, 0);
const wr = posix.waitpid(pid, 0);
if (wr.status.exit_status() != null) {
try stdout.print("\nTracee exited after {d} steps\n", .{step_count});
break;
}
var regs: UserRegs = undefined;
_ = ptrace(PTRACE_GETREGS, pid, 0, @intFromPtr(®s));
// peek at the instruction bytes at RIP
const word: usize = @bitCast(ptrace(PTRACE_PEEKDATA, pid, regs.rip, 0));
const bytes: [8]u8 = @bitCast(word);
try stdout.print(" {d:>3} | 0x{x:0>12} | ", .{ step_count, regs.rip });
for (bytes[0..6]) |b| try stdout.print("{x:0>2} ", .{b});
try stdout.print("\n", .{});
step_count += 1;
}
if (step_count >= max_steps) {
try stdout.print("\n(stopped after {d} steps -- tracee still running)\n", .{max_steps});
// clean up: continue and let it exit
const PTRACE_CONT: u32 = 7;
_ = ptrace(PTRACE_CONT, pid, 0, 0);
_ = posix.waitpid(pid, 0);
}
}
Single-stepping is incredibly slow -- every instruction requires a context switch to the tracer and back. For code coverage you'd use breakpoints at strategic locations instead. But for understanding what a program is doing at the instruction level, single-step gives you the finest granularity possible.
The instruction bytes at RIP show raw machine code. You could disassemble them (like we did in episodes 59-61) to get human-readable instructions. Tools like rr (Mozilla's record-replay debugger) use this approach to record register state at every step.
Software breakpoints are elegantly brutal. You save the original byte at the target address, replace it with 0xCC (the x86 INT3 instruction, which is only 1 byte), and when the CPU hits it, the kernel sends SIGTRAP to the process. The tracer catches the trap, restores the original byte, rewinds RIP by one, and optionaly continues execution:
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const PTRACE_TRACEME: u32 = 0;
const PTRACE_PEEKDATA: u32 = 2;
const PTRACE_POKEDATA: u32 = 5;
const PTRACE_CONT: u32 = 7;
const PTRACE_GETREGS: u32 = 12;
const PTRACE_SETREGS: u32 = 13;
const PTRACE_SINGLESTEP: u32 = 9;
const UserRegs = extern struct {
r15: u64, r14: u64, r13: u64, r12: u64,
rbp: u64, rbx: u64, r11: u64, r10: u64,
r9: u64, r8: u64, rax: u64, rcx: u64,
rdx: u64, rsi: u64, rdi: u64, orig_rax: u64,
rip: u64, cs: u64, eflags: u64, rsp: u64,
ss: u64, fs_base: u64, gs_base: u64,
ds: u64, es: u64, fs: u64, gs: u64,
};
fn ptrace(request: u32, pid: i32, addr: usize, data: usize) isize {
return @bitCast(linux.syscall4(
.ptrace, request,
@as(usize, @bitCast(@as(isize, pid))), addr, data,
));
}
const Breakpoint = struct {
addr: usize,
original_byte: u8,
enabled: bool,
};
fn setBreakpoint(pid: i32, addr: usize) Breakpoint {
// read the word at the address
const word: usize = @bitCast(ptrace(PTRACE_PEEKDATA, pid, addr, 0));
var bytes: [8]u8 = @bitCast(word);
const original = bytes[0];
// replace first byte with INT3 (0xCC)
bytes[0] = 0xCC;
const modified: usize = @bitCast(bytes);
_ = ptrace(PTRACE_POKEDATA, pid, addr, modified);
return .{ .addr = addr, .original_byte = original, .enabled = true };
}
fn handleBreakpoint(pid: i32, bp: *Breakpoint) void {
// restore original byte
const word: usize = @bitCast(ptrace(PTRACE_PEEKDATA, pid, bp.addr, 0));
var bytes: [8]u8 = @bitCast(word);
bytes[0] = bp.original_byte;
const restored: usize = @bitCast(bytes);
_ = ptrace(PTRACE_POKEDATA, pid, bp.addr, restored);
// rewind RIP past the INT3 (it already incremented by 1)
var regs: UserRegs = undefined;
_ = ptrace(PTRACE_GETREGS, pid, 0, @intFromPtr(®s));
regs.rip -= 1; // back to the original instruction
_ = ptrace(PTRACE_SETREGS, pid, 0, @intFromPtr(®s));
}
fn rearmBreakpoint(pid: i32, bp: *Breakpoint) void {
// single-step past the restored instruction, then re-insert INT3
_ = ptrace(PTRACE_SINGLESTEP, pid, 0, 0);
_ = posix.waitpid(pid, 0);
const word: usize = @bitCast(ptrace(PTRACE_PEEKDATA, pid, bp.addr, 0));
var bytes: [8]u8 = @bitCast(word);
bp.original_byte = bytes[0]; // might have changed if code is self-modifying
bytes[0] = 0xCC;
const modified: usize = @bitCast(bytes);
_ = ptrace(PTRACE_POKEDATA, pid, bp.addr, modified);
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
const pid = try posix.fork();
if (pid == 0) {
_ = ptrace(PTRACE_TRACEME, 0, 0, 0);
_ = linux.syscall2(.kill, linux.syscall0(.getpid), 19);
// target function: a simple loop
var sum: u64 = 0;
for (0..5) |i| {
sum += i * 3;
}
const w = std.io.getStdOut().writer();
w.print("Child result: {d}\n", .{sum}) catch {};
posix.exit(0);
}
_ = posix.waitpid(pid, 0);
// get the initial RIP (where the child stopped)
var regs: UserRegs = undefined;
_ = ptrace(PTRACE_GETREGS, pid, 0, @intFromPtr(®s));
try stdout.print("Child stopped at RIP=0x{x}\n", .{regs.rip});
// set a breakpoint a few instructions ahead
const bp_addr = regs.rip + 8; // offset into the child's code
var bp = setBreakpoint(pid, bp_addr);
try stdout.print("Breakpoint set at 0x{x} (original byte: 0x{x})\n\n", .{ bp.addr, bp.original_byte });
// run until breakpoint
_ = ptrace(PTRACE_CONT, pid, 0, 0);
const wr = posix.waitpid(pid, 0);
if (wr.status.stopped_signal()) |sig| {
if (@intFromEnum(sig) == 5) { // SIGTRAP
_ = ptrace(PTRACE_GETREGS, pid, 0, @intFromPtr(®s));
try stdout.print("Hit breakpoint at 0x{x}!\n", .{regs.rip - 1});
try stdout.print(" RAX=0x{x} RBX=0x{x}\n", .{ regs.rax, regs.rbx });
// handle and continue
handleBreakpoint(pid, &bp);
rearmBreakpoint(pid, &bp);
try stdout.print("Breakpoint restored, continuing...\n", .{});
_ = ptrace(PTRACE_CONT, pid, 0, 0);
}
}
// wait for exit
const final = posix.waitpid(pid, 0);
if (final.status.exit_status()) |code| {
try stdout.print("Child exited with code {d}\n", .{code});
}
}
The INT3 replacement is brilliant in its simplicity -- it's ONE byte, so it fits into any instruction without overlapping into the next one. The x86 instruction set is variable-length (1 to 15 bytes), so a multi-byte breakpoint instruction would risk corrupting the following instruction's encoding. 0xCC solves this because it's the smallest possible instruction.
The rearm step is worth understanding: after handling the breakpoint, you need to execute the original instruction that was replaced. So you restore the byte, single-step once (executes that one instruction), then put the INT3 back. This lets you hit the same breakpoint repeatedly -- essential for loops.
PTRACE_SYSCALL is arguably the most useful ptrace request. It continues the tracee but stops it at the next syscall boundary -- once on entry (before the syscall executes) and once on exit (after it returns). This is how strace works:
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const PTRACE_TRACEME: u32 = 0;
const PTRACE_SYSCALL: u32 = 24;
const PTRACE_GETREGS: u32 = 12;
const UserRegs = extern struct {
r15: u64, r14: u64, r13: u64, r12: u64,
rbp: u64, rbx: u64, r11: u64, r10: u64,
r9: u64, r8: u64, rax: u64, rcx: u64,
rdx: u64, rsi: u64, rdi: u64, orig_rax: u64,
rip: u64, cs: u64, eflags: u64, rsp: u64,
ss: u64, fs_base: u64, gs_base: u64,
ds: u64, es: u64, fs: u64, gs: u64,
};
fn ptrace(request: u32, pid: i32, addr: usize, data: usize) isize {
return @bitCast(linux.syscall4(
.ptrace, request,
@as(usize, @bitCast(@as(isize, pid))), addr, data,
));
}
const syscall_names = [_][]const u8{
"read", "write", "open", "close", "stat", "fstat", "lstat", "poll",
"lseek", "mmap", "mprotect", "munmap", "brk", "rt_sigaction",
"rt_sigprocmask", "rt_sigreturn", "ioctl", "pread64", "pwrite64",
"readv", "writev", "access", "pipe", "select", "sched_yield",
"mremap", "msync", "mincore", "madvise", "shmget", "shmat", "shmctl",
"dup", "dup2", "pause", "nanosleep", "getitimer", "alarm", "setitimer",
"getpid", "sendfile", "socket", "connect", "accept", "sendto",
"recvfrom", "sendmsg", "recvmsg", "shutdown", "bind", "listen",
"getsockname", "getpeername", "socketpair", "setsockopt", "getsockopt",
"clone", "fork", "vfork", "execve", "exit", "wait4", "kill", "uname",
};
fn syscallName(nr: u64) []const u8 {
if (nr < syscall_names.len) return syscall_names[nr];
return "???";
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
const pid = try posix.fork();
if (pid == 0) {
_ = ptrace(PTRACE_TRACEME, 0, 0, 0);
_ = linux.syscall2(.kill, linux.syscall0(.getpid), 19);
// do things that generate syscalls
const fd = posix.open("/etc/hostname", .{ .ACCMODE = .RDONLY }, 0) catch posix.exit(1);
var buf: [256]u8 = undefined;
_ = posix.read(fd, &buf) catch {};
posix.close(fd);
posix.exit(0);
}
_ = posix.waitpid(pid, 0);
try stdout.print("Tracing syscalls for pid {d}\n\n", .{pid});
var entering = true;
var entry_nr: u64 = 0;
var call_count: u32 = 0;
while (true) {
_ = ptrace(PTRACE_SYSCALL, pid, 0, 0);
const wr = posix.waitpid(pid, 0);
// check for exit
if (wr.status.exit_status() != null) break;
if (wr.status.signal()) |_| break;
var regs: UserRegs = undefined;
_ = ptrace(PTRACE_GETREGS, pid, 0, @intFromPtr(®s));
if (entering) {
entry_nr = regs.orig_rax;
try stdout.print("[{d:>3}] {s}(", .{ call_count, syscallName(entry_nr) });
// print first 3 args
try stdout.print("0x{x}, 0x{x}, 0x{x}", .{ regs.rdi, regs.rsi, regs.rdx });
try stdout.print(")", .{});
call_count += 1;
} else {
// exit: rax has the return value
const ret: isize = @bitCast(regs.rax);
if (ret < 0) {
try stdout.print(" = -1 (errno {d})\n", .{@as(u32, @intCast(-ret))});
} else {
try stdout.print(" = {d}\n", .{ret});
}
}
entering = !entering;
}
try stdout.print("\nTotal: {d} syscalls traced\n", .{call_count});
}
The orig_rax field is important here -- on syscall entry, rax contains the syscall number, but the kernel overwrites rax with the return value on exit. The kernel saves the original number in orig_rax so tracers can always identify which syscall was called. If you read rax on entry you'd get the right number, but on exit you'd get the return value. Using orig_rax consistently is the safe approach.
Now lets combine everything into a more complete syscall tracer that can run any command. We'll support decoding common arguments (file paths, flags) and formatting the output like strace does:
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const PTRACE_TRACEME: u32 = 0;
const PTRACE_SYSCALL: u32 = 24;
const PTRACE_GETREGS: u32 = 12;
const PTRACE_PEEKDATA: u32 = 2;
const UserRegs = extern struct {
r15: u64, r14: u64, r13: u64, r12: u64,
rbp: u64, rbx: u64, r11: u64, r10: u64,
r9: u64, r8: u64, rax: u64, rcx: u64,
rdx: u64, rsi: u64, rdi: u64, orig_rax: u64,
rip: u64, cs: u64, eflags: u64, rsp: u64,
ss: u64, fs_base: u64, gs_base: u64,
ds: u64, es: u64, fs: u64, gs: u64,
};
fn ptrace(request: u32, pid: i32, addr: usize, data: usize) isize {
return @bitCast(linux.syscall4(
.ptrace, request,
@as(usize, @bitCast(@as(isize, pid))), addr, data,
));
}
// read a C string from the tracee's address space
fn readTraceeString(pid: i32, addr: usize, buf: []u8) []u8 {
if (addr == 0) {
buf[0] = 0;
return buf[0..0];
}
var offset: usize = 0;
while (offset < buf.len - 1) {
const word: usize = @bitCast(ptrace(PTRACE_PEEKDATA, pid, addr + offset, 0));
const bytes: [8]u8 = @bitCast(word);
for (bytes) |b| {
if (b == 0 or offset >= buf.len - 1) return buf[0..offset];
buf[offset] = b;
offset += 1;
}
}
return buf[0..offset];
}
const sc_names = [_][]const u8{
"read", "write", "open", "close", "stat", "fstat", "lstat", "poll",
"lseek", "mmap", "mprotect", "munmap", "brk", "rt_sigaction",
"rt_sigprocmask", "rt_sigreturn", "ioctl", "pread64", "pwrite64",
"readv", "writev", "access", "pipe", "select", "sched_yield",
"mremap", "msync", "mincore", "madvise", "shmget", "shmat", "shmctl",
"dup", "dup2", "pause", "nanosleep", "getitimer", "alarm", "setitimer",
"getpid", "sendfile", "socket", "connect", "accept", "sendto",
"recvfrom", "sendmsg", "recvmsg", "shutdown", "bind", "listen",
"getsockname", "getpeername", "socketpair", "setsockopt", "getsockopt",
"clone", "fork", "vfork", "execve", "exit", "wait4", "kill", "uname",
// gap...
};
fn scName(nr: u64) []const u8 {
if (nr < sc_names.len) return sc_names[nr];
if (nr == 79) return "getcwd";
if (nr == 102) return "getuid";
if (nr == 104) return "getgid";
if (nr == 110) return "getppid";
if (nr == 158) return "arch_prctl";
if (nr == 228) return "clock_gettime";
if (nr == 231) return "exit_group";
if (nr == 257) return "openat";
if (nr == 262) return "newfstatat";
if (nr == 302) return "prlimit64";
if (nr == 318) return "getrandom";
if (nr == 334) return "rseq";
return "???";
}
pub fn main() !void {
const stderr = std.io.getStdErr().writer();
var args = std.process.args();
_ = args.next(); // skip our name
const target = args.next() orelse {
try stderr.print("Usage: mini-strace \n", .{});
return;
};
const pid = try posix.fork();
if (pid == 0) {
_ = ptrace(PTRACE_TRACEME, 0, 0, 0);
_ = linux.syscall2(.kill, linux.syscall0(.getpid), 19);
const argv = [_]?[*:0]const u8{ @ptrCast(target.ptr), null };
const envp = [_]?[*:0]const u8{ null };
_ = linux.syscall3(.execve, @intFromPtr(argv[0].?), @intFromPtr(&argv), @intFromPtr(&envp));
posix.exit(127);
}
_ = posix.waitpid(pid, 0);
var entering = true;
var entry_regs: UserRegs = undefined;
var path_buf: [256]u8 = undefined;
while (true) {
_ = ptrace(PTRACE_SYSCALL, pid, 0, 0);
const wr = posix.waitpid(pid, 0);
if (wr.status.exit_status() != null) break;
if (wr.status.signal()) |_| break;
var regs: UserRegs = undefined;
_ = ptrace(PTRACE_GETREGS, pid, 0, @intFromPtr(®s));
if (entering) {
entry_regs = regs;
const nr = regs.orig_rax;
const name = scName(nr);
// format based on syscall type
if (nr == 257) { // openat
const path = readTraceeString(pid, regs.rsi, &path_buf);
try stderr.print("{s}(AT_FDCWD, \"{s}\", 0x{x})", .{ name, path, regs.rdx });
} else if (nr == 0) { // read
try stderr.print("{s}({d}, buf, {d})", .{ name, @as(isize, @bitCast(regs.rdi)), regs.rdx });
} else if (nr == 1) { // write
try stderr.print("{s}({d}, buf, {d})", .{ name, @as(isize, @bitCast(regs.rdi)), regs.rdx });
} else if (nr == 3) { // close
try stderr.print("{s}({d})", .{ name, @as(isize, @bitCast(regs.rdi)) });
} else if (nr == 59) { // execve
const path = readTraceeString(pid, regs.rdi, &path_buf);
try stderr.print("{s}(\"{s}\", ...)", .{ name, path });
} else {
try stderr.print("{s}(0x{x}, 0x{x}, 0x{x})", .{ name, regs.rdi, regs.rsi, regs.rdx });
}
} else {
const ret: isize = @bitCast(regs.rax);
if (ret < 0) {
const errno: u32 = @intCast(-ret);
const ename: []const u8 = switch (errno) {
1 => "EPERM", 2 => "ENOENT", 9 => "EBADF",
13 => "EACCES", 17 => "EEXIST", 22 => "EINVAL",
else => "?",
};
try stderr.print(" = -1 {s} (errno {d})\n", .{ ename, errno });
} else {
try stderr.print(" = {d}\n", .{ret});
}
}
entering = !entering;
}
}
This is a stripped-down strace. The real strace is ~30,000 lines of C because it decodes all ~450 syscalls with full struct formatting, but the core mechanism is identical. Notice we write trace output to stderr, not stdout -- the traced program's stdout must pass through unmodified, same convention strace uses.
Programs can detect they're being traced and refuse to run. This is common in malware, DRM, and anti-cheat systems. There are three main techniques:
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
fn ptrace(request: u32, pid: i32, addr: usize, data: usize) isize {
return @bitCast(linux.syscall4(.ptrace, request,
@as(usize, @bitCast(@as(isize, pid))), addr, data));
}
fn demonstrateAntiDebug() void {
const w = std.io.getStdOut().writer();
// technique 1: PTRACE_TRACEME self-check
const result = ptrace(0, 0, 0, 0); // PTRACE_TRACEME
if (result < 0) {
w.print("[anti-debug] PTRACE_TRACEME failed -- debugger detected!\n", .{}) catch {};
} else {
w.print("[anti-debug] PTRACE_TRACEME succeeded -- not being debugged\n", .{}) catch {};
}
// technique 2: check /proc/self/status for TracerPid
const fd = posix.open("/proc/self/status", .{ .ACCMODE = .RDONLY }, 0) catch return;
defer posix.close(fd);
var buf: [4096]u8 = undefined;
const n = posix.read(fd, &buf) catch 0;
if (std.mem.indexOf(u8, buf[0..n], "TracerPid:\t")) |pos| {
const start = pos + "TracerPid:\t".len;
var end = start;
while (end < n and buf[end] != '\n') end += 1;
const tpid = buf[start..end];
w.print("[anti-debug] TracerPid: {s}", .{tpid}) catch {};
if (std.mem.eql(u8, std.mem.trim(u8, tpid, " \t\n"), "0"))
w.print(" (not traced)\n", .{}) catch {}
else
w.print(" (TRACER DETECTED!)\n", .{}) catch {};
}
// technique 3: timing -- traced programs run much slower
const t0 = std.time.nanoTimestamp();
var dummy: u64 = 0;
for (0..100000) |i| dummy +%= i;
const elapsed = std.time.nanoTimestamp() - t0;
_ = dummy;
w.print("[anti-debug] Loop: {d}ns", .{elapsed}) catch {};
if (elapsed > 50_000_000)
w.print(" -- SUSPICIOUS\n", .{}) catch {}
else
w.print(" -- normal\n", .{}) catch {};
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
try stdout.print("=== Anti-debugging demos ===\n\nWithout debugger:\n", .{});
const pid = try posix.fork();
if (pid == 0) { demonstrateAntiDebug(); posix.exit(0); }
_ = posix.waitpid(pid, 0);
try stdout.print("\nWith debugger attached:\n", .{});
const pid2 = try posix.fork();
if (pid2 == 0) {
_ = ptrace(0, 0, 0, 0);
_ = linux.syscall2(.kill, linux.syscall0(.getpid), 19);
demonstrateAntiDebug();
posix.exit(0);
}
_ = posix.waitpid(pid2, 0);
_ = ptrace(7, pid2, 0, 0); // CONT
_ = posix.waitpid(pid2, 0);
try stdout.print("\nCountermeasures:\n", .{});
try stdout.print(" TRACEME check: tracer intercepts the syscall, fakes return 0\n", .{});
try stdout.print(" /proc check: tracer intercepts read, patches TracerPid to 0\n", .{});
try stdout.print(" Timing: hardest to defeat -- the overhead is real\n", .{});
}
The PTRACE_TRACEME self-check is trivial to bypass -- the tracer intercepts the ptrace syscall itself and modifies rax to 0. The /proc/self/status check is also defeatable by intercepting read and patching the buffer. Timing checks are harder because the tracing overhead is genuine. In the security research world this is an arms race with no definitive winner.
Here's the capstone for this episode -- a focused tracer that only logs file-related system calls (open, read, write, close, stat) and produces a clean summary. This is genuinely useful for understanding what files a program touches:
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const PTRACE_TRACEME: u32 = 0;
const PTRACE_SYSCALL: u32 = 24;
const PTRACE_GETREGS: u32 = 12;
const PTRACE_PEEKDATA: u32 = 2;
const UserRegs = extern struct {
r15: u64, r14: u64, r13: u64, r12: u64,
rbp: u64, rbx: u64, r11: u64, r10: u64,
r9: u64, r8: u64, rax: u64, rcx: u64,
rdx: u64, rsi: u64, rdi: u64, orig_rax: u64,
rip: u64, cs: u64, eflags: u64, rsp: u64,
ss: u64, fs_base: u64, gs_base: u64,
ds: u64, es: u64, fs: u64, gs: u64,
};
fn ptrace(request: u32, pid: i32, addr: usize, data: usize) isize {
return @bitCast(linux.syscall4(
.ptrace, request,
@as(usize, @bitCast(@as(isize, pid))), addr, data,
));
}
fn readString(pid: i32, addr: usize, buf: []u8) []u8 {
if (addr == 0) return buf[0..0];
var off: usize = 0;
while (off < buf.len - 1) {
const word: usize = @bitCast(ptrace(PTRACE_PEEKDATA, pid, addr + off, 0));
const bytes: [8]u8 = @bitCast(word);
for (bytes) |b| {
if (b == 0 or off >= buf.len - 1) return buf[0..off];
buf[off] = b;
off += 1;
}
}
return buf[0..off];
}
const FileOp = struct {
path: [256]u8,
path_len: usize,
ops: struct {
opened: bool = false,
read_bytes: u64 = 0,
write_bytes: u64 = 0,
closed: bool = false,
} = .{},
};
pub fn main() !void {
const stderr = std.io.getStdErr().writer();
var args = std.process.args();
_ = args.next();
const target = args.next() orelse {
try stderr.print("Usage: file-tracer \n", .{});
return;
};
const pid = try posix.fork();
if (pid == 0) {
_ = ptrace(PTRACE_TRACEME, 0, 0, 0);
_ = linux.syscall2(.kill, linux.syscall0(.getpid), 19);
const argv = [_]?[*:0]const u8{ @ptrCast(target.ptr), null };
const envp = [_]?[*:0]const u8{ null };
_ = linux.syscall3(.execve, @intFromPtr(argv[0].?), @intFromPtr(&argv), @intFromPtr(&envp));
posix.exit(127);
}
_ = posix.waitpid(pid, 0);
// track fd -> path mapping
var fd_paths: [256][256]u8 = undefined;
var fd_path_lens: [256]usize = [_]usize{0} ** 256;
var total_reads: u64 = 0;
var total_writes: u64 = 0;
var total_opens: u32 = 0;
var path_buf: [256]u8 = undefined;
var entering = true;
var entry_nr: u64 = 0;
var entry_regs: UserRegs = undefined;
while (true) {
_ = ptrace(PTRACE_SYSCALL, pid, 0, 0);
const wr = posix.waitpid(pid, 0);
if (wr.status.exit_status() != null) break;
if (wr.status.signal()) |_| break;
var regs: UserRegs = undefined;
_ = ptrace(PTRACE_GETREGS, pid, 0, @intFromPtr(®s));
if (entering) {
entry_nr = regs.orig_rax;
entry_regs = regs;
} else {
const ret: isize = @bitCast(regs.rax);
switch (entry_nr) {
257 => { // openat
if (ret >= 0 and ret < 256) {
const fd_idx: usize = @intCast(ret);
const path = readString(pid, entry_regs.rsi, &path_buf);
@memcpy(fd_paths[fd_idx][0..path.len], path);
fd_path_lens[fd_idx] = path.len;
total_opens += 1;
try stderr.print("open(\"{s}\") = {d}\n", .{ path, ret });
}
},
2 => { // open (legacy)
if (ret >= 0 and ret < 256) {
const fd_idx: usize = @intCast(ret);
const path = readString(pid, entry_regs.rdi, &path_buf);
@memcpy(fd_paths[fd_idx][0..path.len], path);
fd_path_lens[fd_idx] = path.len;
total_opens += 1;
try stderr.print("open(\"{s}\") = {d}\n", .{ path, ret });
}
},
0 => { // read
if (ret > 0) {
const fd_idx: usize = @intCast(@as(isize, @bitCast(entry_regs.rdi)));
if (fd_idx < 256 and fd_path_lens[fd_idx] > 0) {
const bytes: u64 = @intCast(ret);
total_reads += bytes;
try stderr.print("read({d} \"{s}\", {d} bytes)\n", .{
fd_idx,
fd_paths[fd_idx][0..fd_path_lens[fd_idx]],
bytes,
});
}
}
},
1 => { // write
if (ret > 0) {
const fd_idx: usize = @intCast(@as(isize, @bitCast(entry_regs.rdi)));
if (fd_idx < 256 and fd_path_lens[fd_idx] > 0) {
const bytes: u64 = @intCast(ret);
total_writes += bytes;
}
}
},
3 => { // close
const fd_val: isize = @bitCast(entry_regs.rdi);
if (fd_val >= 0 and fd_val < 256) {
const fd_idx: usize = @intCast(fd_val);
if (fd_path_lens[fd_idx] > 0) {
try stderr.print("close({d} \"{s}\")\n", .{
fd_idx, fd_paths[fd_idx][0..fd_path_lens[fd_idx]],
});
fd_path_lens[fd_idx] = 0;
}
}
},
else => {},
}
}
entering = !entering;
}
try stderr.print("\n=== File I/O Summary ===\n", .{});
try stderr.print("Files opened: {d}\n", .{total_opens});
try stderr.print("Total bytes read: {d}\n", .{total_reads});
try stderr.print("Total bytes written: {d}\n", .{total_writes});
}
The fd-to-path mapping is the key technique. When openat returns a file descriptor, we record which path was opened. When read/write happens on that fd, we report the filename alongside the byte count. This gives you a file-centric view of I/O that's incredibly useful for debugging "why is my program slow" -- often it's reading files you didn't expect (config files, locale data, shared libraries).
Build a memory watchpoint tool using ptrace. The tool accepts a PID and a memory address, and monitors that address for changes. Use PTRACE_ATTACH to attach to a running process, periodically read the target address with PTRACE_PEEKDATA, and print a message whenever the value changes. Include the old value, new value, and current RIP. Stop after detecting 5 changes or when the target process exits.
Extend the file operation tracer to also decode the flags argument to openat -- print whether the file was opened read-only, write-only, read-write, with O_CREAT, O_TRUNC, O_APPEND, etc. Also track the total number of read and write syscalls per fd (not just bytes) and print a per-file summary at the end showing path, open flags, read count, write count, total bytes in each direction.
Build a syscall argument modifier that uses ptrace to intercept specific syscalls and change their arguments before the kernel processes them. For example, intercept openat calls for a specific filename and redirect them to a different file by modifying the path pointer in the tracee's memory (write a new path string into the tracee's stack, then point RSI to it). Demonstrate by tracing /bin/cat /etc/hostname and redirecting it to read /etc/os-release instead.
PTRACE_PEEKDATA / PTRACE_POKEDATA read and write one machine word at a time -- for bulk access, wrap them in helper functions that handle partial wordsPTRACE_SYSCALL stops the tracee twice per syscall (entry and exit) -- read orig_rax for the syscall number and rax for the return value
@scipio