Buby Script Basics Part 5

√ evt_http_message     
√ evt_scan_issue         
√ doActiveScan         
√ doPassiveScan         
√ excludeFromScope 
√ includeInScope       
√ isInScope
√ issueAlert   
√ sendToIntruder
√ sendToRepeater
   sendToSpider
   makeHttpRequest


In this portion of the Buby Script Basics series (Part 5), we will cover all but two of the remaining methods (methods without lines through them) on our checklist.


As always, you can find sample scripts for each of these under the examples directory of the buby-script repo located Here.


The three methods we will cover are issueAlert, sendToIntruder, and sendToRepeater. The example script is called sendto_and_issue_alert.rb and encompasses all three.


The purpose of this script is to check the body of post messages to see if one of the parameters matches our list of interesting parameters (FUZZ_PARAMS) which deserve manual analysis. We'll perform the manual analysis with intruder/repeater and then issue an alert when the request has been sent over.


Unlike the previous tutorials, this script will be ran by invoking the method via the command line. 


Example of how to run this script (covered in Part 1 of this series:

$ jruby -S buby -i -B burp_pro.jar -r sendto_and_issue_alert.rb


This script is going to be run against the proxy history, it's going to search the proxy history looking for the interesting requests. After you've interacted with the site type "$burp.run".

If the parameters in the body of the POST message match our interesting params, you should see the following:


Request sent to repeater, notice the name of the tab (it is our fuzz param "Price")

The request has been sent to intruder

Lastly, an alert will appear notifying you that the previously mentioned actions have been taken.

Time to discuss the code that does all this :-)

First we establish parameters that could be interesting to us in terms of performing manual analysis.

This method '$burp.run' is the catalyst for everything that comes next. When the user types $burp.run at the console they are invoking this method. 

Line 2 instantiates the proxy_hist object ($burp.get_proxy_history). The fourth line determines if the length is greater than 0. If so, start iterating thru each obj in the get_proxy_history array. Line 7 invokes the hmeth method (passes it the 'obj' object). Line 8 calls extract_str with the result of Line 7 (hmeth...which is the HTTP Method) and the 'obj' object.

The req_meth takes the request_headers, takes the first line and converts it to a string. The '[0..3]' method extracts the first 4 characters of the first line of the request headers. The method returns this value.

Part 1 of extract_str

The extract_str method is where the FUZZ_PARAMS are searched against the request message and sent to repeater/intruder (along with the alert). 

The second line splits objs into the http_meth and req objects. 

The third line ensures that we do not execute any further code unless the http_meth is a POST method. 

Then we instantiate the bparams object as a Hash on line 4.

On line 5, the request_body gets split by the ampersand (so that we break up all the params and their values into key/value pairs (ex: Price=2099.00).

Next, we split these pairs up by the '=' (equal sign) and place each param/value (key/value) into the bparam hash. Conceptually the bparam hash would look like

bparam = {'Price' => '2099.00}

The last line assigns either true or false to the proto object based on whether or not the protocol is https.

Part 2 of extract_str

Here we begin iterating thru each item in the FUZZ_PARAM array. If the bparam hash has as key which matches on of the items in FUZZ_PARAM, we send it to intruder/repeater and issue our alerts.

Explanation of methods:


sendToIntruder(host, port, https, req)
-host
-port
-true/false (for http/https)
-request string

sendToRepeater(host, port, https, req, tab = nil)
-host
-port
-true/false (for http/https)
-request string
-the name of the tab (String value) )


issueAlert(msg)
- Takes only one parameter, a string value. This is what shows up in the alert.

*We will cover the remaining two methods in the next portion of the series. This post turned into a rather long one so it was postponed.

Happy Hacking,

~cktricky

Buby Script Basics Part 4

√ evt_http_message     
√ evt_scan_issue         
√ doActiveScan         
√ doPassiveScan         
√ excludeFromScope 
√ includeInScope       
√ isInScope
   issueAlert
   makeHttpRequest
   sendToIntruder
   sendToRepeater
   sendToSpider


In Part 3 of this series we covered the two methods with lines drawn through them (above: evt_http_message and evt_scan_issue).


In Part 4, the methods with checks next to them will be described along with code examples.

You can find sample scripts for each of these under the examples directory of the buby-script repo located Here.

includeInScope, excludeFromScope

----------------------------------------------


The code here is nothing more than two arrays. The first array, EXCLUSION_LIST, contains items we'd like to exclude from scope. The second array, INCLUSION_LIST, contains items to include.

This following portion of code contains a PREFIX array (both http and https). We perform an iteration of both and while iterating through this prefix array, we start iterating through a second list (EXCLUSION_LIST) and concatenating the prefix + host + the item in the EXCLUSION_LIST. This step is repeated for the INCLUSION_LIST. The $burp.includeInScope() method is called and we submit the concatenated value (url) to it. 

do_active_scan, do_passive_scan, isInScope

----------------------------------------------------

The def $burp.evt_proxy_message is a familiar one at this point in the series so we won't discuss this in detail. The code @@msg = nil exists solely to instantiate a global object called msg. We will need to keep an object associated with the request message (headers/body) because passive scanning requires both a request message and response message.


pre = is_https? 'https' : 'http' is just a way to define the "pre" object based on whether or not it is http or https message.


pre_bool does the same thing as the pre object but instead of http/https it is a true/false.


uri = "#{pre}://#{rhost}:#{rport}#{url}" is just the url (string concatenation). 



The last three lines of code here basically set the @@msg value. We only want to do this if it is a request. Remember, we need an object to hold the request message so that even if the current message is a response we can call both the request message and response message.

Next bit of code basically says, if this message is in scope AND is a request message, start performing an active scan. Otherwise if it is a message which is in scope but a response message then perform passive scanning. 


$burp.do_active_scan takes 4 objects
-rhost           => host value
-rport           => port value
-pre_bool    => true/false based on whether or not it is https
-message    => String value (or Java bytes), full message (request only of course)


$burp.do_passive_scan takes 5 objects

-rhost           => host value

-rport           => port value

-pre_bool    => true/false based on whether or not it is https

-@@msg    => request message, string value (or Java bytes)
-message    =>  response message, string value (or Java bytes)

Okay, next up is Part 5 of this series where we will cover the rest of the methods listed above.


Happy Hacking,


~cktricky

Buby Script Basics Part 3

In part 2 of this series we covered the "evt_proxy_message" method. In part 3 of this series we will cover the two methods shown below which have "checks" next to them.


√ evt_http_message    
√ evt_scan_issue        
   doActiveScan        
   doPassiveScan        
   excludeFromScope
   includeInScope      
   isInScope
   issueAlert
   makeHttpRequest
   sendToIntruder
   sendToRepeater
   sendToSpider

So let's cover each individually with brief explanation and a code example.

You can find sample scripts for each of these under the examples directory of the buby-script repo located Here.


EVT_HTTP_MESSAGE
---------------------------------


The following code will allow you to obtain methods exposed by the message_info object (which is a class):

The 3 separate objects that make up the param are:


tool_name => This is a string value, it is the name of the tool for which the message originated. Examples include proxy, scanner and repeater.


is_request => Boolean value (true/false), this returns true when it is a request and false when a response.


message_info => This is a class. It is an instance of the IHttpRequestResponse Java class. So there are methods such as get_comment, set_comment and getUrl exposed. 


An example of using evt_http_message can be seen here (code):

....and the result

w00t!

So what does the code actually do?

Lines 1 and 2 - Define the method and separate param into 3 separate objects.

Lines 3-5

Ln 3 If the tool the message originated from was the spider and this is NOT a request proceed to Ln 4.

Ln4 If the response status code is 200 (OK), then move to Ln 5.

Ln 5 Puts "Yo, we received a 200 FTW!" to the console.

Lines 6-9 Are closing statements/method and passing the param back up to the superclass method.


You can find another example using this method in the zlib_inflate.rb script.




EVT_SCAN_ISSUE
---------------------------


The following code will allow you obtain methods exposed by the issue object (which is a class):

Only one object is exposed, it is a class, it is called issue. Some of the methods exposed by this class are

-issue_name
-severity
-confidence
-protocol
-host
-url
-port
-issue_detail
-issue_background
-remediation_detail  
-remediation_background

The following code:

...produces:

Lets step through the code


1.  def prnt(*objs)
2.    strn, meth = objs  
3.    str = ''
4.    str << "\n#{strn}\n"
5.    str << '=' * strn.length + "\n\n"
6.    str << "#{meth}\n"
7.    puts str
8.  end


Lines 1-2 - Defines the method (prnt) and separates objs into two objects (strn, meth).


Lines 3-4 - This defines a string instance variable (str), and then proceeds to put the strn object onto it.

Lines 5-7 - The length of strn gets multiplied by '=' so that we can create the following visual....

Example:

something
=========

...then we push meth onto the string and then we "puts" or print it to the console.

Lets step through the second method "hm_prnt".


1.   def hm_prnt(*objs)
2.     strn, meth = objs
3.     str = ''
4.     str << "\n#{strn}\n"
5.     str << '=' * strn.length + "\n\n"
6.     meth.each do |itm|
7.       str << "#{itm.request_headers}\n"
8.       str << "#{itm.request_body}\n"
9.       str << "#{itm.response_headers}\n"
10.     str << "#{itm.response_body}\n"
11.    end
12.    puts str 
13 . end

Lines 1-2 - Defines the method (prnt) and separates objs into two objects (strn, meth).

Lines 3-4 - This defines a string instance variable (str), and then proceeds to put the strn object onto it. 

Lines 6-10 - We take the meth object which is an Array, we iterate thru each item in the array, convert it to a string while calling the four methods it exposes (request_headers, request_body, response.headers, and response_body). Now these methods all belong to http_messages and itm really represents the http_messages class. So when we are iterating thru this array we are really iterating thru an array containing a bunch of http_messages classes. Hopefully that makes sense.

Finally, we need to discuss the $burp.evt_scan_issue method.



1.  def $burp.evt_scan_issue(issue)
2.    meth_arry =  [
3.      'issue_name',
4.      'severity',
5.      'confidence',
6.      'protocol',
7.      'host',
8.      'url',
9.      'port',
10.     'issue_detail',
11.     'issue_background',      
12.     'remediation_detail',      
13.     'remediation_background',     
14.    ]
15.   
16.   meth_arry.each do |meth| 
17.     prnt("#{meth}", "#{issue.send("#{meth}")}")
18.   end
19.   
20.   hm_prnt('http_messages', issue.http_messages)
21. 
22. end


Line 1 - Defines the method ($burp.evt_scan_issue) and instantiates the "issue" object.


Lines 2-14  - Creates an Array called "meth_array" which consists of methods associated with the issue object instantiated on line 1.


Lines 16-18 - Iterates thru the meth_arry we created on line 2 picking out each method and then sends the method name and the method itself to prnt.


Line 20 - The http_message method attached to the issue object isn't in the meth_arry because it can't be called directly and converted to a string. This is because http_message is a an array of classes. Each class has it's own methods. So, we made a special prnt method for it called hm_prnt. 


Well that is all for Part 3 of this series. Part 4 will cover some of the other methods listed in the first part of this post. If you have any feedback please provide it so that the series can be improved upon.

Happy Hacking,


~cktricky

Buby Script Basics Part 2

In part 1 of this series, we've discussed a few options via the command line. In this part of the series, we will focus on actually writing a script. If you remember, to run the script you can type:

jruby -S buby -B burp.jar -r myscript.rb

**(myscript.rb is your buby script)**

I've provided some sample scripts Here .

Lets cover one of the most used methods (in my opinion/experience) exposed by buby called "evt_proxy_message". I'd like to cover some of the objects exposed by this method and to best accomplish this task we will step through the cookie_snatch.rb script located Here.

So here is the code from "cookie_snatch.rb"

def $burp.evt_proxy_message(*param)
msg_ref, is_req, rhost, rport, is_https, http_meth, url, resourceType, status, req_content_type, message, action = param
  file = ('cookiez.txt')
  prefix = is_https ? "https://" : "http://"
  rurl = "#{prefix}://#{rhost}:#{rport}"
  if is_req == false
    spmsg = message.split("\n\n")
    short_msg = "#{spmsg[0]}"
    mitem = short_msg.match(/^Set-Cookie:.+$/) 
      if $burp.in_scope?(rurl)  
        if !mitem.nil?
          File.open(file, "a") {|f| f.write("#{mitem}")} 
        end
      end
  end   
 super(*param)
end

On the second line you see that we convert *param to 12 separate objects. Here is a brief explanation of each:

msg_ref

===== 

This is the request/response number. It is nothing more than a tracking number.

is_req

====

This is a boolean value, returns either true or false. If it is a request, this returns true, else, false.

rhost

===

This is your target's hostname ONLY. 

It does NOT include the prefix (http/s), rport (80/443), or path (/directory/something.php).

rport

===

This is the remote port value (80/443/etc)

is_https

======

Returns true when https and false when http.

http_meth

=======

This is the method (GET/POST/etc)

url

==

This is the path portion of a URL. Not the full URL itself.

Example: If the target was http://www.target.com/mydir/test.aspx then url would be 

/mydir/test.aspx

resourceType

==========

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 request messages.

req_content_type

============

String value, content-type header returned by the server. (nil for requests)

message

======

String value, the entire message, regardless of request/response, contains headers and body.

action

====

There are 4 types of actions 

ACTION_FOLLOW_RULES (0, this is the default)

ACTION_DO_INTERCEPT (1, direction to intercept a msg)

ACTION_DONT_INTERCEPT (2, don't intercept the msg)

ACTION_DROP (3, drops the in/outbound msg)

Example of using action (folks seem to have some confusion at times regarding this):

if rhost == "www.example.com

action[0] = 2

end

The above code logic is, if the rhost value is www.example.com then don't intercept. The full code can be found in dont_intercept.rb in the Buby-Scripts repo.

Back to the code:

Lines 3-5

Ln 3 is assigning cookiez.txt to 'file'.

Ln 4 is evaluating the boolean value behind is_https?. If it is true then prefix = https:// and if false, http://.

Ln 5 is creating a rurl object which consists of a string concatenation of prefix, rhost and rport.

Lines 6-9

Ln 6 is evaluating if is_req equals false (meaning it is a response). So unless it is a response, the code following it won't be run.

Ln 7 spmsg (split message) is the message string split by two newlines. This separates the headers from the body. Array item 0 of spmsg (spmsg[0]) is going to be the headers and spmsg[1] will be the body.

Ln 8 short_msg is assigned to spgmsg[0], converted to a string.

Ln 9 assigns mitem to a the Set-Cookie portion of the response header.

Lines 10-12

Ln 10 uses the method in_scope?, which takes the full URL. This is the reason for creating the rurl object on line 5. If the response is from a site that is in scope, we evaluate the next 2 lines of code.

Ln 11 basically if mitem (the Set-Cookie key, value) isn't nil, then we evaluate line 12.

Ln 12 Open the file (file is created on line 3 and it is cookiez.txt), and write to it. Because we have assigned "a" instead of "w", the cookies will be appended versus overwritten.

The rest of the code terminates "if" statements and sends the params up to the super class's version of evt_proxy_msg. This super(*params) can be nice when you'd like to modify data prior to it's arrival to Burp.

Okay, well hopefully this was a good start for those interested in extending Burp's capabilities.

Part 3 in this series will cover other useful methods exposed by Buby.

~Happy Hacking

cktricky

Buby Script Basics Part 1

For those of you who are new to Buby, it is a platform to write Ruby based extensions for the Burp Suite API and I'm going to attempt to cover some of the basics.  First let me say thank you to Tebo for providing his insight. Tebo is the author of the Buby.kicks_ass => true article. Additionally, thank you Eric Monti the creator of Buby. Buby's homepage is located Here .

Installing:

Although you can write Ruby code, this is a JRuby Gem. What does this mean? It means that the code execution environment is JRuby (Java+Ruby) and the Gem should be installed in the JRuby environment.

Lets install JRuby first:

Next, install the Buby Gem.

Basic example of running a script:

The options you see explained

jruby -S buby  => runs the jruby environment leveraging the buby gem

-i  => interactive, this means you can interact with Burp from the console.

-B => this is the location of your Burp jar file

-r => The script you'd like to run. This is an easy way to run the buby code you've created.

Finally, an example of sending a command to burp via the -i (interactive option). Here we produce an alert "Hello World".

Pre-command

Command

Post Command

Okay so that wraps up Part 1 of Buby Basics.

If you'd like some scripts to mess around before Part 2, you can find some scripts I put together Here.

~Happy Hacking

cktricky