ProfessionalCommunity Edition

Match and replace

• Last updated: December 19, 2024

• Read time: 5 Minutes

Match and replace rules enable you to automatically replace parts of messages as they pass through the Proxy. You can configure and enable these in the Proxy > Match and replace tab for both HTTP and WebSocket messages. Burp executes enabled match and replace rules in turn for each message, making any applicable replacements.

The HTTP match and replace rules include 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.

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

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. You can configure match and replace rules in two different ways:

• Settings mode enables you to configure a match and replace rule using checkboxes and drop-downs. You can use this to create rules for both HTTP and WebSocket messages. For more information, see Settings mode.
• Professional Bambda mode enables you to write a powerful match and replace rule using Burp's Java-based Bambdas. You can use this to create rules for HTTP messages. For more information, see Bambda mode.

Settings mode

On the Settings mode tab, you can apply a match and replace rule using the configuration options.

To add a new rule using Settings mode:

1. Click Add to open the Add match/replace rule dialog.
2. In the Add match/replace rule dialog, click the Settings mode tab.

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

   • Type - For HTTP requests, specify the type of rule you want to define. For example, Request header or Response body.
   • Direction - For WebSocket messages, specify the direction of the message you want the rule to apply to. Choose from Client to server, Server to client, or Both directions.
   • Match - The string or regex pattern you want the rule to match. If you leave this blank for an HTTP rule with the Request header or Response header type, the replacement string is added as a new header.
   • Replace - The string you want the rule to replace. If you leave this blank for an HTTP rule with the Request header or Response header type, then any header that matches is removed.
   • Comment - An optional description of the rule.
4. If you want Burp to treat the match parameter as a regex, select Regex match. For more information, see Using regex syntax.
5. For HTTP messages, you can test the rule using the built-in test function. For more information, see Testing HTTP match and replace rules.
6. Click OK. The new rule is added to the table and automatically enabled for the current project.

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.

Bambda mode

Professional On the Bambda mode tab, you can write Java-based Bambdas to apply HTTP match and replace rules.

Two objects of the Montoya API are available to help you write your Bambdas:

• ProxyHttpRequestResponse
• Utilities

The Bambda must return either the HttpRequest or HttpResponse object.

For advanced use cases, you can also access a subset of the MontoyaAPI functionality. This enables you to create more complex Bambdas.

To add a new rule using a Bambda:

1. Click Add to open the Add match/replace rule dialog.
2. In the Add match/replace rule dialog, click Bambda mode.
3. Write your Bambda using Java.
4. Click OK.

The Bambda is added to the HTTP match and replace rules table and automatically enabled for the current project.

Example Bambdas

In the example below, we'll create a Request Bambda that forces all HTTP requests to https://ginandjuice.shop and adds a User: Admin header.

return requestResponse.request() .withService(HttpService.httpService("https://ginandjuice.shop")) .withAddedHeader("User", "Admin") .withUpdatedHeader("Host", "ginandjuice.shop");

In the example below, we'll create a Response Bambda that uses the MontoyaAPI functionality to send items to Organizer with the note "Cached response" when they meet the following criteria:

• The response has an X-Cache header with a value of Hit.

In this example, our Bambda is:

if(requestResponse.response().headerValue("X-Cache").contains("Hit")) { api().organizer().sendToOrganizer(HttpRequestResponse.httpRequestResponse(requestResponse.request(), requestResponse.response(), Annotations.annotations("Cached response"))); } return requestResponse.response();

Testing HTTP match and replace rules

When adding or editing a HTTP match and replace rule, you can test your rule using the built-in test function. This enables you to confirm that the string or regex pattern correctly matches and replaces the intended text.

To test a HTTP match and replace rule in the match/replace rule editor:

1. Review the sample message under Original request or Original response. Optionally, replace this sample message with the specific request or response you'd like to test the rule against.
2. Click Test. Burp applies the rule to the original message, creating a modified request or response.
3. Review the modified request or response under Auto-modified request or Auto-modified response.
4. Adjust the rule as necessary.

To restore the sample request or response, click .

Using regex syntax

You can use a regex pattern to match the text you want to replace. This enables you to match a variety of text inputs that follow a specific format, such as email addresses or IP addresses. It also enables you to match the underlying structure for content that changes dynamically.

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:

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

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:

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

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:

Replaced: $1