httpbl 0.1.3

data/CHANGELOG

@@ -0,0 +1 @@
+v0.1.3. First public test release, not ready for production

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009 Brandon Palmen
+
+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/Manifest

@@ -0,0 +1,7 @@
+README
+lib/httpbl.rb
+Rakefile
+httpbl.gemspec
+CHANGELOG
+LICENSE
+Manifest

data/README

@@ -0,0 +1,147 @@
+HttpBL
+===========
+
+HttpBL is drop-in IP-filtering middleware for Rails 2.3+ and other Rack-based 
+applications. It resolves information about each request's source IP address 
+from the Http:BL service at http://projecthoneypot.org, and denies access to
+clients whose IP addresses are associated with suspicious behavior like impolite
+crawling, comment-spamming, dictionary attacks, and email-harvesting.
+
+	*	Deny access to IP addresses that are associated with suspicious 
+		behavior which exceeds a customizable threshold.
+	*	Expire blocked IPs that have not been associated with suspicious
+		behavior after a customizable period of days.
+	* 	Identify common search engines by IP address (not User-Agent), and
+		disallow access to a specific subset.
+
+Installation
+------------
+
+	gem install bpalmen-httpbl
+	
+Basic Usage
+------------
+
+HttpBL is Rack middleware, and can be used with any Rack-based application. First,
+you must obtain an API key for the Http:BL service at http://projecthoneypot.org
+
+To add HttpBL to your middleware stack, simply add the following to config.ru:
+
+	require 'httpbl'
+	
+	use HttpBL, :api_key => "YOUR API KEY"
+	
+For Rails 2.3+ add the following to environment.rb:
+	
+	require 'httpbl'
+	
+	config.middleware.use HttpBL, :api_key => "YOUR API KEY"
+	
+Advanced Usage
+-------------
+
+To insert HttpBL at the top of the Rails rackstack:
+	(use 'rake middleware' to confirm that Rack::Lock is at the top of the stack)
+	
+	config.middleware.insert_before(Rack::Lock, HttpBL, :api_key => "YOUR API KEY")
+	
+To customize HttpBL's filtering behavior, use the available options:
+
+	use HttpBL, :api_key => "YOUR API KEY",
+				:deny_types => [1, 2, 4],
+				:threat_level_threshold => 0,
+				:age_threshold => 5,
+				:blocked_search_engines => [0],
+
+Available Options:
+
+The following options (shown with default values) are available to 
+customize the particular types of suspicious activity you wish to thwart:
+
+	:deny_types => [1, 2, 4, 8, 16, 32, 64, 128]
+		
+		Project Honeypot classifies suspicious behavior as belonging to
+		certain types, which are identified in the API's response to
+		each IP lookup. You can tell HttpBL to only deny certain kinds
+		of behavior by changing this to a subset of those possible.
+		
+		As of March 2009, only types 1, 2, and 4 have been specified,
+		but additional types are reserved for the future and HttpBL checks
+		against all of the anticipated type codes by default.  Thus, 
+		there may be a very small performance advantage to setting
+		:deny_types => [1, 2, 4] simply to exclude checks for codes 
+		that aren't (yet) being used; however, this will have to be 
+		updated if more codes come into use, whereas the default 
+		requires no further attention.
+		
+		The current types are:
+			1: Suspicious
+			2: Harvester
+			4: Comment Spammer
+			
+	:threat_level_threshold => 2
+	
+		The threat level reported by Project Honeypot is based on a 
+		logarithmic scale, approximated by:
+			1: 1 spam
+			25: 100 spam
+			50: 10,000 spam
+			100: 1,000,000 spam.
+		in which spam is pronounced spam even in the plural.
+		
+		Choosing a threat level threshold can be tricky business if
+		one isn't sure how accurate the measure of threat is, since it 
+		would be improper to block legitimate traffic by mistake. Because
+		the email addresses that Project Honeypot uses as spam-bait are unique,
+		artificial, and well-hidden, NO email should be sent to those addresses
+		at all, and it is fair to assume that even the low threat level 
+		associated with just a few spam is still significant.
+		
+		With that in mind, the default threshold is 2; if you want to
+		filter more aggressively, set :threat_level_threshold => 0
+		
+	:age_threshold => 10
+		
+		This sets the number of days that IP addresses that have been
+		associated with suspicous activity must wait to regain access after
+		the suspicious activity has ceased. Keeping this at a sane value will
+		allow IPs that are reassigned or cleaned up to expire from the blacklist.
+		
+		If you want to be more aggressive (require a longer cool-off-period),
+		set :age_threshold => 30; if you want to let IPs back in after just a
+		few days, set :age_threshold => 5
+		
+	:blocked_search_engines => []
+	
+		Because Project Honeypot identifies search engine traffic by IP
+		address, this filter may be used to exclude certain robots from your
+		site. If one presumes that request-IPs are at least marginally more
+		difficult to spoof than User-Agent strings, this filter may be marginally
+		more effective than some other robot detection systems.
+		
+		If there are particular search engines that you would like to exclude
+		from your site, set :blocked_search_engines => [0, ... ] where the codes
+		defined by http://projecthoneypot.org/httpbl_api are:
+		
+			0: Misc
+			1: AltaVista	
+			2: Ask
+			3: Baidu
+			4: Excite
+			5: Google
+			6: Looksmart
+			7: Lycos
+			8: MSN
+			9: Yahoo
+			10: Cuil
+			11: InfoSeek
+	
+	:dns_timeout => 0.5
+	
+		DNS requests to the Http:BL service should NEVER take this long, but if
+		they do, you can modify this setting to prevent the application from 
+		hanging until a system default timeout.  Of course, setting this timeout 
+		too low will essentially disable the filter (but 0 is a bad idea), if responses
+		can't be returned from the API before the request is permitted, by default.  
+		Best not to mess with it unless you know what you're doing - it's a safety 
+		mechanism. 

data/Rakefile

@@ -0,0 +1,7 @@
+require 'echoe'
+Echoe.new('httpbl') do |p|
+  p.author = "Brandon Palmen"
+  p.summary = "A Rack middleware IP filter that uses Http:BL to exclude suspicious robots."
+  p.url = "http://github.com/bpalmen/httpbl"
+  p.runtime_dependencies = ["rack"]
+end

data/httpbl.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{httpbl}
+  s.version = "0.1.3"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brandon Palmen"]
+  s.date = %q{2009-03-22}
+  s.description = %q{A Rack middleware IP filter that uses Http:BL to exclude suspicious robots.}
+  s.email = %q{}
+  s.extra_rdoc_files = ["README", "lib/httpbl.rb", "CHANGELOG", "LICENSE"]
+  s.files = ["README", "lib/httpbl.rb", "Rakefile", "httpbl.gemspec", "CHANGELOG", "LICENSE", "Manifest"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/bpalmen/httpbl}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Httpbl", "--main", "README"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{httpbl}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{A Rack middleware IP filter that uses Http:BL to exclude suspicious robots.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rack>, [">= 0"])
+    else
+      s.add_dependency(%q<rack>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rack>, [">= 0"])
+  end
+end

data/lib/httpbl.rb

@@ -0,0 +1,59 @@
+# The Httpbl middleware 
+
+class HttpBL
+  autoload :Resolv, 'resolv'
+  
+  def initialize(app, options = {})
+    @app = app
+    @options = {:blocked_search_engines => [],
+                :age_threshold => 10,
+                :threat_level_threshold => 2,
+                # 8..128 aren't used as of 3/2009, but might be used in the future
+                :deny_types => [1, 2, 4, 8, 16, 32, 64, 128],
+                # DONT set this to 0
+                :dns_timeout => 0.5
+                }.merge(options)
+    raise "Missing :api_key for Http:BL middleware" unless @options[:api_key]
+  end
+  
+  def call(env)
+    dup._call(env)
+  end
+  
+  def _call(env)
+    request = Rack::Request.new(env)
+    bl_status = resolve(request.ip)
+    if bl_status and blocked?(bl_status)
+      [403, {"Content-Type" => "text/html"}, "<h1>403 Forbidden</h1> Request IP is listed as suspicious by <a href='http://projecthoneypot.org/ip_#{request.ip}'>Project Honeypot</a>"]
+    else
+      @app.call(env)
+    end
+    
+  end
+  
+  def resolve(ip)
+    query = @options[:api_key] + '.' + ip.split('.').reverse.join('.') + '.dnsbl.httpbl.org'
+    Timeout::timeout(@options[:dns_timeout]) do
+       Resolv::DNS.new.getaddress(query).to_s rescue nil
+    end
+    rescue Timeout::Error, Errno::ECONNREFUSED
+  end
+  
+  def blocked?(response)
+    response = response.split('.').collect!(&:to_i)
+    if response[0] == 127 
+      if response[3] == 0
+        @blocked = true if @options[:blocked_search_engines].include? response[2]
+      else 
+        @age = true if response[1] < @options[:age_threshold]
+        @threat = true if response[2] > @options[:threat_level_threshold]
+        @options[:deny_types].each do |key|
+          @deny = true if response[3] & key == key  
+        end
+        @blocked = true if @deny and @threat and @age
+      end
+    end
+    return @blocked
+  end
+
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: httpbl
+version: !ruby/object:Gem::Version 
+  version: 0.1.3
+platform: ruby
+authors: 
+- Brandon Palmen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-22 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rack
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A Rack middleware IP filter that uses Http:BL to exclude suspicious robots.
+email: ""
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- lib/httpbl.rb
+- CHANGELOG
+- LICENSE
+files: 
+- README
+- lib/httpbl.rb
+- Rakefile
+- httpbl.gemspec
+- CHANGELOG
+- LICENSE
+- Manifest
+has_rdoc: true
+homepage: http://github.com/bpalmen/httpbl
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Httpbl
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: httpbl
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: A Rack middleware IP filter that uses Http:BL to exclude suspicious robots.
+test_files: []
+