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

Tuesday, December 6, 2011

v1.4.05

This release fixes a silly bug that was introduced in v1.4.04 and which prevented the session handler from working properly in certain configurations.

Thursday, December 1, 2011

v1.4.04

This release contains a large number of new features, usability tweaks and bug fixes. The more interesting items are listed below.

HTTP message viewer

  • The inline text conversion operations that are accessible via the context menu now also work on non-editable HTTP messages. The result of the conversion is shown in a pop-up dialog.

  • The HTTP params view now automatically URL-decodes relevant parameter names and values when these are displayed in the table. If you edit a URL-encoded value, this reverts to the raw encoded value while you are editing. Further, if you enter any parameter delimiters in raw form (space, ampersand or equals), these are automatically URL-encoded when you complete your edit.

  • Cut / copy / paste operations within the message editor are now integrated with the Linux selection buffer, as well as the system clipboard. Selecting text within a message automatically copies this to the selection buffer, and clicking the middle mouse button pastes from the selection buffer.

  • The lower search bar now has an option (accessible via the + button at the bottom left) to automatically scroll to the first search match when a new message is displayed. This feature is useful when you are stepping through a series of responses (e.g. in the proxy history) and need to view the matched expression within each response.

  • Clicking on the "N matches" caption on the lower search bar now selects the next matched item, in the same way as the > button does.

  • The maximum size of the mouse-over pop-ups for decoded syntax has been reduced, to avoid huge popups when the mouse is hovered over large encoded items (e.g. ViewStates).

Search / filters

  • A "negative" search option has been added to the suite-wide and in-filter search functions. This causes the search to return all items that do not match the specified expression. This can be useful to filter out responses containing a common error message, etc.

  • The filter bars on the Proxy history etc. now have buttons to show all items, show no items, and restore defaults.

  • Regex expressions in the search functions and elsewhere now allow the dot to match line terminator characters. So, for example, you can search for expressions spanning two lines using "foo.*?bar".

Proxy

  • There are new options to disable the web interface (at http://burp) and to suppress Burp error messages in responses. These options can be useful to mask the presence of Burp from users who connect via it.

Scanner

  • The active scan queue context menu now has new options to delete selected items, delete finished items, and automatically delete items as they finish.

  • The active scan wizard window is now resizable, to make it easier to select which items you wish to scan from a long list.

  • Double-clicking the active scan queue status bar now toggles the scanner between the paused/running state.

  • The passive check on SSL certificates now correctly handles the x.509v3 extension for alternative subject names.

Intruder

  • When using null payloads, you can now start an attack without needing to define a payload position.

  • When saving or copying the table of attack results, Burp now provides an alert if it was not possible to include full payload values. You can use the "store full payloads" option to ensure these are available in the results.

Spider

  • There is a new option to limit the number of parameterised requests that are made to each unique URL. This option is useful, for example, when crawling calendar applications, where each page links to the next using a different parameter value, creating an unlimited crawling space.

Repeater

  • The context menu now has a "paste URL as request" item. This configures Repeater to make a GET request using the URL on the clipboard. The headers included within this request are taken from the request headers defined in the Spider options.

  • The context menu now has an "add to site map" item, to facilitate manual content mapping.

Misc

  • The function to automatically save Burp's state now shows an alert on startup if the configured backup directory is not available. If backup on exit fails, Burp now shows a blocking dialog, allowing the user to cancel and not exit.

  • When exporting HTTP items and scanner issues in XML format, there is a default-on option to Base64-encode all request and response data. This avoids problems with binary characters within XML. If this option is used, Burp reverts to v1.0 of XML, which is more widely supported by parsers. The XML DTD now includes a "base64" attribute on the request and response elements, indicating whether the contents of those elements is Base64-encoded.

  • There is a new option to drop all out-of-scope requests. Using this option prevents Burp from issuing any requests to out-of-scope URLs, even if they are requested via the Proxy, Repeater etc. You can use this option based on the defined suite-wide scope or on a custom scope. You can find the new feature at options / connections / drop all out-of-scope requests.

  • There is a new wizard (accessed from the about menu) to clean up Burp's footprint on the local computer. Optionally, you can remove temporary files, saved preferences, your license key, and the Burp program executable.

  • Multi-row deletion now works on the lists of scope rules and comparer items.

Extender

  • There is a new method in IBurpExtenderCallbacks to send an HTTP request to Intruder with custom payload positions defined.

  • There are new methods in IHttpRequestResponse to get/set highlights on relevant items.

  • The IHttpRequestResponse object passed to IBurpExtender.processHttpMessage() by the Proxy now properly handles comments (and highlights) and links these to the corresponding item in the Proxy history.

The APIs for the new Burp Extender methods are shown below.

In IBurpExtenderCallbacks:

/**
* 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.
*
* @param host The hostname of the remote HTTP server.
* @param port The port of the remote HTTP server.
* @param useHttps Flags whether the protocol is HTTPS or HTTP.
* @param request The full HTTP request.
* @param 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 offset for the payload position.
* @throws java.lang.Exception
*/
public void sendToIntruder(
String host,
int port,
boolean useHttps,
byte[] request,
List payloadPositionOffsets) throws Exception;

In IHttpRequestResponse:

 /**
* Returns the user-annotated highlight for this item, if applicable.
*
* @return The highlight color for this item, or null if none is set.
*/
String getHighlight() throws Exception;

/**
* Sets the user-annotated highlight for this item.
*
* @param color The highlight color to be assigned to this item. Accepted
* values are: red, orange, yellow, green, cyan, blue, pink, magenta, gray.
* @throws Exception
*/
void setHighlight(String color) throws Exception;

Thursday, November 10, 2011

v1.4.03

1. There is a new CSRF generator, which produces proof-of-concept HTML for generating virtually any HTTP request. You can access this feature by right-clicking any item within Burp, and using the engagement tools context menu to select "generate CSRF PoC":

Some useful features are:

  • Support for all form encoding types: standard URL encoding, multipart encoding, and plain text encoding.

  • Auto-detection of the optimal encoding type, with manual override.

  • Ability to edit both the request and response in-place, to fine tune attacks.

  • In-browser testing, by pasting a URL into your browser that will cause Burp Proxy to serve up the CSRF PoC in its response.

Using this feature, you can even generate CSRF attacks containing completely arbitrary content in the message body, including binary data, provided the target application accepts text/plain encoding.

2. You can now add comments and highlighting to items as they appear in the proxy intercept window. This is useful when manually stepping through an application, allowing you to annotate interesting requests as they are made, and then return to these in the proxy history for further investigation:

3. The site analyser function (accessible via the engagement tools context menu), now has a tab showing all the unique parameters found, and the number of URLs in which they appear. You can drill down into the individual requests that use a given parameter, allowing you to quickly focus in on interesting or unusual parameters when testing a large application:

4. You can now bind proxy listeners to specific IP addresses, in addition to the loopback interface and all interfaces:

5. Burp now implements sslstrip-style functionality, allowing you to use non-SSL-capable tools against HTTPS applications, or to perform active MITM attacks against users who begin browsing using HTTP:

  • You can force Burp Proxy to use HTTPS in outgoing requests, even if the incoming request did not use HTTPS. This is configured per-listener, in the request redirection settings.

  • You can configure Burp Proxy to convert all HTTPS links in responses and redirects to use HTTP.

  • You can configure Burp Proxy to remove the secure flag on set cookies, so that browsers will still submit them over HTTP.

6. The configuration UI for session handling rules and macros now includes "copy" buttons, allowing you to duplicate and modify an existing rule or macro.


Wednesday, October 12, 2011

v1.4.02

As well as fixing a number of bugs, this release adds a range of cool new features.

1. Burp now supports streaming HTTP responses, and handles these in a way that lets you and the application continue working. Streaming responses are often used for functions like continuously updating price data in trading applications. Typically, some client side script code makes a request, and the server keeps the response stream open, pushing further data in real time as this becomes available. Because intercepting proxies use a store-and-forward model, they can break these applications - the proxy waits indefinitely for the streaming response to finish, and none of it is ever forwarded to the client.

Burp now lets you specify which URLs return streaming responses. The Proxy tool will pass these responses straight through to the client as data is received. The Repeater tool will update the response panel in real time as data is received. Other Burp tools will ignore streaming responses and will close the connections (which is no worse than the way they are handled in prior versions of Burp). Here is the new configuration (under options / HTTP / streaming responses):

In order to view the contents of streaming responses within the Proxy history and Repeater response panel, you will need to check the "store streaming responses" option.

In order to make the responses more human-readable, you can also check the "strip chunked encoding metadata" option, although removing this metadata may break the client-side application, depending on how it is implemented.

Streaming responses are often compressed using gzip encoding - you can configure Burp to decompress this content via the normal options in the Proxy and Repeater configuration.

The new support for streaming responses is also useful for handling responses that are not strictly streaming but nevertheless very large (such as some Flash objects), in order to bypass the store-and-forward proxy model and improve Burp's performance.

2. Burp Intruder has a new ECB Block Shuffler payload type. This is designed for testing ECB-encrypted tokens and other data, to check their vulnerability to block shuffling attacks. Because ECB ciphers always encrypt the same block of plaintext to the same block of ciphertext, it is possible to meaningfully modify the plaintext in a structure by duplicating and shuffling the blocks of ciphertext. Depending on the contents of the structure, and the application's handling of the modified data, it may be possible to interfere with application logic - for example, switching the user ID field in a structured session token, changing an encrypted price, etc.

The configuration for the new payload type looks like this:

You can tell Burp whether to shuffle blocks in the base value for the payload position, or in a supplied string, and you can configure whether the ciphertext is encoded as ASCII hex (which is typically the case) and configure the block size (normally 8 or 16 bytes). You can handle complications like Base64-encoding via the usual payload post-processing rules.

If you aren't sure what exactly the item you are targeting contains, you can try various different settings, since this is not normally a lengthy attack to run.

There is often a large element of luck involved when blindly shuffling blocks in ECB-encrypted data structures, and success often depends upon happening to find a block of ciphertext whose decrypted plaintext contains the right meaningful data when inserted into the structure (such as a number that could be a valid user ID or price). You can dramatically increase the likelihood of success by providing Burp with a large sample of other data that is encrypted using the same cipher and key. For example, in the case of session tokens, you can harvest a large number of valid tokens using Burp Intruder or Sequencer, and configure these in the ECB block shuffling payload, under "obtain additional blocks from these encrypted strings". Burp will then take all of the unique ciphertext blocks that you have provided, and use these when shuffling blocks in the original data. In practice, if you can find suitable additional encrypted data, this method proves highly effective when targeting vulnerable applications.

I've also blogged about an example of using the new ECB block shuffler to compromise sessions in a vulnerable application.

3. Burp has a new UI component to aid configuration in situations where you need to specify interesting parts of HTTP responses. This is an improved version of the configuration used in earlier versions of Burp Sequencer. The new Sequencer configuration for defining a custom token location looks like this:

The easiest way to use this configuration is to select the relevant item within the response. As you make your selection, Burp will automatically show in the top panel various configuration options which specify this item in the current response. If required, you can modify this configuration manually to ensure that it will work across multiple responses. You can also refetch the current response to test that your configuration is specifying the correct item.

Various methods are available of specifying the item's location, including fixed offset and length, literal expressions which precede and delimit the item, or a regex group. (Obviously, the more powerful of these options impose a greater processing overhead at runtime.) There is help available within the UI dialog regarding the appropriate syntax to use with each option.

4. Burp Intruder now has improved extract grep functionality, which makes use of the new response selection configuration:

The new functionality lets you define each extract grep location using the same fine-grained settings as already described for tokens in Sequencer, and each extract grep item is defined independently of the others. This lets you use different options (for delimiter, regex, case sensitivity, etc.) for each item to be extracted, removing an annoying limitation on the prior version of Intruder. You can also specify an overall length limit, to avoid consuming unnecessary memory in the event of misconfiguration or unexpected responses.

Two nice features of the extract grep functionality are:

  • If you specify identical successive extract grep items (using the copy button), then Burp will search each response from the end of the previous match. In this way, you can easily extract multiple similar data fields from each response with an easy configuration. For example, if responses contain lots of interesting data within an HTML table, you can define multiple successive extract grep items using the regex <td>(.*?)</td> in order to extract the contents of successive cells within the table.

  • Often, when browsing through the results of an Intruder attack, you will notice some responses with anomalous content, such as an error message, that does not appear within the original base response. If you want to extract a specific string from these responses you can use the context menu within the Intruder results table and choose the "define extract grep from response" option. This will show the extract grep configuration dialog with the specific response you have selected, allowing you to quickly define an extract grep item that will work for responses of this type:

5. A much-requested feature has been added to session-handling macros - the ability to define custom parameter locations within macro responses. In today's Ajax-heavy applications, items such as anti-CSRF tokens are often transmitted to the client within JavaScript or JSON structures; client-side code then processes the item and sends it within the relevant parameter in subsequent requests. Burp previously only identified parameters appearing within HTML forms, URL query strings and other conventional locations, and so could not cope with these kind of tokens.

In the new release, you can configure arbitrary named parameter locations within a macro response, using the same response extraction UI already described. For example, this allows you to specify that a particular JavaScript string contains a parameter with a specific name. When updating parameters in subsequent requests, Burp will update any parameter with that name using the value extracted from the configured location in the prior response:

Some users have identified a further requirement within the macro parameter handling - the ability to deal with and update ephemerally-named parameters, which some applications are using for anti-CSRF defenses. In these applications, the name of the anti-CSRF parameter changes with each request, and Burp is not currently able to automatically update this parameter name via session handling rules. We hope to have a solution for this situation in a future release.

Tuesday, August 16, 2011

v1.4.01

This release fixes a number of bugs, most notably:

  • A thread synchronization problem that caused the proxy to stop forwarding requests in certain high-volume conditions.

  • A problem with the NTLMv2 negotiation which caused it to fail against certain server configurations.

  • A bug that sometimes caused active scan tasks to fail silently.

The release also contains several enhancements to the handling of parameters in macros, including:

  • The option to URL-encode parameters in macro requests is now by default applied only to derived parameters. Preset parameter values are now not encoded by default, because they are typically already encoded within the configured request.

  • In the "run macro" action, there is a new, default-on option to URL-encode parameter values in the current request that have been derived from the final macro response.

  • In the "run macro" action, there is a new, default-off option to tolerate a mismatched URL when attempting to match parameters from the final macro response. This is useful for URL-agnostic anti-CSRF tokens, and enables you to configure a single macro to retrieve a valid token, which you can use in requests to multiple URLs, considerably simplifying the necessary Burp configuration in some applications.

A compatibility issue with Java 7 has been resolved. Burp will still display a compatibility warning on this platform until full testing has been carried out and any further issues dealt with.

Friday, June 3, 2011

v1.4

This is the stable release incorporating all of the features contained in the beta releases.

Many thanks to everyone who made feature requests and provided feedback on the beta versions.

Thursday, May 26, 2011

v1.4beta3

This release fixes a few bugs, and also adds some further features to enhance the new functionality added in v1.4:

  • There is a new tracer function for troubleshooting the session handling configuration. This shows you all of the steps performed when Burp applies session handling rules to a request, allowing you to see exactly how requests are being updated and issued. You can access the session handling tracer via options / sessions / view sessions tracer:

  • There is a new session handling action, to execute a post-request macro. This action issues the request that is currently being processed, and then executes a further macro (request sequence). Optionally, you can configure Burp to update parameters in the first macro request with values taken from the response to the current request, to handle anti-CSRF tokens, etc. Also, you can configure whether the invoking tool should receive the response from the current request, or the response from the final macro request. You can use this feature to perform testing on an request that is part way through a multi-stage process, and ensure that the rest of the process is completed in the normal way. This can be useful to identify some bugs like XSS and SQL injection, where the relevant input is supplied at one stage of a process, and is processed in a vulnerable way at a later stage of the process.

  • The auto-matching of parameter values between macro requests and responses now works for URL-encoded parameters. Further, there is a default-on option to URL-encode any problematic characters in parameter values that are updated by the session handler.

  • When you are performing a site map comparison that involves re-requesting a site map in the current session context, the comparison wizard displays the new site map while it is in the process of being re-requested. This enables you to inspect responses within the re-requested map to ensure that your session context is still valid and your session handling configuration is working in the way you intend.

Thursday, May 12, 2011

v1.4beta2

This release fixes a few bugs that were identified in the first beta release, and also adds some new features:

  • NTLMv2 authentication is now supported, for both web and proxy servers, allowing you to work with Windows servers that do not accept the older version of NTLM.

  • All relevant Burp features now work with IPv6.

  • Charsets are now automatically recognised and correctly rendered, per response. This avoids the need to set a specific charset on the command line when starting Burp, and allows you to work with content that uses multiple different charsets within the same instance of Burp. You can override this default behaviour and set a specific charset at options / display / charset handling. Note that some charsets are not supported for all fonts. If you are using a charset that employs non-Latin glyphs, you should first try using a system font such as Courier New or Dialog.

  • The directory path where Burp saves its temporary files is now configurable, at options / misc / temporary files location. This allows you to specify a directory on a different volume, or which is not world-readable, if required. Changes to this setting take effect the next time Burp starts up.

  • A new method has been added to IBurpExtenderCallbacks allowing you to programmatically send items to Burp Scanner with custom attack insertion points (in the same way as could already be done from the Intruder UI). The definition of this method is as follows:

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

    The insertionPointOffsets parameter is 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.

  • There is a new EULA, written by a proper lawyer.

Friday, March 25, 2011

v1.4beta

This release contains various new features, including:

See the links above for more details about each new feature.