TRINITY(1)

👑 TRINITY 👑 — the trinity manual page, bestie edition 💅

okay so. sit down, grab a strawberry 🍓, because we're talking about trinity, and she is literally a Linux system call fuzzer. lowercase name, capital energy. 🦋

✨ DESCRIPTION ✨

"After the initial euphoria of witnessing the explosion had passed, test director Kenneth Bainbridge commented to Los Alamos director J. Robert Oppenheimer, "Now we are all sons of bitches." Oppenheimer later stated that while watching the test he was reminded of a line from the Hindu scripture the Bhagavad Gita: Now I am become Death, the destroyer of worlds."

like. that's the description. that's the vibe. the manpage said destroyer of worlds and honestly? periodt. 💀✨

🌈 SYNOPSIS 🌈

so like, system call fuzzers aren't a particularly new idea, bestie. As far back as 1991, people have written apps that bomb syscall inputs with garbage data, and they've had a variety of success in crashing assorted operating systems. iconic behavior, lowkey. 😌

but here's the thing — after fixing the obvious dumb bugs? a majority of the time these calls will just be rejected by the kernel very near the beginning of their function entry point, because basic parameter validation is performed. like the kernel's bouncer checking IDs at the door and turning everyone away. 🙈

Trinity is a system call fuzzer which employs some techniques to pass semi-intelligent arguments to the syscalls being called. no cap. she's not just throwing slop at the wall.

The intelligence features include:

• If a system call expects a certain datatype as an argument (for example a file descriptor) it gets passed one. This is the reason for the slow initial startup, as it generates a list of fd's of files it can read from /sys, /proc and /dev and then supplements this with fd's for various network protocol sockets. (Information on which protocols succeed/fail is cached on the first run, greatly increasing the speed of subsequent runs).
• If a system call only accepts certain values as an argument, (for example a 'flags' field), trinity has a list of all the valid flags that may be passed. Just to throw a spanner in the works, occasionally, it will bitflip one of the flags, just to make things more interesting. 😈
• If a system call only takes a range of values, the random value passed is biased to usually fit within that range.

Trinity logs it's output to a files (1 for each child process), and fsync's the files before it actually makes the system call. This way, should you trigger something which panics the kernel, you should be able to find out exactly what happened by examining the log. forensics queen fr fr 💖

There are several test harnesses provided (test-*.sh), which run trinity in various modes and takes care of things like cpu affinity, and makes sure it runs from the tmp directory. (Handy for cleaning up any garbage named files; just rm -rf tmp afterwards). chef's kiss. 🎀

💖 OPTIONS 💖

• --arch, -a — selects syscalls for the specified architecture (32 or 64). Both by default. so like, she's ambidextrous. 💅
• --bdev, -b <node> — add dev node to list of block devices to use for destructive tests. ⚠️ destructive, bestie. read that word twice.
• --children, -C — specify number of child processes. her little minions 🧚
• --debug, -D — enable debug. for when you need the tea ☕
• --dropprivs, -X — if run as root, switch to nobody [EXPERIMENTAL]. it's giving "handing over the aux cord". experimental so pls be careful 🫶
• --exclude, -x — don't call a specific syscall. ghosting, but make it technical 👻
• --enable-fds or --disable-fds — options are: sockets, pipes, perf, epoll, eventfd, pseudo, timerfd, testfile, memfd and drm
• --group, -g = {vfs,vm} — only run syscalls from a certain group. pick your clique 🎀
• --ioctls, -I — list all ioctls.
• --kernel_taint, -T — controls which kernel taint flags should be considered.
• --list, -L — list all syscalls known on this architecture. the whole roster, slay 📋
• --logging, -l — off=disable logging. <dirname> specify a directory where logfiles will be placed.
• --domain, -P — specify specific network domain for sockets.
• --no_domain, -E — specify network domains to be excluded from testing. not invited to the party 🙅‍♀️
• --quiet, -q — less output. shhh 🤫
• --random, -r# — pick N syscalls at random and just fuzz those. chaos mode activated 🌪️
• --syslog, -S — log important info to syslog. useful if syslog is remote.
• --verbose, -v — increase output verbosity. tell me EVERYTHING 🗣️
• --victims, -V — path to victim files. bestie the naming?? 💀
• -c# @ — target specific syscall, takes syscall name as parameter and optionally 32 or 64 as bit-width. Default is both.
• -N# — do # syscalls then exit. commitment issues, respectfully.
• -p — pause after syscall. lil breather 🌸
• -s# — use # as random seed.

🦋 EXAMPLES 🦋

trinity -c splice

Stress test the splice syscall. targeted. personal. iconic.

trinity -x splice

Call every syscall except for splice. the silent treatment ✨

trinity -qq -l off -C16

Turn off logging, and suppress most output to run as fast as possible. Use 16 child processes. speedrun energy 🔥

👑 AUTHOR 👑

Trinity is written by Dave Jones <davej@codemonkey.org.uk> 💜

and that's the whole page, bestie!! this was trinity version trinity-1.5, from the Trinity manual — she's been out here destroying worlds and taking names. go forth, fuzz responsibly, and remember: fsync before you syscall 🫶🌈💖