a big hairy fuzzy spider that crawls your site, wreaking havoc
JavaScript Ruby
Switch branches/tags
Nothing to show
Pull request Compare This branch is 6 commits ahead, 189 commits behind relevance:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
laf
lib/relevance
rails
tasks
template
test
vendor/xss-shield
.autotest
.gitignore
CHANGELOG
MIT-LICENSE
README.rdoc
Rakefile
init.rb
install.rb
manifest.txt
tarantula.gemspec
uninstall.rb

README.rdoc

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.

Fail on reaching certain URLs

You can tell tarantula to record a failure if it reaches a page with a URL matching a certain pattern:

def test_tarantula

t = tarantula_crawler(self)
t.handlers << Relevance::Tarantula::UnexpectedUrlHandler.new(/some_bad_page\.html/)
t.crawl "/"

end

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 add the following line into your Rakefile.

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

Substituting the proper version of relevance-tarantula in the path. This assumes that you have vendored tarantula. To do so simply run

gem unpack relevance-tarantula

from the vendor/gems directory of your application.

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 and Copyright

(The MIT License)

Copyright © 2008 Relevance, Inc. - thinkrelevance.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.