Burp Proxy Help

Contents

What is Burp Proxy?

Burp Proxy is an interactive HTTP/S proxy server for attacking and debugging web applications. It operates as a man-in-the-middle between the end browser and the target web server, and allows the user to intercept, inspect and modify the raw traffic passing in both directions.

Burp Proxy allows you to find and exploit application vulnerabilities by monitoring and manipulating critical parameters and other data transmitted by the application. By modifying browser requests in various malicious ways, Burp Proxy can be used to perform attacks such as SQL injection, cookie subversion, privilege escalation, session hijacking, directory traversal and buffer overflows. Intercepted traffic can be modified as raw text, as a table of parameters or headers, or in hexadecimal form, so even transfers of binary data can be manipulated. Response messages containing HTML or image data can be rendered within Burp Proxy.

In addition to per-request manipulation, Burp Proxy maintains a complete history of every request sent by the browser, all modifications made, and all responses received. You can review earlier requests, and reissue and re-modify any individual request, and view saved responses in raw form or rendered as web pages. The entire conversation in both directions can also be logged to file for further analysis or to provide an audit trail.

Burp Proxy is tightly integrated with the other tools within Burp Suite, and allows any request or response to be sent to other tools for further processing. With a single click, you can send an interesting request to be used as the basis for session token analysis, manual modification and reissue, vulnerability analysis, or a custom automated attack using Burp Intruder.

The interactive behaviour of Burp Proxy can be controlled using fine-grained rules for requests and responses, based on domain, IP address, protocol, HTTP method, URL, resource type, parameters, cookies, header/body content, response code, content type and HTML page title. It can be configured to operate quietly without any per-request interaction. You can later review the history to identify requests that bear closer examination. Burp Proxy can be used to automate modification of HTTP request and response messages, through the use of regex-based match and replace rules.

In addition to the main user interface, Burp Proxy can also be controlled from within the end browser, for reviewing the request history and reissuing individual requests.

Burp Proxy can be used in conjunction with a upstream proxy server. It can handle basic, NTLM and digest authentication to the upstream proxy and to web servers, and so can be used in almost any LAN environment. It supports SSL (with the ability to configure custom server or client certificates), and allows HTTPS traffic to be viewed and modified as clear-text. In addition, it automatically handles various encodings of server responses, including chunked transfer-encoding and compressed content-encoding.

Using Burp Proxy

When Burp Proxy is launched, the HTTP/S proxy service is started automatically on port 8080 of the loopback interface only. To start using Burp Proxy, simply configure your browser to use a proxy server on 127.0.0.1:8080, and begin browsing.

By default, Burp Proxy is configured to intercept requests for non-media resources, and display these for inspection and modification. Other requests (for images and stylesheets) and all server responses are automatically forwarded. This default behaviour can be modified (see Options tab).

Intercept tab

This tab is used to display and modify individual browser requests and server responses.

The top of the display indicates whether the HTTP message shown is a request or response, and the hostname and IP address of the target server. When you have reviewed and (if required) edited the message, click "forward" to send it on to the server or browser. Click "drop" to abandon the message.

You can also forward or drop the message using the shortcut keys Alt-F and Alt-D.

Each request and response message can be displayed and analysed in various forms, by clicking on one of the available display tabs. The available tabs will appear and disappear as appropriate for the type of message being displayed:

Right-clicking on any of the display tabs produces a context menu that can be used to perform various actions. The same menu can also be accessed via the "action" button on the main display:

The intercept tab contains a toggle button which can be used to quickly turn interception mode on and off. If this is showing "intercept is on" then messages will be intercepted or automatically forwarded according to the interception rules configured on the  Options tab. If this is showing "intercept is off" then no messages will be intercepted.

Options tab

This tab contains various configuration options which control the behaviour of Burp Proxy, as described below.

Burp Proxy allows you to define multiple listeners. Each listener opens a port on your computer and waits for connections from your browser. By default, Burp opens a single listener on port 8080 of the loopback interface, but you can modify this listener and add as many others as you require. For each listener, you can configure a number of properties, as described below.

local listener port - This is the port on the local computer which will be opened to listen for incoming connections. You should configure your browser settings to use the host 127.0.0.1 and this port as its proxy server.

listen on loopback interface only - This controls whether the listener binds only to the loopback interface (127.0.0.1) or to all network interfaces. Note: if this option is deselected then other computers may be able to connect to the listener. This may enable them to initiate outbound connections originating from your IP address, and to access the contents of the proxy history, which may contain sensitive data such as login credentials. You should only deselect this option when you are located on a trusted network.

support invisible proxying for non-proxy-aware clients - If you are using a standard browser, you should leave this option unchecked. The option is sometimes useful if the application you are targeting employs a thick client component which runs outside of the browser, or which makes its own HTTP requests outside of the browser's framework. Often, these clients don't support HTTP proxies, or don't provide an easy way to configure them to use one. In this situation, you can effectively force the client to connect to Burp by redirecting the client's requests lower down the networking stack - e.g. by adding an entry to your hosts file, or changing your routing configuration. However, the requests issued by the client will probably not be in the style normally used with web proxies.

A proxy-style request looks like this:

GET http://myapp.com/foo.php HTTP/1.1

Host: myapp.com

whereas the corresponding non-proxy request looks like this:

GET /foo.php HTTP/1.1

Host: myapp.com

Normally, web proxies need to receive the full URL in the first line of the request in order to determine which destination host to forward the request to (they do not, if they follow the spec, look at the Host header to determine the destination). To enable Burp Proxy to work with clients that send non-proxy-style requests, you need to check the "support invisible proxying" option. When you do this, if Burp receives any non-proxy-style requests, it will by parse out the contents of the Host header, and use that as the destination host for that request.

redirect to host/port - You should normally leave these options blank. If they are configured, Burp Proxy will forward every request to the host and port specified, regardless of the target requested by the browser. Note that if you are using this option, it may be necessary to configure a match/replace rule to rewrite the Host header in requests, if the server to which you are redirecting requests expects a Host header that differs from the one sent by the browser.

server SSL certificate - This option lets you configure the server SSL certificates that are presented to your browser. Correct use of these options can resolve some SSL issues that arise when using an intercepting proxy. See the server SSL certificates help for full details of how to use these options.

Note: By default, 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. To make most effective use of this feature, you can install Burp's CA certificate as a trusted root in your browser (see instructions), so that the per-host certificates are accepted without any alerts.

Sometimes, you may wish to create a custom SSL certificate to use within Burp. You can use the following commands in OpenSSL to create a custom certificate (called "foo.crt") with a name of your choosing:

openssl genrsa 1024 > foo.key

openssl req -new -x509 -nodes -sha1 -days 7300 -key foo.key > foo.crt

openssl pkcs12 -export -out foo.p12 -in foo.crt -inkey foo.key -name "your name"

These panels allow fine grained interception rules to be configured governing the interception of requests and responses. The "intercept if" checkboxes control whether any requests and responses at all are intercepted. If one or both of these boxes are checked, then the relevant messages will be intercepted according to the active rules in the table. Individual rules can be activated or deactivated with the checkbox on the left of each rule. Rules can be edited, removed, added or relocated using the buttons on the right.

Rules can be configured on practically any attribute of the message, including domain name, IP address, protocol, HTTP method, URL, resource type, parameters, cookies, header/body content, response code, content type and HTML page title. You can configure rules to only intercept items for URLs that are within the target scope. Regular expressions can be used to define complex matching conditions for each attribute. Rules are combined using the Boolean operators AND and OR. These are processed with a simple "left to right" logic in which the scope of each operator is as follows:

(cumulative result of all prior rules) AND/OR (result of current rule)

All active rules are processed on every message, and the result after the final active rule is applied determines whether the message is intercepted or forwarded in the background.

The "update Content-Length" checkboxes control whether Burp Proxy automatically updates the Content-Length header of requests and responses when these have been modified by the user. If checked, Burp Proxy will recalculate the length of the HTTP body of the modified message, and set the correct value in the HTTP header. This feature is normally essential when the HTTP body has been modified. The HTTP specification, and most web servers, require the correct value for the length of the HTTP body to be submitted in the Content-Length header. If the correct value is not specified, then the server or browser receiving the message may generate an error, process an incomplete message, or may wait indefinitely for further data to be received.

You can use these options to achieve various tasks by automatically rewriting the HTML in application responses. Unhiding hidden fields enables you to edit their values directly in the browser, rather than by intercepting subsequent requests. Similarly with enabling disabled fields, and removing length limitations. Disabling JavaScript and OBJECT tags provides a quick way to disable any client-side logic for testing purposes. (Note that this feature is not designed to be used as a security defence in the manner of NoScript.)

match and replace - These options configure Burp Proxy to perform regex-based pattern matching and replacement on HTTP request and response headers and body. For each rule selected, a regular expression is used to test the header or body for matches, and any matching parts are replaced with the specified string.

For message headers, if the test matches the entire header and the replacement string is left blank, then the header is deleted. If a blank matching expression is specified, then the replacement string will be added as a new header. This feature is useful to automate certain application attacks, such as manipulation of cookies or URL query string fields.

talk HTTP/1.0 to server - This controls whether Burp Proxy enforces HTTP version 1.0 communications with the target server. The default setting is to use whichever version of HTTP is used by the browser. Burp Proxy has been tested successfully with most common web servers using both versions 1.0 and 1.1. However some legacy servers or applications may require version 1.0 in order to function correctly, and so this can be specified here.

unpack gzip / deflate - Some browsers accept gzip- and deflate-compressed content from servers. In order to view or modify this content, it needs to be unpacked into uncompressed form. This option controls whether Burp Proxy performs this unpacking automatically.

History tab

This tab displays details of all requests made, and shows the target server and port number, the HTTP method, the URL, whether the request contains parameters or was manually modified, the HTTP status code of the response, the response size in bytes, the MIME type of the response, the file type of the requested resource, the title of the HTML page, whether SSL was used, the remote IP address, any cookies set by the server, and the time of the request. This tab is useful when you have interception turned off, as it allows you to browse without interruption whilst still monitoring key details about application traffic.

You can click on any column heading in the history table to sort the table according to the contents of that column (or shift-click the column to reverse-sort). For example, if you prefer your history table to grow "upwards", with the most recent items at the top of the table, then you can shift-click the leftmost column showing the request number. Alternatively, if you want to group all of the requested items according the their content type, you can click the "MIME type" column. 

Below the history table is a preview pane. If you select an item from the history, the relevant request and response (if received) will be displayed in the lower pane. If the request or response was modified, either manually or through any rules that you have configured, then the modified items will also be shown alongside the originals.

Right-clicking on one or more items in the history table will show a context menu enabling you to perform various actions, including modifying the target scope, sending the items to other Burp tools, or deleting the items from the history:

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

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.

In addition to viewing request details in the preview pane, you can also double-click on any item in the table to show the request and response in a pop-up window:

The content displayed within the history table is effectively a view into an underlying database, and you can configure filters to determine which items of underlying data are displayed within the table. Some applications contain a large amount of content like images, CSS, etc., which it is normally helpful to hide from view. AJAX applications often generate large numbers of very similar asynchronous requests which you may want to filter from view to see the more interesting items. At the top of the history table, there is a filter bar. Clicking on this shows a popup enabling you to configure exactly what content will be displayed within the table:

You can choose to display only requests with parameters, or which are within the current target scope, or for which a response has been received. 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.

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

As well as filtering, you can also permanently delete items from the history, by selecting one or more items in the history table, and choosing "delete" from the context menu.

In some situations, it can be useful to display more than one view into the underlying history data, and apply different filters to each view. For example, when testing access controls, you may log into an application in different user contexts, and want to review separately the different sequences of requests that occur in each user context. You can open additional views of the proxy history by selecting the "show new history window" option from the proxy history context menu. You can then configure the display filter for each history window to show the requests that you want to see.

To use this feature to help test access controls, you need to use a separate browser for each user context you are testing, and create a separate proxy listener in Burp for use by each browser (you will need to update your proxy configuration in each browser to point to the relevant listener). For each browser, you can then open a separate proxy history window in Burp, and set the filter to show only requests from the relevant proxy listener port. As you use the application in each browser, each history window will show only the items for the associated user context:

In-browser controls

In addition to the main interface, you can control Burp Proxy directly from within your browser.

The full proxy history can be accessed by visiting http://burp with your browser. The history is displayed in a table which shows the target server and port number, the HTTP method, the URL, the file extension, and whether or not the request was modified:

Clicking on an entry in the "URL" column displays the original request. Clicking on an entry in the "modified?" column displays the relevant modified request.

When an individual request is displayed in full, the request can be reissued by clicking the "repeat request" button. Depending on the currently configured interception rules (see Options tab), the request may be displayed within Burp Proxy for modification. When the browser receives the server's response to the re-issued request, onward browsing can continue as normal.

If available, you can also view the original response within your browser by clicking the "view response" button. This causes Burp Proxy to return the exact response originally received from the server, and neither the request nor response will be displayed within Burp Proxy for modification. Note that when the browser receives the saved response from Burp Proxy, this may cause the browser to launch additional requests (e.g. for embedded images). These new requests will be handled by Burp Proxy in the normal way, and will not be returned from any previously saved data.

Extensibility

Burp Proxy is extensible via the IBurpExtender interface. This allows third-party developers to extend the functionality of Burp Suite by creating implementations of the interface which will be dynamically loaded and executed. The processProxyMessage() method of this interface allows implementations to receive full details of every request and response, to perform logging functions, modify the message, specify an action (intercept, drop, etc) and perform any other arbitrary processing. See the source code and Javadoc for the interface for more details.

Copyright © 2010 PortSwigger Ltd. All rights reserved.