From 5c7ea5d4e92a15051ac284e0b503beb81a48857e Mon Sep 17 00:00:00 2001 From: Ian Gulliver Date: Fri, 4 Mar 2016 21:58:44 -0800 Subject: [PATCH] Add README --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..13457e7 --- /dev/null +++ b/README.md @@ -0,0 +1,50 @@ +# stutterfuzz + +stutterfuzz is a fuzzer & stress tester for TCP servers. Using a directory +of input files to be sent, it rapidly opens many connections in parallel to a +single server and sends one file over each connection. It randomly varies +packet boundaries each time to attempt to trigger buffering & parsing issues +on the server. + + +## Input files + +To generate input files for your server, you can start with some hand-crafted +client -> server protocol data, or dumps from existing connections. To expand +this test set to exercise more paths in your server code, consider using +[american fuzzy lop](http://lcamtuf.coredump.cx/afl/). Note that you may need +to modify your server to accept data from stdin to use afl. It's worth the +effort. + + +## Running the server + +Connecting over loopback is best (for speed), so it's better if you can run +stutterfuzz and your server on the same machine. Consider making your server +[valgrind clean]() and running it under strict valgrind options: + +```bash +valgrind --track-fds=yes --show-leak-kinds=all --leak-check=full ./yourserver --flag1 --flag2=value --dont-fork +``` + +This enables you to detect more cases of problems triggered by stutterfuzz. + + +## Running stutterfuzz + +```bash +sudo apt-get -y install build-essential git clang +git clone https://github.com/flamingcowtv/stutterfuzz +cd stutterfuzz +make +./stutterfuzz --blob-dir=/path/to/source/directory --host=::1 --port=6789 +``` + +stutterfuzz will print statistics about source files (check these for sanity), +then continously print a count of rounds. Each round consists of sending all +input files once. Each round uses different packet boundaries. + +stutterfuzz never exits normally; the search space is too large to be +deterministic. Hit ctrl-c to exit manually. It will also exit with an error +if any connections to the server fail, assuming that it has triggered a +problem (or is being blocked).