= Tarantula

== DESCRIPTION

Tarantula is a big fuzzy spider. It crawls your Rails application, fuzzing data to see what breaks.

== Usage

   #!sh
   rake tarantula:setup

Creates a Rails integration test that looks like this, filling in your own auth params. You will probably want to include all fixtures.

   require 'relevance/tarantula'

   # in your test
   def test_with_login
       post '/sessions/create', :password => 'your-pass'
       follow_redirect!
       tarantula_crawl(self)
   end

If you want to set custom options, you can get access to the crawler and set properties before running it. For example, this would turn on HTMLTidy.

   def test_with_login
       post '/sessions/create', :password => 'your-pass'
       assert_response :redirect
       assert_redirected_to '/'
       follow_redirect!
       t = tarantula_crawler(self)
       t.handlers << Relevance::Tarantula::TidyHandler.new
       t.crawl '/'
   end

Assuming your project is at /work/project/:

   #!sh
   cd /work/project
   rake tarantula:test

== Verbose Mode

If you run the test you will get a report in tmp/tarantula. You can also set VERBOSE=true to see more detail as the test runs.

For more options see the test suite.

== Allowed Errors

If, for example, a 404 is an appropriate response for some URLs, you can
tell Tarantula to allow 404s for URLs matching a regexp:

     t = tarantula_crawler(self)
     t.allow_404_for %r{/users/\d+/}

== Custom Attack Handlers

You can specify the attack strings that Tarantula throws at your application.

    def test_tarantula
      t = tarantula_crawler(self)

      Relevance::Tarantula::AttackFormSubmission.attacks << { 
        :name => :xss,
        :input => "<script>gotcha!</script>",
        :output => "<script>gotcha!</script>",
      }

      Relevance::Tarantula::AttackFormSubmission.attacks << { 
        :name => :sql_injection,
        :input => "a'; DROP TABLE posts;",
      }

      t.handlers << Relevance::Tarantula::AttackHandler.new
      t.fuzzers << Relevance::Tarantula::AttackFormSubmission
      t.times_to_crawl = 2
      t.crawl "/posts"
    end

This example adds custom attacks for both SQL injection and XSS.  It also tells tarantula to crawl the app 2 times.  This
is important for XSS attacks because the results won't appear until the second time tarantula performs the crawl.

== Install

See the rakefile for dependencies, or just let Rubygems handle it.

The latest and greatest gem will always be available from Github:

    gem install relevance-tarantula --source http://gems.github.com

To setup tarantula in your application add the following line into either config/environment.rb or config/environments/test.rb (preferred).
This assumes that you have Rails 2.1 or higher installed.

    config.gem 'relevance-tarantula', :source => "http://gems.github.com", :lib => 'relevance/tarantula'

Since rails doesn't (yet) support loading rake tasks that live inside gems you will need to update your Rakefile.  This assumes that you have vendored tarantula.  Simply run
	
	cd vendor/gems
    gem unpack relevance-tarantula

You can then add the following line into your Rakefile, substituting the proper version of relevance-tarantula in the path.

    load File.join(RAILS_ROOT, "vendor/gems/relevance-tarantula-0.0.8.1/tasks/tarantula_tasks.rake")

You can also grab it from Rubyforge, where we will push stable releases but may not be as bleeding edge as the Github gem.

    gem install tarantula

== Bugs/Requests

Please submit your bug reports, patches or feature requests at Lighthouse:

http://relevance.lighthouseapp.com/projects/17868-tarantula/overview

== License

Tarantula is released under the MIT license.