burp
Interface IBurpExtender

public interface IBurpExtender

This interface allows third-party code to extend Burp Suite's functionality. Implementations must be called BurpExtender, in the package burp, must be declared public, and must provide a default (public, no-argument) constructor. On startup, Burp Suite searches its classpath for the class burp.BurpExtender, and attempts to dynamically load and instantiate this class. The IBurpExtender methods implemented will then be dynamically invoked as appropriate.

Partial implementations are acceptable. The class will be used provided at least one of the interface's methods is implemented.

To make use of the interface, create a class called BurpExtender, in the package burp, which implements one or more methods of the interface, and place this into the application's classpath at startup. For example, if Burp Suite is loaded from burp.jar, and BurpProxyExtender.jar contains the class burp.BurpExtender, use the following command to launch Burp Suite and load the IBurpExtender implementation:

    java -classpath burp.jar;BurpProxyExtender.jar burp.StartBurp

ACTION_FOLLOW_RULES

static final int ACTION_FOLLOW_RULES

Causes Burp Proxy to follow the current interception rules to determine the appropriate action to take for the message.

ACTION_DO_INTERCEPT

static final int ACTION_DO_INTERCEPT

Causes Burp Proxy to present the message to the user for manual review or modification.

ACTION_DONT_INTERCEPT

static final int ACTION_DONT_INTERCEPT

Causes Burp Proxy to forward the message to the remote server or client.

ACTION_DROP

static final int ACTION_DROP

Causes Burp Proxy to drop the message and close the client connection.

ACTION_FOLLOW_RULES_AND_REHOOK

static final int ACTION_FOLLOW_RULES_AND_REHOOK

Causes Burp Proxy to follow the current interception rules to determine the appropriate action to take for the message, and then make a second call to processProxyMessage.

ACTION_DO_INTERCEPT_AND_REHOOK

static final int ACTION_DO_INTERCEPT_AND_REHOOK

Causes Burp Proxy to present the message to the user for manual review or modification, and then make a second call to processProxyMessage.

ACTION_DONT_INTERCEPT_AND_REHOOK

static final int ACTION_DONT_INTERCEPT_AND_REHOOK

Causes Burp Proxy to skip user interception, and then make a second call to processProxyMessage.

setCommandLineArgs

void setCommandLineArgs(java.lang.String[] args)

This method is invoked immediately after the implementation's constructor to pass any command-line arguments that were passed to Burp Suite on startup. It allows implementations to control aspects of their behaviour at runtime by defining their own command-line arguments.

Parameters:

args - The command-line arguments passed to Burp Suite on startup.

processProxyMessage

byte[] processProxyMessage(int messageReference,
                           boolean messageIsRequest,
                           java.lang.String remoteHost,
                           int remotePort,
                           boolean serviceIsHttps,
                           java.lang.String httpMethod,
                           java.lang.String url,
                           java.lang.String resourceType,
                           java.lang.String statusCode,
                           java.lang.String responseContentType,
                           byte[] message,
                           int[] action)

This method is invoked by Burp Proxy whenever a client request or server response is received. It allows implementations to perform logging functions, modify the message, specify an action (intercept, drop, etc.) and perform any other arbitrary processing.

Parameters:

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

messageIsRequest - Flags whether the message is a client request or a server response.

remoteHost - The hostname of the remote HTTP server.

remotePort - The port of the remote HTTP server.

serviceIsHttps - Flags whether the protocol is HTTPS or HTTP.

httpMethod - The method verb used in the client request.

url - The requested URL.

resourceType - The filetype of the requested resource, or a zero-length string if the resource has no filetype.

statusCode - The HTTP status code returned by the server. This value is null for request messages.

responseContentType - The content-type string returned by the server. This value is null for request messages.

message - The full HTTP message.

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. Set action[0] to one of the other possible values to perform a different action.

Returns:

Implementations should return either (a) the same object received in the message paramater, or (b) a different object containing a modified message.

registerExtenderCallbacks

void registerExtenderCallbacks(IBurpExtenderCallbacks callbacks)

This method is invoked on startup. It registers an instance of the IBurpExtenderCallbacks interface, providing methods that may be invoked by the implementation to perform various actions. The call to registerExtenderCallbacks need not return, and implementations may use the invoking thread for any purpose.

Parameters:

callbacks - An implementation of the IBurpExtenderCallbacks interface.

applicationClosing

void applicationClosing()

This method is invoked immediately before Burp Suite exits. It allows implementations to carry out any clean-up actions necessary (e.g. flushing log files or closing database resources).

processHttpMessage

void processHttpMessage(java.lang.String toolName,
                        boolean messageIsRequest,
                        IHttpRequestResponse messageInfo)

This method is invoked whenever any of Burp's tools makes an HTTP request or receives a response. It allows extensions to intercept and modify the HTTP traffic of all Burp tools. For each request, the method is invoked after the request has been fully processed by the invoking tool and is about to be made on the network. For each response, the method is invoked after the response has been received from the network and before any processing is performed by the invoking tool.

Parameters:

toolName - The name of the Burp tool which is making the request.

messageIsRequest - Indicates whether the message is a request or response.

messageInfo - Details of the HTTP message.

newScanIssue

void newScanIssue(IScanIssue issue)

This method is invoked whenever Burp Scanner discovers a new, unique issue, and can be used to perform customised reporting or logging of issues.

Parameters:

issue - Details of the new scan issue.