-======================-
this is a port for OSX/iOS by eQuiNoX__

-======================-

Original readme follows -->



Trinity v1.0

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



Warning: 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.
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 ensured to fit within that range.


Trinity logs it's output to a file, and fsync's the file 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.

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 ###############################################

 -sN: use N as random seed.  (Omitting this uses time of day as a seed).

There exist a number of further options that define what kinds of values are passed
in registers to the syscalls.

 -z:  Use all zeros as register parameters.
This calls every syscall with zeros in each of the registers in turn, in
every possible combination, with random junk in the other registers.
Useful for testing for missing NULL checks.



There also exist some options which apply to all available modes.

-bN: begin at offset N.
Useful for reproducing bugs that start after a certain # of runs.
*note*, this feature is currently broken. It passes the correct seed, but
 as we don't know how much entropy was used up between seed and N,
 runs won't be identical.

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

Other useful arguments:

-g vm
 Just call VM related syscalls

-l off
 This disables logging. Useful if you have a serial console, though you
 will likely lose any information about what system call was being called,
 what maps got set up etc. Does make things go considerably faster however,
 as it no longer fsync()'s after every syscall

--list will dump all available syscalls, and their syscall number.

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

Examples:
./trinity -c splice
Stress test the splice syscall, with random parameters, but sanitise
the passed params so they look almost sensible.


######### Links to similar projects ####################################

= tsys - 1991.
  http://groups.google.com/groups?q=syscall+crashme&hl=en&lr=&ie=UTF-8&selm=1991Sep20.232550.5013%40smsc.sony.com&rnum=1

= iknowthis
  http://iknowthis.googlecode.com
  Fuzzer by Tavis Ormandy with very similar goals to this project.

= sysfuzz
  basic fuzzer by Ilja van Sprundel
  mentioned in http://events.ccc.de/congress/2005/fahrplan/attachments/683-slides_fuzzing.pdf
  http://leetupload.com/dbindex2/index.php?dir=Linux/&file=sysfuzz.tar.gz

= xnufuzz
  https://github.com/fintler/xnufuzz/tree/
  basic fuzzer for XNU.  Looks to be based on Ilja's sysfuzz.

= kg_crashme / ak_crashme / dj_crashme
  Kurt Garloff wrote a fuzzer similar to Ilja's sysfuzz in 2003.
  The ak / dj variants were improvements added by Andi Kleen, and Dave Jones.