Burp Suite Help

Quick links

Contents

What is Burp Suite?

Burp Suite is an integrated platform for attacking web applications. It contains a variety of tools with numerous interfaces between them designed to facilitate and speed up the process of attacking an application. All of the tools share the same robust framework for handling and displaying HTTP messages, persistence, authentication, proxies, logging, alerting and extensibility.

Burp Suite allows the individual tools to work together in highly effective ways, for instance:

Burp Suite tools

Burp Suite contains the following tools:

Use the above links to read the detailed help specific to each of the individual Burp Suite tools. The remainder of this help describes some typical usage scenarios for Burp Suite and the shared functionality and configuration options that affect the behaviour of all of the Burp tools.

Using Burp Suite

When Burp Suite is launched, Burp Proxy is started by default on port 8080 of the local loopback interface. By setting a web browser to use this as its proxy server, all web traffic can be intercepted, inspected and modified. By default, requests for non-media resources are intercepted and displayed (this default behaviour can be modified using options within Burp Proxy). All web traffic passing through Burp Proxy is by default analysed and incorporated into the target site map, to build up a picture of the content and functionality of the applications visited. In Burp Suite Professional, all requests are by default passively analysed by Burp Scanner to identify a range of security vulnerabilities.

Before you begin work in earnest, you should ideally define the target scope for your work. The easiest way to do this is to browse to the application(s) you are targeting, then locate the relevant hosts or directories within the site map, and use the context menus to add URL paths to the scope. This central scope configuration can be used to control the behaviour of the individual Burp tools in various ways.

As you browse the target application, you can intercept requests and responses in the Proxy for manual editing, or you can turn interception off altogether. With interception off, a full history is still maintained of each request and response, and content still accumulates within the site map.

As well as modifying intercepted messages within the Proxy, you can send these to other Burp tools to perform various actions, for example:

You can also perform any of the above actions on items in the proxy history, on individual hosts, directories or files within the target site map, or from anywhere within any of the tools where requests and responses are displayed.

A central logging function can be used to record all requests and responses made by individual tools, or the entire suite. The tools can run in a single tabbed window, or be detached in individual windows. All tool and suite configuration is optionally persistent across program loads. In Burp Suite Professional, you can save the entire state of the component tools, to reload at a later stage and resume your work.

Burp menu

This menu contains a number of key functions and configuration options, which are described below.

Search

[Pro version] Selecting "search" from the Burp menu opens a search dialog, which is very easy to use. You can specify the following search parameters:

When you click "go", the search begins, and the key details of each search match are shown in a sortable table, with a preview pane where you can see the full request and response, including highlighted matches for your search item. The usual context menus can be used to initiate attacks against specific items, or send them to other tools for further analysis:

Note that if you initiate a search via the context menu within the target site map (as opposed to the Burp menu), then the search will be specific to the selected branch(es) of the site map.

Saving and restoring state

[Pro version] The help below describes the process of saving and restoring state, and some common usage scenarios for this functionality.

Saving state

The items that can be saved include:

Selecting "save state" from the Burp menu launches a wizard where you can define which items you want to save the state and configuration of:

You then choose your output file, and Burp does the rest. You can continue using Burp while its state is being saved - you may experience some brief delays if you try to perform an operation on data which Burp is in the process of saving, to prevent any data corruption.

Obviously, because the save file includes the requests and responses accumulated within the tools you are saving, this file can grow very large. In practice, a few hours' testing will typically save or restore in a minute or two. You can make this process leaner and quicker by deleting unneeded items from the site map and proxy history before performing a save.

Restoring state

Selecting "restore state" from the Burp menu launches a wizard where you can define which items you want to restore the state and configuration of. The first step is to select a file which you previously saved. Burp then analyses this file to identify all of its contents (remember that each save file can include the state and configuration for any combinations of tools). For each type of saved state and configuration, Burp lets you choose whether you want to restore it, and if so whether to add to or replace the tool's existing state:

Burp then goes to work and restores everything you have selected. You can continue using Burp while its state is being restored - you may experience some brief delays if you try to perform an operation on data which Burp is in the process of restoring, to prevent any data corruption.

Usage scenarios

The ability to save and restore tool state and configuration is of huge benefit to penetration testers:

Remembering settings

The "remember settings" options determine whether Burp Suite will remember configuration settings across different loads of the software. You can tell Burp to remember settings for all tools, or for individually selected tools.

The "restore defaults" options reset all configuration settings within Burp Suite or individual tools to their default values.

Lean mode

If this option is selected, then the next time Burp Suite starts, it will run in a "lean" mode in which the only tools available are Burp Proxy, Intruder and Repeater. Running in this mode creates a smaller impact on system resources and is designed for users who prefer a more simple lightweight tool.

Target site map

The central site map aggregates all of the information which Burp has gathered about the application you are attacking. This includes all of the resources which have been directly requested via the Proxy, any items which have been inferred by analysing the responses to those requests, and all content discovered using the Spider. When you begin browsing a typical application, a large amount of content will be mapped out for you before you even get as far as requesting it, for example:

Items that have been requested are shown in black; those which Burp has inferred but not yet requested are shown in grey. By default, items that are typically uninteresting to penetration testers are filtered from the display, but this behaviour can be modified (described below).

The site map interface works essentially like a graphical email client. A tree view of hosts and directories is shown on the left. Selecting one or more nodes in the tree view causes all of the items below these nodes to be shown in table form on the top right. This table includes the key detail about each item (URL, status code, page title, etc.) and allows the items to be sorted according to any column (click any column heading to sort descending, or shift-click to sort ascending). Selecting an item in the table causes the request and response for that item to show in a preview pane on the bottom right. This preview pane contains all of the functions familiar from elsewhere in Burp - analysis of headers and parameters, text search, media rendering, etc.

As well as displaying all of the information gathered about your target, the site map enables you to control and initiate specific attacks against it, using the context menus that appear everywhere. For example, you can select a host or folder within the tree view, and perform actions on the entire branch of the tree, such as spidering or scanning:

Similarly, you can select an individual file within the tree or table, and send the associated request to other tools, such as Intruder or Repeater. If the item has not yet been requested by your browser, Burp will construct a default request for the item, based on the URL and any cookies received from the target domain:

[Pro version] You can use the context menu to access various engagement tools, such as searching for comments and scripts, analysing your target web site, scheduling tasks, etc.

In the table view, you can annotate individual or multiple items, by adding comments and highlights:

You can highlight individual items using a drop-down menu on the left-most table column:

And you can comment individual items in-place by double-clicking and editing the table cell:

Alternatively, if you want to annotate several items at once, you select the relevant items and use the context menu to add comments or apply highlights:

When you have annotated interesting requests, you can use column sorting and display filters to quickly find these items later.

The content displayed within the site map is effectively a view into an underlying database, and you can configure filters to determine which items of underlying data are displayed within the map. Some applications contain a large amount of content like images, CSS, etc., which it is normally helpful to hide from view. At the top of the site map, there is a filter bar. Clicking on this shows a popup enabling you to configure exactly what content will be displayed within the map:

You can choose to display only requests with parameters, or which are within the current target scope. You can filter by MIME type, HTTP status code and file extension. If you set a filter to hide some items, these are not deleted, only hidden, and will reappear if you unset the relevant filter. This means you can use the filter to help you systematically examine a complex site map to understand where different kinds of interesting content reside.

[Pro version] You can also specify a search term to filter on, which will only show items containing that expression in the request or response, or within the user-added comment if applicable.

In addition to filtering content from view, you may sometimes want to delete it altogether. For example, if you have browsed to off-target domains, you will have accumulated data within Burp that you just don't need. In this situation, you can permanently delete the superfluous items using the context menus within the site map. For example, you can select multiple hosts or folders within the tree or table views and delete them altogether:

Comparing site maps

You can use Burp to compare two site maps and highlight differences. This feature can be used in various ways to help find different types of access control vulnerabilities, and identify which areas of a large application warrant close manual inspection. Some typical use-cases for this functionality are as follows:

You can access the "compare site maps" feature using the context menu on the main site map. This opens a wizard that lets you configure the details of the site maps you want to compare, and how the comparison should be done. When selecting the site maps you want to compare, the following options are available:

You can choose to include all of the site map's contents, or you can restrict only to selected or in-scope items. If you choose to re-request a site map in a different session context, it is particularly important not to include requests that might disrupt that context - for example, login, logout, user impersonation functions, etc.

To perform the comparison, Burp works through each request in the first site map, and matches this with a request in the second site map, and vice versa. The responses to matched requests are then compared to identify any differences. Any unmatched items in either site map are flagged as deleted or added, respectively. The exact process by which this is done is highly configurable, allowing you to tailor the comparison to features of the target application.

The options for configuring how Burp matches requests in the two site maps are shown below:

The default options shown will work well in most situations, and match requests based on URL file path, HTTP method and the names of parameters in the query string and message body. For some applications, you will need to modify these options to ensure that requests are correctly matched. For example, if an application uses the same base URL for various different actions, and specifies the action using the values of query string parameters, you will need to match requests on the values of these parameters as well as their names.

The options for configuring how Burp compares the responses to matched requests are shown below:

Again, the default options will work in most situations. These options ignore various common HTTP headers and form fields that have ephemeral values, and also ignore whitespace-only variations in responses. The default options are designed to reduce the noise generated by inconsequential variations in responses, allowing you to focus attention on differences that are more likely to matter.

The results of a simple site map comparison are shown below. This shows an application that has been mapped out with administrative privileges, and the resulting site map re-requested with user-level privileges. The results contain a colourised analysis of the differences between the site maps, and show items that have been added, deleted or modified between the two maps. (In this case, since the whole of the first site map was re-requested, there are no added or deleted items in the maps themselves.) For modified items, the table includes a “diff count” column, which is the number of edits required to modify the item in the first map into the item in the second map. When you select an item, the corresponding item in the other site map is also selected, and each response is highlighted to show the locations of the differences:

Interpreting the results of the site map comparison requires human intelligence, and an understanding of the meaning and context of specific application functions. For example, the screenshot above shows the responses that are returned to each user when they view their home page. The two responses show a different description of the logged-in user, and the administrative user has an additional menu item. These differences are to be expected, and they are neutral as to the effectiveness of the application’s access controls, since they only concern the user interface.

The screenshot below shows the response returned when each user requests the top-level admin page. Here, the administrative user sees a menu of available options, while the ordinary user sees a “not authorised” message. These differences indicate that access controls are being correctly applied:

The screenshot below shows the response returned when each user requests the “list users” admin function. Here, the responses are identical, indicating that the application is vulnerable, since the ordinary user should not have access to this function and does not have any link to it in their user interface:

As this example shows, simply exploring the site map tree and looking at the number of differences between items is not sufficient to evaluate the effectiveness of an application’s access controls. Two identical responses may indicate a vulnerability (for example, in an administrative function that discloses sensitive information), or may be harmless (for example, in an unprotected search function). Conversely, two different responses may still mean that a vulnerability exists (for example, in an administrative function that returns different content each time it is accessed), or may be harmless (for example, in a page showing profile information about the currently logged-in user). All of these scenarios may coexist even in the same application. This is why fully automated tools are so ineffective at identifying access control vulnerabilities.

So Burp does not relieve you of the task of closely examining the application's functionality, and evaluating whether access controls are being properly applied in each case. What the site map comparison feature does is to automate as much of the process as possible, giving you all the information you need in a clear form, and letting you apply your knowledge of the application’s functionality to identify any actual vulnerabilities.

Target scope

The "scope" tab lets you tell Burp, at a Suite-wide level, exactly what hosts and URLs constitute the target for your current work. You can think of the target scope as, roughly, the items which you are currently interested in and willing to attack.

The target scope can affect the behaviour of the individual Burp tools in numerous ways, for example:

By telling Burp what your current target is, you can ensure that Burp carries out numerous such actions in an appropriate way, only going after items that you are interested in and willing to attack. In all cases, you can additionally fine tune the target scope and the associated behaviour at the level of individual tools, giving you fine-grained control over everything that Burp does, if you need it. However, the Suite-wide scope definition provides a quick and easy way to tell Burp what is fair game and what is off limits, and is almost always worth configuring before you begin your work in earnest.

The configuration of target scope is very powerful, but also very easy. The UI in the "scope" tab lets you define rules for what is included within, or excluded from, the target scope. For each rule, you can define the following fields:

When Burp evaluates a URL to decide if it is within the target scope, it will be deemed to be in scope if the URL matches at least one "include" rule and does not match any "exclude" rules. This enables you to define specific hosts and directories as being generally within scope, and yet exclude from that scope specific subdirectories or files. For example, the target scope defined below will match any content within https://www.myapp.com and https://staging.myapp.com with the exception of content below https://www.myapp.com/admin and any URL containing the expression "logout":

Configuring scope rules directly as described above is somewhat unfriendly for many users. A much easier approach is to let Burp define the rules for you based on intuitive instructions which you give it using the context menus in the site map or elsewhere. Before you begin testing the application, you simply need to browse to the relevant content so that it appears in the site map. You can then select one or more hosts and folders, and use the context menu to include or exclude these from the scope. This process is extremely easy and in most situations will let you quickly define all of the rules necessary for your testing:

Suite options

The options tab contains Suite-wide settings which are not specific to any individual tools. These are divided into several sub-tabs containing different areas of settings.

Connections tab

This tab contains options controllling how Burp handles network connections, including authentication, proxy servers, redirections, timeouts and hostname resolution.

These settings control whether Burp Suite should perform authentication to destination web servers. Different authentication types and credentials can be configured for individual hosts. Supported types are: basic, NTLMv1, NTLMv2 and digest authentication. The domain and hostname fields are only used for NTLM authentication. The "prompt for credentials" option causes an interactive popup to appear whenever an authentication failure is encountered.

These settings allow you to configure rules specifying different proxy settings for different (ranges of) destination hosts.

The configuration shown above will make Burp talk directly to staging.intranet.corp.com, use an internal proxy server without authentication for everything else on *.intranet.corp.com, and use an authenticated gateway web proxy for everything else, including the public internet.

You can use standard wildcards in the destination host specification. Rules are applied in sequence, and the first rule which matches the web server you are communicating with will be used. If no rule is matched, Burp defaults to direct, non-proxy connections. For each upstream proxy you configure, you can specify an authentication type and credentials if required. Supported types are: basic, NTLMv1, NTLMv2 and digest authentication. The domain and hostname fields are only used for NTLM authentication.

These options let you configure Burp to use a SOCKS proxy for all outgoing communications.

These settings control what types of redirection Burp will recognise and attempt to follow where applicable. The redirection targets which Burp will actually follow are still determined by the configuration within each individual tool (e.g. based on target scope).

These settings determine timeouts for various network tasks. The "normal" setting is used for most network communications, and determines how long Burp Suite will wait before abandoning an individual request and record that a timeout has occurred. The "read until close" setting is only used where a response is being processed which does not contain a Content-Length or Transfer-Encoding HTTP header. In this situation, Burp Suite waits for the specified interval before determining that the transmission has been completed. The "domain name resolution" setting determines how often Burp Suite will re-perform successful domain name look-ups. This should be set to a suitably low value if target host addresses are frequently changing. The "failed domain name resolution" setting determines how often Burp Suite will reattempt unsuccessful domain name look-ups.

These settings enable you 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.

These options control the handling of HTTP 100 Continue responses from servers. These often occur when a POST request is sent to the server, and it makes an interim response before the request body has been transmitted. If "understand 100 Continue responses" is checked, Burp Suite will skip the interim response and parse the real response headers for response information like status code and content type. If "remove 100 Continue headers" is checked, Burp Suite will remove any interim headers from the server's response before this is passed to individual tools.

Sessions tab

This tab allows you to configure Burp's session handling and macro capabilities. For more information about making use of these feature, see the session handling help.

Display tab

This tab contains options controlling how Burp displays HTTP requests and responses.

These settings control the font which is used to display HTTP messages, and whether syntax highlighting is performed for requests and responses.

These settings control how Burp handles character sets when displaying HTTP requests and responses. By default, charsets are 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, or tell Burp to display raw bytes with no charset handling, in the above options.

 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.

Any location where HTTP responses are displayed within Burp Suite it is possible to render HTML content as it would appear within your browser. This option controls whether Burp Suite will make any additional HTTP requests that are required to fully render HTML content (for example, for embedded images). Use of this option involves a trade-off between the speed and the quality of HTML rendering performed by Burp Suite.

SSL tab

This tab contains options for how SSL should be used, and information about the SSL certificates presented by destination servers.

This option enables you to configure a client SSL certificate (in PKCS12 format) which will be used whenever a destination HTTPS server requires client certificate authentication. You can also configure Burp to allow unsafe renegotiation, which is apparently necessary when using some client certificates.

Sometimes, you may have difficulty negotiating SSL connections with certain web servers. The Java SSL stack contains a few gremlins, and fails to work with certain unusual server configurations. To help you troubleshoot this problem, Burp lets you specify which protocols should be offered to servers during SSL negotiations.

Note that Burp itself implements a few workarounds for SSL issues, and if a negotiation fails with the protocols you have configured, Burp will still try some alternative combinations of protocols which often work. So you shouldn't use this feature as a method of testing which protocols are actually supported by the server.

You can also configure Burp to enable all supported cipher suites during SSL negotiation. This option is not normally necessary but may be useful when attempting to connect to unusually configured SSL stacks.

This information-only panel contains details of all X509 certificates received from destination web servers. Double-click an item in the table to display the full details of the certificate.

Misc tab

This tab contains miscellaneous settings regarding logging, backup, location of temporary files, and scheduled tasks.

These settings control logging of network requests and responses. Logging can be configured per-tool or for all Burp Suite traffic.

[Pro version] These settings let you configure Burp to save a backup of all tools' state and configuration in the background at a configurable interval, and also optionally on exit. 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.

These options let you configure the directory path where Burp saves its temporary files. 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.

[Pro version] You can use the task scheduler to automatically start and stop certain tasks at defined times and intervals. For example, the configuration shown above will begin scanning a target overnight at 2am, and suspend the scanner each day during working hours.

You can create tasks via the context menus which appear throughout Burp, or using the "new task" button in the above panel. This action starts a wizard which lets you configure the details and timing of the task. Various different types of task are available:

You can configure each task to be one-off, or to repeat at regular intervals.

Engagement tools

[Pro version] A number of tools exist to help make your work faster and more effective. These can be accessed via the context menus which appear throughout Burp:

Search

See search help.

Note that if you initiate a search from within the target site map (as opposed to the Burp menu), then the search will be specific to the selected branch(es) of the site map.

Find comments and scripts

You can use these functions to search part or all of the site map for scripts and comments. The search results window shows responses from all Burp tools containing either scripts or comments. Selecting an individual item shows the full request and response in a preview pane, with relevant items automatically highlighted, and also extracted into their own tab:

You can use the "export" button to save all of the scripts or comments to file or to the clipboard, optionally consolidating duplicated items.

Find references

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. The search results window shows responses from all Burp tools which link to the selected 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.

Analyse target

This function can be used to analyse a target web application and tell you how many static and dynamic URLs it contains, and how many parameters each URL takes. This can help you assess how much effort a penetration testing engagement is likely to involve, and can help you decide where to focus your attention during the test itself.

To access this feature, select one or more hosts or branches within the site map, and launch it using the context menu. The summarised information looks like this:

And you can drill down into more detail about individual URLs:

You can also export all of this information as an HTML report, which you can attach to client proposals and reports to show the attack surface you have covered.

Note: (i) This function only analyses the content already captured within the site map, so you should ensure that you have fully browsed or spidered all of the application's content and functionality before running it. (ii) URLs are deemed to be "static" if they no not take any parameters in the URL or message body; however the responses from these URLs may still be dynamically generated by the application.

Discover content

You can use this function to discover content and functionality which is not linked from visible content which you can browse to or spider.

Burp uses various techniques to discover content, including name guessing, web spidering, and extrapolation from naming conventions observed in use within the application. The feature is highly configurable, as shown by the available options which are explained below:

Target - These options control which directory to begin discovery from. Only items within this path and its subdirectories will be requested during the session. You can choose to discover files or directories or both, and how deep to recurse into discovered subdirectories.

Test case generation - These options control which file and directory names Burp will use when making requests to discover content. As well as built-in lists, Burp can harvest names used elsewhere within an application, and retry them at other locations, and can construct names based on discovered items, for example by cycling values in filenames containing numbers.

File extensions - You can specify a list of file extensions with which to test each possible filename. Burp can harvest file extensions observed in use within the application, and test these with every filename. When a file has been confirmed, Burp can also try a specific list of variant extensions with that filename, for example to check for old or backup versions of the same file.

Discovery engine - You can control how many threads are used for content discovery and spidering, whether file names are handled case sensitively, and how the discovery session interacts with Burp's main site map (in the target tab of the suite).

When you have configured your discovery session, you can start it from the control tab, which also provides runtime information about the actions being performed. The work is divided into numerous discrete tasks, which are prioritised according to their likelihood of quickly discovering new content, and new tasks are generated recursively as content is confirmed:

The discovery session employs its own site map, showing all of the content which has been discovered within the defined scope. If you have configured Burp to do so, newly discovered items will also be added to Burp's main site map.

Schedule task

See task scheduler help.

Simulate manual testing

This feature won't exactly enhance your productivity, but you may sometimes find it useful nonetheless. You can use it to make Burp simulate manual testing activities, by sending common test payloads to random URLs and parameters within a target application, at irregular intervals. Burp doesn't do anything with the responses, so you won't find out about any bugs in this way. But if you think that someone might be reviewing the application's logs to confirm that you are working, you can use this feature while you nip out for a long lunch, gym session, drinking binge, or whatever happens to be your preferred diversion.

Easter Eggs, anyone?

Message editor

Throughout Burp, a custom text editor is used which is optimised for viewing and editing HTTP requests and responses. Request and response syntax is automatically colourised to highlight interesting items. Mouse-over pop-ups perform automatic URL decoding (for requests) and HTML decoding (for responses).

The following shortcut keys are available:

Right-clicking on any request or response produces a context menu that can be used to perform various actions:

Extensibility

Burp Suite is extensible via the IBurpExtender interface. This allows third-party developers to extend the functionality of Burp by creating implementations of the interface which will be dynamically loaded and executed. Extensions can perform a wide range of functions, including processing and modifying HTTP requests made via all Burp tools, issuing arbitrary HTTP requests via Burp, extending Burp's UI with custom menu items, querying and modifying Burp's configuration data, and accessing key runtime information, including the Proxy history, site map and Scanner issues. See the source code and Javadoc for the interface for more details.

Copyright © 2010 PortSwigger Ltd. All rights reserved.