trinity.1

.TH TRINITY 1 Trinity trinity\-1.5
.nh
.SH NAME
Trinity -  Linux system call fuzzer

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

.SH SYNOPSIS

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 under scripts/ (test-multi.sh,
test-vm.sh, test-all-syscalls-parallel.sh, test-all-syscalls-sequentially.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)


.SH OPTIONS

.TP
\fI \-\-arch \-a\fP
Selects syscalls for the specified architecture (32 or 64). Both by default.

.TP
\fI \-\-bdev \-b\ <node>\fP
Add \/dev\/\fP node to list of block devices to use for destructive tests.

.TP
\fI \-\-children \-C \fP
Specify number of child processes

.TP
\fI \-\-debug \-D\fP
Enable debug

.TP
\fI\-\-dropprivs \-X\fP
If run as root, switch to nobody \fB[EXPERIMENTAL]

.TP
\fI\-\-exclude \-x\fP
Don't call a specific syscall

.TP
\fI\-\-enable\-fds or \-\-disable\-fds\fp
Options are: sockets, pipes, perf, epoll, eventfd, pseudo, timerfd,
testfile, memfd and drm

.TP
\fI\-\-group \-g\fP
only run syscalls from a certain group
(vfs, vm, net, ipc, process, signal, io_uring, bpf, sched, time)

.TP
\fI\-\-ioctls \-I\fP
List all ioctls.

.TP
\fI\-\-kernel_taint \-T\fP
Controls which kernel taint flags should be considered.

.TP
\fI\-\-list \-L\fP
List all syscalls known on this architecture.

.TP
\fI\-\-domain \-P\fP
Specify specific network domain for sockets.

.TP
\fI\-\-no_domain \-E\fP
Specify network domains to be excluded from testing.

.TP
\fI\-\-random \-r# \fP
Pick N syscalls at random and just fuzz those

.TP
\fI\-\-syslog \-S\fP
Log important info to syslog. Useful if syslog is remote.

.TP
\fI\-\-verbose \-v\fP
Increase output verbosity. Default output is minimal. Use -v for
operational detail, -vv for full debug output.

.TP
\fI\-\-victims \-V\fP
Path to victim files.

.TP
\fI\-c# @\fP
Target specific syscall, takes syscall name as parameter and optionally 32 or
64 as bit\-width. Default is both.

.TP
\fI\-N#\fP
Do # syscalls then exit.

.TP
\fI\-p\fP
Pause after syscall.

.TP
\fB\-s#\fP
use # as random seed.

.TP
\fI\-\-dry-run\fP
parse args and exit without fuzzing

.TP
\fI\-\-max-runtime\fP
maximum runtime before exit, with optional suffix s/m/h/d (e.g., 30s, 10m,
2h, 1d). Overrides --epoch-timeout.

.TP
\fI\-\-memory-max\fP
total trinity memory budget. Split into children/memory.max=<this>-parent_high
and a small parent reservation parent_high=min(200M,this/16) so worker OOM
doesn't take the parent. Accepts "max", N% of MemTotal, or N[KMG] bytes.
Default: 60%.

.TP
\fI\-\-memory-high\fP
children/memory.high back-pressure threshold (workers cgroup). Accepts
"max", N% of MemTotal, or N[KMG] bytes. Default: 50%.

.TP
\fI\-\-memory-swap-max\fP
children/memory.swap.max cap (workers cgroup). Accepts "max", N% of
MemTotal, or N[KMG] bytes. Default: 20%.

.TP
\fI\-\-no-cgroup\fP
skip self-cgroup creation entirely (no in-binary memory containment)

.TP
\fI\-\-strategy\fP
arm-selection POLICY for the multi-strategy rotation (NOT a specific arm):
bandit/ucb1 (default) or round-robin/rr. The set of arms is fixed
(heuristic, random, coverage-frontier); this flag picks how the rotation
chooses between them.

.TP
\fI\-\-explorer-children\fP
reserve N children to always run STRATEGY_RANDOM as a strategy-independent
explorer pool (default: max_children/4 under --strategy=bandit, 0
otherwise; max: max_children/2). Works in any picker mode; non-bandit
modes get no explorer pool unless this is set.

.TP
\fI\-\-alt-op-children\fP
reserve N children to run dedicated alt ops (mmap_lifecycle, mprotect_split,
...) round-robin instead of mixing them at 1% in every child (default:
max(2, --children/8))

.TP
\fI\-\-canary-slots\fP
reserve N slots from the front of --alt-op-children to run the dormant-op
canary queue (default: min(alt-op-children, 2) when unset). Clamped to
min(N, alt_op_children); N=0 disables the queue identically to
--no-canary-queue.

.TP
\fI\-\-canary-window\fP
invocations of the active canary op per window (default 10000, range
1000..1000000). Counted against the per-op invocation counter, not the
fleet-wide op count, so window size is independent of -C and
--canary-slots. Lower windows are too noisy to promote on; higher windows
let a useless op squat a slot for too long.

.TP
\fI\-\-canary-seed\fP
comma-separated list of childop names to override the built-in wave-1
canary seed list. Names match alt_op_name (e.g.
'genetlink_fuzzer,bpf_lifecycle'). Unknown names abort startup.

.TP
\fI\-\-no-canary-queue\fP
disable the dormant-childop canary queue entirely; the dormant gate is
consulted as a static compile-time vector and no canary slots are reserved.

.TP
\fI\-\-no-warm-start\fP
skip loading and saving the persisted minicorpus

.TP
\fI\-\-warm-start-path\fP
override the on-disk minicorpus path (default:
$XDG_CACHE_HOME/trinity/corpus/<arch>)

.TP
\fI\-\-no-kcov-warm-start\fP
skip loading and saving the persisted kcov edge bitmap

.TP
\fI\-\-no-cmp-hints-warm-start\fP
skip loading and saving the persisted kcov CMP-hint pool

.TP
\fI\-\-stats\fP
show errno distribution per syscall before exiting

.TP
\fI\-\-stats-json\fP
emit dump_stats output as a single JSON object on stdout (machine-readable)

.TP
\fI\-\-stats-log-file\fP
path to append periodic stats dumps to (in addition to stdout)

.TP
\fI\-\-effector-map\fP
calibrate per-bit input significance under KCOV and exit (one-shot)


.SH EXAMPLES
.TP
.B trinity -c splice
Stress test the splice syscall
.TP
.B trinity \-x splice
Call every syscall except for splice.
.TP
.B trinity \-C16
Run with 16 child processes

.fi
.SH AUTHOR
Trinity is written by Dave Jones <davej@codemonkey.org.uk>