emonti-buby 1.0.0

data/lib/buby.rb

@@ -0,0 +1,462 @@
+include Java
+
+require 'pp'
+require "buby.jar"
+
+include_class 'BurpExtender'
+
+# Buby is a mash-up of the commercial security testing web proxy PortSwigger 
+# Burp Suite(tm) allowing you to add scripting to Burp. Burp is driven from 
+# and tied to JRuby with a Java extension using the BurpExtender API.
+#
+# The Buby class is an abstract implementation of a BurpExtender ruby handler. 
+# Included are several abstract event handlers used from the BurpExtender
+# java implementation:
+# * evt_extender_init
+# * evt_proxy_message
+# * evt_command_line_args
+# * 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):
+# * doActiveScan
+# * doPassiveScan
+# * excludeFromScope
+# * includeInScope
+# * isInScope
+# * issueAlert
+# * makeHttpRequest
+# * sendToIntruder
+# * sendToRepeater
+# * sendToSpider
+#
+# Credit:
+# * Burp and Burp Suite are trade-marks 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 
+#   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.
+#
+#   However, this author would like to express his personal and professional 
+#   respect and appreciation for their making available the IBurpExtender 
+#   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.
+#
+# * Forgive the name. It won out over "Burb" and "BurpRub". It's just easier 
+#   to type and say out-loud. Mike Tracy gets full credit as official 
+#   Buby-namer.
+#
+class Buby
+
+  # :stopdoc:
+  VERSION = '1.0.0'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the internal reference to the BurpExtender instance. This
+  # reference gets set from Java through the evt_extender_init method.
+  def burp_extender; @burp_extender; end
+
+  # Returns the internal reference to the IBupExtenderCallbacks instance.
+  # This reference gets set from Java through the evt_register_callbacks
+  # method.
+  def burp_callbacks; @burp_callbacks; end
+
+  def _check_cb
+    @burp_callbacks or raise "Burp callbacks have not been set"
+  end
+
+  # Send an HTTP request to the Burp Scanner tool to perform an active 
+  # vulnerability scan.
+  #  * host = The hostname of the remote HTTP server.
+  #  * port = The port of the remote HTTP server.
+  #  * https = Flags whether the protocol is HTTPS or HTTP.
+  #  * req  = The full HTTP request.
+  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
+
+  # Send an HTTP request and response to the Burp Scanner tool to perform a 
+  # passive vulnerability scan.
+  #  * host = The hostname of the remote HTTP server.
+  #  * port = The port of the remote HTTP server.
+  #  * https = Flags whether the protocol is HTTPS or HTTP.
+  #  * req  = The full HTTP request.
+  #  * rsp  = The full HTTP response.
+  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
+
+  # Exclude the specified URL from the Suite-wide scope.
+  #  * url = The URL to exclude from the Suite-wide scope.
+  def excludeFromScope(url)
+    _check_cb.excludeFromScope(java.net.URL.new(url.to_s))
+  end
+
+  alias exclude_from_scope excludeFromScope
+  alias exclude_scope excludeFromScope
+
+  # Include the specified URL in the Suite-wide scope.
+  #  * url = The URL to exclude in the Suite-wide scope.
+  def includeInScope(url)
+    _check_cb.includeInScope(java.net.URL.new(url.to_s))
+  end
+
+  alias include_in_scope includeInScope 
+  alias include_scope includeInScope 
+
+  # Query whether a specified URL is within the current Suite-wide scope.
+  #  * url = The URL to query
+  #
+  # Returns: true / false
+  def isInScope(url)
+    _check_cb.isInScope(java.net.URL.new(url.to_s))
+  end
+
+  alias is_in_scope isInScope
+  alias in_scope? isInScope
+
+  # Display a message in the Burp Suite alerts tab.
+  #  * msg =  The alert message to display.
+  def issueAlert(msg)
+    _check_cb.issueAlert(msg.to_s)
+  end
+
+  alias issue_alert issueAlert
+  alias alert issueAlert
+
+  # Issue an arbitrary HTTP request and retrieve its response
+  #  * host  = The hostname of the remote HTTP server.
+  #  * port  = The port of the remote HTTP server.
+  #  * https = Flags whether the protocol is HTTPS or HTTP.
+  #  * req   = The full HTTP request.
+  #
+  # Returns: The full response retrieved from the remote server.
+  def makeHttpRequest(host, port, https, req)
+    String.from_java_bytes(
+      _check_cb.makeHttpRequest(host, port, https, req.to_java_bytes)
+    )
+  end
+
+  alias make_http_request makeHttpRequest
+  alias make_request makeHttpRequest
+
+  # Send an HTTP request to the Burp Intruder tool
+  #  * host  = The hostname of the remote HTTP server.
+  #  * port  = The port of the remote HTTP server.
+  #  * https = Flags whether the protocol is HTTPS or HTTP.
+  #  * req   = The full HTTP request.
+  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
+
+  # Send an HTTP request to the Burp Repeater tool.
+  #  * host  = The hostname of the remote HTTP server.
+  #  * port  = The port of the remote HTTP server.
+  #  * https = Flags whether the protocol is HTTPS or HTTP.
+  #  * req   = The full HTTP request.
+  #  * tab   = The tab caption displayed in Repeater. (default: auto-generated)
+  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
+
+  # Send a seed URL to the Burp Spider tool.
+  #  * url = The new seed URL to begin spidering from.
+  def sendToSpider(url)
+    _check_cb.includeInScope(java.net.URL.new(url.to_s))
+  end
+
+  alias send_to_spider sendToSpider
+  alias spider sendToSpider
+
+
+  ### Event Handlers ###
+
+  # This method is called by the BurpExtender java implementation upon 
+  # initialization of the BurpExtender instance for Burp. The args parameter
+  # is passed with a instance of the newly initialized BurpExtender instance 
+  # so that implementations can access and extend its public interfaces.
+  #
+  # The return value is ignored.
+  def evt_extender_init ext
+    @burp_extender = ext
+    pp([:got_extender, ext]) if $DEBUG
+  end
+
+  # This method is called by the BurpExtender implementation Burp startup.
+  # The args parameter contains main()'s argv command-line arguments array. 
+  #
+  # Note: This maps to the 'setCommandLineArgs' method in the java 
+  # implementation of BurpExtender.
+  #
+  # The return value is ignored.
+  def evt_command_line_args args
+    pp([:got_args, args]) if $DEBUG
+  end
+
+  # This method is called by BurpExtender on startup to register Burp's 
+  # IBurpExtenderCallbacks interface object.
+  #
+  # This maps to the 'registerExtenderCallbacks' method in the Java 
+  # implementation of BurpExtender.
+  #
+  # The return value is ignored.
+  def evt_register_callbacks cb
+    @burp_callbacks = cb
+    cb.issueAlert("[JRuby::#{self.class}] registered callback")
+    pp([:got_callbacks, cb]) if $DEBUG
+  end
+
+  ACTION_FOLLOW_RULES   = BurpExtender::ACTION_FOLLOW_RULES
+  ACTION_DO_INTERCEPT   = BurpExtender::ACTION_DO_INTERCEPT
+  ACTION_DONT_INTERCEPT = BurpExtender::ACTION_DONT_INTERCEPT
+  ACTION_DROP           = BurpExtender::ACTION_DROP
+
+  # This method is called by BurpExtender while proxying HTTP messages and
+  # before passing them through the Burp proxy. Implementations can use this
+  # method to implement arbitrary processing upon HTTP requests and responses 
+  # such as interception, logging, modification, and so on.
+  #
+  # The 'is_req' parameter indicates whether it is a response or request.
+  #
+  # Note: This method maps to the 'processProxyMessage' method in the java 
+  # implementation of BurpExtender.
+  #
+  # Below are the parameters descriptions based on the IBurpExtender 
+  # javadoc. Where applicable, decriptions have been modified for 
+  # local parameter naming and other ruby-specific details added.
+  #
+  # * msg_ref:
+  #   An identifier which is unique to a single request/response pair. This 
+  #   can be used to correlate details of requests and responses and perform 
+  #   processing on the response message accordingly. This number also 
+  #   corresponds to the Burp UI's proxy "history" # column.
+  #
+  # * is_req: (true/false)
+  #   Flags whether the message is a client request or a server response.
+  #
+  # * rhost:
+  #   The hostname of the remote HTTP server.
+  #
+  # * rport:
+  #   The port of the remote HTTP server.
+  #
+  # * is_https:
+  #   Flags whether the protocol is HTTPS or HTTP.
+  #
+  # * http_meth:
+  #   The method verb used in the client request.
+  #
+  # * url:
+  #   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.
+  #
+  # * status:
+  #   The HTTP status code returned by the server. This value is nil for 
+  #   request messages.
+  #
+  # * req_content_type:
+  #   The content-type string returned by the server. This value is nil for 
+  #   request messages.
+  #
+  # * message:
+  #   The full HTTP message.  
+  #   **Ruby note: 
+  #     For convenience, the message is received and returned as a ruby 
+  #     String object. Internally within Burp it is handled as a java byte[] 
+  #     array. See also the notes about the return object below.
+  #
+  # * action:
+  #   An array containing a single integer, allowing the implementation to 
+  #   communicate back to Burp Proxy a non-default interception action for 
+  #   the message. The default value is ACTION_FOLLOW_RULES (or 0). 
+  #   Possible values include:
+  #     ACTION_FOLLOW_RULES = 0
+  #     ACTION_DO_INTERCEPT = 1
+  #     ACTION_DONT_INTERCEPT = 2
+  #     ACTION_DROP = 3
+  #
+  #   Refer to the BurpExtender.java source comments for more details.
+  #
+  #
+  # Return Value:
+  #   Implementations should return either (a) the same object received
+  #   in the message paramater, or (b) a different object containing a 
+  #   modified message. 
+  #
+  # **IMPORTANT RUBY NOTE:
+  # Always be sure to return a new object if making modifications to messages.
+  #
+  # Explanation: 
+  # The (a) and (b) convention above is followed rather literally during type 
+  # conversion on the return value back into the java BurpExtender.
+  #
+  # When determining whether a change has been made in the message or not, 
+  # the decision is made based on whether the object returned is the same
+  # as the object submitted in the call to evt_proxy_message. 
+  #
+  #
+  # So, for example, using in-place modification of the message using range 
+  # substring assignments or destructive method variations like String.sub!() 
+  # and String.gsub! alone won't work because the same object gets returned 
+  # to BurpExtender. 
+  #
+  # In short, this means that if you want modifications to be made, be sure
+  # to return a different String than the one you got in your handler.
+  #
+  # So for example this code won't do anything at all:
+  #
+  #   ...
+  #   message.sub!(/^GET /, "HEAD ")
+  #   return message
+  #
+  # Nor this:
+  #
+  #   message[0..4] = "HEAD "
+  #   return message
+  #
+  # But this will
+  #
+  #   ...
+  #   return message.sub(/^GET /, "HEAD ")
+  #
+  # And so will this
+  #
+  #   ...
+  #   message[0..4] = "HEAD "
+  #   return message.dup
+  #
+  def evt_proxy_message msg_ref, is_req, rhost, rport, is_https, http_meth, url, resourceType, status, req_content_type, message, action
+    pp([ (is_req)? :got_proxy_request : :got_proxy_response,
+         [:msg_ref, msg_ref], 
+         [:is_req, is_req], 
+         [:rhost, rhost], 
+         [:rport, rport], 
+         [:is_https, is_https], 
+         [:http_meth, http_meth], 
+         [:url, url], 
+         [:resourceType, resourceType], 
+         [:status, status], 
+         [:req_content_type, req_content_type], 
+         [:message, message], 
+         [:action, action[0]] ]) if $DEBUG
+    
+    return message
+  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.
+  def evt_application_closing 
+    pp([:got_app_close]) if $DEBUG
+  end
+
+  # Prepares the java BurpExtender implementation with a reference
+  # to self as the module handler and launches burp suite.
+  def start(args=[])
+    BurpExtender.set_handler(self)
+    Java::Burp::StartBurp.main(args.to_java(:string))
+    return self
+  end
+
+  # Starts burp using a supplied handler class, 
+  #  h_class = Buby or a derived class. instance of which will become handler.
+  #  args = arguments to Burp
+  #  init_args = arguments to the handler constructor
+  #
+  #  Returns the handler instance
+  def self.start_burp(h_class=nil, init_args=nil, args=nil)
+    h_class ||= self
+    init_args ||= []
+    args ||= []
+    h_class.new(*init_args).start(args)
+  end
+
+  # Attempts to load burp with require and confirm it provides the required 
+  # class in the Java namespace.
+  #
+  # Returns: true/false depending on whether the required jar provides us
+  # the required class
+  #
+  # Raises: may raise the usual require exceptions if jar_path is bad.
+  def self.load_burp(jar_path)
+    require jar_path
+    return burp_loaded?
+  end
+
+  # Checks the Java namespace to see if Burp has been loaded.
+  def self.burp_loaded?
+    begin 
+      include_class 'burp.StartBurp'
+      return true
+    rescue
+      return false
+    end
+  end
+
+  ### Extra cruft added by Mr Bones:
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+end
+
+# Try requiring 'burp.jar' from the Ruby lib-path
+unless Buby.burp_loaded?
+  begin require "burp.jar" 
+  rescue LoadError 
+  end
+end
+

data/samples/basic.rb

@@ -0,0 +1,42 @@
+#!/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("/")
+
+

data/spec/buby_spec.rb

@@ -0,0 +1,7 @@
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+describe Buby do
+end
+
+# EOF

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib buby]))
+
+Spec::Runner.configure do |config|
+  # == Mock Framework
+  #
+  # RSpec uses it's own mocking framework by default. If you prefer to
+  # use mocha, flexmock or RR, uncomment the appropriate line:
+  #
+  # config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+end
+
+# EOF

data/tasks/ann.rake

@@ -0,0 +1,80 @@
+
+begin
+  require 'bones/smtp_tls'
+rescue LoadError
+  require 'net/smtp'
+end
+require 'time'
+
+namespace :ann do
+
+  # A prerequisites task that all other tasks depend upon
+  task :prereqs
+
+  file PROJ.ann.file do
+    ann = PROJ.ann
+    puts "Generating #{ann.file}"
+    File.open(ann.file,'w') do |fd|
+      fd.puts("#{PROJ.name} version #{PROJ.version}")
+      fd.puts("    by #{Array(PROJ.authors).first}") if PROJ.authors
+      fd.puts("    #{PROJ.url}") if PROJ.url.valid?
+      fd.puts("    (the \"#{PROJ.release_name}\" release)") if PROJ.release_name
+      fd.puts
+      fd.puts("== DESCRIPTION")
+      fd.puts
+      fd.puts(PROJ.description)
+      fd.puts
+      fd.puts(PROJ.changes.sub(%r/^.*$/, '== CHANGES'))
+      fd.puts
+      ann.paragraphs.each do |p|
+        fd.puts "== #{p.upcase}"
+        fd.puts
+        fd.puts paragraphs_of(PROJ.readme_file, p).join("\n\n")
+        fd.puts
+      end
+      fd.puts ann.text if ann.text
+    end
+  end
+
+  desc "Create an announcement file"
+  task :announcement => ['ann:prereqs', PROJ.ann.file]
+
+  desc "Send an email announcement"
+  task :email => ['ann:prereqs', PROJ.ann.file] do
+    ann = PROJ.ann
+    from = ann.email[:from] || Array(PROJ.authors).first || PROJ.email
+    to   = Array(ann.email[:to])
+
+    ### build a mail header for RFC 822
+    rfc822msg =  "From: #{from}\n"
+    rfc822msg << "To: #{to.join(',')}\n"
+    rfc822msg << "Subject: [ANN] #{PROJ.name} #{PROJ.version}"
+    rfc822msg << " (#{PROJ.release_name})" if PROJ.release_name
+    rfc822msg << "\n"
+    rfc822msg << "Date: #{Time.new.rfc822}\n"
+    rfc822msg << "Message-Id: "
+    rfc822msg << "<#{"%.8f" % Time.now.to_f}@#{ann.email[:domain]}>\n\n"
+    rfc822msg << File.read(ann.file)
+
+    params = [:server, :port, :domain, :acct, :passwd, :authtype].map do |key|
+      ann.email[key]
+    end
+
+    params[3] = PROJ.email if params[3].nil?
+
+    if params[4].nil?
+      STDOUT.write "Please enter your e-mail password (#{params[3]}): "
+      params[4] = STDIN.gets.chomp
+    end
+
+    ### send email
+    Net::SMTP.start(*params) {|smtp| smtp.sendmail(rfc822msg, from, to)}
+  end
+end  # namespace :ann
+
+desc 'Alias to ann:announcement'
+task :ann => 'ann:announcement'
+
+CLOBBER << PROJ.ann.file
+
+# EOF

data/tasks/bones.rake

@@ -0,0 +1,20 @@
+
+if HAVE_BONES
+
+namespace :bones do
+
+  desc 'Show the PROJ open struct'
+  task :debug do |t|
+    atr = if t.application.top_level_tasks.length == 2
+      t.application.top_level_tasks.pop
+    end
+
+    if atr then Bones::Debug.show_attr(PROJ, atr)
+    else Bones::Debug.show PROJ end
+  end
+
+end  # namespace :bones
+
+end  # HAVE_BONES
+
+# EOF