buby 1.1.6-java

data/History.txt

@@ -0,0 +1,67 @@
+== 1.1.6 / 2009-11-19
+* fix
+  * poc_generator.rb example fixed to properly parse port in Host header
+  * fix evt_proxy_message bridge to deal correctly with binary content data
+
+== 1.1.5 / 2009-10-15
+* enhancements
+  * added support for exitSuite in burp v 1.2.17+
+  * added samples/poc_generator.rb
+
+== 1.1.4.1 / 2009-09-22
+* fix
+  * Buby.harvest_cookies_from_history() was broken. 
+    It now implements select() block semantics and always returns an array.
+    
+== 1.1.4 / 2009-09-14
+* enhancements
+  * buby got implants! (har har)
+  * Ruby wrapper classes added for proxy_history, site_map, and scan_issues
+  * Extensions module for IHttpRequestResponse burp's class implementation
+  * Extensions module for IScanIssue burp's class implementation
+  * Added -s/--state, -r/--require, -e/--extend to buby cmd-line executable
+  * Added -v/--version buby cmd-line flag
+  * Modified samples for use as modules with -r/-e as well as run standalone
+  * Added drb client and server sample
+
+== 1.1.3.1 / 2009-09-09
+* fix
+  * fixed a typo in the String type-check for Buby.getParameters()
+
+== 1.1.3 / 2009-08-25
+* 1 enhancement
+  * new convenience methods added for iterating and searching through
+    proxy history, scan history, etc.
+* 1 fix
+  * The gem now includes a buby.jar which should be usable with Java 1.5+
+    (previously the jar had been compiled only for Java 1.6)
+
+== 1.1.2 / 2009-08-20
+* 1 enhancement
+  * Support added for the new getScanIssues extender method exposed in v1.2.15
+    See http://releases.portswigger.net/2009/08/v1215.html
+
+== 1.1.1 / 2009-06-24
+* Fix
+  * fixed getSiteMap callback front-end so that it takes the urlprefix argument
+
+== 1.1.0 / 2009-06-18
+* 1 major enhancement
+  * Support added for the new Burp API features added in Burp 1.2.09.
+    See http://releases.portswigger.net/2009/05/v1209.html
+* 1 minor enhancement
+  * buby command-line tool exposes arguments for debugging and IRB
+
+== 1.0.2 / 2009-06-02
+* Enhancements
+  * Added a sample illustrating synching cookies with Mechanize
+
+== 1.0.1 / 2009-05-10
+* Enhancements
+  * Added some sugar to make swapping Burp event handlers easier.
+  * Fixed documentation errors
+
+== 1.0.0 / 2009-05-08
+
+* 1 major enhancement
+  * Birthday!

data/README.rdoc

@@ -0,0 +1,289 @@
+buby
+  by Eric Monti
+  http://emonti.github.com/buby
+
+== DESCRIPTION:
+
+Buby is a mashup of JRuby with the popular commercial web security testing tool Burp Suite from PortSwigger.  Burp is driven from and tied to JRuby with a Java extension using the BurpExtender API.  This extension aims to add Ruby scriptability to Burp Suite with an interface comparable to the Burp's pure Java extension interface.
+
+== FEATURES/PROBLEMS:
+
+* Intercept and log proxied requests and responses via Burp into Ruby and 
+  perform arbitrary processing on them.
+
+* Modify requests and responses in-line using Ruby scripts.
+
+* Pass requests and other information from JRuby to various sub-interfaces in 
+  Burp
+
+* Use the Burp framework for active and passive scanning using arbitrary
+  requests and responses.
+
+* Use the Burp framework for making arbitrary HTTP requests
+
+
+Buby is implemented using an abstract Ruby event handler and interface class. The Buby Ruby class is back-ended with a minimal BurpExtender class implemented in Java.  The java code is required to conform to nuances in the Burp extension interface and while it's in the pure Java runtime, it acts as 'glue' where deemed appropriate, but otherwise tries to stay out of the way.
+
+The java BurpExtender included with Buby is an implementation of IBurpExtender which is the interface API supplied by PortSwigger for writing extensions to Burp Suite. It mostly acts as a method proxy between Ruby and Java, doing very little except event handler proxying between the java and ruby runtimes with run-time type conversion as needed.
+
+
+== REQUIREMENTS:
+
+* JRuby - http://jruby.org
+  Burp is Java based and the extension is developed specifically around JRuby.
+  The C version of ruby will not work.
+
+* Burp (pro or free version): Buby is useless without a copy of Burp. 
+  Buby has been tested successfully with Burp 1.2.x.
+
+
+== BUILD/INSTALL:
+
+=== Gem
+You should be able to get up and running with just the gem and a copy of Burp. 
+I've packaged up a pre-built buby.jar file containing the required classes 
+minus ofcourse, Burp itself. 
+
+  jruby -S gem sources -a http://gems.github.com # only have to do this once
+  jruby -S gem install emonti-buby
+
+* IMPORTANT: The buby gem doesn't include a copy of Burp!  See manual step #5 
+  below. For best results, you'll still want to make your burp.jar available 
+  in the ruby runtime library path.
+
+
+=== Manual
+Here are manual instructions if you want or need to build things yourself:
+
+==== Step 1. Download buby from github
+  git clone git://github.com/emonti/buby.git
+
+==== Step 2. Compile BurpExtender.java. Include jruby.jar in the classpath:
+
+  cd buby/java/src
+  javac -classpath (.../jruby/root)/lib/jruby.jar:. BurpExtender.java
+
+==== Step 3. Create a new java/buby.jar
+
+  jar cvf ../buby.jar .
+
+==== Step 4. Build a local gem and install it
+
+  cd ../../
+  jruby -S gem build buby.gemspec
+  jruby -S gem install --local buby-*.gem
+
+==== Step 5. 
+
+The last part is a bit tricky. Burp Suite itself is obviously not included
+with buby. You'll want to somehow put your 'burp.jar' in a place where it 
+is visible in the JRuby RUBY-LIB paths. There are a few other ways of pulling 
+in Burp during runtime, but this method probably involves the least amount of 
+hassle in the long run.
+
+JRuby usually gives you a 'java' lib directory for this kind of thing.  Here's 
+a quick way to see jruby's runtime lib-path:
+    
+  jruby -e 'puts $:'
+
+There is usually a '.../jruby/lib/1.8/java' directory reference in there, 
+though the actual directory may need to be created.
+
+Here's how I do it. I have my jruby installation under my home directory.
+Your configuration details can be substituted below. 
+
+  mkdir ~/jruby-1.1.5/lib/ruby/1.8/java
+  ln -s ~/tools/burp.jar ~/jruby-1.1.5/lib/ruby/1.8/java/burp.jar
+
+Now everything should be ready to go. Try at least the first few parts of the 
+test below to confirm everything is set up. 
+
+== TEST AND USAGE EXAMPLE:
+
+The gem includes a command-line executable called 'buby'. You can use this to 
+test your Buby set-up and try out a few features.
+
+  $ buby -h
+  Usage: buby [options]
+      -i, --interactive          Start IRB
+      -d, --debug                Debug info
+      -B, --load-burp=PATH       Load Burp Jar from PATH
+      -s, --state=FILE           Restore burp state file on startup
+      -r, --require=LIB          load a ruby lib (or jar) after Burp loads
+      -e, --extend=MOD           Extend Buby with a module (loaded via -r?)
+      -h, --help                 Show this help message
+
+  $ buby -i -d
+  [:got_extender, #<Java::Default::BurpExtender:0x80 ...>]
+  Global $burp is set to #<Buby:0x78de07 @burp_callbacks=#<#<Class:...>
+  [:got_callbacks, #<#<Class:01x38ba04>:0x90 ...>]
+  irb(main):001:0> 
+
+
+Once Burp is running, click on the alerts tab.
+
+You should see now something like the following in alerts:
+
+  2:46:01 PM  suite   method BurpExtender.processProxyMessage() found
+  2:46:01 PM  suite   method BurpExtender.registerExtenderCallbacks() found
+  2:46:01 PM  suite   method BurpExtender.setCommandLineArgs() found
+  2:46:01 PM  suite   method BurpExtender.applicationClosing() found
+  2:46:01 PM  proxy   proxy service started on port 8080
+  2:46:01 PM  suite   [BurpExtender] registering JRuby handler callbacks
+  2:46:01 PM  suite   [JRuby::Buby] registered callback
+
+Here are some simple test examples using Buby through the IRB shell:
+
+To confirm you are connected back to Burp in IRB, you can try writing to the
+alerts panel with something like the following:
+
+  $burp.alert("hello Burp!")
+
+Which should produce a new alert:
+
+  2:47:00 PM  suite   hello Burp!
+
+
+Next, try making an HTTP request through the proxy. We'll use Net:HTTP right 
+in IRB for illustration purposes. However, you can just as easily perform this 
+test through a browser configured to use Burp as its proxy.  
+
+  require 'net/http'
+  p = Net::HTTP::Proxy("localhost", 8080).start("www.example.com")
+  p.get("/")
+
+
+With $DEBUG = true, you should see the debugging output from Ruby as the proxy
+passes your request back to your HTTP client/browser.
+
+It will look something like the following in IRB:
+
+  >> p.get("/")   
+  [:got_proxy_request,
+   [:msg_ref, 1],
+   [:is_req, true],
+   [:rhost, "www.example.com"],
+   [:rport, 80],
+   [:is_https, false],
+   [:http_meth, "GET"],
+   [:url, "/"],
+   [:resourceType, nil],
+   [:status, nil],
+   [:req_content_type, nil],
+   [:message, "GET / HTTP/1.1\r\nAccept:..."],
+   [:action, 0]]
+
+You may also see the response right away depending on your intercept settings 
+in Burp. Back the in Burp proxy's intercept window, turn off interception if 
+it hasn't already been disabled. Now you should definitely see the response 
+in IRB as it passes back through the Burp proxy.
+
+  [:got_proxy_response,
+   [:msg_ref, 1],
+   [:is_req, false],
+   [:rhost, "www.example.com"],
+   [:rport, 80],
+   [:is_https, false],
+   [:http_meth, "GET"],
+   [:url, "/"],
+   [:resourceType, nil],
+   [:status, "200"],
+   [:req_content_type, "text/html; charset=utf-8"],
+   [:message, "HTTP/1.1 200 OK\r\n..."],
+   [:action, 0]]
+  => #<Net::HTTPOK 200 OK readbody=true>
+  >>
+
+Note also, the Net::HTTP request should have returned the same result as shown in the proxy.
+
+Now, lets try something mildly interesting with the proxy. This contrived example will implement a proxy request manipulator to do HTTP request verb tampering on every GET request that goes through the proxy. 
+
+  # Note: I'm using 'instance_eval' here only to stay with the flow of the 
+  # existing IRB session. Normally, you'd probably want to implement this as 
+  # an override in your Buby-derived class.
+
+  $burp.instance_eval do
+
+    def evt_proxy_message(*param)
+      msg_ref, is_req, rhost, rport, is_https, http_meth, url, resourceType, 
+      status, req_content_type, message, action = param
+
+      if is_req and http_meth=="GET"
+        # Change the HTTP request verb to something silly
+        message[0,3] = "PET"
+
+        # Forcibly disable interception in the Burp UI
+        action[0] = Buby::ACTION_DONT_INTERCEPT
+
+        # Return a new instance and still get $DEBUG info
+        return super(*param).dup
+      else
+        # Just get $DEBUG info for all other requests
+        return super(*param)
+      end
+    end
+
+  end
+
+  # Now, make another request using the Net::HTTP client
+  p.get("/")
+
+
+This should produce a request that looks like the following in IRB:
+
+  [:got_proxy_request,
+   ...
+   [:message,
+    "PET / HTTP/1.1\r\nAccept: */*\r\nUser-Agent: Ruby..."],
+    [:action, 2]]
+
+And, assuming 'www.example.com' checks for valid request verbs, you should see something like the following response:
+
+  [:got_proxy_response,
+   ...
+   [:http_meth, "PET"],
+   [:url, "/"],
+   [:resourceType, nil],
+   [:status, "400"],
+   ...
+   [:message,
+    "HTTP/1.1 400 Bad Request\r\nContent-Type:..."],
+   [:action, 0]]
+  => #<Net::HTTPBadRequest 400 Bad Request readbody=true>
+
+
+== CREDIT:
+* Burp and Burp Suite are trademarks of PortSwigger(ltd) 
+  Copyright 2008 PortSwigger Ltd. All rights reserved.
+  See http://portswigger.net for license terms.
+
+* This ruby library and the accompanying BurpExtender.java implementation are 
+  written by Eric Monti @ Matasano Security. Matasano Security claims no 
+  professional or legal affiliation with PortSwigger LTD.
+
+  However, the author would like to express his personal and professional 
+  respect and admiration to Burp's authors and appreciation to PortSwigger for 
+  the availability of the IBurpExtender extension API.
+
+  The availability of this interface goes a long way to helping make Burp Suite 
+  a truly first-class application.
+
+== LICENSE:
+
+* Burp and Burp Suite are trademarks of PortSwigger Ltd.
+  Copyright 2008 PortSwigger Ltd. All rights reserved.
+  See http://portswigger.net for license terms.
+
+* The Buby Ruby library and its accompanying BurpExtender implementation are
+  both freely available under the terms of the MIT public license:
+
+(The MIT License)
+
+Copyright (C) 2009 Eric Monti, Matasano Security
+
+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

@@ -0,0 +1,34 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+ensure_in_path 'java'
+require 'buby'
+
+task :default => 'spec:run'
+
+PROJ.name = 'buby'
+PROJ.authors = 'Eric Monti - Matasano Security'
+PROJ.email = 'emonti@matasano.com'
+PROJ.url = 'http://emonti.github.com/buby'
+PROJ.version = Buby::VERSION
+PROJ.rubyforge.name = 'buby'
+PROJ.readme_file = 'README.rdoc'
+PROJ.libs << "java"
+PROJ.platform = 'java'
+
+PROJ.spec.opts << '--color'
+
+# EOF

data/bin/buby

@@ -0,0 +1,108 @@
+#!/usr/bin/env jruby
+
+require File.expand_path(File.join(File.dirname(__FILE__), %w[.. lib buby]))
+require 'irb'
+require 'optparse'
+
+args = {}
+
+begin
+  opts = OptionParser.new do |o|
+    o.banner = "Usage: #{File.basename $0} [options]"
+
+    o.on_tail("-h", "--help", "Show this help message") do
+      raise opts.to_s
+    end
+
+    o.on("-i", "--interactive", "Start IRB") { args[:irb] = true }
+
+    o.on("-d", "--debug", "Debug info") { args[:debug] = true }
+
+    o.on("-B", "--load-burp=PATH", "Load Burp Jar from PATH") do |b|
+      args[:load_burp] = b
+    end
+
+    o.on('-s', '--state=FILE', "Restore burp state file on startup") do |r|
+      args[:restore] = r
+    end
+
+    o.on('-r', '--require=LIB', 
+         'load a ruby lib (or jar) after Burp loads') do |i|
+      (args[:requires] ||= []).push(i)
+    end
+
+    o.on('-e', '--extend=MOD', 
+         'Extend Buby with a module (loaded via -r?)') do |m|
+      (args[:extensions] ||= []).push(m)
+    end
+
+    o.on('-v', '--version', 'Prints version and exits.') do 
+      puts "#{File.basename $0} v#{Buby::VERSION}"
+      exit 0
+    end
+  end
+
+  opts.parse!(ARGV)
+
+  if jar=args[:load_burp]
+    raise "Load Burp Error: #{jar} did not provide burp.StartBurp" unless Buby.load_burp(jar)
+  end
+
+  raise "Load Burp Error: Specify a path to your burp.jar with -B" unless Buby.burp_loaded?
+
+rescue
+  STDERR.puts $!
+  exit 1
+end
+
+$DEBUG=true if args[:debug]
+
+$burp = Buby.start_burp()
+
+if libs=args[:requires]
+  libs.each {|lib| STDERR.puts "Loading: #{lib.inspect}"; require(lib)}
+end
+
+def resolve_const(str)
+  raise "can't resolve empty name #{str.inspect}" if str.empty?
+  names = str.split('::')
+  obj = ::Object
+  names.each do |name|
+    raise "#{name.inspect} is not defined" unless obj.const_defined?(name)
+    obj = obj.const_get(name)
+  end
+  return obj if obj != ::Object
+end
+
+if mods=args[:extensions]
+  mods.each do |mod|
+    obj = resolve_const(mod)
+    raise "#{obj.name} is not a module" unless obj.kind_of? Module
+    STDERR.puts "Extending $burp with: #{obj.name}"
+    $burp.extend(obj)
+    if $burp.respond_to?(imeth=:"init_#{mod.split('::').last}")
+      $burp.__send__ imeth
+    end
+  end
+end
+
+if f=args[:restore]
+  raise "no such file #{f.inspect}" unless File.exists?(f)
+  STDERR.puts "Restoring burp state from: #{f.inspect}"
+  $burp.restore_state(f)
+end
+
+if args[:irb]
+  # yucky hack...
+  IRB.setup(nil)
+  IRB.conf[:IRB_NAME] = File.basename($0, ".rb")
+  module IRB
+    class <<self
+      def setup(*args); end
+    end
+  end
+  puts "Global $burp is set to #{$burp.inspect}",
+       " Important Note: exit with $burp.close"
+  IRB.start()
+end
+