Home | History | Annotate | Download | only in docs 
      1 # Introduction #
      2 
      3 With honggfuzz you can fuzz files by flipping bytes (`-mB`) or bits (`-mb`). You can also specify the rate (`-r`) of how many bytes or bits should be changed in the input file.
      4 
      5 Alternatively to this _"dumb"_ fuzzing mode, you can specify a custom fuzzer (`-c`) to modify input files.
      6 
      7 # Details #
      8 
      9 When run in `-mB` or `-mb` mode, honggfuzz does the following:
     10   1. a random file from the input files is chosen, and saved as a `.honggfuzz` file
     11   1. depending on the file size, the specified rate (`-r`) of bits or bytes is flipped
     12   1. the fuzzing target is executed with the input file (either via STDIN (`-s`) or via a command line parameter (`___FILE___`)
     13 
     14 When run in `-c` mode, the first and last steps are the same, but the file modification differs:
     15   1. a random file from the input files is chosen, and saved as a `.honggfuzz` file
     16   1. honggfuzz executes the external fuzzing binary or script specified by the `-c` parameter and appends the temporary `.honggfuzz` file as the first argument to the external fuzzer
     17   1. the external fuzzer should open and modify the temporary file
     18   1. honggfuzz waits for the external fuzzer to terminate
     19   1. the fuzzing target is executed with the modified input file (either via STDIN (`-s`) or via a command line parameter (`___FILE___`)
     20 
     21 # Example #
     22 
     23 If we consider the badcode1.c examples from the examples directory, we can see that it runs correctly for the sample input:
     24 
     25 ```
     26 $ ./examples/targets/badcode1 examples/inputfiles/badcode1.txt
     27 123456789012345678901234567890123456789012345678901234567890
     28 123456789012345678901234567890123456789012345678901234567890
     29 ```
     30 
     31 The bug in badcode1.c is that it reads lines up to 128 bytes from the input file and writes them to a 64 byte buffer (`fgets(str, 128, fp)`). If we would modify random bytes in the input file, the bug would only trigger when we overwrite the newline in the inputfile. With standard honggfuzz options this might take a while:
     32 
     33 ```
     34 $ ./honggfuzz -n 1 -f examples/badcode/inputfiles/badcode1.txt -- ./examples/badcode/targets/badcode1 ___FILE___
     35 honggfuzz, version 0.1 Robert Swiecki <swiecki (a] google.com>, Copyright 2010 by Google Inc. All Rights Reserved.
     36 [INFO] Launched new process, pid: 43288, (1/1)
     37 123456789012345678901234567890123456789012345678901234567890
     38 12345678012345678901234567890123456789012345678901234567890
     39 [INFO] Launched new process, pid: 43289, (1/1)
     40 123456789012345678901234567890123456789012345678901234567890
     41 12345678901234567890123456789?123456789012345678901234567890
     42 ...
     43 ```
     44 
     45 Now if we take a look at the script under [examples/externalfuzzers/lowBytesIncrease.py](http://code.google.com/p/honggfuzz/source/browse/trunk/examples/externalfuzzers/lowBytesIncrease.py), we see that it searches the input file (as provided by `argv[1]`) for low bytes and increases them randomly. This will modify the newlines, and thus trigger the bug much faster, as shown below:
     46 
     47 ```
     48 $ ./honggfuzz -n 1 -f examples/badcode/inputfiles/badcode1.txt -c `pwd`/examples/externalfuzzers/lowBytesIncrease.py -- ./examples/badcode/targets/badcode1 ___FILE___
     49 honggfuzz, version 0.1 Robert Swiecki <swiecki (a] google.com>, Copyright 2010 by Google Inc. All Rights Reserved.
     50 [INFO] Launched new process, pid: 44578, (1/1)
     51 [INFO] Ok, that's interesting, saving the '.honggfuzz.1287067149.44576.413228313.fuzz' as 'SIGSEGV.44578.2010-10-14.16.39.09.fuzz'
     52 [INFO] Launched new process, pid: 44580, (1/1)
     53 [INFO] Ok, that's interesting, saving the '.honggfuzz.1287067149.44576.637798454.fuzz' as 'SIGSEGV.44580.2010-10-14.16.39.09.fuzz'
     54 ...
     55 ```$ ./honggfuzz -n 1 -f examples/badcode/inputfiles/badcode1.txt -c `pwd`/examples/externalfuzzers/lowBytesIncrease.py -- ./examples/badcode/targets/badcode1 ___FILE___
     56 honggfuzz, version 0.1 Robert Swiecki <swiecki (a] google.com>, Copyright 2010 by Google Inc. All Rights Reserved.
     57 [INFO] Launched new process, pid: 44578, (1/1)
     58 [INFO] Ok, that's interesting, saving the '.honggfuzz.1287067149.44576.413228313.fuzz' as 'SIGSEGV.44578.2010-10-14.16.39.09.fuzz'
     59 [INFO] Launched new process, pid: 44580, (1/1)
     60 [INFO] Ok, that's interesting, saving the '.honggfuzz.1287067149.44576.637798454.fuzz' as 'SIGSEGV.44580.2010-10-14.16.39.09.fuzz'
     61 ...
     62 }}}```
     63