Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tduehr/buby

A JRuby implementation of the BurpExtender interface for PortSwigger Burp Suite.
https://github.com/tduehr/buby

Last synced: 2 months ago
JSON representation

A JRuby implementation of the BurpExtender interface for PortSwigger Burp Suite.

Lists

README 

        
= buby

  by Eric Monti, Timur Duehr

  http://tduehr.github.com/buby



== NOTE:



This documentation is for the old gem version of Buby. It does not apply for current versions of BurpSuite. For Burp version 1.5.01 and higher use the BApp version of Buby. This documentation will be updated at the next release.



== 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 or a JRuby BurpExtender implementation using the new embedded JRuby support.  This extension aims to add Ruby scriptability to Burp Suite with an interface comparable to the Burp's pure Java extension interface. This extension works best with Burp Suite Professional. The Free version may also be used but does not contain many of the features that make Burp Suite and Buby shine.



== 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 or JRuby depending on how it's launched.  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.



== Caveat



  Note: 1.6 fixes a bug were some of the newer wrapper methods return the native

        Java arrays. This haas been corrected to return the appropriate

        HttpRequestResponseList or ScanIssuesList object. Most code in use

        should not be affected by this. In 2.0 these methods will return the

        correct Java/JRuby arrays. These were originally created to make nice

        Ruby Array-like objects but are no longer needed.



Burp's extension interfaces have changed significantly in 1.5.01. I don't yet know how compatible this will be with Burp versions 1.5.0 and lower going forward. If you want compatibility with Burp Suite versions 1.5.0 and earlier stick with Buby version 1.3.3 or prior.



I will keep the API provided by earlier Buby versions and mark methods deprecated as required. Hopefully, I'll be able to keep them around for a while so old buby scripts will continue to work for a while.



Methods removed/deprecated in 1.5.01 interfaces:

* IBurpExtenderCallbacks.setCommandLineArgs (removed no replacement)

* IBurpExtenderCallbacks.applicationClosing (removed use IExtensionStateListener instead)

* IBurpExtenderCallbacks.getParameters (deprecated, use IExtensionHelpers analyze methods instead)

* IBurpExtenderCallbacks.getHeaders (deprecated, use IExtensionHelpers analyze methods instead)

* IBurpExtenderCallbacks.registerMenuItem (deprecated, use IBurpExtenderCalbacks.registerContextMenuFactory instead)

* IMenuItemHandler (deprecated, use IContextMenuFactory instead)



The deprecated getParameters and getHeaders methods will, for now, call the equivalent methods on IBurpExtenderCallbacks. At some point soon they'll forward the calls to the correct interface before being removed entirely in favor of the new interfaces.



In 2.0 bin/buby to use a bash script as the primary starting point for the current script - which will be renamed to bin/buby.rb. I may also just leave it as it is; the new Ruby extension stuff is quite nice.



... And one more thing. The next version of buby will require JRuby 1.7.0+. It won't use 1.9 syntax for a little while. So, extensions that require 1.8 will still work for now. Just don't forget to add the `--1.8` switch to JRuby when starting buby.



Now that MRI 2.0 is out and 2.1 is around the corner, 1.9 mode support is semi-deprecated pending 2.0/2.1 support in jruby.



== 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.



== 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, of course, Burp itself.



  (sudo)? jruby -S gem install buby --source=http://gemcutter.org



* 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/tduehr/buby.git



==== Step 2. Compile BurpExtender.java. Include jruby.jar in the classpath:



Install the development dependencies:

  jruby -S gem install jeweler rake-compiler



==== Step 3. Build with rake



  jruby -S rake build



==== Step 4. Build a local gem and install it



  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.



  ln -s ~/tools/burp.jar ~/jruby-1.7.1/lib/ruby/1.9/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

      -p, --pry                        Start pry

      -d, --debug                      Debug info

      -B, --load-burp=PATH             Load Burp Jar from PATH

      -P, --proxy-interception         Enable intercept on load

      -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?)

      -v, --version                    Prints version and exits.

      -h, --help                       Show this help message



  $ buby -i -d

  [:got_extender, #]

  Global $burp is set to #

  [:got_callbacks, #<#: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]]

  => #

  >>



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]]

  => #



== CREDIT:

Burp and Burp Suite are trademarks of PortSwigger(ltd)

  Copyright 2013 PortSwigger Ltd. All rights reserved.

  See http://portswigger.net for license terms.



This JRuby library and the accompanying Java and JRuby BurpExtender

implementations were written by Timur Duehr @ Matasano Security. The original

version of this library and BurpExtender.java implementation was written my Eric

Monti @ Matasano Security. Matasano Security claims no professional or legal

affiliation with PortSwigger LTD.



However, the authors would like to express their personal and professional

respect and admiration to Burp's authors and appreciation to PortSwigger for the

availability of the IBurpExtender extension API and its continued improvement.

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 2013 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

Copyright (C) 2010-2013 Timur Duehr, 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.