Creating a basic extension

So you've set up the framework and have been using it.. but now you want to develop your own extension... Where to start?

If you did not notice, we've included a couple example skeletons for developers to look at so they have a nice base to work with. There are a couple of necessary calls to communicate with the framework and a little bit of a standard we've tried to enforce to make it cleaner for future extensions. For this post we'll go over a very basic extension.

First we'll start by importing some necessary modules
If you're planning on using a right click menu item you'll need to import the IMenuItemHandler module. As for the Extension import, this will always be necessary, it is the deciding factor if the extension will be imported or not.

from burp import IMenuItemHandler
from Extension import Extension

At this point we can now create our class. For all extensions that will be displayed in the GUI and imported will have to have 'Extension' subclassed... with the exception of an outbound extension that will be processed for each request, but that will be covered in a later date. The name of the class will by default be the name of the extension inside of the list. As a standard we've tried to implement a nice INFO dictionary at the beginning of all classes. By default it will print these values to that extensions Log tab so the user can view the extensions Name, Usage, and Author.

class SimpleSkeleton(Extension):
    INFO = {
        'Name'      :   'Simple Skeleton',
        'Usage'     :   'This is a Simple Example Skeleton',
        'Author'    :   'James Lester, Joseph Tartaro'
    }

Once this is complete you can now create the methods you would like for your extension. By default you'll start with a 'finishedLaunching' method that will always process the code once the GUI is finished loading. In this case we'll call the registerMenuItem method to add our right click menu demo. You can get more details on these methods by looking at the burp extender javadocs. In this case:
menuItemCaption - The caption to be displayed on the menu item.
menuItemHandler - The handler to be invoked when the user clicks on the menu item.

    def finishedLaunching(self):
        self.getCallBacks().registerMenuItem("Extension: ___Simple Example Menu Item___", MenuHandler(self))

Now we will create our 'MenuHandler' class with 'IMenuItemHandler' subclassed. Inside of here is the second aspect of our standard INFO dictionary, where it will print to the Log tab. Methods such as 'printLogTab' are available since 'Extension' was subclassed... you can view /Lib/lib/Extension.py to see the other methods that can be used if they're not covered in future tutorials. For this extension we're going to make the method 'menuItemClicked', this is method will be called every time the user clicks the menu item that we've registered. As an example for now, we'll include 'menuItemCaption' and 'messageInfo' from the IMenuItemHandler as arguments, these will be sent from Burp by default when right click the various aspects of the Burp GUI (selections, requests, etc). For now we'll print to the Log tab that "You clicked the simple example button!" and also list all of the URL's from the items selected by the user when they click our menu item.

class MenuHandler(IMenuItemHandler):

    def __init__(self, parent):
        self.parent = parent
        for key in ["Name", "Usage", "Author"]:
            self.parent.printLogTab("%s: %s\n" % (key, self.parent.INFO[key]))

    def menuItemClicked(self, menuItemCaption, messageInfo):
        self.parent.printLogTab("You clicked the simple example button!\n")
        msglen = len(messageInfo)
        for l in range(0,msglen):
            self.parent.printLogTab(str(messageInfo[l].getUrl()) + "\n")

Well, there you have it. A very basic extension that should explain some of the frameworks inner workings to get you started. Feel free to ask questions in the comments, forums, or even our IRC channel (#burp irc.2600.net) Example screenshots:

Extension code:

from burp import IMenuItemHandler
from Extension import Extension

class SimpleSkeleton(Extension):
    INFO = {
            'Name'      :   'Simple Skeleton',
            'Usage'     :   'This is a Simple Example Skeleton',
            'Author'    :   'James Lester, Joseph Tartaro'
    }
    def finishedLaunching(self):
        self.getCallBacks().registerMenuItem("Extension: ___Simple Example Menu Item___", MenuHandler(self))
        


class MenuHandler(IMenuItemHandler):

    def __init__(self, parent):
        self.parent = parent
        for key in ["Name", "Usage", "Author"]:
            self.parent.printLogTab("%s: %s\n" % (key, self.parent.INFO[key]))

    def menuItemClicked(self, menuItemCaption, messageInfo):
        self.parent.printLogTab("You clicked the simple example button!\n")
        msglen = len(messageInfo)
        for l in range(0,msglen):
            #print all selected items in "scope" area
            self.parent.printLogTab(str(messageInfo[l].getUrl()) + "\n")
            #(\/)(*;;;;*)(\/) whoop! whoop! whoop! whoop!