Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 163 lines (110 sloc) 5.437 kb
d2377f1d »
2008-09-05 making tarantula into a gem
1 = Tarantula
2
3 == DESCRIPTION
4
5 Tarantula is a big fuzzy spider. It crawls your Rails application, fuzzing data to see what breaks.
6
7 == Usage
8
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
9 === Installation
10
11 The latest and greatest version is always available on GitHub. (See the rakefile for dependencies, or
d4926257 »
2009-05-22 Update README with better instructions for installing from GitHub. Cl…
12 just let RubyGems handle it.)
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
13
d4926257 »
2009-05-22 Update README with better instructions for installing from GitHub. Cl…
14 gem sources -a http://gems.github.com
1fa74bbb »
2009-05-29 Update README with better instructions for installing from GitHub.
15 gem install relevance-tarantula
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
16
17 You can also grab it from RubyForge, where we will push stable releases but may not be as bleeding edge
18 as the GitHub gem.
19
20 gem install tarantula
21
22 === Project Setup
23
24 To set up Tarantula into your application, add the following line into either config/environment.rb or
25 config/environments/test.rb (preferred). This assumes that you have Rails 2.1 or higher installed.
26
27 config.gem 'relevance-tarantula', :source => "http://gems.github.com", :lib => 'relevance/tarantula'
28
29 Since Rails doesn't (yet) support automatically loading rake tasks that live inside gems, you will need
30 to update your Rakefile to load Tarantula's rake tasks. The simplest approach is to start by vendoring
31 Tarantula into your Rails app.
32
33 mkdir -p vendor/gems
34 cd vendor/gems
35 gem unpack relevance-tarantula
36
9cd992bd »
2009-02-20 Update README to suggest a better "load" statement for your Rakefile ...
37 You can then add the following line into your Rakefile, which will allow your application to discover
38 Tarantula's rake tasks.
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
39
9cd992bd »
2009-02-20 Update README to suggest a better "load" statement for your Rakefile ...
40 load File.join(RAILS_ROOT, Dir["vendor/gems/relevance-tarantula-*/tasks/*.rake"])
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
41
42 === Crawling Your App
43
44 Use the included rake task to create a Rails integration test that will allow Tarantula to crawl your
45 app.
46
d2377f1d »
2008-09-05 making tarantula into a gem
47 #!sh
48 rake tarantula:setup
49
8baaaf2f »
2009-01-16 Update the tarantula_test template ...
50 Take a moment to familiarize yourself with the generated test. If parts of your application require
51 login, update the test to make sure Tarantula can access those parts of your app.
52
53 require "relevance/tarantula"
54
55 class TarantulaTest < ActionController::IntegrationTest
56 # Load enough test data to ensure that there's a link to every page in your
57 # application. Doing so allows Tarantula to follow those links and crawl
58 # every page. For many applications, you can load a decent data set by
59 # loading all fixtures.
60 fixtures :all
61
62 def test_tarantula
63 # If your application requires users to log in before accessing certain
64 # pages, uncomment the lines below and update them to allow this test to
65 # log in to your application. Doing so allows Tarantula to crawl the
66 # pages that are only accessible to logged-in users.
67 #
68 # post '/session', :login => 'quentin', :password => 'monkey'
69 # follow_redirect!
70
71 tarantula_crawl(self)
72 end
73 end
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
74
75 If you want to set custom options, you can get access to the crawler and set properties before running
76 it. For example, this would turn on HTMLTidy.
77
78 def test_tarantula
79 post '/session', :login => 'kilgore', :password => 'trout'
80 assert_response :redirect
81 assert_redirected_to '/'
82 follow_redirect!
8baaaf2f »
2009-01-16 Update the tarantula_test template ...
83
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
84 t = tarantula_crawler(self)
85 t.handlers << Relevance::Tarantula::TidyHandler.new
86 t.crawl '/'
d2377f1d »
2008-09-05 making tarantula into a gem
87 end
88
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
89 Now it's time to turn Tarantula loose on your app. Assuming your project is at /work/project/:
d2377f1d »
2008-09-05 making tarantula into a gem
90
36b2c697 »
2008-11-01 updating README to include gem based installation instructions.
91 #!sh
92 cd /work/project
93 rake tarantula:test
d2377f1d »
2008-09-05 making tarantula into a gem
94
95 == Verbose Mode
96
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
97 If you run the test using the steps shown above, Tarantula will produce a report in tmp/tarantula. You
98 can also set VERBOSE=true to see more detail as the test runs.
d2377f1d »
2008-09-05 making tarantula into a gem
99
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
100 For more options, please see the test suite.
d2377f1d »
2008-09-05 making tarantula into a gem
101
102 == Allowed Errors
103
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
104 If, for example, a 404 is an appropriate response for some URLs, you can tell Tarantula to allow 404s
105 for URLs matching a given regex:
d2377f1d »
2008-09-05 making tarantula into a gem
106
107 t = tarantula_crawler(self)
108 t.allow_404_for %r{/users/\d+/}
109
12aba080 »
2009-09-11 Version bump: 0.3.0
110 == Testing for Common Attacks
67b12f38 »
2008-11-01 adding custom attack handler example to README
111
112 You can specify the attack strings that Tarantula throws at your application.
113
114 def test_tarantula
115 t = tarantula_crawler(self)
116
837628bc »
2009-06-20 #8: unify FormSubmission and AttackFormSubmission. INCOMPATIBLE
117 Relevance::Tarantula::FormSubmission.attacks << {
67b12f38 »
2008-11-01 adding custom attack handler example to README
118 :name => :xss,
119 :input => "<script>gotcha!</script>",
120 :output => "<script>gotcha!</script>",
121 }
122
837628bc »
2009-06-20 #8: unify FormSubmission and AttackFormSubmission. INCOMPATIBLE
123 Relevance::Tarantula::FormSubmission.attacks << {
67b12f38 »
2008-11-01 adding custom attack handler example to README
124 :name => :sql_injection,
125 :input => "a'; DROP TABLE posts;",
126 }
127
7f639b04 »
2008-11-03 fixing typo in README
128 t.handlers << Relevance::Tarantula::AttackHandler.new
67b12f38 »
2008-11-01 adding custom attack handler example to README
129 t.times_to_crawl = 2
130 t.crawl "/posts"
131 end
132
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
133 This example adds custom attacks for both SQL injection and XSS. It also tells Tarantula to crawl the
134 app 2 times. This is important for XSS attacks because the results won't appear until the second time
135 Tarantula performs the crawl.
332777a6 »
2008-09-26 improve readme, add install notes and proper license
136
12483dfb »
2009-04-06 add docs and tweak the timeout message
137 == Timeout
138
139 You can specify a timeout for each specific crawl that Tarantula runs. For example:
140
141 def test_tarantula
142 t = tarantula_crawler(self)
143 t.times_to_crawl = 2
144 t.crawl_timeout = 5.minutes
145 t.crawl "/"
146 end
147
148 The above will crawl your app twice, and each specific crawl will timeout if it takes longer then 5 minutes. You may need a timeout to keep the tarantula test time reasonable if your app is large or just happens to have a large amount of 'never-ending' links, such as with an any sort of "auto-admin" interface.
149
d2377f1d »
2008-09-05 making tarantula into a gem
150 == Bugs/Requests
151
e90b8477 »
2009-01-16 Update README to better serve first-time users ...
152 Please submit your bug reports, patches, or feature requests at Lighthouse:
332777a6 »
2008-09-26 improve readme, add install notes and proper license
153
dfe1cbb7 »
2008-10-05 move tracking for Tarantula to lighthouse, and update all urls; requi…
154 http://relevance.lighthouseapp.com/projects/17868-tarantula/overview
d2377f1d »
2008-09-05 making tarantula into a gem
155
8032bbf0 »
2009-03-11 add link to RCR and dont use doc formatter -- too verbose with the ma…
156 You can view the continuous integration results for Tarantula, including results against all supported versions of Rails, on RunCodeRun here:
157
158 http://runcoderun.com/relevance/tarantula
159
336c4b0c »
2009-01-16 Update license years
160 == License
161
162 Tarantula is released under the MIT license.
Something went wrong with that request. Please try again.