Proxy settings

The Proxy page in the Settings dialog contains settings for the following:

• Proxy listeners.
• Request and response interception rules.
• WebSocket interception rules.
• Response modification rules.
• Match and replace rules.
• TLS pass through.
• Proxy history logging.
• Default Proxy interception state.
• Miscellaneous.

Proxy listeners

A proxy listener is a local HTTP proxy server that listens for incoming connections from the browser. It enables 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.

You may need to create or configure listeners when you test unusual applications, or work with non-browser-based HTTP clients. Use the Add and Edit buttons to open the Add a new proxy listener dialog. You can configure the proxy listener settings in the dialog tabs.

The Proxy listeners settings are project settings. They apply to the current project only.

Binding

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

• Bind to port - Specify a port on the local interface. Burp opens the port to listen for incoming connections. Make sure you use a free port that has not been bound by another application.

• Bind to address - Specify an IP address of the local interface for Burp to bind to. You have the following options:

  • The loopback interface only.
  • All interfaces.
  • A specific local IP address.

Request handling

These settings control whether Burp redirects the requests received by the listener:

• Redirect to host - Specify a host. Burp forwards every request to the host, regardless of the target requested by the browser.

  • If you redirect requests to a server that expects a different Host header to the one sent by the browser, you may need to configure a match and replace rule to rewrite the Host header in requests.
• Redirect to port - Specify a port. Burp forwards every request to the port, regardless of the target requested by the browser.

• Force use of TLS - Enable this setting to use HTTPS in all outgoing connections, even if the incoming request uses HTTP.

  • To carry out sslstrip-like attacks, use this option with the TLS-related response modification settings. This type of attack downgrades an application that enforces HTTPS to plain HTTP, for a victim whose traffic is unwittingly being proxied through Burp.
• Support invisible proxying - This setting enables non-proxy-aware clients to connect directly to the listener. For more details, see Burp Proxy: invisible proxying.

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.

Certificate

These settings control the server TLS certificate that is presented to TLS clients. You can use these settings to resolve some TLS issues that arise when you use an intercepting proxy.

The following options are available:

• Use a self-signed certificate - If this option is selected, Burp presents a self-signed certificate to your browser. This always causes a TLS alert.
• Generate CA-signed per-host certificates - This is the default option. If selected, Burp creates a unique, self-signed Certificate Authority (CA) certificate on installation. The certificate is stored on your computer for use each time Burp is run. When your browser makes a TLS connection, Burp generates a TLS certificate for the host, signed by the CA certificate.
• Generate a CA-signed certificate with a specific hostname - Specify a hostname, which Burp uses to generate a single host certificate to use with every TLS connection. Use this option if you perform invisible proxying, as the client does not send a CONNECT request, so Burp can't identify the required hostname prior to the TLS negotiation.
• Use a custom certificate - Load a specific certificate to present to your browser. Note that the certificate must be in in PKCS#12 format with a .p12 file extension; certificates in .psx format are not supported. Use this option if the application uses a client that requires a specific server certificate with, for example, a given serial number or certification chain.

TLS Protocols

These settings control the TLS protocols that Burp uses to perform TLS negotiation with the browser.

The following options are available:

• Use the default protocols of your Java installation.
• Use custom protocols. Select the required protocols from the list.

HTTP

This setting controls whether the proxy listener allows clients to use HTTP/2. It 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.

Request and response interception rules

The Request interception rules and Response interception rules settings control which messages are stalled for you to view and edit in the Proxy > Intercept tab.

Adding an interception rule

To add an interception rule:

1. Select Intercept requests / responses based on the following rules to configure rules that determine which messages are intercepted.
2. Click Add to open the Add request interception rule dialog.

3. Specify the details of the interception rule:

   • Boolean operator - The operator that Burp uses to combine the rule to the rule above. You can choose from AND and OR.
   • Match type - The attribute of the message that the rule attempts to match on. For example, the domain name, IP address, or protocol.
   • Match relationship - This can be either Matches or Does not match.
   • Match condition - The value that the rule uses when matching. You can use regular expressions to define complex matching conditions.
4. Click OK to create the rule.

Burp applies the enabled rules to the message to determine whether it should be intercepted. Each rule is combined to the rules above in order, using the selected boolean operator.

Use the checkbox on the left of each rule to activate or deactivate it. You can also Edit and Remove rules, or reorder them using the Up and Down buttons.

Modifying intercepted messages

These settings enable you to avoid invalid requests and responses being issued when you modify an intercepted message.

• Automatically update Content-Length header when the request / response is edited - Enable this setting to automatically update the Content-Length header with the correct length of the message's HTTP body. This is normally essential when the HTTP body is modified.

• Automatically fix missing or superfluous new lines at end of request - Enable this setting to automatically correct common mistakes that are made when requests are edited in the interception view:

  • Burp adds a blank line following the headers if there is not one already present.
  • Burp removes any newline characters at the end of a body containing URL-encoded parameters.

The Request and response interception rules settings are project settings. They apply to the current project only.

WebSocket interception rules

These settings control whether Burp holds WebSocket messages for viewing and editing in the Intercept tab.

You can select to:

• Intercept client-to-server messages.
• Intercept server-to-client messages.

The WebSocket interception rules settings are project settings. They apply to the current project only.

Response modification rules

These settings control whether Burp automatically rewrites the HTML in application responses.

You can use the following settings to remove client-side controls over data:

• Unhide hidden form fields. You can also select Prominently highlight unhidden fields, for easy identification on-screen.
• Enable disabled form fields.
• Remove input field length limits.
• Remove JavaScript form validation.

You can use the following settings to disable client-side logic for testing purposes:

• Remove all JavaScript.
• Remove <object> tags.

You can use the following settings to deliver sslstrip-like attacks against a victim user whose traffic is unwittingly being proxied via Burp. Use these settings with the listener's Force use of TLS setting to effectively strip TLS from the user's connection:

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

The Response modification rules settings are project settings. They apply to the current project only.

Match and replace rules

These settings automatically replace parts of requests and responses as they pass through the Proxy.

There are various predefined rules which you can enable to assist with common tasks. These are disabled by default.

To only apply match and replace rules to items that are in the project scope, select Only apply to in-scope items. For more information on how to set a scope for your work, see Scope settings - Target scope.

Adding a match and replace rule

Each match and replace rule specifies a literal string or regex pattern to match, and a string to replace it with. To add a new rule:

1. Click Add to open the Add match/replace rule dialog.

2. Specify the details of the match/replace rule:

   • Rule type - The type of rule you want to define. For example request header or response body.
   • Match - The string or regex pattern you want the rule to match. If you leave this blank, the replacement string is added as a new header.
   • Replace - The string you want the rule to replace. If you leave this blank, then any header that matches is removed.
   • Comment - An optional description of the rule.
3. If you want Burp to treat the match parameter as a regex, select Regex match.
4. Click OK. The new rule is automatically enabled.

Burp executes the enabled match and replace rules in turn for each message, and makes any applicable replacements.

You can also Edit and Remove rules, or reorder them using the Up and Down buttons.

Matching multi-line regions

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

then using the regex:

will match:

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

which will match:

Using regex groups in back-references and replacement strings

In a Match expression you can:

• Define groups using parentheses. Burp assigns groups a 1-indexed reference number in order from left to right (with group 0 representing the entire match).
• Back-reference groups. Use 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:

You can reference groups in the replacement string by using a $ followed by the group index. For example, the following replacement string would include the name of the tag that matched the above regex:

The Match and replace rules settings are project settings. They apply to the current project only.

TLS pass through

You can use these settings to specify the destination web servers that Burp passes directly through TLS connections.

Use these settings when it is difficult to eliminate TLS errors on the client. For example, in mobile applications that perform TLS certificate pinning. If the application accesses multiple domains or uses both HTTP and HTTPS connections, you can pass through TLS connections to specific problematic hosts, and still work on other traffic as normal.

Adding TLS passthrough targets

To add a new TLS passthrough target, copy the URL and then click Paste URL to add the relevant web server to the list. You can also configure the target manually:

1. Click Add to display the Add TLS passthrough target dialog.

2. Specify the target details:

   • Host or IP range - This can be a regex or an IP range. Leave blank to match any item.
   • Port - The port that TLS passthrough should apply on. Leave blank to match any item.
3. Click OK to add the target to the list.

You can Edit and Remove targets from the list. To upload a CSV or text list of targets, click Load and select the relevant file from the dialog.

Select Automatically add entries on client TLS negotiation failure to add the relevant server to the TLS pass through list when a client fails a TLS negotiation. A TLS negotiation may fail, for example, if Burp's CA certificate is not recognized.

The TLS pass through settings are project settings. They apply to the current project only.

Proxy history logging

Use this setting to manage whether Burp Proxy sends out-of-scope items to the history or live tasks when new items are added to the target scope. This enables you to avoid accumulating project data for out-of-scope items.

There are three options available:

• Stop logging out-of-scope items.
• Ask me what to do each time.
• Do nothing.

The Proxy history logging settings are user settings. They apply to all installations of Burp on your machine.

Default Proxy interception state

Use this setting to choose whether Burp Proxy interception is enabled by default when you start Burp.

There are three options available:

• Enable interception.
• Disable interception.
• Restore the setting that was selected in the Proxy > Intercept tab when Burp closed.

The Default Proxy interception state settings are user settings. They apply to all installations of Burp on your machine.

Miscellaneous

These settings control various aspects of Burp Proxy's behavior:

• Use HTTP/1.0 in requests to server - Enable this setting to use HTTP version 1.0 in requests to destination servers. This may be useful when working with legacy servers or applications that require version 1.0 to function correctly.
• Use HTTP/1.0 in responses to client - Enable this setting to use HTTP version 1.0 in responses. All current browsers support both version 1.0 and 1.1 of HTTP, however version 1.0 has a reduced feature set. A reduced feature set can help you to control aspects of a browsers' behavior, for example to prevent attempts to perform HTTP pipelining.
• Set response header "Connection: close" - Enable this setting to add or update the response Connection header with the value close. This can enable you to prevent HTTP pipelining in some situations.
• Set "Connection: close" on incoming requests - By default, Burp adds or updates the request Connection header with the value close. This can enable you to prevent HTTP pipelining in some situations.
• Strip Proxy-* headers in incoming requests - By default, Burp strips Proxy-* headers from incoming requests. This prevents leakage of any information, as browsers sometimes send request headers containing information intended for the proxy server. A malicious web site may attempt to induce a browser to include sensitive data within these headers.
• Remove unsupported encodings from Accept-Encoding headers in incoming requests - By default, Burp removes encodings that cause problems when Burp processes responses. This reduces the chance that they are used. You may need to de-select this setting if a server requires an unsupported encoding.
• Strip Sec-WebSocket-Extensions headers in incoming requests - By default, Burp removes this header. This reduces the chance that extensions relating to WebSocket connections are used, as some encodings cause problems when processing responses in Burp. You may need to de-select this setting if a server requires a particular extension.
• Unpack gzip / deflate in requests - Enable this setting to automatically unpack compressed request bodies, which are often present in applications using custom client components. Note that some applications may experience issues if they expect a compressed body but the compression has been removed.
• Unpack gzip / deflate in responses - Enable this setting to automatically unpack compressed response bodies. Note that you can often prevent servers from compressing responses - use a match and replace rule to remove the Accept-Encoding header from requests.
• Disable web interface at http://burpsuite - This setting may be useful if you need 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 - Enable this setting to suppress the messages that are usually sent to the browser when errors occur. This may be useful if you wish to run Burp in stealth mode in order to perform man-in-the-middle attacks against a victim user.
• Don't send items to Proxy history or live tasks - If you enable this setting, Burp can't log requests in the Proxy history or send them to live tasks. This enables you to limit the memory and storage overhead. This may be useful, for example, if you are using Burp to authenticate upstream servers or perform match-and-replace operations.
• Don't send items to Proxy history or live tasks, if out of scope - If you enable this setting, Burp can't log any out-of-scope requests in the Proxy history or send them to live tasks. This enables you to avoid accumulating project data for out-of-scope items.

The Miscellaneous settings are project settings. They apply to the current project only.