From be62fa16a298644e143b83a3605d38ac25437ce0 Mon Sep 17 00:00:00 2001
From: Fabian Keil <fk@fabiankeil.de>
Date: Thu, 8 Jun 2017 13:08:39 +0000
Subject: [PATCH] Add a small fuzzing section to the developer documentation

---
 doc/source/developer-manual.sgml | 68 +++++++++++++++++++++++++++++++-
 1 file changed, 66 insertions(+), 2 deletions(-)

diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index 6d137649..ad9588fc 100644
--- a/doc/source/developer-manual.sgml
+++ b/doc/source/developer-manual.sgml
@@ -21,7 +21,7 @@
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
 
- $Id: developer-manual.sgml,v 2.81 2016/08/26 12:32:19 fabiankeil Exp $
+ $Id: developer-manual.sgml,v 2.82 2017/01/23 12:59:45 fabiankeil Exp $
 
  Copyright (C) 2001-2016 Privoxy Developers https://www.privoxy.org/
  See LICENSE.
@@ -49,7 +49,7 @@
     </pubdate>
 
 
-    <pubdate>$Id: developer-manual.sgml,v 2.81 2016/08/26 12:32:19 fabiankeil Exp $</pubdate>
+    <pubdate>$Id: developer-manual.sgml,v 2.82 2017/01/23 12:59:45 fabiankeil Exp $</pubdate>
 
 <!--
 
@@ -1975,6 +1975,70 @@ Install the rpm. Any error messages?
 </para>
     </sect2>
     <!-- XXX: Document how to write test reports and where to send them -->
+
+    <!--   ~~~~~       New section      ~~~~~     -->
+    <sect2 id="fuzzing"><title>Fuzzing Privoxy</title>
+     <para>
+       To make fuzzing more convenient, Privoxy can be configured
+       with --enable-fuzz which will result in the --fuzz option
+       becoming available.
+     </para>
+     <para>
+      Example (tested on ElectroBSD):
+     </para>
+     <programlisting>
+# Compile Privoxy with instrumentation for afl
+$ export CC=afl-clang
+$ export CFLAGS="-fsanitize=address -ggdb"
+$ export CPPFLAGS=-I/usr/local/include/
+$ export LDFLAGS="-fsanitize=address -L/usr/local/lib"
+$ export AFL_USE_ASAN=1
+$ export AFL_HARDEN=1
+$ ./configure --with-debug --enable-extended-host-patterns --enable-accept-filter --enable-no-gifs --enable-compression --enable-strptime-sanity-checks --enable-external-filters --enable-fuzz
+
+$ ./privoxy --fuzz
+Privoxy version 3.0.24 (http://www.privoxy.org/)
+Usage: ./privoxy [--config-test] [--chroot] [--help] [--no-daemon] [--pidfile pidfile] [--pre-chroot-nslookup hostname] [--user user[.group]] [--version] [configfile]
+       ./privoxy --fuzz fuzz-mode ./path/to/fuzzed/input [--stfu]
+
+Supported fuzz modes and the expected input:
+ action: Text to parse as action file.
+ client-request: Client request to parse. Currently incomplete
+ client-header: Client header to parse.
+ chunked-transfer-encoding: Chunk-encoded data to dechunk.
+ deflate: deflate-compressed data to decompress.
+ filter: Text to parse as filter file.
+ gif: gif to deanimate.
+ gzip: gzip-compressed data to decompress.
+ pcrs-substitute: A pcrs-substitute to compile. Not a whole pcrs job! Example: Bla $1 bla C $3 blah.
+ server-header: Server header to parse.
+ server-response: Server response to parse.
+
+The following fuzz modes read data from stdin if the 'file' is '-'
+ client-request
+ client-header
+ chunked-transfer-encoding
+ deflate
+ gif
+ gzip
+ pcrs-substitute
+ server-header
+ server-response
+
+Aborting
+
+$ export ASAN_OPTIONS='abort_on_error=1'
+$ mkdir input output
+$ echo '$1 bla fasel $2' > input/pcrs
+$ afl-fuzz -i input -o output -m none ~/git/privoxy/privoxy --fuzz pcrs-substitute - --stfu
+
+$ cat >input/pcrs.txt
+FILTER: bla fasel
+s@(.{1})[432](\d+)@$1$2$hostname@UgisT
+
+$ afl-fuzz -i input/ -o output/ -f bla.filter -m none privoxy --fuzz filter bla.filter --stfu
+</programlisting>
+    </sect2>
   </sect1>
 
   <!--   ~~~~~       New section      ~~~~~     -->
-- 
2.39.2