Trinity: Linux system call fuzzer.

	"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."


#######################################################################

Twenty years after its public introduction, I haven't had time to work on this much
at all in the last decade. You should consider this abandonware for the most part.
Nearly every commit you see here (after the v1.9 tag) is being now generated autonomously by an LLM.

Just updating the syscall definitions used to be one of the more laborious parts of
keeping this up to date with modern kernel versions. It now tracks additions to Linus Torvalds
mainline tree and adds new definitions as they get added upstream.

I also seeded it with some TODO items, and had it explore the codebase to come up with its
own ideas for fuzzing syscall interfaces, which it seems to have done a pretty decent job of so far.

I pick up the latest commits and run it every so often, and give it feedback if it's
introduced new bugs, which it fixes in its next cycle.
This means on any given day, it might be completely broken.

Don't bother sending PR's/email diffs, I just don't have time, all this activity
is basically an experiment to see just how far the LLM can take it.

(I especially don't have time to care about supporting older distributions outside of the ones I use any more.
 If you make it work on some old enterprise distro, keep the changes in your distro package.
 Chances are high the LLM will break them again soon anyway).

For a stable syscall fuzzer, see syzkaller, which is actively maintained/supported.

#######################################################################

WARNINGS:
* This program may seriously corrupt your files, including any of those
  that may be writable on mounted network file shares.  It may create network
  packets that may cause disruption on your local network.

* Trinity may generate the right selection of syscalls to start sending random network
  packets to other hosts. While every effort is made to restrict this to IP addresses
  on local lans, multicast & broadcast, care should be taken to not allow the
  packets it generates to go out onto the internet.

  Run at your own risk.


#######################################################################

System call fuzzers aren't a particularly new idea.   As far back as 1991,
people have written apps that bomb syscall inputs with garbage data,
that have had a variety of success in crashing assorted operating systems.

After fixing the obvious dumb bugs however, a majority of the time
these calls will just by rejected by the kernel very near the beginning
of their function entry point as basic parameter validation is performed.

Trinity is a system call fuzzer which employs some techniques to
pass semi-intelligent arguments to the syscalls being called.

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 outputs only essential messages by default (errors, taint detection,
syscall counts). Use -v for more detail, -vv for full debug output.

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)

######### options ###############################################

 --verbose/-v: increase output verbosity. Repeat for more detail (-vv).

 -D: Debug mode.
     This is useful for catching core dumps if trinity is segfaulting, as by default
     the child processes ignore those signals.

 -sN: use N as random seed.  (Omitting this uses time of day as a seed).
  Note: There are currently a few bugs that mean no two runs are necessary 100%
  identical with the same seed. See the TODO for details.

 --kernel_taint/-T: controls which kernel taint flags should be considered.
	The following flag names are supported: PROPRIETARY_MODULE, FORCED_MODULE, UNSAFE_SMP,
	FORCED_RMMOD, MACHINE_CHECK, BAD_PAGE, USER, DIE, OVERRIDDEN_ACPI_TABLE, WARN, CRAP,
	FIRMWARE_WORKAROUND, and OOT_MODULE. For instance, to set trinity to monitor only BAD,
	WARN and MACHINE_CHECK flags one should specify "-T BAD,WARN,MACHINE_CHECK" parameter.

 --list/-L: list known syscalls and their offsets

 --proto/-P: For network sockets, only use a specific packet family.

 --victims/-V: Victim file/dirs.  By default, on startup trinity tree-walks /dev, /sys and /proc.
     Using this option you can specify a different path.
     (Currently limited to just one path)

 -p: Pause after making a syscall

 --children/-C: Number of child processes.

 -x: Exclude a syscall from being called.  Useful when there's a known kernel bug
     you keep hitting that you want to avoid.
     Can be specified multiple times.

 -cN: do syscall N with random inputs.
     Good for concentrating on a certain syscall, if for eg, you just added one.
     Can be specified multiple times.

 --group/-g
   Used to specify enabling a group of syscalls. Current groups defined are 'vm' and 'vfs'.

 --ioctls/-I will dump all available ioctls.

 --arch/-a Explicit selection of 32 or 64 bit variant of system calls.

#######################################################################

Examples:
./trinity -c splice
Stress test the splice syscall

./trinity -x splice
Call every syscall except for splice.

./trinity -C16
Run with 16 child processes