# $Id: README.txt 411 2007-07-31 03:07:35Z meddingt $

Peach Fuzzing Framework 1.0
===========================

Michael Eddington (mike@phed.org)
http://peachfuzz.sf.net
http://groups-beta.google.com/group/peachfuzz

-- Written while drinking beer at ph-neutral --

Peach is fuzzer framework intended to provide a good mix of flexability, code
reuse and fast development time.  Peach is object oriented in design and was
implemented in the Python language for portability.  This initial version is
subject to change as the code is further refined and tested.  This is the first
implementation of this code.

Requirements

  Peach requires Python version 2.3 or higher due to module dependencies.  It
  is possible to use Peach with older versions of Python if one avoids/modifies
  Peach to not import 2.3 specific modules.  Currently I am not making use of
  the new True/Flase booleans, but instead, good old 0 and 1.
  
  Peach developement occurs on OS X and Windows, so things should pretty much
  work okay anywhere a current Python lives.

Concepts

  The Peach fuzzer has the following general components that are used to 
  construct a script: Generators, Transformers, Protocols, and Publishers.
  
  Generators
  
    Generators are objects that generate data.  Generators can be very 
	simplistic, such as a static string, or much more complex like a TCP
	packet or HTTP message.  Some generators are comprised of other
	generators.  Generators can also have a Transormer object attached to them
	to perform data transformations.
	
  Transformers
  
    Transformers are objects that change data in a specific way.  For instance
	HTML encoding could be a transformer as could a gziping or un-gziping data.
	
	Trasnformers can be chained together to perform multiple transformations on
	data (for example: perform HTML encoding and then URL encode the result).
	
  Protocols
  
    Protocols are objects that can manage state transitions inherent to 
	protocols.  Protocols should not generate much in the way of data but
	should instead use one or more Generators to allow for flexability and
	re-use.  An example of a Protocol could be to manage state accross multiple
	HTTP requests in which cookies could be used, or authentication, etc.
	
	Protocols also contain a reference to a Publisher object which is used as
	the transport for the generated data.

  Publishers
  
    Publishers implement some form of transport for data generated through a 
	Protocol.  Example Publishers could be a file publisher (write data to a
	file), TCP publisher could push data over a TCP socket, or an RCP protocol
	to call RCP commands on another host.
   
	Publishers should in general not manage any state if possible.
	
	NOTE: I would like to have a common generic interface for publishers such that
		  any protocol could be hooked up with any publisher.  Currently this
		  generic interface is not completed.  Suggestions are always welcome.

  Group

    A Group contains one or more Generators and is the mechanism used to change
	to the next value a Generator will produce.  This allows for multiple sets
	of Generators that can increment at different times but does not tie them
	together in anyother way (e.g. there data can be stuck anywhere).
	
	Several stock group implementations have been provided to do things like fixed
	# of increments, or increment over one group in a set at a time, etc.

  Script
  
    Script objects take some of the redundent code out of the fuzzer script for
	doing the actual looping of calling the group.next and protocol.step.

	
Examples

  A number of examples are provided in the samples directory.  Also a template.py
  is also available that contains the base imports required to write a fuzzer.
  

Flexability and Crazyness

  Peach can be used in many many ways, most of which will be left to the user to
  dream up.  However here are a few ideas:
  
  Instrumented Clients/Servers
  
    It's easy to embed Python into C/C++ and other code.  Now you can build
	instrumented client/server fuzzers by calling Peach right from native code!
	
  Bounds Checker/Purify
  
    Afraid you may miss bugs that don't cause your program to crash?  Run things through
	a program like Bounds Checker or Purify.  For extra credit check how how easy it is
	to create Python COM objects that allow Peach to access information from these proggys!
	
  Fuzzing Shared Libraries/DLL's
  
    Calling into shared libraries, DLL's, Windows system calls, etc is easy with Python!
	

-- end