Zzuf tutorial

WARNING: this tutorial requires zzuf version 0.11 or later.

Basics

Let’s start with a simple command that reads data from a file. We choose hd, the hexadecimal dump command, and tell it to read 32 bytes from /dev/zero:

% hd -vn 32 /dev/zero
00000000  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020
%

Now let’s fuzz hd’s input using zzuf. It’s completely straightforward: just prepend zzuf to the commandline.

% zzuf hd -vn 32 /dev/zero
00000000  00 00 02 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 02 00 00  00 00 00 00 00 00 00 00  |................|
00000020
%

We see that two 00 values have been changed to 02s. zzuf intercepted hd's opening of /dev/zero and automatically corrupted the bytes it read at random. Let’s do it again:

% zzuf hd -vn 32 /dev/zero
00000000  00 00 02 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 02 00 00  00 00 00 00 00 00 00 00  |................|
00000020
%

We get exactly the same output. This is a very important property of zzuf: its behaviour is reproducible.

Altering the fuzzing ratio

The fuzzing ratio is the proportion of bits that zzuf changes. It is specified with the -r flag. The default fuzzing ratio is 0.004, meaning "fuzz 0.4% of the bits". 32 bytes is 256 bits, and 0.4% of 256 bits is approximately 1. zzuf should have fuzzed 1 bit, but since it fuzzes bits at random, 2 bits is not surprising.

Let’s try fuzzing more bits, for instance 5% of the bits, using -r 0.05:

% zzuf -r 0.05 hd -vn 32 /dev/zero
00000000  00 01 00 00 00 00 44 00  04 80 00 40 21 00 0a 20  |......D....@!.. |
00000010  40 20 00 04 00 00 02 00  00 00 00 00 00 00 00 00  |@ ..............|
00000020
%

We see that 15 bits have been changed. 5% of 256 bits is 12.8, so here again the behaviour is as expected.

Now let’s fuzz fewer bits, for instance 0.1%, using -r 0.001:

% zzuf -r 0.001 hd -vn 32 /dev/zero
00000000  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000020
%

No bits have been changed, because 0.1% of 256 is 0.256, so there were few chances that the bits would be changed at all.

Very high fuzzing ratios can be specified, for instance 50%, using -r 0.5:

% zzuf -r 0.5 hd -vn 32 /dev/zero  
00000000  c0 a0 20 b0 ad 40 07 c2  8a 14 30 1b 83 21 1a 69  |.. ..@....0..!.i|
00000010  11 28 05 07 30 00 70 01  43 08 62 c8 6d 45 e4 1a  |.(..0.p.C.b.mE..|
00000020
%