README

   1 Trinity: Linux system call fuzzer.
   2
   3         "After the initial euphoria of witnessing the explosion had passed, test
   4          director Kenneth Bainbridge commented to Los Alamos director J. Robert
   5          Oppenheimer, "Now we are all sons of bitches."   Oppenheimer later stated
   6          that while watching the test he was reminded of a line from the Hindu
   7          scripture the Bhagavad Gita:
   8
   9                 Now I am become Death, the destroyer of worlds."
  10
  11
  12
  13 Warning: This program may seriously corrupt your files, including any of those
  14 that may be writable on mounted network file shares.  It may create network
  15 packets that may cause disruption on your local network.
  16 Run at your own risk.
  17
  18
  19 System call fuzzers aren't a particularly new idea.   As far back as 1991,
  20 people have written apps that bomb syscall inputs with garbage data,
  21 that have had a variety of success in crashing assorted operating systems.
  22
  23 After fixing the obvious dumb bugs however, a majority of the time
  24 these calls will just by rejected by the kernel very near the beginning
  25 of their function entry point as basic parameter validation is performed.
  26
  27 Trinity is a system call fuzzer which employs some techniques to
  28 pass semi-intelligent arguments to the syscalls being called.
  29
  30 The intelligence features include:
  31
  32 - If a system call expects a certain datatype as an argument
  33   (for example a file descriptor) it gets passed one.
  34   This is the reason for the slow initial startup, as it generates a
  35   list of fd's of files it can read from /sys, /proc and /dev
  36   and then supplements this with fd's for various network protocol sockets.
  37   (Information on which protocols succeed/fail is cached on the first run,
  38    greatly increasing the speed of subsequent runs).
  39
  40 - If a system call only accepts certain values as an argument,
  41   (for example a 'flags' field), trinity has a list of all the valid
  42   flags that may be passed.
  43   Just to throw a spanner in the works, occasionally, it will bitflip
  44   one of the flags, just to make things more interesting.
  45
  46 - If a system call only takes a range of values, the random value
  47   passed is ensured to fit within that range.
  48
  49
  50 Trinity logs it's output to a files (1 for each child process), and fsync's
  51 the files before it actually makes the system call. This way, should you trigger
  52 something which panics the kernel, you should be able to find out exactly what
  53 happened by examining the log.
  54
  55 There are several test harnesses provided (test-*.sh), which run trinity in
  56 various modes and takes care of things like cpu affinity, and makes sure it runs from the
  57 tmp directory. (Handy for cleaning up any garbage named files; just rm -rf tmp afterwards)
  58
  59 ######### options ###############################################
  60
  61  --quiet/-q: reduce verbosity.
  62    Specify once to not output register values, or twice to also suppress syscall count,
  63    and just reseed values.
  64
  65  --verbose: increase verbosity.
  66
  67  -D: Debug mode.
  68      This is useful for catching core dumps if trinity is segfaulting, as by default
  69      the child processes ignore those signals.
  70
  71  -sN: use N as random seed.  (Omitting this uses time of day as a seed).
  72   Note: There are currently a few bugs that mean no two runs are necessary 100%
  73   identical with the same seed. See the TODO for details.
  74
  75  --kernel_taint/-T: controls which kernel taint flags should be considered.
  76         The following flag names are supported: PROPRIETARY_MODULE, FORCED_MODULE, UNSAFE_SMP,
  77         FORCED_RMMOD, MACHINE_CHECK, BAD_PAGE, USER, DIE, OVERRIDDEN_ACPI_TABLE, WARN, CRAP,
  78         FIRMWARE_WORKAROUND, and OOT_MODULE. For instance, to set trinity to monitor only BAD,
  79         WARN and MACHINE_CHECK flags one should specify "-T BAD,WARN,MACHINE_CHECK" parameter.
  80
  81  --list/-L: list known syscalls and their offsets
  82
  83  --monochrome/-m: Don't output ANSI control codes
  84
  85  --proto/-P: For network sockets, only use a specific packet family.
  86
  87  --victims/-V: Victim file/dirs.  By default, on startup trinity tree-walks /dev, /sys and /proc.
  88      Using this option you can specify a different path.
  89      (Currently limited to just one path)
  90
  91  -p: Pause after making a syscall
  92
  93  --children/-C: Number of child processes.
  94
  95  -x: Exclude a syscall from being called.  Useful when there's a known kernel bug
  96      you keep hitting that you want to avoid.
  97
  98  -cN: do syscall N with random inputs.
  99       Good for concentrating on a certain syscall, if for eg, you just added one.
 100
 101  --group/-g vm
 102    Just call VM related syscalls
 103
 104  --logging/-l off: This disables logging. Useful if you have a serial console, though you
 105          will likely lose any information about what system call was being called,
 106          what maps got set up etc. Does make things go considerably faster however,
 107          as it no longer fsync()'s after every syscall
 108
 109  --ioctls/-I will dump all available ioctls.
 110
 111  --arch/-a Explicit selection of 32 or 64 bit variant of system calls.
 112
 113 #######################################################################
 114
 115 Examples:
 116 ./trinity -c splice
 117 Stress test the splice syscall
 118
 119 ./trinity -x splice
 120 Call every syscall except for splice.
 121
 122 ./trinity -qq -l off -C16
 123 Turn off logging, and suppress most output to run as fast as possible. Use 16 child processes
 124
 125
 126 #######################################################################
 127
 128 WARNINGS:
 129 * Trinity may generate the right selection of syscalls to start sending random network
 130   packets to other hosts. While every effort is made to restrict this to IP addresses
 131   on local lans, multicast & broadcast, care should be taken to not allow the
 132   packets it generates to go out onto the internet.
 133
 134
 135 #######################################################################
 136
 137 Development discussion of trinity occurs at trinity@vger.kernel.org
 138 As with all vger mailing lists, subscribe by sending 'subscribe trinity'
 139 in the body of a mail to majordomo@vger.kernel.org
 140
 141
 142 Reporting bugs upstream:
 143 If you find a kernel bug using trinity, first check the list at
 144 http://www.codemonkey.org.uk/projects/trinity/bugs-found.php
 145
 146 You may find that the bug is either already fixed (in which case
 147 a git commit hash should point to the fix), or there will be a link
 148 to an existing upstream report on the bug.
 149
 150 If you find something new, report it to the relevant kernel component maintainer,
 151 CC'd to linux-kernel.  CC'ing trinity@ will also be appreciated, so it
 152 can be recorded in the 'known bugs' section
 153
 154 ######### Links to similar projects ####################################
 155
 156 = tsys - 1991.
 157   http://groups.google.com/groups?q=syscall+crashme&hl=en&lr=&ie=UTF-8&selm=1991Sep20.232550.5013%40smsc.sony.com&rnum=1
 158
 159 = iknowthis
 160   http://iknowthis.googlecode.com
 161   Fuzzer by Tavis Ormandy with very similar goals to this project.
 162
 163 = sysfuzz
 164   basic fuzzer by Ilja van Sprundel
 165   mentioned in http://events.ccc.de/congress/2005/fahrplan/attachments/683-slides_fuzzing.pdf
 166   http://leetupload.com/dbindex2/index.php?dir=Linux/&file=sysfuzz.tar.gz
 167
 168 = xnufuzz
 169   https://github.com/fintler/xnufuzz/tree/
 170   basic fuzzer for XNU.  Looks to be based on Ilja's sysfuzz.
 171
 172 = kg_crashme / ak_crashme / dj_crashme
 173   Kurt Garloff wrote a fuzzer similar to Ilja's sysfuzz in 2003.
 174   The ak / dj variants were improvements added by Andi Kleen, and Dave Jones.