Unlock enhanced API scanning with Burp Suite Enterprise Edition  –  Learn more
Research Academy
My account Customers About Blog Careers Legal Contact Resellers

ProfessionalCommunity Edition

Match and replace

  • Last updated: August 30, 2024

  • Read time: 3 Minutes

Match and replace rules enable you to automatically replace parts of messages as they pass through the Proxy. You can configure these for both HTTP and WebSocket messages.

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.

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:

    • 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.
  3. If you want Burp to treat the match parameter as a regex, select Regex match.
  4. For HTTP messages, you can test the rule using the built-in test function. For more information, see Testing HTTP match and replace rules.
  5. Click OK. The new rule is 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.

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

Was this article helpful?