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 
    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 
    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:

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

License

Tarantula is released under the MIT license.