Burp Proxy Options

This tab contains Burp Proxy settings for Proxy listeners, intercepting HTTP requests and responses, intercepting WebSockets messages, response modification, match and replace, SSL pass through, and miscellaneous options.

Proxy Listeners

A Proxy listener is a local HTTP proxy server that listens for incoming connections from your browser. It allows you to monitor and intercept all requests and responses, and lies at the heart of Burp's user-driven workflow. By default, Burp creates a single listener on port 8080 of the loopback interface. To use this listener, you need to configure your browser to use 127.0.0.1:8080 as its proxy server. This default listener is all that is required for testing virtually all browser-based web applications.

Burp lets you create multiple Proxy listeners, and provides a wealth of configuration options for controlling their behavior. You may occasionally need to use these options when testing unusual applications, or working with some non-browser-based HTTP clients.

Binding

These settings control how Burp binds the Proxy listener to a local network interface:

• Bind to port - This is the port on the local interface that will be opened to listen for incoming connections. You will need to use a free port that has not been bound by another application.
• Bind to address - This is the IP address of the local interface that Burp will bind to. You can bind to just the loopback interface, or to all interfaces, or to any specific local IP address. Note: if the listener is bound to all interfaces or to a specific non-loopback interface, 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 enable this when you are located on a trusted network.

Request Handling

These settings include options to control whether Burp redirects requests received by this listener:

• Redirect to host - If this option is configured, Burp will forward every request to the specified host, 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.
• Redirect to port - If this option is configured, Burp will forward every request to the specified port, regardless of the target requested by the browser.
• Force use of SSL - If this option is configured, Burp will use HTTPS in all outgoing connections, even if the incoming request used plain HTTP. You can use this option, in conjunction with the SSL-related response modification options, to carry out sslstrip-like attacks using Burp, in which an application that enforces HTTPS can be downgraded to plain HTTP for a victim user whose traffic is unwittingly being proxied through Burp.

Note that each of the redirection options can be used individually. So for example, you can redirect all requests to a particular host, while preserving the original port and protocol used in each original request.

Burp's support for invisible proxying allows non-proxy-aware clients to connect directly to the listener. For more details see the invisible proxying help.

Certificate

These settings control the server SSL certificate that is presented to SSL clients. Use of these options can resolve 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.
• 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 following options are available:

• Use a self-signed certificate - 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 default option. Upon installation, Burp creates a unique, self-signed Certificate Authority (CA) certificate, and stores this on your computer to use each time Burp is run. When your browser makes an SSL connection to a given host, Burp generates an SSL certificate for that host, signed by the CA certificate. You can install Burp's CA certificate as a trusted root in your browser, so that the per-host certificates are accepted without any alerts. You can also export the CA certificate to use in other tools or other instances of Burp.
• 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. This option is sometimes necessary when performing invisible proxying, because the client does not send a CONNECT request, and so Burp cannot identify the required hostname prior to the SSL negotiation. As previously, you can install Burp's CA certificate as a trusted root.
• Use a custom certificate - This option enables you to load a specific certificate (in PKCS#12 format) 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).

Exporting and Importing the CA Certificate

You can export your installation-specific CA certificate for use in other tools or in other instances of Burp, and you can import a certificate to use in the current instance of Burp. Click the "Import / export CA certificate" button to do this.

You can choose to export the certificate only (for importing into the truststore of your browser or other device), or you can export both the certificate and its private key.

Note: You should not disclose the private key for your certificate to any untrusted party. A malicious attacker in possession of your certificate and key may be able to intercept your browser's HTTPS traffic even when you are not using Burp.

You can also export the certificate only by visiting http://burp/cert in your browser. This is the same certificate that Burp presents to your browser when it makes HTTPS requests, but the facility to download it via a URL is helpful when installing on some mobile devices.

If you want to generate a new CA certificate, you can do this by clicking the "Regenerate CA certificate" button. You will need to restart Burp for the change to take effect, and then install the new certificate in your browser.

Creating a Custom CA Certificate

You can use the following OpenSSL commands to create a custom CA certificate with your own details, such as CA name:

openssl req -x509 -days 730 -nodes -newkey rsa:2048 -outform der -keyout server.key -out ca.der

[OpenSSL will prompt you to enter various details for the certificate. Be sure to enter suitable values for all the prompted items.]

openssl rsa -in server.key -inform pem -out server.key.der -outform der

openssl pkcs8 -topk8 -in server.key.der -inform der -out server.key.pkcs8.der -outform der -nocrypt

Then click on the "Import / export CA certificate" button in Burp, and select "Cert and key in DER format". Select ca.der as the certificate file, and server.key.pkcs8.der as the key file. Burp will then load the custom CA certificate and begin using it to generate per-host certificates.

Intercepting HTTP Requests and Responses

These settings control which requests and responses are stalled for viewing and editing in the Intercept tab. Separate settings are applied to requests and responses.

The "Intercept" checkbox determines whether any messages are intercepted. If it is checked, then Burp applies the configured rules to each message to determine whether it should be intercepted.

Individual rules can be activated or deactivated with the checkbox on the left of each rule. Rules can be added, edited, removed, or reordered using the buttons.

Rules can be configured on practically any attribute of the message, including domain name, IP address, protocol, HTTP method, URL, file extension, parameters, cookies, header/body content, status code, MIME type, HTML page title, and Proxy listener port. 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 processed in order, and 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 "Automatically update Content-Length" checkbox controls whether Burp automatically updates the Content-Length header of the message when this has been modified by the user. Using this option is normally essential when the HTTP body has been modified.

For requests, there is an option to automatically fix missing or superfluous new lines at the end of requests. If an edited request does not contain a blank line following the headers, Burp will add this. If an edited request with a body containing URL-encoded parameters contains any newline characters at the end of the body, Burp will remove these. This option can be useful to correct mistakes made while manually editing requests in the interception view, to avoid issuing invalid requests to the server.

Intercepting WebSockets Messages

Use these settings to control which WebSockets messages are stalled for viewing and editing in the intercept tab.

You can configure separately whether outgoing (client-to-server) messages and incoming (server-to-client) messages are intercepted.

Response Modification

These settings are used to perform automatic modification of responses. You can use these options to achieve various tasks by automatically rewriting the HTML in application responses.

The following options may be useful to remove client-side controls over data:

• Unhide hidden form fields. (There is a sub-option to prominently highlight unhidden fields on-screen, for easy identification.)
• Enable disabled form fields
• Remove input field length limits
• Remove JavaScript form validation

The following options may be useful for disabling client-side logic for testing purposes (note that these features are not designed to be used as a security defense in the manner of NoScript):

• Remove all JavaScript
• Remove <object> tags

The following options may be used to deliver sslstrip-like attacks against a victim user whose traffic is unwittingly being proxied via Burp. You can use these in conjunction with the listener option to force SSL in outgoing requests to effectively strip SSL from the user's connection:

• Convert HTTPS links to HTTP
• Remove secure flag from cookies

Match and Replace

These settings are used to automatically replace parts of requests and responses passing through the Proxy. For each HTTP message, the enabled match and replace rules are executed in turn, and any applicable replacements are made.

Rules can be defined separately for requests and responses, for message headers and bodies, and also specifically for the first line only of requests. Each rule can specify a literal string or regex pattern to match, and a string to replace it with.

For message headers, if the match condition 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.

There are various default rules available to assist with common tasks - these are disabled by default.

Matching Multi-Line Regions

You can use standard regex syntax to match multi-line regions of message bodies. For example, if a response body contains only:

Now is the time for all good men
to come to the aid of the party

then using the regex:

Now.*the

will match:

Now is the time for all good men
to come to the aid of the

If you want to match only within a single line, you can modify the regex to:

Now[^\n]*the

which will match:

Now is the

Using Regex Groups in Back-References and Replacement Strings

Groups can be defined within a matcher expression using parentheses, and are assigned a 1-indexed reference number in order from left to right (with group 0 representing the entire match).

Groups can be back-referenced within the same matcher expression by using a backslash followed by the group's index. For example, to match a pair of opening and closing tags with no other tags between, you could use the regex:

<([^/]\w*)[^>]*>[^>]*?</\1[^>]*>

In the replacement string, groups can be referenced using a $ followed by the group index. So the following replacement string will include the name of the tag that was matched in the above regex:

Replaced: $1

SSL Pass Through

These settings are used to specify destination webservers for which Burp will directly pass through SSL connections. No details about requests or responses made via these connections will be available in the Proxy intercept view or history.

Passing through SSL connections can be useful in cases where it is not straightforward to eliminate SSL errors on the client - for example, in mobile applications that perform SSL certificate pinning. If the application accesses multiple domains, or uses a mix of HTTP and HTTPS connections, then passing through SSL connections to specific problematic hosts still enables you to work on other traffic using Burp in the normal way.

If the option to automatically add entries on client SSL negotiation failure is enabled, then Burp will detect when the client fails an SSL negotiation (for example, due to not recognizing Burp's CA certificate), and will automatically add the relevant server to the SSL pass through list.

Miscellaneous

These settings control some specific details of Burp Proxy's behavior. The following options are available:

• Use HTTP/1.0 in requests to server - This option controls whether Burp Proxy enforces HTTP version 1.0 in requests to destination servers. The default setting is to use whichever version of HTTP is used by the browser. However, some legacy servers or applications may require version 1.0 in order to function correctly.
• Use HTTP/1.0 in responses to client - All current browsers support both version 1.0 and 1.1 of HTTP. Since version 1.0 has a reduced feature set, forcing use of version 1.0 can sometimes be useful to control aspects of browsers' behavior, such as preventing attempts to perform HTTP pipelining.
• Set response header "Connection: close" - This option may also be useful to prevent HTTP pipelining in some situations.
• Set "Connection: close" on incoming requests - This option may also be useful to prevent HTTP pipelining in some situations.
• Strip Proxy-* headers in incoming requests - Browsers sometimes send request headers containing information intended for the proxy server that is being used. Some attacks exist whereby a malicious web site may attempt to induce a browser to include sensitive data within these headers. By default, Burp Proxy strips these headers from incoming requests to prevent leakage of any information. Unchecking this option will cause Burp to leave these headers unmodified.
• Strip Accept-Encoding headers in incoming requests - Browsers typically offer to accept various encodings in responses, e.g. for compression of content. Some encodings cause problems when processing responses in Burp. By default, Burp removes this header to reduce the chance that encoding is used. If a server mandates encoding then you might need to uncheck this option.
• Strip Sec-WebSocket-Extensions headers in incoming requests - Browsers may offer to support various extensions relating to WebSocket connections, e.g. for compression of content. Some encodings cause problems when processing responses in Burp. By default, Burp removes this header to reduce the chance that extensions are used. If a server mandates a particular extension then you might need to uncheck this option.
• Unpack gzip / deflate in requests - Some applications (often those using custom client components), compress the message body in requests. This option controls whether Burp Proxy automatically unpacks compressed request bodies. Note that some applications may break if they expect a compressed body and the compression has been removed by Burp.
• Unpack gzip / deflate in responses - Most browsers accept gzip- and deflate-compressed content in responses. This option controls whether Burp Proxy automatically unpacks compressed response bodies. Note that you can often prevent servers from attempting to compress responses by removing the Accept-Encoding header from requests (possibly using Burp Proxy's match and replace feature).
• Disable web interface at http://burp - This option may be useful if you are forced to configure your listener to accept connections on an unprotected interface, and wish to prevent others gaining access to Burp's in-browser interface.
• Suppress Burp error messages in browser - When certain errors occur, by default Burp returns meaningful error messages to the browser. If you wish to run Burp in stealth mode, to perform man-in-the-middle attacks against a victim user, then it may be useful to suppress these error messages to disguise the fact that Burp is involved.
• Don't send items to Proxy history or other Burp tools - This option prevents Burp from logging any requests to the Proxy history or the Target site map, and sending any items for live scanning. It may be useful if you are using Burp Proxy for some specific purpose, such as authenticating to upstream servers or performing match-and-replace operations, and you want to avoid incurring the memory and storage overhead that logging entails.
• Don't send items to Proxy history or other Burp tools, if out of scope - This option prevents Burp from logging any out-of-scope requests to the Proxy history or the Target site map, and sending any out-of-scope items for live scanning. It is useful to avoid accumulating project data for out-of-scope items.