Burp Proxy options
Last updated: January 27, 2023
Read time: 11 Minutes
The Options tab contains Burp Proxy settings for:
A Proxy listener is a local HTTP proxy server that listens for incoming connections from the browser. It allows you to monitor and intercept all requests and responses.
By default, Burp creates a single listener on port 8080 of the loopback interface. The default listener enables you to use Burp's browser to test virtually all browser-based web applications.
Burp lets you create multiple Proxy listeners, and provides a wealth of configuration options to control their behavior. You may need to configure these options when you test unusual applications, or work with non-browser-based HTTP clients.
To access the configuration options:
- Select the listener.
- Click Edit to open the Edit proxy listener menu.
- Go to the relevant option tab.
The following option tabs are available:
The Binding tab controls how Burp binds the Proxy listener to a local network interface:
- Bind to port - This is the port on the local interface that is opened to listen for incoming connections. You 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 binds to. You can bind to:
- The loopback interface only.
- All interfaces.
- A specific local IP address.
If the listener is bound to all interfaces or to a specific non-loopback interface, other computers may be able to connect to the listener.
The Request handling tab controls whether Burp redirects requests received by the listener:
- Redirect to host - Forward every request to the specified host, regardless of the target requested by the browser. If you use this option, you may need to rewrite the Host header in requests by configuring a match/replace rule. This is necessary if you redirect requests to a server that expects a different Host header to the one sent by the browser.
- Redirect to port - Forward every request to the specified port, regardless of the target requested by the browser.
- Force use of TLS - Force Burp to use HTTPS in all outgoing connections, even if the incoming request uses plain HTTP. To carry out sslstrip-like attacks, use this option in conjunction with the TLS-related response modification options. This type of attack downgrades an application that enforces HTTPS to plain HTTP, for a victim whose traffic is unwittingly being proxied through Burp.
The redirection options can be used individually. For example, you can redirect all requests to a particular host while preserving the request's port and protocol.
Invisible proxying allows non-proxy-aware clients to connect directly to the listener. For more details see Invisible proxying.
The Certificate tab controls the server TLS certificate that Burp presents to TLS clients. You can use these options to resolve some TLS issues that arise when using an intercepting proxy:
- You can eliminate TLS alerts in your browser, and the need to create TLS exceptions.
- Where web pages load TLS-protected items from other domains, you can make sure that these are properly loaded by the browser, without manually accepting the proxy's TLS certificate for each referenced domain.
- You can work with thick client applications that refuse to connect to the server if an invalid TLS certificate is received.
The following options are available:
- Use a self-signed certificate - A simple self-signed TLS certificate is presented to your browser, which always causes a TLS 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 a TLS connection to a given host, Burp generates a TLS 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 - Burp generates a single host certificate to use with every TLS connection, using the hostname you specify. You may need this option if you perform invisible proxying - the client does not send a CONNECT request, so Burp can't identify the required hostname prior to the TLS negotiation. You can install Burp's CA certificate as a trusted root.
Use a custom certificate - This enables you to load a specific certificate (in PKCS#12 format) to present to your browser. Note that this must have the
.p12file extension; certificates in
.psxformat are not supported. Use this option if the application uses a client which requires a specific server certificate with, for example, a given serial number or certification chain.
For information on importing, exporting and creating CA certificates, see Managing CA certificates.
These settings control the TLS protocols that Burp uses to perform TLS negotiation with the browser. You can configure Burp to use the default protocols of your Java installation, or override the defaults and enable custom protocols.
This setting controls whether the proxy listener allows clients to use HTTP/2. This is enabled by default.
You may want to disable this in certain cases, such as when a client has problems with its HTTP/2 implementation.
This setting does not change the connection between Burp and the server. To learn how to change the connection between Burp and the server, see HTTP settings.
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.
Use the checkbox on the left of each rule to activate or deactivate it. Use the buttons to add, edit, remove, or reorder rules.
You can configure rules on practically any attribute of the message, including:
- Domain name.
- IP address.
- HTTP method.
- File extension.
- Header/body content.
- Status code.
- MIME type.
- HTML page title.
- 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. 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 adds this. If an edited request with a body containing URL-encoded parameters contains any newline characters at the end of the body, Burp removes 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.
Intercept WebSocket Messages
Use these settings to control which WebSocket 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.
You can 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.
You can use the following options to disable 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 <object> tags.
You can use the following options to deliver sslstrip-like attacks against a victim user whose traffic is unwittingly being proxied via Burp. Use these with the listener option to force TLS in outgoing requests to effectively strip TLS from the user's connection:
- Convert HTTPS links to HTTP.
- Remove secure flag from cookies.
Match and Replace
You can use Match and Replace rules to automatically replace parts of requests and responses that pass through the Proxy. For each HTTP message, Burp executes the enabled rules in turn, and makes any applicable replacements.
You can define rules separately for requests and responses, for message headers and bodies, and also for the first line only of requests. You can specify a literal string or regex pattern to match for each rule, 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 you specify a blank matching expression, the replacement string is 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 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:
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:
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:
TLS Pass Through
Use these settings to specify destination web servers which Burp directly passes TLS connections to. No details about requests or responses made via these connections are available in the Proxy intercept view or history.
TLS Pass Through can be useful in cases where it is difficult to eliminate TLS errors on the client, such as mobile applications that perform TLS certificate pinning. If the application accesses multiple domains or uses a mix of HTTP and HTTPS connections, you can pass through TLS connections to specific problematic hosts, and still work on other traffic using Burp in the normal way.
If you enable Automatically add entries on client TLS negotiation failure, Burp detects when the client fails a TLS negotiation. For example, Burp's CA certificate may not be recognized. In this case, Burp automatically adds the relevant server to the TLS pass through list.
You can access the following options in the Miscellaneous section:
- 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 a browsers' behavior, such as preventing attempts to perform HTTP pipelining.
- Set response header "Connection: close" - This option may be useful to prevent HTTP pipelining in some situations.
- Set "Connection: close" on incoming requests - This option may 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. Some attacks use a malicious website 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.
- Remove unsupported encodings from Accept-Encoding headers in incoming requests - Browsers typically offer to accept various encodings in responses. Some encodings cause problems when processing responses in Burp. By default, Burp removes unsupported encodings to reduce the chance that they are used. If a server mandates support for an unsupported 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. 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://burpsuite - This option may be useful if you are forced to configure your listener to accept connections on an unprotected interface, and you want 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.
- Don't send items to Proxy history or live tasks - This option prevents Burp from logging any requests to the Proxy history or sending them to live tasks. It may be useful if you want to avoid incurring the memory and storage overhead that logging entails for certain tasks. For example, authenticating to upstream servers or performing match-and-replace operations.
- Don't send items to Proxy history or live tasks, if out of scope - This option prevents Burp from logging any out-of-scope requests to the Proxy history or sending them to live tasks, such as passive crawling or live auditing. It is useful to avoid accumulating project data for out-of-scope items.
Was this article helpful?
An error occurred, please try again.