burp
Interface IBurpExtenderCallbacks


public interface IBurpExtenderCallbacks

This interface is used by Burp Suite to pass to implementations of the IBurpExtender interface a set of callback methods which can be used by implementations to perform various actions within Burp Suite. If an implementation of IBurpExtender is loaded then on startup Burp Suite will invoke the implementation's registerExtenderCallbacks method (if present) and pass to the implementation an instance of the IBurpExtenderCallbacks interface. The implementation may then invoke the methods of this instance as it sees fit in order to extend Burp Suite's functionality.


Method Summary
 void addToSiteMap(IHttpRequestResponse item)
          This method can be used to add an item to Burp's site map with the specified request/response details.
 IScanQueueItem doActiveScan(java.lang.String host, int port, boolean useHttps, byte[] request)
          This method can be used to send an HTTP request to the Burp Scanner tool to perform an active vulnerability scan.
 IScanQueueItem doActiveScan(java.lang.String host, int port, boolean useHttps, byte[] request, java.util.List<int[]> insertionPointOffsets)
          This method can be used to send an HTTP request to the Burp Scanner tool to perform an active vulnerability scan, based on a custom list of insertion points that are to be scanned.
 void doPassiveScan(java.lang.String host, int port, boolean useHttps, byte[] request, byte[] response)
          This method can be used to send an HTTP request to the Burp Scanner tool to perform a passive vulnerability scan.
 void excludeFromScope(java.net.URL url)
          This method can be used to exclude the specified URL from the Suite-wide scope.
 void exitSuite(boolean promptUser)
          This method can be used to shut down Burp programmatically, with an optional prompt to the user.
 java.lang.String[] getBurpVersion()
          This method retrieves information about the version of Burp in which the extension is running.
 java.lang.String[] getHeaders(byte[] message)
          This method parses the specified request and returns details of each HTTP header.
 java.lang.String[][] getParameters(byte[] request)
          This method parses the specified request and returns details of each request parameter.
 IHttpRequestResponse[] getProxyHistory()
          This method returns details of all items in the proxy history.
 IScanIssue[] getScanIssues(java.lang.String urlPrefix)
          This method returns all of the current scan issues for URLs matching the specified literal prefix.
 IHttpRequestResponse[] getSiteMap(java.lang.String urlPrefix)
          This method returns details of items in the site map.
 void includeInScope(java.net.URL url)
          This method can be used to include the specified URL in the Suite-wide scope.
 boolean isInScope(java.net.URL url)
          This method can be used to query whether a specified URL is within the current Suite-wide scope.
 void issueAlert(java.lang.String message)
          This method can be used to display a specified message in the Burp Suite alerts tab.
 void loadConfig(java.util.Map config)
          This method causes Burp to load a new configuration from the Map of name/value Strings provided.
 byte[] makeHttpRequest(java.lang.String host, int port, boolean useHttps, byte[] request)
          This method can be used to issue arbitrary HTTP requests and retrieve their responses.
 void registerMenuItem(java.lang.String menuItemCaption, IMenuItemHandler menuItemHandler)
          This method can be used to register a new menu item which will appear on the various context menus that are used throughout Burp Suite to handle user-driven actions.
 void restoreState(java.io.File file)
          This method can be used to restore Burp's state from a specified saved state file.
 java.util.Map saveConfig()
          This method causes Burp to save all of its current configuration as a Map of name/value Strings.
 void saveState(java.io.File file)
          This method can be used to save Burp's state to a specified file.
 void sendToIntruder(java.lang.String host, int port, boolean useHttps, byte[] request)
          This method can be used to send an HTTP request to the Burp Intruder tool.
 void sendToRepeater(java.lang.String host, int port, boolean useHttps, byte[] request, java.lang.String tabCaption)
          This method can be used to send an HTTP request to the Burp Repeater tool.
 void sendToSpider(java.net.URL url)
          This method can be used to send a seed URL to the Burp Spider tool.
 void setProxyInterceptionEnabled(boolean enabled)
          This method sets the interception mode for Burp Proxy.
 

Method Detail

makeHttpRequest

byte[] makeHttpRequest(java.lang.String host,
                       int port,
                       boolean useHttps,
                       byte[] request)
                       throws java.lang.Exception
This method can be used to issue arbitrary HTTP requests and retrieve their responses.

Parameters:
host - The hostname of the remote HTTP server.
port - The port of the remote HTTP server.
useHttps - Flags whether the protocol is HTTPS or HTTP.
request - The full HTTP request.
Returns:
The full response retrieved from the remote server.
Throws:
java.lang.Exception

sendToRepeater

void sendToRepeater(java.lang.String host,
                    int port,
                    boolean useHttps,
                    byte[] request,
                    java.lang.String tabCaption)
                    throws java.lang.Exception
This method can be used to send an HTTP request to the Burp Repeater tool. The request will be displayed in the user interface, but will not be issued until the user initiates this action.

Parameters:
host - The hostname of the remote HTTP server.
port - The port of the remote HTTP server.
useHttps - Flags whether the protocol is HTTPS or HTTP.
request - The full HTTP request.
tabCaption - An optional caption which will appear on the Repeater tab containing the request. If this value is null then a default tab index will be displayed.
Throws:
java.lang.Exception

sendToIntruder

void sendToIntruder(java.lang.String host,
                    int port,
                    boolean useHttps,
                    byte[] request)
                    throws java.lang.Exception
This method can be used to send an HTTP request to the Burp Intruder tool. The request will be displayed in the user interface, and markers for attack payloads will be placed into default locations within the request.

Parameters:
host - The hostname of the remote HTTP server.
port - The port of the remote HTTP server.
useHttps - Flags whether the protocol is HTTPS or HTTP.
request - The full HTTP request.
Throws:
java.lang.Exception

sendToSpider

void sendToSpider(java.net.URL url)
                  throws java.lang.Exception
This method can be used to send a seed URL to the Burp Spider tool. If the URL is not within the current Spider scope, the user will be asked if they wish to add the URL to the scope. If the Spider is not currently running, it will be started. The seed URL will be requested, and the Spider will process the application's response in the normal way.

Parameters:
url - The new seed URL to begin spidering from.
Throws:
java.lang.Exception

doActiveScan

IScanQueueItem doActiveScan(java.lang.String host,
                            int port,
                            boolean useHttps,
                            byte[] request)
                            throws java.lang.Exception
This method can be used to send an HTTP request to the Burp Scanner tool to perform an active vulnerability scan. If the request is not within the current active scanning scope, the user will be asked if they wish to proceed with the scan.

Parameters:
host - The hostname of the remote HTTP server.
port - The port of the remote HTTP server.
useHttps - Flags whether the protocol is HTTPS or HTTP.
request - The full HTTP request.
Returns:
The resulting scan queue item.
Throws:
java.lang.Exception

doActiveScan

IScanQueueItem doActiveScan(java.lang.String host,
                            int port,
                            boolean useHttps,
                            byte[] request,
                            java.util.List<int[]> insertionPointOffsets)
                            throws java.lang.Exception
This method can be used to send an HTTP request to the Burp Scanner tool to perform an active vulnerability scan, based on a custom list of insertion points that are to be scanned. If the request is not within the current active scanning scope, the user will be asked if they wish to proceed with the scan.

Parameters:
host - The hostname of the remote HTTP server.
port - The port of the remote HTTP server.
useHttps - Flags whether the protocol is HTTPS or HTTP.
request - The full HTTP request.
insertionPointOffsets - A list of index pairs representing the positions of the insertion points that should be scanned. Each item in the list must be an int[2] array containing the start and end offsets for the insertion point.
Returns:
The resulting scan queue item.
Throws:
java.lang.Exception

doPassiveScan

void doPassiveScan(java.lang.String host,
                   int port,
                   boolean useHttps,
                   byte[] request,
                   byte[] response)
                   throws java.lang.Exception
This method can be used to send an HTTP request to the Burp Scanner tool to perform a passive vulnerability scan.

Parameters:
host - The hostname of the remote HTTP server.
port - The port of the remote HTTP server.
useHttps - Flags whether the protocol is HTTPS or HTTP.
request - The full HTTP request.
response - The full HTTP response.
Throws:
java.lang.Exception

isInScope

boolean isInScope(java.net.URL url)
                  throws java.lang.Exception
This method can be used to query whether a specified URL is within the current Suite-wide scope.

Parameters:
url - The URL to query.
Returns:
Returns true if the URL is within the current Suite-wide scope.
Throws:
java.lang.Exception

includeInScope

void includeInScope(java.net.URL url)
                    throws java.lang.Exception
This method can be used to include the specified URL in the Suite-wide scope.

Parameters:
url - The URL to include in the Suite-wide scope.
Throws:
java.lang.Exception

excludeFromScope

void excludeFromScope(java.net.URL url)
                      throws java.lang.Exception
This method can be used to exclude the specified URL from the Suite-wide scope.

Parameters:
url - The URL to exclude from the Suite-wide scope.
Throws:
java.lang.Exception

issueAlert

void issueAlert(java.lang.String message)
This method can be used to display a specified message in the Burp Suite alerts tab.

Parameters:
message - The alert message to display.

getProxyHistory

IHttpRequestResponse[] getProxyHistory()
This method returns details of all items in the proxy history.

Returns:
The contents of the proxy history.

getSiteMap

IHttpRequestResponse[] getSiteMap(java.lang.String urlPrefix)
This method returns details of items in the site map.

Parameters:
urlPrefix - This parameter can be used to specify a URL prefix, in order to extract a specific subset of the site map. The method performs a simple case-sensitive text match, returning all site map items whose URL begins with the specified prefix. If this parameter is null, the entire site map is returned.
Returns:
Details of items in the site map.

addToSiteMap

void addToSiteMap(IHttpRequestResponse item)
This method can be used to add an item to Burp's site map with the specified request/response details. This will overwrite the details of any existing matching item in the site map.

Parameters:
item - Details of the item to be added to the site map

restoreState

void restoreState(java.io.File file)
                  throws java.lang.Exception
This method can be used to restore Burp's state from a specified saved state file. This method blocks until the restore operation is completed, and must not be called from the event thread.

Parameters:
file - The file containing Burp's saved state.
Throws:
java.lang.Exception

saveState

void saveState(java.io.File file)
               throws java.lang.Exception
This method can be used to save Burp's state to a specified file. This method blocks until the save operation is completed, and must not be called from the event thread.

Parameters:
file - The file to save Burp's state in.
Throws:
java.lang.Exception

getParameters

java.lang.String[][] getParameters(byte[] request)
                                   throws java.lang.Exception
This method parses the specified request and returns details of each request parameter.

Parameters:
request - The request to be parsed.
Returns:
An array of: String[] { name, value, type } containing details of the parameters contained within the request.
Throws:
java.lang.Exception

getHeaders

java.lang.String[] getHeaders(byte[] message)
                              throws java.lang.Exception
This method parses the specified request and returns details of each HTTP header.

Parameters:
message - The request to be parsed.
Returns:
An array of HTTP headers.
Throws:
java.lang.Exception

getScanIssues

IScanIssue[] getScanIssues(java.lang.String urlPrefix)
This method returns all of the current scan issues for URLs matching the specified literal prefix.

Parameters:
urlPrefix - This parameter can be used to specify a URL prefix, in order to extract a specific subset of scan issues. The method performs a simple case-sensitive text match, returning all scan issues whose URL begins with the specified prefix. If this parameter is null, all issues are returned.
Returns:
Details of the scan issues.

registerMenuItem

void registerMenuItem(java.lang.String menuItemCaption,
                      IMenuItemHandler menuItemHandler)
This method can be used to register a new menu item which will appear on the various context menus that are used throughout Burp Suite to handle user-driven actions.

Parameters:
menuItemCaption - The caption to be displayed on the menu item.
menuItemHandler - The handler to be invoked when the user clicks on the menu item.

saveConfig

java.util.Map saveConfig()
This method causes Burp to save all of its current configuration as a Map of name/value Strings.

Returns:
A Map of name/value Strings reflecting Burp's current configuration.

loadConfig

void loadConfig(java.util.Map config)
This method causes Burp to load a new configuration from the Map of name/value Strings provided. Any settings not specified in the Map will be restored to their default values. To selectively update only some settings and leave the rest unchanged, you should first call saveConfig to obtain Burp's current configuration, modify the relevant items in the Map, and then call loadConfig with the same Map.

Parameters:
config - A map of name/value Strings to use as Burp's new configuration.

setProxyInterceptionEnabled

void setProxyInterceptionEnabled(boolean enabled)
This method sets the interception mode for Burp Proxy.

Parameters:
enabled - Indicates whether interception of proxy messages should be enabled.

getBurpVersion

java.lang.String[] getBurpVersion()
This method retrieves information about the version of Burp in which the extension is running. It can be used by extensions to dynamically adjust their behavior depending on the functionality and APIs supported by the current version.

Returns:
An array of Strings comprised of: the product name (e.g. burp suite professional), the major version (e.g. 1.4), the minor version (e.g. 03)

exitSuite

void exitSuite(boolean promptUser)
This method can be used to shut down Burp programmatically, with an optional prompt to the user. If the method returns, the user cancelled the shutdown prompt.

Parameters:
promptUser - Indicates whether to prompt the user to confirm the shutdown.