Changes between Version 1 and Version 2 of zzuf/tutorial Tweet

Timestamp:

05/18/08 01:34:39 (5 years ago)

Author:

sam

Comment:

random seed, different applications, file creation

zzuf/tutorial

@@ -1 @@
-= Zzuf tutorial =
+This tutorial is a hands-on guide to the most important `zzuf` features. It starts with the working principles but goes on with very advanced uses of the tool.
 
-'''WARNING''': this tutorial requires `zzuf` version 0.11 or later.
+Warning: this tutorial requires `zzuf` version 0.11 or later.
 
-== Basics ==
+= Basic `zzuf` usage =
 
-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`:
+`zzuf`’s behaviour is configured through the command line. A comprehensive list of flags and their meaning is given in the `zzuf` manual page. Just run '''`man zzuf`''' on your system to see it.
+
+== Launching `zzuf` ==
+
+Let’s start with a simple command that reads data from a file. We choose `hd`, the hexadecimal dump command, so that we get a chance to observe what exactly happens to the data.
+
+We tell `hd` to read 32 bytes from `/dev/zero`:
 
 {{{
@@ -37 +43 @@
 We get exactly the same output. This is a very important property of `zzuf`: its behaviour is '''reproducible'''.
 
-== Altering the fuzzing ratio ==
+== Invoking different programs ==
+
+Let’s fuzz the `cat` utility instead of `hd`, but read the final output with `hd` nonetheless:
+
+{{{
+% zzuf cat /dev/zero | hd -vn 32
+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
+%
+}}}
+
+Now instead of calling `hd`, let’s try `od`, the octal dumper:
+{{{
+% zzuf od -vN 32 /dev/zero
+0000000 000000 000002 000000 000000 000000 000000 000000 000000
+0000020 000000 000000 001000 000000 000000 000000 000000 000000
+0000040
+%
+}}}
+
+If you understand octal dumps as fluently as hexadecimal dumps, you noticed that the data has been fuzzed exactly like with `hd`.
+
+This is another very important property of `zzuf`: '''data is fuzzed the same way regardless of the fuzzed application'''.
+
+== 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.
@@ -74 +105 @@
 %
 }}}
+
+== The random seed ==
+
+`zzuf`’s behaviour is reproducible, but we might not be satisfied with the output. Or we may simply want to fuzz in several different ways, but still using the same fuzzing ratio. This is done by changing the '''random seed''' with the '''`-s` flag'''. The random seed is the initial value of `zzuf`’s random number generator. The default seed is 0, so let’s try with other values:
+
+{{{
+% zzuf -s 2 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 80 00 00 00  00 00 00 00 00 00 00 00  |................|
+00000020
+% zzuf -s 79432 hd -vn 32 /dev/zero  
+00000000  00 00 00 00 00 00 00 20  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
+%
+}}}
+
+As can be seen, each seed value initiates a different behaviour of the random number generator.
+
+== Creating fuzzed files ==
+
+It is possible to fuzz files directly, without calling applications at all.
+
+To do so, simply call `zzuf` with no application argument. It will fuzz its standard input by default:
+
+{{{
+% cat /dev/zero | zzuf | hd -vn32          
+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
+%
+}}}
+
+`zzuf` can be used to create files:
+
+{{{
+% dd if=/dev/zero bs=1 count=32 | zzuf > output.file
+32+0 records in
+32+0 records out
+32 bytes (32 B) copied, 9.1129e-05 s, 351 kB/s
+% hd -v output.file
+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
+%
+}}}
+
+This may be useful if a given application is not supported by `zzuf`, but it is especially useful to generate files that reproduce `zzuf`’s behaviour without requiring `zzuf`.
+