Support Center

Burp Community

See what our users are saying about Burp Suite:

How do I?

New Post View All

Feature Requests

New Post View All

Burp Extensions

New Post View All

Bug Reports

New Post View All
Documentation

Burp Suite Documentation

Take a look at our Documentation section for full details about every Burp Suite tool, function and configuration option.

Full Documentation Contents Burp Projects
Suite Functions Burp Tools
Options Using Burp Suite
Extensibility

Burp Extender

Burp Extender lets you extend the functionality of Burp Suite in numerous ways.

Extensions can be written in Java, Python or Ruby.

API documentation Writing your first Burp Suite extension
Sample extensions View community discussions about Extensibility

Monday, November 30, 2009

v1.3beta

This release adds numerous new features. See the preview for full details, but here are the highlights:

Have fun!

Friday, October 9, 2009

v1.2.17

Burp Scanner now allows reporting of issues in XML format, to enable easy integration with other tools. To create an XML report, simply select the issues you wish to report, and choose XML within the reporting wizard:

The XML has a flat structure, and contains a list of issues, with meta-information about issue type, URL, etc., reported within each issue element. The (internal) DTD looks like this:

<!DOCTYPE issues [
<!ELEMENT issues (issue*)>
<!ATTLIST issues burpVersion CDATA "">
<!ATTLIST issues exportTime CDATA "">
<!ELEMENT issue (serialNumber, type, name, host, path, location, severity, confidence, issueBackground?, remediationBackground?, issueDetail?, remediationDetail?, requestresponse*)>
<!ELEMENT serialNumber (#PCDATA)>
<!ELEMENT type (#PCDATA)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT host (#PCDATA)>
<!ELEMENT path (#PCDATA)>
<!ELEMENT location (#PCDATA)>
<!ELEMENT severity (#PCDATA)>
<!ELEMENT confidence (#PCDATA)>
<!ELEMENT issueBackground (#PCDATA)>
<!ELEMENT remediationBackground (#PCDATA)>
<!ELEMENT issueDetail (#PCDATA)>
<!ELEMENT remediationDetail (#PCDATA)>
<!ELEMENT requestresponse (request?, response?)>
<!ELEMENT request (#PCDATA)>
<!ELEMENT response (#PCDATA)>
]>

The serialNumber element contains a long integer that is unique to that individual issue. If you export issues several times from the same instance of Burp, you can use the serial number to identify incrementally new issues.

The type element contains an integer which uniquely identifies the type of finding (SQL injection, XSS, etc.). This value is stable across different instances and builds of Burp.

The name element contains the corresponding descriptive name for the issue type.

The path element contains the URL for the issue (excluding query string).

The location element includes both the URL and a description of the entry point for the attack, where relevant (a specific URL parameter, request header, etc.).

The other elements, some of which are optional and can be selected by the user within the reporting wizard, are hopefully self-explanatory.

Now, edt, the clock is ticking for the Dradis function to import Burp Scanner issues!

P.S., IBurpExtenderCallbacks now has the following method, which you can use to shut down Burp programmatically:

public void exitSuite(boolean promptUser);

If the method returns, the user cancelled the shutdown prompt.

Wednesday, September 2, 2009

v1.2.16

Improved handling of AMF messages, to support some data types which were previously omitted.

Tuesday, August 18, 2009

v1.2.15

1. Burp Scanner now checks for a few new issues:

  • XML external entity injection

  • Server-side XML / SOAP injection

  • Vulnerable Flash cross-domain policies

2. IBurpExtenderCallbacks gets a new method:

public IScanIssue[] getScanIssues(String urlPrefix);

This method returns all of the current scan issues for URLs matching the specified literal prefix. The prefix can be null to match all issues.

3. Previously, Burp Scanner could be configured to skip server-side injection checks for specific parameters. This feature is useful to avoid wasting time testing built-in platform parameters that are unlikely to contain vulnerabilities like SQL injection. Client-side issues like XSS are still checked for because this involves hardly any overhead.

Now, you can also configure Burp Scanner to skip absolutely all tests for specific parameters. This is useful if you know that a parameter is not used by the application, or if changing its value causes problems like session termination:

4. Various bugfixes.

Wednesday, August 12, 2009

v1.2.14

Adds AMF support to all tools except for Burp Intruder. Anywhere you see an HTTP request or response with an AMF-encoded body, Burp will display a tab containing a tree view of the decoded message:

If the message is editable, you can double-click individual nodes in the tree to modify their values, and Burp will reserialise the message with your new data. Burp supports all primitive data types, and also the array and hashmap data structures.

Burp Scanner is also updated to automatically place attack payloads within string-based AMF values.

Friday, July 17, 2009

v1.2.13

1. You can now pause and resume active scanning, using the context menu on the scan queue tab. A new status bar shows you whether the scanner is running, and the number of currently active scan threads.

2. There is a new task scheduler, which you can use to automatically start and stop certain tasks at defined times and intervals. You can schedule a task on a specific URL using the new context menu item that appears throughout Burp:

This action starts a wizard which lets you configure the details and timing of the task. The tasks currently implemented are shown below:

You can configure each task to be one-off, or to repeat at regular intervals. Tasks that you have created appear in a table in the suite Options tab. For example, the following configuration will begin scanning a target overnight at 2am, and suspend the scanner each day during working hours:

You can also create a new task, and edit or remove existing tasks, using the above buttons.

3. The extensibility method IBurpExtenderCallbacks.getParameters now returns the type of each parameter, as well as its name and value. The method's signature is unchanged, however the implementation now returns the following object for each parameter:

String[] { name, value, type }

4. Passwords are now masked on-screen in the UI for configuring www and proxy authentication.

Friday, July 3, 2009

v1.2.12

1. This release adds a new "find references" feature, which you can access via the context menus throughout Burp:

Anywhere you see an HTTP request, URL, domain, etc., you can use the "find references" function to search all of Burp's tools for HTTP responses which link to that item. When you view an individual search result, the response is automatically highlighted to show where the linking reference occurs:

Note that this feature treats the original URL as a prefix when searching for links, so if you select a host, you will find all references to that host; if you select a folder, you will find all references to items within that folder or deeper.

The new "find references" feature effectively serves the same purpose as the "linked from" list that existed in earlier versions of Burp Spider, but is much more powerful.

2. There is a new autosave feature, which saves a backup of Burp's state in the background at a configurable interval:

This setting persists across reloads of Burp. So you can configure Burp to always save its state to a local temp directory, and know that every time you use Burp you will have a backup copy of your work.

3. The HTTP message editor now has an option to URL-encode relevant characters as you type. If this option is turned on (via the context menu) then characters like & and = will be automatically replaced with their URL-encoded equivalents as you type:

4. The live active scanning feature has been modified to ignore requests for media resources (images, etc.) where the request does not contain any non-cookie parameters. Requests like these are virtually always for static resources which do not have any security significance, and so can be safely ignored by the scanner.

Note that despite this change to the live scanning feature, if you manually select items like these and send them for active scanning, then they will of course be scanned in the normal way.

Wednesday, June 10, 2009

v1.2.11

This release adds some new options to Burp Proxy for configuring the server SSL certificates that are presented to your browser. Use of these options can eliminate some SSL issues that arise when using an intercepting proxy:

  • You can eliminate SSL alerts in your browser, and the need to create SSL exceptions in Firefox.

  • Where web pages load SSL-protected items from other domains, you can ensure that these are properly loaded by the browser, without the need to first manually accept the proxy's SSL certificate for each referenced domain.

  • You can work with thick client applications that refuse to connect to the server if an invalid SSL certificate is received.

The new options for handling server certificates can be configured individually for each proxy listener, and look like this:

These options are explained more fully below:

  • use a self-signed certificate - This is the default option in previous releases of Burp. A simple self-signed SSL certificate is presented to your browser, which always causes an SSL alert.

  • generate CA-signed per-host certificates - This is the new default option. Upon installation, Burp creates a unique, self-signed CA certificate, and stores this on your computer to use every time Burp is run. Each time you connect to an SSL-protected website, Burp generates a server certificate for that host, signed by the CA certificate. You can install Burp's CA certificate as a trusted root in your browser (see instructions below), so that the per-host certificates are accepted without any alerts.

  • generate a CA-signed certificate with a specific hostname - This is similar to the preceding option, however Burp will generate a single host certificate to use with every SSL connection, using the hostname you specify. You should use this option if you are using invisible proxy mode with SSL connections - in this scenario, per-host certificates cannot be generated because the browser does not send a CONNECT request, and so the SSL negotiation precedes the receipt of the host information from the browser. The fixed host certificate is signed by Burp's CA certificate, which you can install in your browser (see instructions below), so that the host certificate is accepted without any alerts (provided you specify the correct hostname).

  • use a custom certificate - This option was supported previously, and enables you to configure a specific certificate to present to your browser. This option should be used if the application uses a client which requires a specific server certificate (e.g. with a given serial number or certification chain). If the client simply requires a valid server certificate for the application domain, it is normally easier and quicker to use auto-generation of per-host certificates, as described above.

To make full use of Burp's CA-signed host certificates, you will need to install Burp's CA certificate as a trusted root in your browser. Note: If you install a trusted root certificate in your browser, then an attacker who has the private key for that certificate may be able to man-in-the-middle your SSL connections without obvious detection, even when you are not using an intercepting proxy. To protect against this, Burp generates a unique CA certificate for each installation, and the private key for this certificate is stored on your computer, in a platform-dependent location. If untrusted people can read local data on your computer, you may not wish to install Burp's CA certificate.

To install Burp's CA certificate on IE, perform the following steps:

  1. If you have previously installed a different CA certificate generated by Burp, you should first remove it (see instructions below).

  2. Configure your browser to use Burp as its proxy, and configure Burp's proxy listener to generate CA-signed per-host certificates.

  3. Visit any SSL-protected URL. If you receive a warning, click "Continue to this website (not recommended)".

  4. Click on the "Certificate error" button in the address bar.

  5. Click "View certificates".

  6. Go to the "Certification Path" tab.

  7. Select the root certificate in the tree (PortSwigger CA).

  8. Click "View Certificate".

  9. Click "Install Certificate".

  10. In the Certificate Import Wizard, select "Place all certificates in the following store".

  11. Click "Browse".

  12. Select "Trusted Root Certification Authorities".

  13. Click "OK".

  14. Complete the wizard.

  15. Click "Yes" on the security warning.

  16. Close all dialogs and restart IE.

If everything has worked, when you visit SSL-protected URLs using Burp you should see a valid certificate chain:



To remove a Burp CA certificate which you have previously installed on IE, perform the following steps:

  1. Go to Tools Internet Options.

  2. Go to the Content tab.

  3. Click "Certificates".

  4. Go to the Trusted Root Certification Authorities tab.

  5. Select the PortSwigger CA entry in the list.

  6. Click "Remove".

  7. Click "Yes" in each confirmation dialog.

  8. Confirm that the PortSwigger CA entry has been removed.

  9. Restart IE.

To install Burp's CA certificate on Firefox, perform the following steps:

  1. If you have previously installed a different CA certificate generated by Burp, you should first remove it (see instructions below).

  2. Configure your browser to use Burp as its proxy, and configure Burp's proxy listener to generate CA-signed per-host certificates.

  3. Visit any SSL-protected URL.

  4. On the "Secure Connection Failed" screen, click on "Or you can add an exception", and then click "Add Exception".

  5. Click "Get Certificate", then click "View".

  6. Select the root certificate in the tree (PortSwigger CA).

  7. Click "Export" and save the certificate somewhere.

  8. Click "Close" on the Certificate Viewer dialog, and "Cancel" on the "Add Security Exception" dialog.

  9. Go to Tools Options.

  10. Click "Advanced".

  11. Go to the Encryption tab.

  12. Click "View Certificates".

  13. Go to the Authorities tab.

  14. Click "Import" and select the certificate file that you previously saved.

  15. On the "Downloading Certificate" dialog, check the box "Trust this CA to identify web sites", and click "OK".

  16. Close all dialogs and restart Firefox.

If everything has worked, when you visit SSL-protected URLs using Burp you should see a valid certificate chain:

To remove a Burp CA certificate which you have previously installed on Firefox, perform the following steps:

  1. Go to Tools Options.

  2. Click "Advanced".

  3. Go to the Encryption tab.

  4. Click "View Certificates".

  5. Go to the Authorities tab.

  6. Select the PortSwigger CA entry in the list (this is a sub-entry under PortSwigger).

  7. Click "Delete".

  8. Click "OK" in the confirmation dialog.

  9. Confirm that the PortSwigger CA entry has been removed.

  10. Restart Firefox.

Thanks are due to Rogan Dawes of WebScarab fame for prompting me to add this feature and sharing some sample code for implementing it.

Friday, May 29, 2009

v1.2.10

Implements a workaround for a JRE bug which causes a "bad record mac" error in the SSL handshake when the server implements a certain combination of SSL protocols.

Fixes a bug introduced in v1.2.09 which prevented saving of state from the UI.

Provides an alert on startup and on restoration of state if live active scanning is enabled, to reduce the likelihood of inadvertently attacking websites that have been added to the target scope during previous work.

In the params view of HTTP requests, allows copying (via the context menu) of multiple rows as tab/newline delimited data, for pasting into spreadsheets, etc.

Tuesday, May 26, 2009

v1.2.09

This release contains some major enhancements to Burp's extensibility APIs. You only need to download this release if you want to extend Burp's capabilities with your own code.

I'll produce full Javadoc for the new interfaces at a later date, but below is a summary of the new APIs, followed by an example of how they might be used. If you encounter any problems getting the new APIs working, email me.

The existing IBurpExtender interface adds two new methods which you can optionally implement:

public void processHttpMessage(String toolName, boolean messageIsRequest, IHttpRequestResponse messageInfo);

public void newScanIssue(IScanIssue issue);

The processHttpMessage method is invoked whenever any of Burp's tools makes an HTTP request or receives a response. This is effectively a generalised version of the existing processProxyMessage method, and can be used to intercept and modify the HTTP traffic of all Burp tools.

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

The existing IBurpExtenderCallbacks interface adds several new methods which you can invoke to query and update Burp's state, and to parse raw HTTP messages for parameters and headers. These methods are hopefully self-explanatory:

public IHttpRequestResponse[] getProxyHistory();

public IHttpRequestResponse[] getSiteMap(String urlPrefix);

public void restoreState(java.io.File file) throws Exception;

public void saveState(java.io.File file) throws Exception;

public String[][] getParameters(byte[] request) throws Exception;

public String[] getHeaders(byte[] message) throws Exception;

The existing IBurpExtenderCallbacks.doActiveScan method, which previously returned void, has been modified to return an object which can be used to query and control the resulting item in the active scanning queue:

public IScanQueueItem doActiveScan(String host, int port, boolean useHttps, byte[] request) throws Exception;

The methods described above make use of three new interfaces, all of which reside in the burp package.

The new IHttpRequestResponse interface contains the following methods, which can be used to query and update details of HTTP requests and responses:

public String getHost();

public int getPort();

public String getProtocol();

public void setHost(String host) throws Exception;

public void setPort(int port) throws Exception;

public void setProtocol(String protocol) throws Exception;

public byte[] getRequest() throws Exception;

public java.net.URL getUrl() throws Exception;

public void setRequest(byte[] message) throws Exception;

public byte[] getResponse() throws Exception;

public void setResponse(byte[] message) throws Exception;

public short getStatusCode() throws Exception;

Note that the set methods can only be used where the message has been intercepted before being forwarded (i.e. using IBurpExtender.processHttpMessage) and not in read-only contexts (e.g. using IBurpExtender.getProxyHistory). Also, the methods relating to responses can only be used after the request has been issued and the response received.

The new IScanIssue interface contains the following methods, which can be used to query information about issues discovered by Burp Scanner:

public String getHost();

public int getPort();

public String getProtocol();

public java.net.URL getUrl();

public String getIssueName();

public String getSeverity();

public String getConfidence();

public String getIssueBackground();

public String getRemediationBackground();

public String getIssueDetail();

public String getRemediationDetail();

public IHttpRequestResponse[] getHttpMessages();

The new IScanQueueItem interface contains the following methods, which can be used to query and control items in the active scanning queue:

public String getStatus();

public byte getPercentageComplete();

public int getNumRequests();

public int getNumErrors();

public int getNumInsertionPoints();

public void cancel();

public IScanIssue[] getIssues();

Note that different items within the scan queue may contain duplicated versions of the same issue - for example, if the same request has been scanned multiple times. Duplicated issues are consolidated in the main view of scan results. You can implementIBurpExtender.newScanIssue to get details only of unique, newly discovered scan issues post-consolidation.

The new extensibility APIs should enable users to create much more powerful extensions to Burp's functionality. One example of this is a means of fully automating periodic scanning of a specific application to identify any new vulnerabilities it contains. There are various ways of accomplishing this, but one way is described below. First, on a single occasion, you will need to manually explore all of the application's functionality using Burp Proxy, and save the state of Burp's target site map and scope configuration to file, in the usual way. Then, on future occasions, you can create an extension which performs the following actions:

  1. Load the saved site map and scope configuration back into Burp, using IBurpExtenderCallbacks.restoreState.

  2. Use IBurpExtenderCallbacks.getSiteMap to retrieve all of the site map items for the target application, by specifying a suitable URL prefix (e.g. "https://myapp.example.org/").

  3. If required, use IBurpExtenderCallbacks.sendToSpider to discover any content that has been newly added to the application, and then use IBurpExtenderCallbacks.getSiteMap again to obtain the updated site map.

  4. Use IBurpExtenderCallbacks.doActiveScan to initiate active scans of each site item that interests you (based on URL, file extension, parameters etc). Keep a reference to each IScanQueueItem returned from this method.

  5. If the application uses authentication, implement IBurpExtender.processHttpMessage to intercept every request made by Burp, and modify the Scanner's requests to add suitable session information to each request as required. You can use IBurpExtenderCallbacks.makeHttpRequest to make arbitrary additional HTTP requests to perform an application login and obtain a valid session token to be added into the Scanner's requests.

  6. Implement IBurpExtender.newScanIssue to retrieve details about each discovered scan issue, and save these details if required.

  7. Monitor the progress of each IScanQueueItem created in step #4, to determine when all your initiated scans are completed.

  8. Use IBurpExtenderCallbacks.saveState to save the full state of Burp when all scanning is completed, to enable manual review and reporting as required.

Monday, May 11, 2009

v1.2.08

Much faster save and restore of state (by a factor of 5, at least). The downside is that the state file format has changed and files saved using earlier releases won't load into this release.

The active scan queue now has a "scan again" menu option for items that are completed or cancelled.

Various minor bugfixes.

Thursday, April 23, 2009

v1.2.07

Burp Scanner is updated to allow the severity and confidence levels of scanner issues to be modified by the user. Issues can also be marked as false positives, and deleted.

To reclassify issues, select the desired issues in the Results tab, and use the right-click context menu to adjust the severity and confidence levels.

To delete issues, select the desired issues and use the context menu or the 'del' key to delete them.

Note that if you delete an issue, and Burp rediscovers the same issue (for example, if you rescan the same request), the issue will be reported again. If instead you mark the issue as a false positive, then this will not happen. Therefore, deletion of issues is best used for cleaning up the Results tree to remove hosts or paths you are not interested in. For unwanted issues within the functionality you are still working on, you should use the false positive flag.

Thursday, April 16, 2009

v1.2.06

1. Scanner adds support for REST-style parameters in the URL. Some applications use the path portion of the URL to transmit data parameters, for example:

/cars/red/diesel/2004/ShowDetails

If you configure Scanner to attack REST-style parameters, then each of "cars", "red", etc. will be tested for input-based vulnerabilities. This option is off by default, to avoid creating excessive numbers of scan requests if this is not necessary. You should enable this option any time you believe the application may be transmitting data using the REST paradigm.

The rules for defining non-injectable parameters are now extended so you can exclude specific REST parameters by their index number. So, if you know that "cars" is used to define the application path, and is not a data parameter, you can define a rule to skip server-side injection tests for REST parameter 1 (use the index number as the parameter name in the rule).

2. Scanner adds support for fully customisable attack insertion points, so you can specify arbitrary locations within a base request where attack strings should be placed. To use this function, send the relevant base request to Intruder, use the payload positions UI to define the start/end of each insertion point in the usual way, and select the new Intruder menu option "actively scan defined insertion points".

3. Automatic placement of payload positions within Intruder now recognises XML-formatted data within the currently-selected range of the request template. Some applications send XML-encapsulated data within a multipart request body, for example:

POST /function HTTP/1.0
Content-Type: multipart/form-data; boundary=weidhwiderfhwiuehwiuehfwerrf
Content-Length: 202

--weidhwiderfhwiuehwiuehfwerrf
Content-Disposition: form-data; name="data"

<data>
<param1>foo</param1>
<param2>bar</param2>
<param3>123</param3>
</data>

--weidhwiderfhwiuehwiuehfwerrf--

If you perform auto-placement of payload positions on the entire message, then Intruder will mark the whole of the XML block as a single insertion point, which is probably not what you want:

However, if instead you manually select the precise XML block, then the auto-placement function will recognise that the selection contains XML, and will mark the individual XML parameter values as insertion points:

Used in conjunction with scanning of configurable insertion points (see #2), this enables you to quickly scan complex message bodies properly.

4. In any message display you can now copy to file, and (when editable) paste from file, using the right-click context menu. Copying operates on the selected text or, if nothing is selected, the whole message. Pasting replaces the selected text or, if nothing is selected, inserts at the cursor position.

5. When a message is showing in the Proxy intercept tab, you can forward or drop the message using the shortcut keys Alt-F and Alt-D.

Thursday, April 9, 2009

v1.2.05

Beta release containing a new text editor for raw HTTP requests and responses. The new editor has a number of enhancements:

  • Much faster display of large messages.

  • Colouring of request parameters and response syntax with minimal processing overhead.

  • Undo/redo.

  • Mouseover URL-decoding (in requests) and HTML-decoding (in responses).

  • Configurable font and text size.

The editor supports the following control keys:

  • Ctrl + A, select all

  • Ctrl + C, copy selected text

  • Ctrl + F, find and highlight the selected text throughout the message

  • Ctrl + V, paste

  • Ctrl + X, cut selected text

  • Ctrl + Y, redo last undone edit

  • Ctrl + Z, undo last edit

  • Ctrl + left, move to previous word

  • Ctrl + right, move to next word

  • Ctrl + up, move to previous paragraph

  • Ctrl + down, move to next paragraph

  • Ctrl + home, go to start of message

  • Ctrl + end, go to end of message

  • Ctrl + backspace, delete previous word

  • Ctrl + del, delete next word

Any feedback and suggestions much appreciated, particularly from users on less mainstream OS platforms.

This release also fixes a problem saving state when responses contain international characters, and addresses various other bugs.

Thursday, March 5, 2009

v1.2.04

Adds configurable DNS resolution, enabling the user to specify hostname-to-IP mappings which override the DNS resolution provided by the operating system. This feature can be used to ensure correct onward forwarding of requests when the hosts file has been modified to perform invisible proxying of traffic from non-proxy-aware thick client components.

Adds finer-grained control of active scan checks, enabling specific kinds of checks for SQL injection and OS command injection to be turned on and off.

Saturday, February 14, 2009

v1.2.03

Fixes the parameters view of HTTP requests to continue parsing parameters when malformed syntax is encountered.

Thursday, February 12, 2009

v1.2.02

Adds a Host header to CONNECT requests when using SSL with upstream proxies. This header is apparently required by some content-filtering proxies, notably Webwasher.

Wednesday, February 4, 2009

v1.2.01

Adds improved selection into large site maps. Previously, when one or more branches were selected, the UI would block while the table of selected leaf nodes was compiled. Now, a progress bar with cancel option is displayed while the table is compiled, and the rest of the UI is still usable.