burp
Interface IBurpExtenderCallbacks


public interface IBurpExtenderCallbacks

This interface is used by Burp Suite to pass to extensions a set of callback methods that can be used by extensions to perform various actions within Burp. When an extension is loaded, Burp invokes its registerExtenderCallbacks() method and passes an instance of the IBurpExtenderCallbacks interface. The extension may then invoke the methods of this interface as required in order to extend Burp's functionality.


Field Summary
static int TOOL_COMPARER
          Flag used to identify the Burp Comparer tool.
static int TOOL_DECODER
          Flag used to identify the Burp Decoder tool.
static int TOOL_EXTENDER
          Flag used to identify the Burp Extender tool.
static int TOOL_INTRUDER
          Flag used to identify the Burp Intruder tool.
static int TOOL_PROXY
          Flag used to identify the Burp Proxy tool.
static int TOOL_REPEATER
          Flag used to identify the Burp Repeater tool.
static int TOOL_SCANNER
          Flag used to identify the Burp Scanner tool.
static int TOOL_SEQUENCER
          Flag used to identify the Burp Sequencer tool.
static int TOOL_SPIDER
          Flag used to identify the Burp Spider tool.
static int TOOL_SUITE
          Flag used to identify Burp Suite as a whole.
static int TOOL_TARGET
          Flag used to identify the Burp Target tool.
 
Method Summary
 void addScanIssue(IScanIssue issue)
          This method is used to register a new Scanner issue.
 void addSuiteTab(ITab tab)
          This method is used to add a custom tab to the main Burp Suite window.
 void addToSiteMap(IHttpRequestResponse item)
          This method can be used to add an item to Burp's site map with the specified request/response details.
 IHttpRequestResponseWithMarkers applyMarkers(IHttpRequestResponse httpRequestResponse, java.util.List<int[]> requestMarkers, java.util.List<int[]> responseMarkers)
          This method is used to apply markers to an HTTP request or response, at offsets into the message that are relevant for some particular purpose.
 IBurpCollaboratorClientContext createBurpCollaboratorClientContext()
          This method is used to create a new Burp Collaborator client context, which can be used to generate Burp Collaborator payloads and poll the Collaborator server for any network interactions that result from using those payloads.
 IMessageEditor createMessageEditor(IMessageEditorController controller, boolean editable)
          This method is used to create a new instance of Burp's HTTP message editor, for the extension to use in its own UI.
 ITextEditor createTextEditor()
          This method is used to create a new instance of Burp's plain text editor, for the extension to use in its own UI.
 void customizeUiComponent(java.awt.Component component)
          This method is used to customize UI components in line with Burp's UI style, including font size, colors, table line spacing, etc.
 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.
 void generateScanReport(java.lang.String format, IScanIssue[] issues, java.io.File file)
          This method is used to generate a report for the specified Scanner issues.
 java.lang.String[] getBurpVersion()
          This method retrieves information about the version of Burp in which the extension is running.
 java.lang.String[] getCommandLineArguments()
          This method returns the command line arguments that were passed to Burp on startup.
 java.util.List<IContextMenuFactory> getContextMenuFactories()
          This method is used to retrieve the context menu factories that are registered by the extension.
 java.util.List<ICookie> getCookieJarContents()
          This method is used to retrieve the contents of Burp's session handling cookie jar.
 java.lang.String getExtensionFilename()
          This method retrieves the absolute path name of the file from which the current extension was loaded.
 java.util.List<IExtensionStateListener> getExtensionStateListeners()
          This method is used to retrieve the extension state listeners that are registered by the extension.
 java.lang.String[] getHeaders(byte[] message)
          Deprecated. Use IExtensionHelpers.analyzeRequest() or IExtensionHelpers.analyzeResponse() instead.
 IExtensionHelpers getHelpers()
          This method is used to obtain an IExtensionHelpers object, which can be used by the extension to perform numerous useful tasks.
 java.util.List<IHttpListener> getHttpListeners()
          This method is used to retrieve the HTTP listeners that are registered by the extension.
 java.util.List<IIntruderPayloadGeneratorFactory> getIntruderPayloadGeneratorFactories()
          This method is used to retrieve the Intruder payload generator factories that are registered by the extension.
 java.util.List<IIntruderPayloadProcessor> getIntruderPayloadProcessors()
          This method is used to retrieve the Intruder payload processors that are registered by the extension.
 java.util.List<IMessageEditorTabFactory> getMessageEditorTabFactories()
          This method is used to retrieve the message editor tab factories that are registered by the extension.
 java.lang.String[][] getParameters(byte[] request)
          Deprecated. Use IExtensionHelpers.analyzeRequest() instead.
 IHttpRequestResponse[] getProxyHistory()
          This method returns details of all items in the Proxy history.
 java.util.List<IProxyListener> getProxyListeners()
          This method is used to retrieve the Proxy listeners that are registered by the extension.
 IScanIssue[] getScanIssues(java.lang.String urlPrefix)
          This method returns all of the current scan issues for URLs matching the specified literal prefix.
 java.util.List<IScannerCheck> getScannerChecks()
          This method is used to retrieve the Scanner checks that are registered by the extension.
 java.util.List<IScannerInsertionPointProvider> getScannerInsertionPointProviders()
          This method is used to retrieve the Scanner insertion point providers that are registered by the extension.
 java.util.List<IScannerListener> getScannerListeners()
          This method is used to retrieve the Scanner listeners that are registered by the extension.
 java.util.List<IScopeChangeListener> getScopeChangeListeners()
          This method is used to retrieve the scope change listeners that are registered by the extension.
 java.util.List<ISessionHandlingAction> getSessionHandlingActions()
          This method is used to retrieve the session handling actions that are registered by the extension.
 IHttpRequestResponse[] getSiteMap(java.lang.String urlPrefix)
          This method returns details of items in the site map.
 java.io.OutputStream getStderr()
          This method is used to obtain the current extension's standard error stream.
 java.io.OutputStream getStdout()
          This method is used to obtain the current extension's standard output stream.
 java.lang.String getToolName(int toolFlag)
          This method is used to obtain the descriptive name for the Burp tool identified by the tool flag provided.
 void includeInScope(java.net.URL url)
          This method can be used to include the specified URL in the Suite-wide scope.
 boolean isExtensionBapp()
          This method determines whether the current extension was loaded as a BApp (a Burp App from the BApp Store).
 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<java.lang.String,java.lang.String> config)
          Deprecated. Use loadConfigFromJson() instead.
 void loadConfigFromJson(java.lang.String config)
          This method causes Burp to load a new project-level configuration from the JSON String provided.
 java.lang.String loadExtensionSetting(java.lang.String name)
          This method is used to load configuration settings for the extension that were saved using the method saveExtensionSetting().
 IHttpRequestResponse makeHttpRequest(IHttpService httpService, byte[] request)
          This method can be used to issue HTTP requests and retrieve their responses.
 byte[] makeHttpRequest(java.lang.String host, int port, boolean useHttps, byte[] request)
          This method can be used to issue HTTP requests and retrieve their responses.
 void printError(java.lang.String error)
          This method prints a line of output to the current extension's standard error stream.
 void printOutput(java.lang.String output)
          This method prints a line of output to the current extension's standard output stream.
 void registerContextMenuFactory(IContextMenuFactory factory)
          This method is used to register a factory for custom context menu items.
 void registerExtensionStateListener(IExtensionStateListener listener)
          This method is used to register a listener which will be notified of changes to the extension's state.
 void registerHttpListener(IHttpListener listener)
          This method is used to register a listener which will be notified of requests and responses made by any Burp tool.
 void registerIntruderPayloadGeneratorFactory(IIntruderPayloadGeneratorFactory factory)
          This method is used to register a factory for Intruder payloads.
 void registerIntruderPayloadProcessor(IIntruderPayloadProcessor processor)
          This method is used to register a custom Intruder payload processor.
 void registerMenuItem(java.lang.String menuItemCaption, IMenuItemHandler menuItemHandler)
          Deprecated. Use registerContextMenuFactory() instead.
 void registerMessageEditorTabFactory(IMessageEditorTabFactory factory)
          This method is used to register a factory for custom message editor tabs.
 void registerProxyListener(IProxyListener listener)
          This method is used to register a listener which will be notified of requests and responses being processed by the Proxy tool.
 void registerScannerCheck(IScannerCheck check)
          This method is used to register a custom Scanner check.
 void registerScannerInsertionPointProvider(IScannerInsertionPointProvider provider)
          This method is used to register a provider of Scanner insertion points.
 void registerScannerListener(IScannerListener listener)
          This method is used to register a listener which will be notified of new issues that are reported by the Scanner tool.
 void registerScopeChangeListener(IScopeChangeListener listener)
          This method is used to register a listener which will be notified of changes to Burp's suite-wide target scope.
 void registerSessionHandlingAction(ISessionHandlingAction action)
          This method is used to register a custom session handling action.
 void removeContextMenuFactory(IContextMenuFactory factory)
          This method is used to remove a context menu factory that has been registered by the extension.
 void removeExtensionStateListener(IExtensionStateListener listener)
          This method is used to remove an extension state listener that has been registered by the extension.
 void removeHttpListener(IHttpListener listener)
          This method is used to remove an HTTP listener that has been registered by the extension.
 void removeIntruderPayloadGeneratorFactory(IIntruderPayloadGeneratorFactory factory)
          This method is used to remove an Intruder payload generator factory that has been registered by the extension.
 void removeIntruderPayloadProcessor(IIntruderPayloadProcessor processor)
          This method is used to remove an Intruder payload processor that has been registered by the extension.
 void removeMessageEditorTabFactory(IMessageEditorTabFactory factory)
          This method is used to remove a message editor tab factory that has been registered by the extension.
 void removeProxyListener(IProxyListener listener)
          This method is used to remove a Proxy listener that has been registered by the extension.
 void removeScannerCheck(IScannerCheck check)
          This method is used to remove a Scanner check that has been registered by the extension.
 void removeScannerInsertionPointProvider(IScannerInsertionPointProvider provider)
          This method is used to remove a Scanner insertion point provider that has been registered by the extension.
 void removeScannerListener(IScannerListener listener)
          This method is used to remove a Scanner listener that has been registered by the extension.
 void removeScopeChangeListener(IScopeChangeListener listener)
          This method is used to remove a scope change listener that has been registered by the extension.
 void removeSessionHandlingAction(ISessionHandlingAction action)
          This method is used to remove a session handling action that has been registered by the extension.
 void removeSuiteTab(ITab tab)
          This method is used to remove a previously-added tab from the main Burp Suite window.
 void restoreState(java.io.File file)
          Deprecated. State files have been replaced with Burp project files.
 IHttpRequestResponsePersisted saveBuffersToTempFiles(IHttpRequestResponse httpRequestResponse)
          This method is used to save the request and response of an IHttpRequestResponse object to temporary files, so that they are no longer held in memory.
 java.util.Map<java.lang.String,java.lang.String> saveConfig()
          Deprecated. Use saveConfigAsJson() instead.
 java.lang.String saveConfigAsJson(java.lang.String... configPaths)
          This method causes Burp to save its current project-level configuration in JSON format.
 void saveExtensionSetting(java.lang.String name, java.lang.String value)
          This method is used to save configuration settings for the extension in a persistent way that survives reloads of the extension and of Burp Suite.
 void saveState(java.io.File file)
          Deprecated. State files have been replaced with Burp project files.
 ITempFile saveToTempFile(byte[] buffer)
          This method is used to create a temporary file on disk containing the provided data.
 void sendToComparer(byte[] data)
          This method can be used to send data to the Comparer tool.
 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 sendToIntruder(java.lang.String host, int port, boolean useHttps, byte[] request, java.util.List<int[]> payloadPositionOffsets)
          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 setExtensionName(java.lang.String name)
          This method is used to set the display name for the current extension, which will be displayed within the user interface for the Extender tool.
 void setProxyInterceptionEnabled(boolean enabled)
          This method sets the master interception mode for Burp Proxy.
 void unloadExtension()
          This method is used to unload the extension from Burp Suite.
 void updateCookieJar(ICookie cookie)
          This method is used to update the contents of Burp's session handling cookie jar.
 

Field Detail

TOOL_SUITE

static final int TOOL_SUITE
Flag used to identify Burp Suite as a whole.

See Also:
Constant Field Values

TOOL_TARGET

static final int TOOL_TARGET
Flag used to identify the Burp Target tool.

See Also:
Constant Field Values

TOOL_PROXY

static final int TOOL_PROXY
Flag used to identify the Burp Proxy tool.

See Also:
Constant Field Values

TOOL_SPIDER

static final int TOOL_SPIDER
Flag used to identify the Burp Spider tool.

See Also:
Constant Field Values

TOOL_SCANNER

static final int TOOL_SCANNER
Flag used to identify the Burp Scanner tool.

See Also:
Constant Field Values

TOOL_INTRUDER

static final int TOOL_INTRUDER
Flag used to identify the Burp Intruder tool.

See Also:
Constant Field Values

TOOL_REPEATER

static final int TOOL_REPEATER
Flag used to identify the Burp Repeater tool.

See Also:
Constant Field Values

TOOL_SEQUENCER

static final int TOOL_SEQUENCER
Flag used to identify the Burp Sequencer tool.

See Also:
Constant Field Values

TOOL_DECODER

static final int TOOL_DECODER
Flag used to identify the Burp Decoder tool.

See Also:
Constant Field Values

TOOL_COMPARER

static final int TOOL_COMPARER
Flag used to identify the Burp Comparer tool.

See Also:
Constant Field Values

TOOL_EXTENDER

static final int TOOL_EXTENDER
Flag used to identify the Burp Extender tool.

See Also:
Constant Field Values
Method Detail

setExtensionName

void setExtensionName(java.lang.String name)
This method is used to set the display name for the current extension, which will be displayed within the user interface for the Extender tool.

Parameters:
name - The extension name.

getHelpers

IExtensionHelpers getHelpers()
This method is used to obtain an IExtensionHelpers object, which can be used by the extension to perform numerous useful tasks.

Returns:
An object containing numerous helper methods, for tasks such as building and analyzing HTTP requests.

getStdout

java.io.OutputStream getStdout()
This method is used to obtain the current extension's standard output stream. Extensions should write all output to this stream, allowing the Burp user to configure how that output is handled from within the UI.

Returns:
The extension's standard output stream.

getStderr

java.io.OutputStream getStderr()
This method is used to obtain the current extension's standard error stream. Extensions should write all error messages to this stream, allowing the Burp user to configure how that output is handled from within the UI.

Returns:
The extension's standard error stream.

printOutput

void printOutput(java.lang.String output)
This method prints a line of output to the current extension's standard output stream.

Parameters:
output - The message to print.

printError

void printError(java.lang.String error)
This method prints a line of output to the current extension's standard error stream.

Parameters:
error - The message to print.

registerExtensionStateListener

void registerExtensionStateListener(IExtensionStateListener listener)
This method is used to register a listener which will be notified of changes to the extension's state. Note: Any extensions that start background threads or open system resources (such as files or database connections) should register a listener and terminate threads / close resources when the extension is unloaded.

Parameters:
listener - An object created by the extension that implements the IExtensionStateListener interface.

getExtensionStateListeners

java.util.List<IExtensionStateListener> getExtensionStateListeners()
This method is used to retrieve the extension state listeners that are registered by the extension.

Returns:
A list of extension state listeners that are currently registered by this extension.

removeExtensionStateListener

void removeExtensionStateListener(IExtensionStateListener listener)
This method is used to remove an extension state listener that has been registered by the extension.

Parameters:
listener - The extension state listener to be removed.

registerHttpListener

void registerHttpListener(IHttpListener listener)
This method is used to register a listener which will be notified of requests and responses made by any Burp tool. Extensions can perform custom analysis or modification of these messages by registering an HTTP listener.

Parameters:
listener - An object created by the extension that implements the IHttpListener interface.

getHttpListeners

java.util.List<IHttpListener> getHttpListeners()
This method is used to retrieve the HTTP listeners that are registered by the extension.

Returns:
A list of HTTP listeners that are currently registered by this extension.

removeHttpListener

void removeHttpListener(IHttpListener listener)
This method is used to remove an HTTP listener that has been registered by the extension.

Parameters:
listener - The HTTP listener to be removed.

registerProxyListener

void registerProxyListener(IProxyListener listener)
This method is used to register a listener which will be notified of requests and responses being processed by the Proxy tool. Extensions can perform custom analysis or modification of these messages, and control in-UI message interception, by registering a proxy listener.

Parameters:
listener - An object created by the extension that implements the IProxyListener interface.

getProxyListeners

java.util.List<IProxyListener> getProxyListeners()
This method is used to retrieve the Proxy listeners that are registered by the extension.

Returns:
A list of Proxy listeners that are currently registered by this extension.

removeProxyListener

void removeProxyListener(IProxyListener listener)
This method is used to remove a Proxy listener that has been registered by the extension.

Parameters:
listener - The Proxy listener to be removed.

registerScannerListener

void registerScannerListener(IScannerListener listener)
This method is used to register a listener which will be notified of new issues that are reported by the Scanner tool. Extensions can perform custom analysis or logging of Scanner issues by registering a Scanner listener.

Parameters:
listener - An object created by the extension that implements the IScannerListener interface.

getScannerListeners

java.util.List<IScannerListener> getScannerListeners()
This method is used to retrieve the Scanner listeners that are registered by the extension.

Returns:
A list of Scanner listeners that are currently registered by this extension.

removeScannerListener

void removeScannerListener(IScannerListener listener)
This method is used to remove a Scanner listener that has been registered by the extension.

Parameters:
listener - The Scanner listener to be removed.

registerScopeChangeListener

void registerScopeChangeListener(IScopeChangeListener listener)
This method is used to register a listener which will be notified of changes to Burp's suite-wide target scope.

Parameters:
listener - An object created by the extension that implements the IScopeChangeListener interface.

getScopeChangeListeners

java.util.List<IScopeChangeListener> getScopeChangeListeners()
This method is used to retrieve the scope change listeners that are registered by the extension.

Returns:
A list of scope change listeners that are currently registered by this extension.

removeScopeChangeListener

void removeScopeChangeListener(IScopeChangeListener listener)
This method is used to remove a scope change listener that has been registered by the extension.

Parameters:
listener - The scope change listener to be removed.

registerContextMenuFactory

void registerContextMenuFactory(IContextMenuFactory factory)
This method is used to register a factory for custom context menu items. When the user invokes a context menu anywhere within Burp, the factory will be passed details of the invocation event, and asked to provide any custom context menu items that should be shown.

Parameters:
factory - An object created by the extension that implements the IContextMenuFactory interface.

getContextMenuFactories

java.util.List<IContextMenuFactory> getContextMenuFactories()
This method is used to retrieve the context menu factories that are registered by the extension.

Returns:
A list of context menu factories that are currently registered by this extension.

removeContextMenuFactory

void removeContextMenuFactory(IContextMenuFactory factory)
This method is used to remove a context menu factory that has been registered by the extension.

Parameters:
factory - The context menu factory to be removed.

registerMessageEditorTabFactory

void registerMessageEditorTabFactory(IMessageEditorTabFactory factory)
This method is used to register a factory for custom message editor tabs. For each message editor that already exists, or is subsequently created, within Burp, the factory will be asked to provide a new instance of an IMessageEditorTab object, which can provide custom rendering or editing of HTTP messages.

Parameters:
factory - An object created by the extension that implements the IMessageEditorTabFactory interface.

getMessageEditorTabFactories

java.util.List<IMessageEditorTabFactory> getMessageEditorTabFactories()
This method is used to retrieve the message editor tab factories that are registered by the extension.

Returns:
A list of message editor tab factories that are currently registered by this extension.

removeMessageEditorTabFactory

void removeMessageEditorTabFactory(IMessageEditorTabFactory factory)
This method is used to remove a message editor tab factory that has been registered by the extension.

Parameters:
factory - The message editor tab factory to be removed.

registerScannerInsertionPointProvider

void registerScannerInsertionPointProvider(IScannerInsertionPointProvider provider)
This method is used to register a provider of Scanner insertion points. For each base request that is actively scanned, Burp will ask the provider to provide any custom scanner insertion points that are appropriate for the request.

Parameters:
provider - An object created by the extension that implements the IScannerInsertionPointProvider interface.

getScannerInsertionPointProviders

java.util.List<IScannerInsertionPointProvider> getScannerInsertionPointProviders()
This method is used to retrieve the Scanner insertion point providers that are registered by the extension.

Returns:
A list of Scanner insertion point providers that are currently registered by this extension.

removeScannerInsertionPointProvider

void removeScannerInsertionPointProvider(IScannerInsertionPointProvider provider)
This method is used to remove a Scanner insertion point provider that has been registered by the extension.

Parameters:
provider - The Scanner insertion point provider to be removed.

registerScannerCheck

void registerScannerCheck(IScannerCheck check)
This method is used to register a custom Scanner check. When performing scanning, Burp will ask the check to perform active or passive scanning on the base request, and report any Scanner issues that are identified.

Parameters:
check - An object created by the extension that implements the IScannerCheck interface.

getScannerChecks

java.util.List<IScannerCheck> getScannerChecks()
This method is used to retrieve the Scanner checks that are registered by the extension.

Returns:
A list of Scanner checks that are currently registered by this extension.

removeScannerCheck

void removeScannerCheck(IScannerCheck check)
This method is used to remove a Scanner check that has been registered by the extension.

Parameters:
check - The Scanner check to be removed.

registerIntruderPayloadGeneratorFactory

void registerIntruderPayloadGeneratorFactory(IIntruderPayloadGeneratorFactory factory)
This method is used to register a factory for Intruder payloads. Each registered factory will be available within the Intruder UI for the user to select as the payload source for an attack. When this is selected, the factory will be asked to provide a new instance of an IIntruderPayloadGenerator object, which will be used to generate payloads for the attack.

Parameters:
factory - An object created by the extension that implements the IIntruderPayloadGeneratorFactory interface.

getIntruderPayloadGeneratorFactories

java.util.List<IIntruderPayloadGeneratorFactory> getIntruderPayloadGeneratorFactories()
This method is used to retrieve the Intruder payload generator factories that are registered by the extension.

Returns:
A list of Intruder payload generator factories that are currently registered by this extension.

removeIntruderPayloadGeneratorFactory

void removeIntruderPayloadGeneratorFactory(IIntruderPayloadGeneratorFactory factory)
This method is used to remove an Intruder payload generator factory that has been registered by the extension.

Parameters:
factory - The Intruder payload generator factory to be removed.

registerIntruderPayloadProcessor

void registerIntruderPayloadProcessor(IIntruderPayloadProcessor processor)
This method is used to register a custom Intruder payload processor. Each registered processor will be available within the Intruder UI for the user to select as the action for a payload processing rule.

Parameters:
processor - An object created by the extension that implements the IIntruderPayloadProcessor interface.

getIntruderPayloadProcessors

java.util.List<IIntruderPayloadProcessor> getIntruderPayloadProcessors()
This method is used to retrieve the Intruder payload processors that are registered by the extension.

Returns:
A list of Intruder payload processors that are currently registered by this extension.

removeIntruderPayloadProcessor

void removeIntruderPayloadProcessor(IIntruderPayloadProcessor processor)
This method is used to remove an Intruder payload processor that has been registered by the extension.

Parameters:
processor - The Intruder payload processor to be removed.

registerSessionHandlingAction

void registerSessionHandlingAction(ISessionHandlingAction action)
This method is used to register a custom session handling action. Each registered action will be available within the session handling rule UI for the user to select as a rule action. Users can choose to invoke an action directly in its own right, or following execution of a macro.

Parameters:
action - An object created by the extension that implements the ISessionHandlingAction interface.

getSessionHandlingActions

java.util.List<ISessionHandlingAction> getSessionHandlingActions()
This method is used to retrieve the session handling actions that are registered by the extension.

Returns:
A list of session handling actions that are currently registered by this extension.

removeSessionHandlingAction

void removeSessionHandlingAction(ISessionHandlingAction action)
This method is used to remove a session handling action that has been registered by the extension.

Parameters:
action - The extension session handling action to be removed.

unloadExtension

void unloadExtension()
This method is used to unload the extension from Burp Suite.


addSuiteTab

void addSuiteTab(ITab tab)
This method is used to add a custom tab to the main Burp Suite window.

Parameters:
tab - An object created by the extension that implements the ITab interface.

removeSuiteTab

void removeSuiteTab(ITab tab)
This method is used to remove a previously-added tab from the main Burp Suite window.

Parameters:
tab - An object created by the extension that implements the ITab interface.

customizeUiComponent

void customizeUiComponent(java.awt.Component component)
This method is used to customize UI components in line with Burp's UI style, including font size, colors, table line spacing, etc. The action is performed recursively on any child components of the passed-in component.

Parameters:
component - The UI component to be customized.

createMessageEditor

IMessageEditor createMessageEditor(IMessageEditorController controller,
                                   boolean editable)
This method is used to create a new instance of Burp's HTTP message editor, for the extension to use in its own UI.

Parameters:
controller - An object created by the extension that implements the IMessageEditorController interface. This parameter is optional and may be null. If it is provided, then the message editor will query the controller when required to obtain details about the currently displayed message, including the IHttpService for the message, and the associated request or response message. If a controller is not provided, then the message editor will not support context menu actions, such as sending requests to other Burp tools.
editable - Indicates whether the editor created should be editable, or used only for message viewing.
Returns:
An object that implements the IMessageEditor interface, and which the extension can use in its own UI.

getCommandLineArguments

java.lang.String[] getCommandLineArguments()
This method returns the command line arguments that were passed to Burp on startup.

Returns:
The command line arguments that were passed to Burp on startup.

saveExtensionSetting

void saveExtensionSetting(java.lang.String name,
                          java.lang.String value)
This method is used to save configuration settings for the extension in a persistent way that survives reloads of the extension and of Burp Suite. Saved settings can be retrieved using the method loadExtensionSetting().

Parameters:
name - The name of the setting.
value - The value of the setting. If this value is null then any existing setting with the specified name will be removed.

loadExtensionSetting

java.lang.String loadExtensionSetting(java.lang.String name)
This method is used to load configuration settings for the extension that were saved using the method saveExtensionSetting().

Parameters:
name - The name of the setting.
Returns:
The value of the setting, or null if no value is set.

createTextEditor

ITextEditor createTextEditor()
This method is used to create a new instance of Burp's plain text editor, for the extension to use in its own UI.

Returns:
An object that implements the ITextEditor interface, and which the extension can use in its own UI.

sendToRepeater

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

sendToIntruder

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

sendToIntruder

void sendToIntruder(java.lang.String host,
                    int port,
                    boolean useHttps,
                    byte[] request,
                    java.util.List<int[]> payloadPositionOffsets)
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 the specified 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.
payloadPositionOffsets - A list of index pairs representing the payload positions to be used. Each item in the list must be an int[2] array containing the start and end offsets for the payload position.

sendToComparer

void sendToComparer(byte[] data)
This method can be used to send data to the Comparer tool.

Parameters:
data - The data to be sent to Comparer.

sendToSpider

void sendToSpider(java.net.URL url)
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.

doActiveScan

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

doActiveScan

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

doPassiveScan

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.

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.

makeHttpRequest

IHttpRequestResponse makeHttpRequest(IHttpService httpService,
                                     byte[] request)
This method can be used to issue HTTP requests and retrieve their responses.

Parameters:
httpService - The HTTP service to which the request should be sent.
request - The full HTTP request.
Returns:
An object that implements the IHttpRequestResponse interface, and which the extension can query to obtain the details of the response.

makeHttpRequest

byte[] makeHttpRequest(java.lang.String host,
                       int port,
                       boolean useHttps,
                       byte[] request)
This method can be used to issue 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.

isInScope

boolean isInScope(java.net.URL url)
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.

includeInScope

void includeInScope(java.net.URL url)
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.

excludeFromScope

void excludeFromScope(java.net.URL url)
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.

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.

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.

generateScanReport

void generateScanReport(java.lang.String format,
                        IScanIssue[] issues,
                        java.io.File file)
This method is used to generate a report for the specified Scanner issues. The report format can be specified. For all other reporting options, the default settings that appear in the reporting UI wizard are used.

Parameters:
format - The format to be used in the report. Accepted values are HTML and XML.
issues - The Scanner issues to be reported.
file - The file to which the report will be saved.

getCookieJarContents

java.util.List<ICookie> getCookieJarContents()
This method is used to retrieve the contents of Burp's session handling cookie jar. Extensions that provide an ISessionHandlingAction can query and update the cookie jar in order to handle unusual session handling mechanisms.

Returns:
A list of ICookie objects representing the contents of Burp's session handling cookie jar.

updateCookieJar

void updateCookieJar(ICookie cookie)
This method is used to update the contents of Burp's session handling cookie jar. Extensions that provide an ISessionHandlingAction can query and update the cookie jar in order to handle unusual session handling mechanisms.

Parameters:
cookie - An ICookie object containing details of the cookie to be updated. If the cookie jar already contains a cookie that matches the specified domain and name, then that cookie will be updated with the new value and expiration, unless the new value is null, in which case the cookie will be removed. If the cookie jar does not already contain a cookie that matches the specified domain and name, then the cookie will be added.

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

@Deprecated
void restoreState(java.io.File file)
Deprecated. State files have been replaced with Burp project files.

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 dispatch thread.

Parameters:
file - The file containing Burp's saved state.

saveState

@Deprecated
void saveState(java.io.File file)
Deprecated. State files have been replaced with Burp project files.

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 dispatch thread.

Parameters:
file - The file to save Burp's state in.

saveConfig

@Deprecated
java.util.Map<java.lang.String,java.lang.String> saveConfig()
Deprecated. Use saveConfigAsJson() instead.

This method is no longer supported. Please use saveConfigAsJson() instead.

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

loadConfig

@Deprecated
void loadConfig(java.util.Map<java.lang.String,java.lang.String> config)
Deprecated. Use loadConfigFromJson() instead.

This method is no longer supported. Please use loadConfigFromJson() instead.

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

saveConfigAsJson

java.lang.String saveConfigAsJson(java.lang.String... configPaths)
This method causes Burp to save its current project-level configuration in JSON format. This is the same format that can be saved and loaded via the Burp user interface. To include only certain sections of the configuration, you can optionally supply the path to each section that should be included, for example: "project_options.connections". If no paths are provided, then the entire configuration will be saved.

Parameters:
configPaths - A list of Strings representing the path to each configuration section that should be included.
Returns:
A String representing the current configuration in JSON format.

loadConfigFromJson

void loadConfigFromJson(java.lang.String config)
This method causes Burp to load a new project-level configuration from the JSON String provided. This is the same format that can be saved and loaded via the Burp user interface. Partial configurations are acceptable, and any settings not specified will be left unmodified. Any user-level configuration options contained in the input will be ignored.

Parameters:
config - A JSON String containing the new configuration.

setProxyInterceptionEnabled

void setProxyInterceptionEnabled(boolean enabled)
This method sets the master 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.5), the minor version (e.g. 03)

getExtensionFilename

java.lang.String getExtensionFilename()
This method retrieves the absolute path name of the file from which the current extension was loaded.

Returns:
The absolute path name of the file from which the current extension was loaded.

isExtensionBapp

boolean isExtensionBapp()
This method determines whether the current extension was loaded as a BApp (a Burp App from the BApp Store).

Returns:
Returns true if the current extension was loaded as a BApp.

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 canceled the shutdown prompt.

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

saveToTempFile

ITempFile saveToTempFile(byte[] buffer)
This method is used to create a temporary file on disk containing the provided data. Extensions can use temporary files for long-term storage of runtime data, avoiding the need to retain that data in memory.

Parameters:
buffer - The data to be saved to a temporary file.
Returns:
An object that implements the ITempFile interface.

saveBuffersToTempFiles

IHttpRequestResponsePersisted saveBuffersToTempFiles(IHttpRequestResponse httpRequestResponse)
This method is used to save the request and response of an IHttpRequestResponse object to temporary files, so that they are no longer held in memory. Extensions can used this method to convert IHttpRequestResponse objects into a form suitable for long-term storage.

Parameters:
httpRequestResponse - The IHttpRequestResponse object whose request and response messages are to be saved to temporary files.
Returns:
An object that implements the IHttpRequestResponsePersisted interface.

applyMarkers

IHttpRequestResponseWithMarkers applyMarkers(IHttpRequestResponse httpRequestResponse,
                                             java.util.List<int[]> requestMarkers,
                                             java.util.List<int[]> responseMarkers)
This method is used to apply markers to an HTTP request or response, at offsets into the message that are relevant for some particular purpose. Markers are used in various situations, such as specifying Intruder payload positions, Scanner insertion points, and highlights in Scanner issues.

Parameters:
httpRequestResponse - The IHttpRequestResponse object to which the markers should be applied.
requestMarkers - A list of index pairs representing the offsets of markers to be applied to the request message. Each item in the list must be an int[2] array containing the start and end offsets for the marker. The markers in the list should be in sequence and not overlapping. This parameter is optional and may be null if no request markers are required.
responseMarkers - A list of index pairs representing the offsets of markers to be applied to the response message. Each item in the list must be an int[2] array containing the start and end offsets for the marker. The markers in the list should be in sequence and not overlapping. This parameter is optional and may be null if no response markers are required.
Returns:
An object that implements the IHttpRequestResponseWithMarkers interface.

getToolName

java.lang.String getToolName(int toolFlag)
This method is used to obtain the descriptive name for the Burp tool identified by the tool flag provided.

Parameters:
toolFlag - A flag identifying a Burp tool ( TOOL_PROXY, TOOL_SCANNER, etc.). Tool flags are defined within this interface.
Returns:
The descriptive name for the specified tool.

addScanIssue

void addScanIssue(IScanIssue issue)
This method is used to register a new Scanner issue. Note: Wherever possible, extensions should implement custom Scanner checks using IScannerCheck and report issues via those checks, so as to integrate with Burp's user-driven workflow, and ensure proper consolidation of duplicate reported issues. This method is only designed for tasks outside of the normal testing workflow, such as importing results from other scanning tools.

Parameters:
issue - An object created by the extension that implements the IScanIssue interface.

createBurpCollaboratorClientContext

IBurpCollaboratorClientContext createBurpCollaboratorClientContext()
This method is used to create a new Burp Collaborator client context, which can be used to generate Burp Collaborator payloads and poll the Collaborator server for any network interactions that result from using those payloads.

Returns:
A new instance of IBurpCollaboratorClientContext that can be used to generate Collaborator payloads and retrieve interactions.

getParameters

@Deprecated
java.lang.String[][] getParameters(byte[] request)
Deprecated. Use IExtensionHelpers.analyzeRequest() instead.

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.

getHeaders

@Deprecated
java.lang.String[] getHeaders(byte[] message)
Deprecated. Use IExtensionHelpers.analyzeRequest() or IExtensionHelpers.analyzeResponse() instead.

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.

registerMenuItem

@Deprecated
void registerMenuItem(java.lang.String menuItemCaption,
                                 IMenuItemHandler menuItemHandler)
Deprecated. Use registerContextMenuFactory() instead.

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.