emonti-buby 1.0.1 → 1.1.0.0

data/History.txt

@@ -1,3 +1,14 @@
+== 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.

data/README.rdoc

@@ -45,39 +45,36 @@ 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. 
 
-  gem install emonti-buby
+  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.
+  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
+==== 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:
+==== 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 lib/buby.jar
+==== Step 3. Create a new java/buby.jar
 
   jar cvf ../buby.jar .
 
-Note: At this point you can also just do a rake gem:install from the 
-top-level, which will install a local 'buby' gem instead of 'emonti-buby'. If
-you do this, just skip the next step and move onto step #5.
-
-Step 4. Copy buby.rb and jar to your JRuby lib-path. Locations may vary:
+==== Step 4. Build a local gem and install it
 
   cd ../../
-  cp lib/buby.rb (.../jruby)/lib/site_ruby/1.8/
-  cp -p java/buby.jar (.../jruby)/lib/site_ruby/1.8/java/buby.jar
+  jruby -S gem build buby.gemspec
+  jruby -S gem install --local buby-*.gem
 
-Step 5. 
+==== 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 
@@ -85,15 +82,15 @@ 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 gives you a 'java' site_ruby directory for this kind of thing.  Here's a 
-quick way to see jruby's runtime lib-path:
+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 jruby installation under my home directory.
+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
@@ -107,25 +104,26 @@ run 'buby' from the command-line.
 == TEST AND USAGE EXAMPLE:
 
 The gem includes a command-line tool called 'buby' but it doesn't do much right
-now. You can, however use this as a minimal test to confirm whether Burp can be 
-launched from ruby and whether Buby and Burp are connected.
+now. You can, however, use this as a minimal test to confirm whether Burp can 
+be launched from ruby and that Buby and Burp are connected.
 
-Here are some really simple test examples using Buby through IRB:
+Launch buby for simple testing and debugging with the 'buby' command-line tool:
 
-  $ jruby -S irb
+  $ buby -h
+  Usage: buby [options]
+      -i, --interactive                Start IRB
+      -d, --debug                      Debug info
+      -B, --load-burp=PATH             Load Burp Jar from PATH
+      -h, --help                       Show this help message
 
-  require 'buby'
-  $DEBUG = true
+  $ 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> 
 
-  # Here's one way to explicitely add burp.jar into the runtime if its not
-  # already.
-  Buby.load_burp("/path/to/burp.jar") if not Buby.burp_loaded?
-  buby = Buby.start_burp()
 
-At this point, you should see Burp starting and with the $DEBUG flag, you'll 
-also see several debug messages in IRB coming from Buby as various events are 
-generated by the BurpExtender java implementation. Once Burp is running, click 
-on the alerts tab.
+Once Burp is running, click on the alerts tab.
 
 You should see now something like the following in alerts:
 
@@ -137,16 +135,19 @@ You should see now something like the following in alerts:
   2:46:01 PM  suite   [BurpExtender] registering JRuby handler callbacks
   2:46:01 PM  suite   [JRuby::Buby] registered callback
 
-To confirm you are connected back to Burp in IRB, do the following:
+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:
 
-  buby.alert("hello Burp!")
+  $buby.alert("hello Burp!")
 
 Which should produce a new alert:
 
   2:47:00 PM  suite   hello Burp!
 
 
-Next, lets make an HTTP request through the proxy. We'll use Net:HTTP right 
+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.  
 
@@ -204,7 +205,7 @@ Now, lets try something mildly interesting with the proxy. This contrived exampl
   # existing IRB session. Normally, you'd probably want to implement this as 
   # an override in your Buby-derived class.
 
-  buby.instance_eval do
+  $buby.instance_eval do
 
     def evt_proxy_message(*param)
       msg_ref, is_req, rhost, rport, is_https, http_meth, url, resourceType, 

data/bin/buby

@@ -2,15 +2,43 @@
 
 require File.expand_path(File.join(File.dirname(__FILE__), %w[.. lib buby]))
 require 'irb'
+require 'optparse'
 
-unless Buby.burp_loaded?
-  begin
-    raise "You must specify the path to your burp.jar" unless jar=ARGV.shift
-    raise "#{jar} did not provide burp.StartBurp" unless Buby.load_burp(jar)
-  rescue
-    STDERR.puts "Error: #{$!}"
-    exit 1
+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
+  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()
-IRB.start if $DEBUG
+
+if args[:irb]
+  puts "Global $burp is set to #{$burp.inspect}"
+  IRB.start 
+end

data/buby.gemspec

@@ -2,36 +2,36 @@
 
 Gem::Specification.new do |s|
   s.name = %q{buby}
-  s.version = "1.0.1"
+  s.version = "1.1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Eric Monti - Matasano Security"]
-  s.date = %q{2009-05-10}
+  s.date = %q{2009-06-21}
   s.default_executable = %q{buby}
   s.description = %q{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.}
   s.email = %q{emonti@matasano.com}
   s.executables = ["buby"]
   s.extra_rdoc_files = ["History.txt", "README.rdoc", "bin/buby"]
-  s.files = ["History.txt", "README.rdoc", "Rakefile", "bin/buby", "buby.gemspec", "java/buby.jar", "java/src/BurpExtender.java", "java/src/burp/IBurpExtender.java", "java/src/burp/IBurpExtenderCallbacks.java", "lib/buby.rb", "samples/basic.rb", "spec/buby_spec.rb", "spec/spec_helper.rb", "tasks/ann.rake", "tasks/bones.rake", "tasks/gem.rake", "tasks/git.rake", "tasks/notes.rake", "tasks/post_load.rake", "tasks/rdoc.rake", "tasks/rubyforge.rake", "tasks/setup.rb", "tasks/spec.rake", "tasks/svn.rake", "tasks/test.rake", "tasks/zentest.rake", "test/test_buby.rb"]
-  s.has_rdoc = true
+  s.files = ["History.txt", "README.rdoc", "Rakefile", "bin/buby", "buby.gemspec", "java/buby.jar", "java/src/BurpExtender.java", "java/src/burp/IBurpExtender.java", "java/src/burp/IBurpExtenderCallbacks.java", "java/src/burp/IHttpRequestResponse.java", "java/src/burp/IScanIssue.java", "java/src/burp/IScanQueueItem.java", "lib/buby.rb", "samples/mechanize_burp.rb", "samples/verb_tamperer.rb", "spec/buby_spec.rb", "spec/spec_helper.rb", "tasks/ann.rake", "tasks/bones.rake", "tasks/gem.rake", "tasks/git.rake", "tasks/notes.rake", "tasks/post_load.rake", "tasks/rdoc.rake", "tasks/rubyforge.rake", "tasks/setup.rb", "tasks/spec.rake", "tasks/svn.rake", "tasks/test.rake", "tasks/zentest.rake", "test/test_buby.rb"]
   s.homepage = %q{http://github.com/emonti/buby}
   s.rdoc_options = ["--main", "README.rdoc"]
   s.require_paths = ["lib", "java"]
   s.rubyforge_project = %q{buby}
-  s.rubygems_version = %q{1.3.1}
+  s.rubygems_version = %q{1.3.3}
   s.summary = %q{Buby is a mashup of JRuby with the popular commercial web security testing tool Burp Suite from PortSwigger}
   s.test_files = ["test/test_buby.rb"]
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 2
+    s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<bones>, [">= 2.5.0"])
+      s.add_development_dependency(%q<bones>, [">= 2.5.1"])
     else
-      s.add_dependency(%q<bones>, [">= 2.5.0"])
+      s.add_dependency(%q<bones>, [">= 2.5.1"])
     end
   else
-    s.add_dependency(%q<bones>, [">= 2.5.0"])
+    s.add_dependency(%q<bones>, [">= 2.5.1"])
   end
 end
+

data/java/src/BurpExtender.java

@@ -2,6 +2,8 @@
 
 import burp.IBurpExtender;
 import burp.IBurpExtenderCallbacks;
+import burp.IScanIssue;
+import burp.IHttpRequestResponse;
 
 import org.jruby.*;
 import org.jruby.javasupport.JavaUtil;
@@ -16,11 +18,13 @@ import org.jruby.runtime.builtin.IRubyObject;
  * as of Burp Suite 1.2/1.2.05
  */
 public class BurpExtender implements IBurpExtender { 
-    public final static String INIT_METH =     "evt_extender_init";
-    public final static String PROXY_METH =    "evt_proxy_message";
-    public final static String MAINARGS_METH = "evt_commandline_args";
-    public final static String REG_METH =      "evt_register_callbacks";
-    public final static String CLOSE_METH =    "evt_application_closing";
+    public final static String INIT_METH =      "evt_extender_init";
+    public final static String PROXYMSG_METH =  "evt_proxy_message";
+    public final static String HTTPMSG_METH =   "evt_http_message";
+    public final static String SCANISSUE_METH = "evt_scan_issue";
+    public final static String MAINARGS_METH =  "evt_commandline_args";
+    public final static String REG_METH =       "evt_register_callbacks";
+    public final static String CLOSE_METH =     "evt_application_closing";
 
     // Internal reference to hold the ruby Burp handler
     private static IRubyObject r_obj = null;
@@ -108,7 +112,7 @@ public class BurpExtender implements IBurpExtender {
      * response is received. 
      *
      * This implementation simply passes all arguments to the Ruby handler's 
-     * method defined by <code>PROXY_METH</code> if both the handler and
+     * method defined by <code>PROXYMSG_METH</code> if both the handler and
      * its ruby method are defined.
      *
      * This allows Ruby implementations to perform logging functions, modify 
@@ -153,10 +157,10 @@ public class BurpExtender implements IBurpExtender {
         String statusCode, 
         String responseContentType, 
         byte[] message, 
-        int[] action
-     ) {
+        int[] action ) 
+    {
 
-      if (r_obj != null && r_obj.respondsTo(PROXY_METH)) {
+      if (r_obj != null && r_obj.respondsTo(PROXYMSG_METH)) {
         Ruby rt = rt(r_obj);
         // prepare an alternate action value to present to ruby
         IRubyObject r_action = to_ruby(rt, action);
@@ -182,7 +186,7 @@ public class BurpExtender implements IBurpExtender {
         // slurp back in the action value in-case it's been changed
         action[0] = ((int[]) JavaUtil.convertRubyToJava(r_action))[0];
 
-        IRubyObject ret = r_obj.callMethod(ctx(r_obj), PROXY_METH, pxy_msg);
+        IRubyObject ret = r_obj.callMethod(ctx(r_obj), PROXYMSG_METH, pxy_msg);
         if(ret != r_msg)
           return ((RubyString) ret).getBytes();
       }
@@ -190,6 +194,46 @@ public class BurpExtender implements IBurpExtender {
       return message;
     }
 
+    /** 
+     * Added in Burp 1.2.09 
+     * No javadoc yet but here's what the PortSwigger dev blog has to say:
+     *
+     * The processHttpMessage method is invoked whenever any of Burp's tools 
+     * makes an HTTP request or receives a response. This is effectively a 
+     * generalised version of the existing processProxyMessage method, and 
+     * can be used to intercept and modify the HTTP traffic of all Burp 
+     * tools.
+     */
+    public void processHttpMessage(
+        String toolName, 
+        boolean messageIsRequest, 
+        IHttpRequestResponse messageInfo ) 
+    {
+      if (r_obj != null && r_obj.respondsTo(HTTPMSG_METH)) {
+        Ruby rt = rt(r_obj);
+        IRubyObject http_msg[] = {
+          to_ruby(rt, toolName),
+          to_ruby(rt, messageIsRequest),
+          to_ruby(rt, messageInfo)
+        };
+
+        r_obj.callMethod(ctx(r_obj), HTTPMSG_METH, http_msg);
+      }
+    }
+
+    /** 
+     * Added in Burp 1.2.09 
+     *
+     * The newScanIssue method is invoked whenever Burp Scanner discovers a 
+     * new, unique issue, and can be used to perform customised reporting or 
+     * logging of issues.
+     */
+    public void newScanIssue(IScanIssue issue) {
+      if (r_obj != null && r_obj.respondsTo(SCANISSUE_METH))
+        r_obj.callMethod(ctx(r_obj), SCANISSUE_METH, to_ruby(rt(r_obj), issue));
+    }
+
+
     /**
      * This method is invoked immediately before Burp Suite exits. 
      * This implementation simply invokes the Ruby handler's method defined
@@ -223,25 +267,27 @@ public class BurpExtender implements IBurpExtender {
       return JavaUtil.convertJavaToUsableRubyObject(rt, obj);
     }
 
-
     /** 
      * Causes Burp Proxy to follow the current interception rules to determine
      * the appropriate action to take for the message.
      */
     public final static int ACTION_FOLLOW_RULES = 0;
+
     /** 
      * Causes Burp Proxy to present the message to the user for manual
      * review or modification.
      */
     public final static int ACTION_DO_INTERCEPT = 1;
+
     /** 
      * Causes Burp Proxy to forward the message to the remote server or client.
      */
     public final static int ACTION_DONT_INTERCEPT = 2;
+
     /** 
      * Causes Burp Proxy to drop the message and close the client connection.
      */
     public final static int ACTION_DROP = 3;    
 
-} 
+}
 

data/java/src/burp/IBurpExtenderCallbacks.java

@@ -154,4 +154,41 @@ public interface IBurpExtenderCallbacks
      * @param message The alert message to display.
      */
     public void issueAlert(String message);
+
+    /**
+     * The existing IBurpExtenderCallbacks interface adds several new methods 
+     * which you can invoke to query and update Burp's state, and to parse raw 
+     * HTTP messages for parameters and headers.
+     */
+
+    /**
+     * no javadoc yet from PortSwigger
+     */
+    public IHttpRequestResponse[] getProxyHistory();
+
+    /**
+     * no javadoc yet from PortSwigger
+     */
+    public IHttpRequestResponse[] getSiteMap(String urlPrefix);
+
+    /**
+     * no javadoc yet from PortSwigger
+     */
+    public void restoreState(java.io.File file) throws Exception;
+
+    /**
+     * no javadoc yet from PortSwigger
+     */
+    public void saveState(java.io.File file) throws Exception;
+
+    /**
+     * no javadoc yet from PortSwigger
+     */
+    public String[][] getParameters(byte[] request) throws Exception;
+
+    /**
+     * no javadoc yet from PortSwigger
+     */
+    public String[] getHeaders(byte[] message) throws Exception;
+
 }

data/java/src/burp/IHttpRequestResponse.java

@@ -0,0 +1,32 @@
+package burp;
+
+import java.net.URL;
+
+public interface IHttpRequestResponse
+{
+
+  public String getHost();
+
+  public int getPort();
+
+  public String getProtocol();
+
+  public void setHost(String host) throws Exception;
+
+  public void setPort(int port) throws Exception;
+
+  public void setProtocol(String protocol) throws Exception;
+
+  public byte[] getRequest() throws Exception;
+
+  public java.net.URL getUrl() throws Exception;
+
+  public void setRequest(byte[] message) throws Exception;
+
+  public byte[] getResponse() throws Exception;
+
+  public void setResponse(byte[] message) throws Exception;
+
+  public short getStatusCode() throws Exception;
+
+}

data/java/src/burp/IScanIssue.java

@@ -0,0 +1,32 @@
+package burp;
+
+import java.net.URL;
+
+public interface IScanIssue
+{
+
+  public String getHost();
+
+  public int getPort();
+
+  public String getProtocol();
+
+  public java.net.URL getUrl();
+
+  public String getIssueName();
+
+  public String getSeverity();
+
+  public String getConfidence();
+
+  public String getIssueBackground();
+
+  public String getRemediationBackground();
+
+  public String getIssueDetail();
+
+  public String getRemediationDetail();
+
+  public IHttpRequestResponse[] getHttpMessages();
+
+}

data/java/src/burp/IScanQueueItem.java

@@ -0,0 +1,20 @@
+package burp;
+
+public interface IScanQueueItem
+{
+
+  public String getStatus();
+
+  public byte getPercentageComplete();
+
+  public int getNumRequests();
+
+  public int getNumErrors();
+
+  public int getNumInsertionPoints();
+
+  public void cancel();
+
+  public IScanIssue[] getIssues();
+
+}

data/lib/buby.rb

@@ -18,8 +18,14 @@ include_class 'BurpExtender'
 # * evt_register_callbacks
 # * evt_application_closing
 #
-# This class also exposes several methods used to access Burp functionality 
-# and user interfaces (note also, abbreviated aliases exist for each):
+# Buby also supports the newer event handlers available in Burp 1.2.09 and up:
+# * evt_http_message
+# * evt_scan_issue
+#
+#
+# This class also exposes several methods to access Burp functionality 
+# and user interfaces through the IBurpExtenderCallbacks interface 
+# (note, several abbreviated aliases also exist for each):
 # * doActiveScan
 # * doPassiveScan
 # * excludeFromScope
@@ -31,6 +37,18 @@ include_class 'BurpExtender'
 # * sendToRepeater
 # * sendToSpider
 #
+# Buby also provides front-end ruby methods for the new callback methods added
+# since Burp 1.2.09:
+# * getProxyHistory
+# * getSiteMap
+# * restoreState
+# * saveState
+# * getParameters
+# * getHeaders
+#
+# If you wish to access any of the IBurpExtenderCallbacks methods directly. 
+# You can use 'burp_callbacks' to obtain a reference.
+#
 # Credit:
 # * Burp and Burp Suite are trade-marks of PortSwigger Ltd.
 #     Copyright 2008 PortSwigger Ltd. All rights reserved.
@@ -40,10 +58,10 @@ include_class 'BurpExtender'
 #   were written by Eric Monti @ Matasano Security. 
 #
 #   Matasano claims no professional or legal affiliation with PortSwigger LTD. 
-#   nor do we sell or officially endorse their products.
+#   nor do we sell or officially endorse any of their products.
 #
 #   However, this author would like to express his personal and professional 
-#   respect and appreciation for their making available the IBurpExtender 
+#   respect and appreciation for their making available the BurpExtender 
 #   extension API. The availability of this interface in an already great tool
 #   goes a long way to make Burp Suite a truly first-class application.
 #
@@ -54,7 +72,7 @@ include_class 'BurpExtender'
 class Buby
 
   # :stopdoc:
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   # :startdoc:
@@ -79,9 +97,12 @@ class Buby
 
   # Returns the internal reference to the IBupExtenderCallbacks instance.
   # This reference gets set from Java through the evt_register_callbacks
-  # method.
+  # method. It is exposed to allow you to access the IBurpExtenderCallbacks 
+  # instance directly if you so choose.
   def burp_callbacks; @burp_callbacks; end
 
+  # Internal method to check for the existence of the burp_callbacks reference
+  # before doing anything with it.
   def _check_cb
     @burp_callbacks or raise "Burp callbacks have not been set"
   end
@@ -95,7 +116,6 @@ class Buby
   def doActiveScan(host, port, https, req)
     _check_cb.doActiveScan(host, port, https, req.to_java_bytes)
   end
-
   alias do_active_scan doActiveScan
   alias active_scan doActiveScan
 
@@ -109,7 +129,6 @@ class Buby
   def doPassiveScan(host, port, https, req, rsp)
     _check_cb.doPassiveScan(host, port, https, req.to_java_bytes, rsp.to_java_bytes)
   end
-
   alias do_passive_scan doPassiveScan
   alias passive_scan doPassiveScan
 
@@ -118,7 +137,6 @@ class Buby
   def excludeFromScope(url)
     _check_cb.excludeFromScope(java.net.URL.new(url.to_s))
   end
-
   alias exclude_from_scope excludeFromScope
   alias exclude_scope excludeFromScope
 
@@ -127,7 +145,6 @@ class Buby
   def includeInScope(url)
     _check_cb.includeInScope(java.net.URL.new(url.to_s))
   end
-
   alias include_in_scope includeInScope 
   alias include_scope includeInScope 
 
@@ -138,7 +155,6 @@ class Buby
   def isInScope(url)
     _check_cb.isInScope(java.net.URL.new(url.to_s))
   end
-
   alias is_in_scope isInScope
   alias in_scope? isInScope
 
@@ -147,7 +163,6 @@ class Buby
   def issueAlert(msg)
     _check_cb.issueAlert(msg.to_s)
   end
-
   alias issue_alert issueAlert
   alias alert issueAlert
 
@@ -163,7 +178,6 @@ class Buby
       _check_cb.makeHttpRequest(host, port, https, req.to_java_bytes)
     )
   end
-
   alias make_http_request makeHttpRequest
   alias make_request makeHttpRequest
 
@@ -175,7 +189,6 @@ class Buby
   def sendToIntruder(host, port, https, req)
     _check_cb.sendToIntruder(host, port, https, req.to_java_bytes)
   end
-
   alias send_to_intruder sendToIntruder
   alias intruder sendToIntruder
 
@@ -188,7 +201,6 @@ class Buby
   def sendToRepeater(host, port, https, req, tab=nil)
     _check_cb.sendToRepeater(host, port, https, req.to_java_bytes, tab)
   end
-
   alias send_to_repeater sendToRepeater
   alias repeater sendToRepeater
 
@@ -197,10 +209,89 @@ class Buby
   def sendToSpider(url)
     _check_cb.includeInScope(java.net.URL.new(url.to_s))
   end
-
   alias send_to_spider sendToSpider
   alias spider sendToSpider
 
+  # This method is a __send__ call back gate for the IBurpExtenderCallbacks
+  # reference. It first checks to see if a method is available before calling
+  # with the specified arguments, and raises an exception if it is unavailable.
+  #
+  # This method was added for provisional calling of new callbacks added since
+  # Burp 1.2.09
+  #
+  # * meth = string or symbol name of method
+  # * args = variable length array of arguments to pass to meth
+  def _check_and_callback(meth, *args)
+    cb = _check_cb
+    unless cb.respond_to?(meth)
+      raise "#{meth} is not available in your version of Burp"
+    end
+    cb.__send__ meth, *args
+  end
+
+  # Returns a Java array of IHttpRequestResponse objects pulled directly from 
+  # the Burp proxy history.
+  def getProxyHistory
+    _check_and_callback(:getProxyHistory)
+  end
+  alias proxy_history getProxyHistory
+  alias get_proxy_history getProxyHistory
+
+  # Returns a Java array of IHttpRequestResponse objects pulled directly from 
+  # the Burp site map.
+  def getSiteMap
+    _check_and_callback(:getSiteMap)
+  end
+  alias site_map getSiteMap
+  alias get_site_map getSiteMap
+
+  # Restores Burp session state from a previously saved state file.
+  # See also: saveState
+  #
+  # IMPORTANT: This method is only available with Burp 1.2.09 and higher.
+  #
+  # * filename = path and filename of the file to restore from
+  def restoreState(filename)
+    _check_and_callback(:restoreState, java.io.File.new(filename))
+  end
+  alias restore_state restoreState
+
+  # Saves the current Burp session to a state file. See also restoreState.
+  #
+  # IMPORTANT: This method is only available with Burp 1.2.09 and higher.
+  #
+  # * filename = path and filename of the file to save to
+  def saveState(filename)
+    _check_and_callback(:saveState, java.io.File.new(filename))
+  end
+  alias save_state saveState
+
+  # Parses a raw HTTP request message and returns an associative array 
+  # containing parameters as they are structured in the 'Parameters' tab in the 
+  # Burp request UI.
+  #
+  # IMPORTANT: This method is only available with Burp 1.2.09 and higher.
+  #
+  # req = raw request string (converted to Java bytes[] in passing)
+  def getParameters(req)
+    _check_and_callback(:getParameters, req.to_s.to_java_bytes)
+  end
+  alias parameters getParameters
+  alias get_parameters getParameters
+
+  # Parses a raw HTTP message (request or response ) and returns an associative
+  # array containing the headers as they are structured in the 'Headers' tab 
+  # in the Burp request/response viewer UI.
+  #
+  # IMPORTANT: This method is only available with Burp 1.2.09 and higher.
+  #
+  # msg = raw request/response string (converted to Java bytes[] in passing)
+  def getHeaders(msg)
+    _check_and_callback(:getHeaders, msg.to_s.to_java_bytes)
+  end
+  alias headers getHeaders
+  alias get_Headers getHeaders
+
 
   ### Event Handlers ###
 
@@ -283,8 +374,8 @@ class Buby
   #   The requested URL. Set in both the request and response.
   #
   # * resourceType:
-  #   The filetype of the requested resource, or a zero-length string if the 
-  #   resource has no filetype.
+  #   The filetype of the requested resource, or nil if the resource has no 
+  #   filetype.
   #
   # * status:
   #   The HTTP status code returned by the server. This value is nil for 
@@ -379,6 +470,52 @@ class Buby
     return message
   end
 
+
+  # This method is invoked whenever any of Burp's tools makes an HTTP request 
+  # or receives a response. This is effectively a generalised version of the 
+  # pre-existing evt_proxy_message method, and can be used to intercept and 
+  # modify the HTTP traffic of all Burp tools.
+  #
+  # IMPORTANT: This event handler is only used in Burp version 1.2.09 and 
+  # higher.
+  # 
+  # Note: this method maps to the processHttpMessage BurpExtender Java method.
+  #
+  # This method should be overridden if you wish to implement functionality
+  # relating to generalized requests and responses from any BurpSuite tool.
+  # You may want to use evt_proxy_message if you only intend to work with only 
+  # proxied messages. Note, however, the IHttpRequestResponse Java object is 
+  # not used in evt_proxy_http_message and gives evt_http_message a somewhat 
+  # nicer interface to work with.
+  #
+  # Parameters:
+  # * tool_name = a string name of the tool that generated the message
+  #
+  # * is_request = boolean true = request / false = response
+  #
+  # * message_info = an instance of the IHttpRequestResponse Java class with
+  #   methods for accessing and manipulating various attributes of the message.
+  #
+  def evt_http_message tool_name, is_request, message_info
+    pp([:got_http_message, tool_name, is_request, message_info]) if $DEBUG
+  end
+
+  # This method is invoked whenever Burp Scanner discovers a new, unique 
+  # issue, and can be used to perform customised reporting or logging of 
+  # detected issues.
+  #
+  # IMPORTANT: This event handler is only used in Burp version 1.2.09 and 
+  # higher.
+  #
+  # Note: this method maps to the newScanIssue BurpExtender Java method.
+  #
+  # Parameters:
+  # * issue = an instance of the IScanIssue Java class with methods for viewing
+  #   information on the scan issue that was generated.
+  def evt_scan_issue(issue)
+    pp([:got_scan_issue, issue]) if $DEBUG
+  end
+
   # This method is called by BurpExtender right before closing the
   # application. Implementations can use this method to perform cleanup
   # tasks such as closing files or databases before exit.

data/samples/mechanize_burp.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env jruby
+
+require 'rubygems'
+require 'buby'
+require 'mechanize'
+require 'rbkb/http'
+require 'irb'
+
+include Java
+
+# This Buby handler implementation simply keeps cookie state synched
+# for a Mechanize agent by intercepting all requests sent through the
+# Burp proxy. This lets you use Mechanize in tandem with your browser
+# through Burp without having to fuss around with cookies.
+class MechGlue < Buby
+  attr_accessor :mech_agent
+
+  def initialize(mech_agent, other=nil)
+    super(other)
+    @mech_agent = mech_agent
+  end
+
+  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 (not is_req) and (message =~ /Set-Cookie/i)
+
+      begin 
+        rsp = Rbkb::Http::Response.parse(message)
+      rescue
+        rsp = nil
+      end
+
+      if rsp
+        # Get an uri object ready for mechanize
+        uri = URI.parse(url)
+        uri.scheme = (is_https)? "https" : "http"
+        uri.host = rhost
+        uri.port = rport
+        
+        # Grab cookies from headers:
+        rsp.headers.get_header_value('Set-Cookie').each do |cookie| 
+          WWW::Mechanize::Cookie.parse(uri, cookie) do |c|
+            $mech.cookie_jar.add(uri, c)
+          end
+        end
+      end
+    end
+    return(message)
+  end
+end
+
+
+if __FILE__ == $0
+  $mech = WWW::Mechanize.new
+  #$mech.set_proxy('localhost', '8080')
+
+  $burp = MechGlue.new($mech)
+  $burp.start_burp
+
+  puts "$burp is set to #{$burp.class}"
+  puts "$mech is set to #{$mech.class}"
+  IRB.start
+end

data/samples/verb_tamperer.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env jruby
+require 'rubygems'
+require 'buby'
+
+class VerbTamperer < Buby
+  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"
+      message[0,3] = "PET"
+      action[0] = Buby::ACTION_DONT_INTERCEPT
+
+      return super(*param).dup
+    else
+      return super(*param)
+    end
+  end
+end
+
+VerbTamperer.start_burp()

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: emonti-buby
 version: !ruby/object:Gem::Version 
-  version: 1.0.1
+  version: 1.1.0.0
 platform: ruby
 authors: 
 - Eric Monti - Matasano Security
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-10 00:00:00 -07:00
+date: 2009-06-21 00:00:00 -07:00
 default_executable: buby
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,7 +20,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 2.5.0
+        version: 2.5.1
     version: 
 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.
 email: emonti@matasano.com
@@ -42,8 +42,12 @@ files:
 - java/src/BurpExtender.java
 - java/src/burp/IBurpExtender.java
 - java/src/burp/IBurpExtenderCallbacks.java
+- java/src/burp/IHttpRequestResponse.java
+- java/src/burp/IScanIssue.java
+- java/src/burp/IScanQueueItem.java
 - lib/buby.rb
-- samples/basic.rb
+- samples/mechanize_burp.rb
+- samples/verb_tamperer.rb
 - spec/buby_spec.rb
 - spec/spec_helper.rb
 - tasks/ann.rake
@@ -60,7 +64,7 @@ files:
 - tasks/test.rake
 - tasks/zentest.rake
 - test/test_buby.rb
-has_rdoc: true
+has_rdoc: false
 homepage: http://github.com/emonti/buby
 post_install_message: 
 rdoc_options: 
@@ -86,7 +90,7 @@ requirements: []
 rubyforge_project: buby
 rubygems_version: 1.2.0
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: Buby is a mashup of JRuby with the popular commercial web security testing tool Burp Suite from PortSwigger
 test_files: 
 - test/test_buby.rb

data/samples/basic.rb

@@ -1,42 +0,0 @@
-#!/usr/bin/env jruby
-$: << File.join(File.dirname(__FILE__), %w[.. lib])
-
-require 'buby'
-$DEBUG = true
-Buby.load_burp("/path/to/burp.jar") if not Buby.burp_loaded?
-buby = Buby.start_burp()
-
-require 'net/http'
-p = Net::HTTP::Proxy("localhost", 8080).start("www.google.com")
-
-# 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.
-
-buby.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("/")
-
-