bot-away 1.1.0 → 1.2.0

data/.gitignore

@@ -0,0 +1,7 @@
+.idea
+*.swp
+*.log
+pkg
+dry-run
+coverage
+doc

data/History.txt

@@ -1,11 +1,21 @@
+=== 1.2.0 2010-10-14
+* Enhancements:
+  * Rails 3 / RSpec 2 support! Yay!
+  * ActionController::Request#accepts_unfiltered_params has been removed. Use BotAway#accepts_unfiltered_params instead.
+  * Exclusion of bot-filtering on a per-controller, per-action and/or per-runmode basis is now possible via
+    BotAway#disabled_for
+
 === 1.1.0 2010-06-21
-* Minor enhancements:
+* Enhancements:
   * ActionController::Request.accepts_unfiltered_params is now accessible as BotAway.accepts_unfiltered_params
   * BotAway.show_honeypots = true will show honeypots as visible elements within the form, for debugging.
   * BotAway.dump_params = true will dump the params hash as it was before BotAway modified it, for debugging.
   * BotAway will no longer generate hashes for, or disguise, elements whose names have been added to
     BotAway.unfiltered_params. This should resolve issues where JavaScript is involved (case in point:
-    CalendarDateSelect).
+    Calendar Date Select).
+* Bugfix:
+  * Resolved: Unfiltered params were not matched if they were of differing types (ie Symbol vs String). This caused
+    problems in particular with Calendar Date Select.
     
 === 1.0.3 2010-06-13
 * Bugfixes:

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Colin MacKenzie IV
+
+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.

data/README.rdoc

@@ -2,13 +2,11 @@
 
 * http://github.com/sinisterchipmunk/bot-away
 
-== DESCRIPTION:
-
 Unobtrusively detects form submissions made by spambots, and silently drops those submissions. The key word here is
 "unobtrusive" -- this is NOT a CAPTCHA. This is a transparent, modular implementation of the bot-catching techniques
 discussed by Ned Batchelder at http://nedbatchelder.com/text/stopbots.html.
 
-== WHAT'S GOING ON:
+== How It Works
 
 If a bot submission is detected, the params hash is cleared, so the data can't be used. Since this includes the
 authenticity token, Rails should complain about an invalid or missing authenticity token. Congrats, spam blocked.
@@ -16,24 +14,139 @@ authenticity token, Rails should complain about an invalid or missing authentici
 The specifics of the techniques employed for filtering spambots are discussed Ned's site in the description; however,
 here's a brief run-down of what's going on:
 
-* Your code stays the same. After the bot-away gem has been activated, all Rails-generated forms on your site
+* Your code stays the same. After the Bot-Away gem has been activated, all Rails-generated forms on your site
   will automatically be transformed into bot-resistent forms.
 * All of the form elements that you create (for instance, a "comment" model with a "body" field) are turned into
   dummy elements, or honeypots, and are made invisible to the end user. This is done using div elements and inline CSS
-  stylesheets. There are several ways an element can be hidden, and these approaches are chosen at random to help
-  minimize predictability. In the rare event that a real user actually can see the element, it has a label next to it
+  stylesheets (I decided against a JavaScript option because it's the most likely to be disabled on a legitimate
+  client). There are several ways an element can be hidden, and these approaches are chosen at random to help
+  minimize predictability.
+  
+  In the rare event that a real user actually can see the element, it has a label next to it
   along the lines of "Leave this blank" -- though the exact message is randomized to help prevent detection.
 * All of the form elements are mirrored by hashes. The hashes are generated using the session's authenticity token,
   so they can't be predicted.
-* When data is submitted, bot-away steps in and 1.) validates that no honeypots have been filled in; and 2)
-  converts the hashed elements back into the field names that you are expecting (replacing the honeypot fields).
+* When data is submitted, Bot-Away steps in and
+  1. validates that no honeypots have been filled in; and
+  2. converts the hashed elements back into the field names that you are expecting (replacing the honeypot fields). Your
+     code is never aware of the difference; it's just business as usual as long as the user is legitimate.
 * If a honeypot has been filled in, or a hashed element is missing where it was expected, then the request is
   considered to be either spam, or tampered with; and the entire params hash is emptied. Since this happens at the
   lowest level, the most likely result is that Rails will complain that the user's authenticity token is invalid. If
   that does not happen, then your code will be passed a params hash containing only a "suspected_bot" key, and an error
   will result. Either way, the spambot has been foiled!
 
-== FEATURES/PROBLEMS:
+== Installation:
+
+* gem install bot-away
+
+== Usage:
+
+Whether you're on Rails 2 or Rails 3, adding Bot-Away to your project is as easy as telling Rails where to find it.
+
+=== Rails 2.x
+
+In your Rails config/environment.rb:
+
+  config.gem 'bot-away'
+
+=== Rails 3
+
+In your Gemfile:
+
+  gem 'bot-away'
+
+That's it.
+
+== Whitelists
+
+Sometimes you don't care about whether or not a bot is filling out a particular form. Even more, sometimes it's
+preferable to make a form bot-friendly. I'm talking specifically about login forms, where all sorts of people
+use bots (their Web browsers, usually) in order to prefill the form with their login information. This is perfectly
+harmless, and even a malicious bot is not going to be able to cause any trouble on a form like this because it'll only
+be denied access to the site.
+
+In cases like this, you'll want to go ahead and disable Bot-Away. Since Bot-Away is only disabled on a per-controller
+or per-action basis, it stays active throughout the remainder of your site, which prevents bots from (for example)
+creating new users.
+
+To disable Bot-Away for an entire controller, add this line to a file called <em>config/initializers/bot-away.rb</em>:
+
+  BotAway.disabled_for :controller => 'sessions'
+  
+And here's how to do the same for a specific action, leaving Bot-Away active for all other actions:
+
+  BotAway.disabled_for :controller => 'sessions', :action => 'login'
+  
+You can also disable Bot-Away for a given action in every controller, but I'm not sure how useful that is. In any case,
+here's how to do it:
+
+  BotAway.disabled_for :action => 'index' # all we did was omit :controller
+  
+This line can be specified multiple times, for each of the controllers and/or actions that you need it disabled for.
+  
+== Disabling Bot-Away in Development
+
+If, while developing your app, you find yourself viewing the HTML source code, it'll probably be more helpful
+to have Bot-Away disabled entirely so that you're not confused by MD5 tags and legions of honeypots. This is easy enough
+to do:
+
+  BotAway.disabled_for :mode => :development
+
+  
+== Further Configuration (Mostly for Debugging):
+
+In general, Bot-Away doesn't have that much to configure. Most options only exist for your debugging pleasure, in
+case something isn't quite working as you'd expected. As shown above, these settings should be specified in a file
+called <em>config/initializers/bot-away.rb</em>. Configuration options available to you are as follows:
+
+=== Accepting Unfiltered Params
+
+Sometimes you need to tell Bot-Away to explicitly _not_ filter a parameter. This is most notable with fields you've
+dynamically added via JavaScript, since those can confuse Bot-Away's catching techniques. (It tends to think Javascript-
+generated fields are honeypots, and raises an error based on that.) Here's how to tell Bot-Away that such fields are
+not to be checked:
+
+  BotAway.accepts_unfiltered_params "name_of_param", "name_of_another_param"
+  
+Note that these parameters can be either model keys, field keys or exact matches. For example, imagine the following
+scenario: you have two models, User and Group, and each has_many :roles. That means you'll likely have an administration
+screen somewhere with check boxes representing user roles and group roles. Here are the different ways you can control
+how Bot-Away interacts with these fields:
+
+  BotAway.accepts_unfiltered_params "user"
+    # disables BotAway filtering for ALL fields belonging to 'user', but NO fields belonging to 'group'
+  
+  BotAway.accepts_unfiltered_params 'user[role_ids]', 'group[role_ids]'
+    # disables BotAway filtering for ONLY the 'role_ids' field belonging to BOTH 'user' and 'group', while leaving
+    # filtering enabled for ALL OTHER fields.
+    
+  BotAway.accepts_unfiltered_params 'role_ids'
+    # disables BotAway filtering for ONLY the 'role_ids' fields belonging to ALL MODELS, while leaving all
+    # other fields enabled.
+    
+You can specify this option as many times as you need to do.
+
+=== Showing the Honeypots
+
+Generally, you want to keep honeypots hidden, because they will clutter your interface and confuse your users. However,
+there was an issue awhile back (near the 1.0 release of Bot-Away) where Safari was a bit smarter than its competitors,
+successfully prefilling honeypots with data where Chrome, FF and IE all failed to do so. Eventually, I added the ability
+to show honeypots on the screen, proving my suspicion that Safari was being "too smart". After resolving the issue, I
+decided to leave this option available to Bot-Away as a debugging tool for handling future issues. To enable:
+    
+  BotAway.show_honeypots = true
+
+=== Dumping Params
+
+Like showing honeypots, above, this option is only useful if you're debugging issues in development
+mode. You can enable this if you need to see exactly what Rails sees _before_ Bot-Away steps in to intervene. Enabling
+this is a major security risk in production mode because it'll include sensitive data such as passwords; but it's very
+useful for debugging false positives (that is, Bot-Away thinks you're a bot, but you're not).
+
+  BotAway.dump_params = true
+  
+== Features / Problems:
 
 * Wherever protection from forgery is not enabled in your Rails app, the Rails forms will be generated as if this gem
   did not exist. That means hashed elements won't be generated, honeypots won't be generated, and posted forms will not
@@ -55,68 +168,12 @@ here's a brief run-down of what's going on:
     BotAway.accepts_unfiltered_params 'role_ids'
     BotAway.accepts_unfiltered_params 'user' # this can be called multiple times
   You should also take note that this is an array, not a hash. So if you have a user[role_ids] as well as a
-  group[role_ids], the +role_ids+ will not be matched on EITHER of these models.
+  group[role_ids], the +role_ids+ will not be filtered on EITHER of these models.
 
 * Currently, there's no direct support for per-request configuration of unfiltered params. This is mostly due to
   Bot-Away's low-level approach to filtering bots: the params have already been filtered by the time your controller
   is created. I'd like to revisit per-request filtering sometime in the future, once I figure out the best way to do it.
 
-== REQUIREMENTS:
+== Requirements:
 
 * Rails 2.3.5 or better.
-
-== INSTALL:
-
-* sudo gem install bot-away
-
-== USAGE:
-
-In your Rails config/environment.rb:
-
-* config.gem 'bot-away'
-
-That's it.
-
-== OPTIONAL CONFIGURATION:
-
-In general, there's not much to the configuration of Bot-Away. Most options are here for your debugging pleasure, in
-case something isn't quite working as you'd expected and Bot-Away seems to be a potential cause. To set a configuration
-option, you should do so from a Rails initializer -- just create a file with any name (ending with ".rb", of course)
-in your config/initializers directory, and it'll get run during server start-up. Configuration options available to you
-for Bot-Away are as follows:
-
-  BotAway.accepts_unfiltered_params "name_of_param", "name_of_another_param"
-    # Causes the specified parameter to NOT be filtered. If, for instance, "role_ids" is given, then parameters such as
-    #   user[role_ids], group[role_ids], etc. will not be processed by Bot-Away.
-  BotAway.show_honeypots = true
-    # Causes Bot-Away to NOT disguise honeypots with CSS or any other technique. This will cause honeypot elements to
-    # be displayed on your page. Not ideal for production, but helpful for debugging browser auto-fill issues.
-  BotAway.dump_params = true
-    # Probably a major security risk in a production application, but again useful in development for gaining insight
-    # into what, exactly, is being passed by the browser into Rails before Bot-Away does its thing. If you're getting
-    # false positives, this may prove helpful in figuring out why.
-
-== LICENSE:
-
-(The MIT License)
-
-Copyright (c) 2010 Colin MacKenzie IV
-
-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.

data/Rakefile

@@ -1,4 +1,60 @@
 require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = 'bot-away'
+    gem.summary = %Q{Unobtrusively detects form submissions made by spambots, and silently drops those submissions.}
+    gem.description = %Q{Unobtrusively detects form submissions made by spambots, and silently drops those submissions.}
+    gem.email = "sinisterchipmunk@gmail.com"
+    gem.homepage = "http://www.thoughtsincomputation.com"
+    gem.authors = ["Colin MacKenzie IV"]
+    gem.add_dependency "actionpack", ">= 2.3.5"
+    gem.add_dependency "sc-core-ext", ">= 1.1.1"
+    gem.add_development_dependency "jeweler", ">= 1.4.0"
+    gem.add_development_dependency "rspec", ">= 1.3.0"
+    gem.add_development_dependency "rspec-rails", ">= 1.3.2"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require File.join(File.dirname(__FILE__), "spec/rspec_version")
+
+if RSPEC_VERSION >= "2.0.0"
+  RSpec::Core::RakeTask.new(:spec) do |spec|
+    spec.pattern = 'spec/**/*_spec.rb'
+  end
+else # Rake task for 1.3.x
+  Spec::Rake::SpecTask.new(:spec) do |spec|
+    spec.libs << 'lib' << 'spec'
+    spec.spec_files = FileList['spec/**/*_spec.rb']
+  end
+  
+  Spec::Rake::SpecTask.new(:rcov) do |spec|
+    spec.libs << 'lib' << 'spec'
+    spec.pattern = 'spec/**/*_spec.rb'
+    spec.rcov = true
+  end
+end
+
+task :spec => :check_dependencies
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?("VERSION") ? File.read("VERSION") : ""
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "bot-away #{version}"
+  rdoc.rdoc_files.include("README*")
+  rdoc.rdoc_files.include("*")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+=begin
+require 'rubygems'
 gem 'hoe', '>= 2.1.0'
 require 'hoe'
 require 'fileutils'
@@ -43,3 +99,4 @@ end
 # TODO - want other tests/tasks run by default? Add them to the list
 # remove_task :default
 # task :default => [:spec, :features]
+=end

data/VERSION

@@ -0,0 +1 @@
+1.2.0

data/bot-away.gemspec

@@ -0,0 +1,96 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{bot-away}
+  s.version = "1.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Colin MacKenzie IV"]
+  s.date = %q{2010-10-14}
+  s.description = %q{Unobtrusively detects form submissions made by spambots, and silently drops those submissions.}
+  s.email = %q{sinisterchipmunk@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "History.txt",
+     "LICENSE",
+     "Manifest.txt",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "bot-away.gemspec",
+     "lib/bot-away.rb",
+     "lib/bot-away/action_dispatch/request.rb",
+     "lib/bot-away/action_view/helpers/instance_tag.rb",
+     "lib/bot-away/param_parser.rb",
+     "lib/bot-away/spinner.rb",
+     "script/console",
+     "script/destroy",
+     "script/generate",
+     "spec/controllers/test_controller_spec.rb",
+     "spec/rspec_version.rb",
+     "spec/spec_helper.rb",
+     "spec/support/honeypot_matcher.rb",
+     "spec/support/obfuscation_helper.rb",
+     "spec/support/obfuscation_matcher.rb",
+     "spec/support/rails/mock_logger.rb",
+     "spec/support/test_controller.rb",
+     "spec/support/views/test/index.html.erb",
+     "spec/support/views/test/model_form.html.erb",
+     "spec/views/lib/action_view/helpers/instance_tag_spec.rb",
+     "spec/views/lib/disabled_for_spec.rb",
+     "spec/views/lib/form_builder_spec.rb",
+     "spec/views/lib/param_parser_spec.rb"
+  ]
+  s.homepage = %q{http://www.thoughtsincomputation.com}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Unobtrusively detects form submissions made by spambots, and silently drops those submissions.}
+  s.test_files = [
+    "spec/controllers/test_controller_spec.rb",
+     "spec/rspec_version.rb",
+     "spec/spec_helper.rb",
+     "spec/support/honeypot_matcher.rb",
+     "spec/support/obfuscation_helper.rb",
+     "spec/support/obfuscation_matcher.rb",
+     "spec/support/rails/mock_logger.rb",
+     "spec/support/test_controller.rb",
+     "spec/views/lib/action_view/helpers/instance_tag_spec.rb",
+     "spec/views/lib/disabled_for_spec.rb",
+     "spec/views/lib/form_builder_spec.rb",
+     "spec/views/lib/param_parser_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<actionpack>, [">= 2.3.5"])
+      s.add_runtime_dependency(%q<sc-core-ext>, [">= 1.1.1"])
+      s.add_development_dependency(%q<jeweler>, [">= 1.4.0"])
+      s.add_development_dependency(%q<rspec>, [">= 1.3.0"])
+      s.add_development_dependency(%q<rspec-rails>, [">= 1.3.2"])
+    else
+      s.add_dependency(%q<actionpack>, [">= 2.3.5"])
+      s.add_dependency(%q<sc-core-ext>, [">= 1.1.1"])
+      s.add_dependency(%q<jeweler>, [">= 1.4.0"])
+      s.add_dependency(%q<rspec>, [">= 1.3.0"])
+      s.add_dependency(%q<rspec-rails>, [">= 1.3.2"])
+    end
+  else
+    s.add_dependency(%q<actionpack>, [">= 2.3.5"])
+    s.add_dependency(%q<sc-core-ext>, [">= 1.1.1"])
+    s.add_dependency(%q<jeweler>, [">= 1.4.0"])
+    s.add_dependency(%q<rspec>, [">= 1.3.0"])
+    s.add_dependency(%q<rspec-rails>, [">= 1.3.2"])
+  end
+end
+