Creating a Buby Module

Background

wXf can load buby scripts or basically scripts that can extend the functionality of Burp but there are fairly specific standards a module developer must follow.

Firstly, place any buby script under modules/buby.

The format is as follows

class WebXploit < WXf::WXfmod_Factory::Buby 

  module Runner

    # Only include the following `include` line of code if you'd like to print something to the console.
    # This BubyApi assists module will do more stuff later but for now it is a way to 
    # ...hook prnt_gen, prnt_err, etc into the module
    include WXf::WXfassists::Buby::BubyApi
    
    def evt_proxy_message(*param)
      msg_ref, is_req, rhost, rport, is_https, http_meth, url, resourceType, status, req_content_type, message, action = param
    end

  end

def initialize
  super(
   'Name'        => 'Name Example',
   'Version'     => '1.0',
   'Description' => %q{
    Description Example, here we demonstrate what an example description would look like.
    Thank you for participating in wXf development!
                    },
   'References'  =>
    [
    ['URL', 'http://www.example.com']
    ],
   'Author'      => [ 'Your Name' ],
   'License'     => WXF_LICENSE
  )
  
  init_opts([
   OptString.new('EXAMPLE', [true, "Example Description of the Option", "default"]),
  ])
  
end

def run
  $datahash = datahash 
    if $burp
      $burp.extend(Runner)
      prnt_gen("We've started running the modules")
    else
      prnt_err("A burp instance is not running")
    end
  rescue => $!
 puts "#{$!}"
end

end

Buby Module Explained

Every wXf module whether auxiliary, exploit or otherwise must include the following class definition. The portion that specifies this as a buby module is < WXf::WXfmod_Factory::Buby. You will notice that we've included a module within the class called Runner. The Runner module will contain the code that Buby will load into Burp. If your familiar with extending modules, Buby will extend itself using the Runner module and therefore Burp itself.

Keep in mind, the Runner module will override Buby methods much like a normal Buby script.

class WebXploit < WXf::WXfmod_Factory::Buby

  module Runner
  end

end

Additionally, every wXf module must initialize and create values that are utilized elsewhere in the framework. This is the 'initialize' method and every module must use it. The values specified within super() are very self-explanatory.

 def initialize 
   super(
   'Name'        => 'Name Example',
   'Version'     => '1.0',
   'Description' => %q{
    Description Example, here we demonstrate what an example description would look like.
    Thank you for participating in wXf development!
                    },
   'References'  =>
    [
    ['URL', 'http://www.example.com']
    ],
   'Author'      => [ 'Your Name' ],
   'License'     => WXF_LICENSE
  )

To add another reference append a comma after the last reference. Create the next reference by following the format: ['ReferenceType', 'Reference']

'References'  =>
[
 ['URL', 'http://www.example.com'],
 ['URL', 'http://another.example.com]
],

To add an additional Author, append a comma to the last Author's name and enclose the new author's name in single or double quotes (all within one bracket). Notice that because the second author's name has a single quote (') within it, we've encapsulated the entire name in double quotes.

Author => [ 'Your Name', "Second Author's Name" ]

Before finishing the initialize function and closing it with the end tag, we need to specify any additional options that the module developer wishes to expose to the user. By default, when an assist module is included, default options are already available. An example of a default option, which is included in every assist module, would be the RURL. You can find which options will be displayed to the users on the Assists Page.

To expose additional options, use init_opts([]) (the 'end' marker closes the initialize function NOT init_opts([]):

init_opts([
   OptString.new('EXAMPLE', [true, "Example Description of the Option", "default"]),
])
  
end

The portion between init_opts([]) is the option the user will see when typing show options. Additionally, this will allow the user to set the option and the module to call it. The basic premise is that the 'EXAMPLE' item (shown above) is the name of the option. The first item in the brackets specifies if it is a required option (true or false) , the second is the description and the final item is the default option as shown to the user.

Finally we need to specify the 'run' method and place very specific code within it. The Runner module's code itself is flexible but it is probably best to stick to the boilerplate code we've provided below when using the WebXploit class's run method. When a user types 'run' from the console this is the method they will invoke and Buby will extend itself using the code placed within the Runner module.

The following is the boilerplate code we discussed. It instantiates a globally accessible value called $datahash (this way the runner Module can access the datahash) and also extends our $burp instance.

def run
  $datahash = datahash 
    if $burp
      $burp.extend(Runner)
      prnt_gen("We've started running the modules")
    else
      prnt_err("A burp instance is not running")
    end
   rescue => $!
  puts "#{$!}"
 end
end

When printing output to the console, the developer may wish to prepend a colored symbol. Caveat, if you'd like to print anything from the Runner module itself, add the following code between module Runner/end. Example:

module Runner
  include WXf::WXfassists::Buby::BubyApi

end

We've provided the follow options:

prnt_gen()  => This is a blue -{*}-
prnt_err()  => This is a red -{-}-
prnt_plus() => This is a green -{+}-
prnt_dbg()  => This is a yellow -{!}-

Whatever is sent to the symbol method will be converted to a string and printed to the console.

If the module is to perform an HTTP(s) or SOAP action, then an assist module must be included. Assist modules are discussed in depth under the Assists Page on this wiki. For now, if you would like to utilize the methods you must include them.

To include the MechReq (HTTPs(s)) assist module:

include WXf::WXfassists::General::MechReq

To include the SavonReq (SOAP) assist module:

include WXf::WXfassists::General::SavonReq

This is the conclusion, if you feel we've omitted an important detail please contact the wXf developers: wXfdev[at]gmail.com.