1. Support Center
  2. Documentation
  3. Desktop editions
  4. Tools
  5. Proxy
  6. Options

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:

Request handling

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

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:

The following options are available:

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:

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):

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:

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: