[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