Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 163 lines (110 sloc) 5.497 kB
d2377f1 making tarantula into a gem
Aaron J. Bedra authored
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
e90b847 @jasonrudolph Update README to better serve first-time users ...
jasonrudolph authored
9 === Installation
10
11 The latest and greatest version is always available on GitHub. (See the rakefile for dependencies, or
12 just let Rubygems handle it.)
13
14 gem install relevance-tarantula --source http://gems.github.com
15
16 You can also grab it from RubyForge, where we will push stable releases but may not be as bleeding edge
17 as the GitHub gem.
18
19 gem install tarantula
20
21 === Project Setup
22
23 To set up Tarantula into your application, add the following line into either config/environment.rb or
24 config/environments/test.rb (preferred). This assumes that you have Rails 2.1 or higher installed.
25
26 config.gem 'relevance-tarantula', :source => "http://gems.github.com", :lib => 'relevance/tarantula'
27
28 Since Rails doesn't (yet) support automatically loading rake tasks that live inside gems, you will need
29 to update your Rakefile to load Tarantula's rake tasks. The simplest approach is to start by vendoring
30 Tarantula into your Rails app.
31
32 mkdir -p vendor/gems
33 cd vendor/gems
34 gem unpack relevance-tarantula
35
9cd992b Update README to suggest a better "load" statement for your Rakefile ...
Jason Rudolph and Glenn Vanderburg authored
36 You can then add the following line into your Rakefile, which will allow your application to discover
37 Tarantula's rake tasks.
e90b847 @jasonrudolph Update README to better serve first-time users ...
jasonrudolph authored
38
9cd992b Update README to suggest a better "load" statement for your Rakefile ...
Jason Rudolph and Glenn Vanderburg authored
39 load File.join(RAILS_ROOT, Dir["vendor/gems/relevance-tarantula-*/tasks/*.rake"])
e90b847 @jasonrudolph Update README to better serve first-time users ...
jasonrudolph authored
40
41 === Crawling Your App
42
43 Use the included rake task to create a Rails integration test that will allow Tarantula to crawl your
44 app.
45
d2377f1 making tarantula into a gem
Aaron J. Bedra authored
46 #!sh
47 rake tarantula:setup
48
8baaaf2 @jasonrudolph Update the tarantula_test template ...
jasonrudolph authored
49 Take a moment to familiarize yourself with the generated test. If parts of your application require
50 login, update the test to make sure Tarantula can access those parts of your app.
51
52 require "relevance/tarantula"
53
54 class TarantulaTest < ActionController::IntegrationTest
55 # Load enough test data to ensure that there's a link to every page in your
56 # application. Doing so allows Tarantula to follow those links and crawl
57 # every page. For many applications, you can load a decent data set by
58 # loading all fixtures.
59 fixtures :all
60
61 def test_tarantula
62 # If your application requires users to log in before accessing certain
63 # pages, uncomment the lines below and update them to allow this test to
64 # log in to your application. Doing so allows Tarantula to crawl the
65 # pages that are only accessible to logged-in users.
66 #
67 # post '/session', :login => 'quentin', :password => 'monkey'
68 # follow_redirect!
69
70 tarantula_crawl(self)
71 end
72 end
e90b847 @jasonrudolph Update README to better serve first-time users ...
jasonrudolph authored
73
74 If you want to set custom options, you can get access to the crawler and set properties before running
75 it. For example, this would turn on HTMLTidy.
76
77 def test_tarantula
78 post '/session', :login => 'kilgore', :password => 'trout'
79 assert_response :redirect
80 assert_redirected_to '/'
81 follow_redirect!
8baaaf2 @jasonrudolph Update the tarantula_test template ...
jasonrudolph authored
82
e90b847 @jasonrudolph Update README to better serve first-time users ...
jasonrudolph authored
83 t = tarantula_crawler(self)
84 t.handlers << Relevance::Tarantula::TidyHandler.new
85 t.crawl '/'
d2377f1 making tarantula into a gem
Aaron J. Bedra authored
86 end
87
e90b847 @jasonrudolph Update README to better serve first-time users ...
jasonrudolph authored
88 Now it's time to turn Tarantula loose on your app. Assuming your project is at /work/project/:
d2377f1 making tarantula into a gem
Aaron J. Bedra authored
89
36b2c69 updating README to include gem based installation instructions.
Aaron J. Bedra authored
90 #!sh
91 cd /work/project
92 rake tarantula:test
d2377f1 making tarantula into a gem
Aaron J. Bedra authored
93
94 == Verbose Mode
95
e90b847 @jasonrudolph Update README to better serve first-time users ...
jasonrudolph authored
96 If you run the test using the steps shown above, Tarantula will produce a report in tmp/tarantula. You
97 can also set VERBOSE=true to see more detail as the test runs.
d2377f1 making tarantula into a gem
Aaron J. Bedra authored
98
e90b847 @jasonrudolph Update README to better serve first-time users ...
jasonrudolph authored
99 For more options, please see the test suite.
d2377f1 making tarantula into a gem
Aaron J. Bedra authored
100
101 == Allowed Errors
102
e90b847 @jasonrudolph Update README to better serve first-time users ...
jasonrudolph authored
103 If, for example, a 404 is an appropriate response for some URLs, you can tell Tarantula to allow 404s
104 for URLs matching a given regex:
d2377f1 making tarantula into a gem
Aaron J. Bedra authored
105
106 t = tarantula_crawler(self)
107 t.allow_404_for %r{/users/\d+/}
108
67b12f3 adding custom attack handler example to README
Aaron J. Bedra authored
109 == Custom Attack Handlers
110
111 You can specify the attack strings that Tarantula throws at your application.
112
113 def test_tarantula
114 t = tarantula_crawler(self)
115
116 Relevance::Tarantula::AttackFormSubmission.attacks << {
117 :name => :xss,
118 :input => "<script>gotcha!</script>",
119 :output => "<script>gotcha!</script>",
120 }
121
122 Relevance::Tarantula::AttackFormSubmission.attacks << {
123 :name => :sql_injection,
124 :input => "a'; DROP TABLE posts;",
125 }
126
7f639b0 fixing typo in README
Aaron J. Bedra authored
127 t.handlers << Relevance::Tarantula::AttackHandler.new
128 t.fuzzers << Relevance::Tarantula::AttackFormSubmission
67b12f3 adding custom attack handler example to README
Aaron J. Bedra authored
129 t.times_to_crawl = 2
130 t.crawl "/posts"
131 end
132
e90b847 @jasonrudolph Update README to better serve first-time users ...
jasonrudolph authored
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.
332777a @rsanheim improve readme, add install notes and proper license
rsanheim authored
136
12483df @rsanheim add docs and tweak the timeout message
rsanheim authored
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
d2377f1 making tarantula into a gem
Aaron J. Bedra authored
150 == Bugs/Requests
151
e90b847 @jasonrudolph Update README to better serve first-time users ...
jasonrudolph authored
152 Please submit your bug reports, patches, or feature requests at Lighthouse:
332777a @rsanheim improve readme, add install notes and proper license
rsanheim authored
153
dfe1cbb @rsanheim move tracking for Tarantula to lighthouse, and update all urls; requ…
rsanheim authored
154 http://relevance.lighthouseapp.com/projects/17868-tarantula/overview
d2377f1 making tarantula into a gem
Aaron J. Bedra authored
155
8032bbf @rsanheim add link to RCR and dont use doc formatter -- too verbose with the ma…
rsanheim authored
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
336c4b0 @jasonrudolph Update license years
jasonrudolph authored
160 == License
161
162 Tarantula is released under the MIT license.
Something went wrong with that request. Please try again.