[or-cvs] r11145: more tutorial for the masses (in topf/trunk: doc lib)

benedikt at seul.org benedikt at seul.org
Thu Aug 16 19:16:12 UTC 2007


Author: benedikt
Date: 2007-08-16 15:16:12 -0400 (Thu, 16 Aug 2007)
New Revision: 11145

Modified:
   topf/trunk/doc/tutorial.tex
   topf/trunk/lib/control.rb
   topf/trunk/lib/fuzz-generic.rb
   topf/trunk/lib/fuzz.rb
Log:
more tutorial for the masses

Modified: topf/trunk/doc/tutorial.tex
===================================================================
--- topf/trunk/doc/tutorial.tex	2007-08-16 18:54:35 UTC (rev 11144)
+++ topf/trunk/doc/tutorial.tex	2007-08-16 19:16:12 UTC (rev 11145)
@@ -11,29 +11,84 @@
 \tableofcontents
 \newpage
 \section{Introduction}
-T.O.P.F is a block-based fuzzing Framework developed to test the TOR protocol-suite.
+T.O.P.F is a fuzzing Framework written in Ruby and developed to test the TOR protocol-suite.
+It uses a block-based approch like the famous SPIKE fuzzer written by Dave-Aitel.
+Block-based means that data is devided into so-called blocks that are then processed in a 
+predefined fassion. Compared to the random byte-flipping that many other fuzzers do, this allows
+a more focused approach on specific vulnerbilities like buffer, format-string or integer overflows.
+If fuzzing and or ruby sound strange to you, you should read into the links listed in the appendix \ref{links}.
 
 \section{Working with T.O.P.F}
+\label{working}
+To use T.O.P.F a few basic steps descriped in this section are nessesary.
 \subsection{Setting up a working Environment}
-T.O.P.F uses mainly Ruby Standart Librarys and supplies the rest through a typical subversion checkout so installing Ruby (Version 1.8) and checking out the latest T.O.P.F trunk should be enough to setup a working Test-Environment on the most Systems.
+As my aim is to make the Installation of T.O.P.F as easy as possible a working Ruby Interpreter and a checkout of  the latest T.O.P.F trunk should be enough to setup up a working Test-Environment on most Systems. If you have any problems or errors you are encouraged to email me to benedikt.boss (at) gmail (dot) com .
 
 \subsubsection{Checking out the current T.O.P.F trunk}
 Checking out T.O.P.F is as simple as starting a "svn co https://tor-svn.freehaven.net/svn/topf/trunk" on your command-shell of choice.
 
-\subsection{Implementing T.O.P.F Structures}
-T.O.P.F uses a modified version of the BitStruct Library to emulate a sort of c-like structures called fuzz-struct. A simple Example of such a structure implemented in Ruby looks like this:\\
+\subsection{Writing T.O.P.F Structures}
+As described in \ref{working}, T.O.P.F organizes its data in blocks. These blocks can have different types which are described detailled in \ref{types}. For example you can use char, signed and unsigned types. 
+
 \begin{verbatim}
+#example1.rb
+require "lib/fuzz-generic"
+
 class Example < BitStruct
     text :example, 7
     unsigned :version, 8
+
     initial_value.example = "example"
     initial_value.version   = 1
 end
+
+begin
+    e = Example.new
+    e.version = 2
+    pp e
+end
 \end{verbatim}
-This creates a Class called "Example" with the contents of a 8*8Bit long String and a 8Bit unsigned integer. Through the initial\_value call default values for all entered fields can be set.
-For a more detailed description of all possible field-types please take a look at the FuzzStruct Reference.
+This creates a Class called "Example" with the fields of a 8*8Bit long String, a 8Bit unsigned integer. and the initial values "example" and 1 for these.
+Next in the begin/end block the programm creates a Example object and sets the value of the version field to 2. This also demonstrates how you are able to access all fields after you created a fuzz-struct object.
+
 \subsection{Writing T.O.P.F Tests}
-T.O.P.F uses tests on a per-field type base. That means you are able to write Tests specific to a field-type the fuzz-struct library supplies (reference to the library reference).
+Tests in the Framework are organized on a field-type base. This means that you write tests for a specific field. To generate a Test you must create on object Fuzz::Test object and assign a type and code-block to it. For example if you want to test a char-field and assign many many "A"'s to the Field, which is a very common test :), you could write something like this:
+\begin{verbatim}
+    a_test = Fuzz::Test.new("char") {|arg, size|  "A"*1000}
+\end{verbatim}
+To apply this test to a fuzz-struct you actually need another object which acts as a collector for many tests. This object is called Fuzz::Tests and is later applied to a fuzz-struct.
+The next example shows how you write some tests, assign them to the collector object and apply all tests to a structure.
+\begin{verbatim}
+#example2.rb
+require "lib/fuzz-generic"
+
+class Example < BitStruct
+    text :example, 7
+    unsigned :version, 8
+
+    initial_value.example = "example"
+    initial_value.version   = 1
+end
+
+begin
+	example_tests = Fuzz::Tests.new
+	# tests for the text field
+	example_tests.register Fuzz::Test.new("char") {|arg, size|  arg} # return argument
+	example_tests.register Fuzz::Test.new("char") {|arg, size|  ""}    # return empty string
+	example_tests.register Fuzz::Test.new("char") {|arg, size|  "A"*1000} # return many many A's
+	# tests for unsigned numbers
+    example_tests.register Fuzz::Test.new("unsigned") {|arg, size|  arg } # return argument
+    example_tests.register Fuzz::Test.new("unsigned") {|arg, size|  0 } # return zero 
+    example_tests.register Fuzz::Test.new("unsigned") {|arg, size|  rand(5) } # return a small number 
+    example_tests.register Fuzz::Test.new("unsigned") {|arg, size|  2.power!(size) } # return biggest number 
+
+    e = Example.new
+	e.prepare! example_tests
+end
+
+\end{verbatim}
+
+
 \subsection{Do the Fuzz!}
 
 \section{T.O.P.F Reference}
@@ -47,5 +102,30 @@
 \subsection{Cell}
 \section{Fuzz-Struct Reference}
 \subsection{Types}
+\label{types}
+All Types beside text are equivalent to the types supplied by the bit-struct library.
+\subsubsection{char}
+Class for fixed length binary strings of characters.
+\subsubsection{text}
+Class for null-terminated printable text strings.
+\subsubsection{float}
+\subsubsection{signed}
+\subsubsection{unsigned}
+\subsubsection{octet}
+\subsubsection{hex-octet}
+\subsubsection{nested}
+\subsubsection{pad}
+\subsection{Logger}
 
+\section{Appendix}
+\subsection{Links}
+\label{links}
+\begin{verbatim}
+http://en.wikipedia.org/wiki/Fuzzing
+http://events.ccc.de/congress/2005/fahrplan/attachments/582-paper_fuzzing.pdf
+http://immunitysec.com/downloads/usingspike3.ppt
+http://en.wikipedia.org/wiki/Ruby_%28programming_language%29
+http://www.ruby-lang.org
+\end{verbatim}
+
 \end{document}\documentclass[10pt]{article}
\ No newline at end of file

Modified: topf/trunk/lib/control.rb
===================================================================
--- topf/trunk/lib/control.rb	2007-08-16 18:54:35 UTC (rev 11144)
+++ topf/trunk/lib/control.rb	2007-08-16 19:16:12 UTC (rev 11145)
@@ -39,7 +39,7 @@
 
         SETCONF_KEYS = [
             [ "version", "Tor 0.0.9.4" ],
-            [ "config-file", "PATH TO CONFIFILE" ],
+            [ "config-file", "/config/torrc" ],
             [ "exit-policy/prepend", "NOT IMPLEMENTED"],
             [ "exit-policy/default", ""],
             [ "desc/id/", "or identity" ],

Modified: topf/trunk/lib/fuzz-generic.rb
===================================================================
--- topf/trunk/lib/fuzz-generic.rb	2007-08-16 18:54:35 UTC (rev 11144)
+++ topf/trunk/lib/fuzz-generic.rb	2007-08-16 19:16:12 UTC (rev 11145)
@@ -2,7 +2,7 @@
 $:.unshift(File.dirname(dir)) unless
 $:.include?(File.dirname(dir)) || $:.include?(File.expand_path(File.dirname(dir)))
 
+require "logger"
 require "timeout"
 require "fuzz-struct"
 require "fuzz"
-require "logger"

Modified: topf/trunk/lib/fuzz.rb
===================================================================
--- topf/trunk/lib/fuzz.rb	2007-08-16 18:54:35 UTC (rev 11144)
+++ topf/trunk/lib/fuzz.rb	2007-08-16 19:16:12 UTC (rev 11145)
@@ -301,8 +301,8 @@
         DEFAULT_TESTS.register Fuzz::Test.new("char") {|arg, size|  arg     } # Return string
         DEFAULT_TESTS.register Fuzz::Test.new("char") {|arg, size|  ""      } # Return empty String 
         DEFAULT_TESTS.register Fuzz::Test.new("char") {|arg, size|  "A"*arg.size    } # FAULTING ARGUMENT STRING
-#        DEFAULT_TESTS.register Fuzz::Test.new("char") {|arg, size|  "A"*Fuzz::MAX_RAND    } # LONG STRING
-#        DEFAULT_TESTS.register Fuzz::Test.new("char") {|arg, size|  "%n"*Fuzz::MAX_RAND   } # FORMAT STRING
+        DEFAULT_TESTS.register Fuzz::Test.new("char") {|arg, size|  "A"*Fuzz::MAX_RAND    } # LONG STRING
+        DEFAULT_TESTS.register Fuzz::Test.new("char") {|arg, size|  "%n"*Fuzz::MAX_RAND   } # FORMAT STRING
 
         # Tests for signed numbers
         DEFAULT_TESTS.register Fuzz::Test.new("signed") {|arg, size|  0 } # return zero 
@@ -314,7 +314,7 @@
         # Tests for unsigned numbers
         DEFAULT_TESTS.register Fuzz::Test.new("unsigned") {|arg, size|  0 } # return zero 
         DEFAULT_TESTS.register Fuzz::Test.new("unsigned") {|arg, size|  rand(5) } # return a small number 
-        DEFAULT_TESTS.register Fuzz::Test.new("unsigned") {|arg, size|  2.power!(bits) } # return biggest number 
+        DEFAULT_TESTS.register Fuzz::Test.new("unsigned") {|arg, size|  2.power!(size) } # return biggest number 
 
         DEBUG_TESTS = Tests.new
         DEBUG_TESTS.register Fuzz::Test.new("char") {|arg, size|  arg     } # Return string



More information about the tor-commits mailing list