Cyber Security Technical Blog

Burp Suite Macros – Reshaper Guide

Written by Karl Schuttler | Oct 7, 2022 11:42:34 AM

Burp Suite Macros

If you’ve performed web application pentests with Burp Suite for a while, you’ve certainly come across applications that don’t play nicely with Burp Suite’s out-of-the-box scanning. Perhaps the application is stateful and requires a few requests to prime the state of the application before you can actually submit the request you are testing. Maybe the web server expects a nonstandard CSRF token to be inserted into a bunch of weird headers or cookies. Nevertheless, Burp Suite offers a few solutions to these problems natively, such as the new-ish Navigation Recorder chrome plugin and macros with session handling rules, or by chaining multiple instances together using upstream proxies. Unfortunately, the workflow of the native tools can be a bit hard to understand, which is compounded by issues like the Macro Recorder window blocking access to the rest of the Burp Suite user interface. 

Thankfully, there is a single plugin you can learn to solve many of your request juggling problems: Reshaper by Daquanne Dwight of Synfron.com.

Reshaper

Reshaper is a plugin designed to “trigger actions and reshape HTTP request and response traffic using configurable rules”. Its rules can apply to any or all Burp Suite tools you want and includes a straightforward debugging interface for its rules engine. A lot of what you can accomplish with Reshaper can be done with macros and a combination of other plugins, but few plugins provide as much functionality to solve these problems in as straightforward a manner.

In the following sections of this post, I’ll briefly discuss the interface of Reshaper and the library of options that it provides, then walk through solving a sample problem that isn’t already covered by the official examples. Here are some pretty good ideas of what Reshaper can do:

  • Use a value from one HTTP message in the following HTTP message.
  • Execute a system process and use its output in HTTP messages.
  • Build and send HTTP requests.
  • Redirect a request to a different server.
  • Change a value in a returned response.
  • Auto-respond to requests without first sending a request to an external server (response mocking).
  • Drop a request so it is not sent to an external server.
  • Share or backup/restore Global Variables and Rules.

Reshaper User Interface

Reshaper has four primary windows, which are selected using the additional row of tabs at the top of the screen:

  • Rules: Create and edit rules based on “When -> Then” type logic.
  • Global Variables: View and edit variables you have created, which may be inserted in requests. Variable values may be viewed in real-time.
  • Logs: Rules debugging interface.
  • Settings: Configure which tools Reshaper will edit, configure logging, and export data.

Most of your time with Reshaper will be spent on the Rules page (above), which is split into two panes: Whens and Thens. The dropdown options at the top of these windows allow you to select the desired “When” or “Then” feature, which may then be added to the rules processing queue. Whens are used to select which requests/responses you want to interact with, and Thens configure how they are handled. A simple rule flow might involve selecting requests sent to a specific URI, parsing the body of that request’s response, saving the output in a variable, and then submitting that variable in a new request. That’s actually the scenario we’ll cover at the end of this article.

A lot of your success and efficiency using Reshaper will depend on your familiarity with the library of Whens and Thens available to you. The plugin was only first published in December 2021 but offers a ton of flexibility through its options. I highly recommend you refer to the Reshaper Rules documentation while designing your solutions.

Reshaper – Whens

The first step in developing a Reshaper rule is to identify the characteristics of the request/response you want to operate on. The Whens you input will act as successive filters, passing messages that match your rules to the Thens. The following Whens are available:

  • Event Direction: Filter based on whether the message is a Request or Response.
  • Has Entity (Boolean): Filter based on the presence of an entity, such as a specific Request Cookie or Response Header.
  • Matches Text: Filter based on basic text matching or regular expression, searching a specific portion of the message (e.g., Request URI) for the string.
  • Content Type: Filter based on the Content-Type header (e.g., JSON, XML).
  • MIME Type: For responses only, filter on the response’s MIME type (e.g., HTML, JSON, SVG).
  • Proxy Name: Filter based on proxy listener interface (e.g., 127.0.0.1:8080).
  • From Tool: Although Reshaper’s Settings allow you to specify globally which Burp Suite tools (e.g., Target, Intruder, Repeater) it will operate on, you can further specify on a per-rule basis by filtering with From Tool.
  • In Scope: Filter based on whether an input URL is within the Target Scope. Can be run dynamically based on the contents of a variable (e.g., scraping a URL from a response body and then executing a subsequent request if the URL is in scope). 

Each of the Whens also include two checkbox options:

  • Use OR Condition: By default, all Whens implement AND logic, but this may be overridden using this checkbox.
  • Negate Result: The Whens’ logic is inverted, selecting all messages that do not match the provided criteria (e.g., select all messages that do not contain a specific string using Matches Text).

Reshaper – Thens

After you’ve successfully selected the HTTP messages you want to act upon, Reshaper’s Thens are used to define the operation you wish to perform. Reshaper offers a lot of Thens configuration options, which are prohibitively too long to list here comprehensively. The author’s Reshaper rules documentation covers each option in detail. A brief description of each Thens is provided below to give you an idea of the type of actions Reshaper can perform:

  • Break: Halt rules/Thens processing.
  • Delay: Pause a specified number of milliseconds.
  • Log: Log a specified value to the Reshaper Logs tab, duplicated within the extension-specific log under Burp Suite Extender. Burp Suite Extender’s extension-specific settings may be used to raise Reshaper’s logs within Burp Suite Dashboard.
  • Highlight: Highlight the message within Burp Suite Proxy History. Useful for visually identifying Proxy items that Reshaper has acted upon.
  • Comment: Add comment to message within Burp Suite Proxy History, with support for variables. Comment does not currently support comments within the Burp Suite Logger tab.
  • Prompt: Raise a dialog window asking for input, and save it to a variable.
  • Run Rules: Force execution of other Reshaper rules, specifying either a single rule to be run or all Reshaper rules.
  • Run Script: Execute arbitrary JavaScript, with access to Reshaper features via its scripting library. Useful for executing more complicated logic than supported by the Evaluate Then.
  • Evaluate: Perform simple operations (e.g., addition, subtraction, division, multiplication, incrementation, rounding, comparison) against inputs.
  • Set Event Direction: After processing the current rule, specify whether to send a request or response to Burp Suite. 
  • Set Encoding: Set the encoding of the current request/response body.
  • Set Value: Set the value of an HTTP event parameter (e.g., request parameter, request URI, response parameter, request cookie). This includes specification by HTTP parameter or JSON node, as well as HTML CSS selector and raw text. Useful for modifying HTTP messages.
  • Delete Value: Remove an HTTP message entity (e.g., response header).
  • Set Variable: Set a Reshaper variable using the value of an HTTP event parameter (e.g., request parameter, request URI, response parameter, request cookie). This includes specification by HTTP parameter or JSON node, as well as HTML CSS selector and raw text. Useful for parsing HTTP messages.
  • Delete Variable: Delete a Reshaper variable.
  • Save File: Save contents of Reshaper variable(s) to a local file. 
  • Send To: Forward message to Burp Suite Comparer, Repeater, Intruder, Spider, or the default system Browser.
  • Run Process: Execute an external system process, with input for standard in and output to Reshaper variable. Useful for integrating external tools or transforming application inputs using native system binaries (e.g., using grep and sed to extract values from HTML responses and save them to Reshaper variables). It’s recommended that you execute shell commands using a shell script rather than building the full command logic within the Reshaper Run Process input fields. Applications may terminate their output with a Newline character (%0A), so it may be necessary to use Set Value to delete it.
  • Build HTTP Message: Develop an HTTP message using a series of Setter arguments to specify message entities (e.g., the Request Body). An existing Starter message may be specified to act as a template. Any additional Setter arguments are cumulative to the Starter message (e.g., if a Starter message was specified that contained request headers and a Setter was also used to add the headers from the previous request to the current request, it’s likely that duplicate headers will result in the request).
  • Parse HTTP Message: Provided a request or response, save one or more event parameters (e.g., Response Body, Request URI) to multiple associated variables. Note that Parse HTTP Message does not support the specification of parameters by JSON node, HTML CSS path, or HTTP variable name, unlike the Set Value Then.
  • Send Request: Provided a variable or string containing a request message, send that request to its target. The URL, Protocol, Address, and Port options override any value set within the initial request message.
  • Drop: Drop the message.

Reshaper Variables

Reshaper’s Whens and Thens control how you select and manipulate HTTP messages, but it doesn’t have built-in pipeline processing that passes your values automatically from one When/Then to the next. Nearly all textual input fields allow you to specify a variable as the source of their data and a second variable to save the modified value. Built-in message variables give you access to a lot of the information you’ll want to work with, like request URIs, headers, and bodies – and will save a lot of time having to parse out these details yourself. When working with variables in Reshaper, I suggest using the right-click context menu to insert them to avoid issues with variable tag markup (seen below).

Keep in mind that Variable Tags only reference the variable’s value, so variable tags are typically used for input fields, and the variable’s name (non-tagged) used for output fields.

Variable tags are enclosed in double curly brackets {}, with a lowercase letter specifier denoting which variable type you are referencing. For example, the global variable “confirmationID” will be represented as . The following variable types are available:

  • Event: Custom variables (user-defined) specific to rules running against the same unique request or response. 
  • Global: Custom variables (user-defined) available across all rules.
  • Message: Built-in variables that reference components of the message you are working with, such as the Request URI or Response Body.
  • File: Supply file-based input in a variety of encoding formats.
  • Special: Allows you to specify special characters for input without worrying about encoding/escaping issues (e.g., New Line, Carriage Return, arbitrary Unicode characters).
  • Cookie Jar: Reference cookie values from Burp Suite’s built-in cookie jar.

Reshaper Debugging

It’s unlikely that the first rule configurations you develop will be successful right off the bat. Enabling the “Enable Event Diagnostics” setting will allow you to view the results of the rules processing engine within the Logs tab. By walking through the application with rules enabled, you can validate that the behavior of Reshaper matches your expectations. Use of Reshaper’s Logs tab, Burp Suite Logger, and Burp Suite Comparer together will help you determine where things are going awry.

Some common pitfalls are:

  • The target web application might expect that requests that you build using Reshaper have different headers, such as a different “accept” header.
  • The Burp Suite UI sometimes misrepresents the status of checkboxes, such as the box used to enable/disable rules. You may need to hover your mouse over them to view their current status.
  • Requests may require multiple token values (e.g., Spring Flow timestamps) to create a valid request, necessitating multiple rules to handle them.
  • Execution of external commands using the Thens -> Run Process feature may be difficult to debug interactively, so it is recommended that all logic is performed within a shell script called by Run Process, rather than trying to build the full command logic within the Burp Suite Reshaper configuration input window. Applications may terminate their output with a Newline character (%0A), so it may be necessary to use Set Value to delete it.
  • Stateful applications, such as those that require an updated Cross Site Request Forgery (CSRF) token on each request, will require that you scan using a single thread. These scans may take a significant time to run, so you may need to also implement a Reshaper rule or slow running Intruder attack to perform a session keep-alive function.  
  • Be careful to provide the appropriate variable markup within the UI, depending on whether you are referencing the value of a variable or referencing the variable identifier itself. In general, inputs to Thens expect the variable’s value, provided by referencing the variable’s tag (e.g., to reference the value stored by the confirmationId variable). Outputs from Thens typically reference the variable’s name directly and should not include tag markup. 
  • If using Global variables, consider marking them “Persistent” so that their value will be saved and restored when you close and open Burp Suite.

Solving A Sample Problem With Reshaper

The sample problem below involves parsing data from HTTP responses and submitting a newly developed request using that data. The format of the step-by-step instructions in this section approximates the format used in Reshaper’s official example documentation to make it easier to transition between them. 

I recently tested an application designed to allow 401K retirement plan owners to manage their investments. Plan owners could change how much money they contributed from their paycheck each month and to which investments it would be applied to, or rearrange the entirety of their investments as they saw fit. The application was highly stateful, and for any change requested to a plan, the application locked the plan’s owner from submitting additional change requests until the queued change was processed the next day. Thankfully, a DELETE request could be used to cancel pending account changes, so the Burp Suite Scanner could be used to perform automated scanning against the change request while using Reshaper to automate deletion of pending changes as they were created…

The general application flow looked like this:

  1. The user makes a POST request to /accounts/421337/change including desired changes in the request body.
  2. When successful, the application responds with a JSON body, including confirmation ID and epoch time of the processed request.
  3. To cancel the change request, a DELETE request is submitted to /accounts/421337/<confirmation ID>. 

Reshaper Example – Whens

In order to automate this flow, we’ll first need to detect when change requests are successfully submitted by filtering with Whens:

Create a new Rule:

  1. Open the Rules tab
  2. Create a Rule
  3. Set the Rule name to “Delete Change”

Operate on application Responses:

  1. Add When -> “Event Direction” (if not already added)
  2. Change “Event Direction” to “Response”

Select Change Requests based on their URI:

  1. Add When-> “Matches Text”
  2. Select “Use Message Value” to use the previous HTTP request as the source.
  3. Set the “Source Message Value” to the “Request URI Path”
  4. Set the Source Value Type to “Text”
  5. Set the Match Type to “Contains”
  6. Set the Match Text to “change” to match change requests for any account number

Select only Change Requests that include a confirmation ID in their response:

  1. Add When -> “Matches Text”
  2. Set Source Message Value to Response Body.
  3. Set Match Type to “Contains”
  4. Set Match Text to confirmation ID parameter “confirmationID”

Reshaper Example – Thens

Now that we’ve detected a change request, we’ll need to parse out the confirmation ID, build the DELETE request, and send it.

Extract the Confirmation ID:

  1. Add Thens -> Set Variable
  2. Select “Use Message Value”
  3. Set Source Message Value to Response Body
  4. Set the Source Value Type to JSON
  5. Set Source Value Path to the JSON variable key, “confirmationID”
  6. Set Destination Variable Source to “Global”
  7. Set Destination Variable Name to a new global variable, “confirmationID”

Save the previous request’s headers to a Global Variable for use in the subsequent DELETE request:

  1. Add Thens -> Set Variable
  2. Select “Use Message Value”
  3. Set Source Message Value to “Request Headers”
  4. Set Source Value Type to “Text”
  5. Set Destination Variable Source to “Global”
  6. Set Destination Variable Name to “requestHeaders”
  7. Set Destination Value Type to “Text”

Build the DELETE Request:

  1. Add Thens -> Build HTTP Message
  2. Set Event Direction to Request
  3. Set Starter HTTP Message to URI line from the DELETE request in Burp Suite,
    DELETE /accounts/421337/22F14B0261919BB HTTP/1.1
  4. Delete the confirmation ID and use the right-click Insert Variable Tag > Tag Type “Global” > Variable Name “confirmationID”:
    DELETE /accounts/421337/ HTTP/1.1
  5. Set Message Value Setter Source Text to the “requestHeaders” Global Variable using the right-click menu. 
  6. Set Destination Variable Source to “Global”.
  7. Set Destination Variable Name to “deleteRequest”

Send the DELETE Request

  1. Add Thens -> Send Request
  2. Set Request to the “deleteRequest” Global Variable using the right-click menu. It’s not mandatory to fill out all the fields. Any additional field input will supersede the values set within the Request.
  3. Select Wait for Completion

Enable the Rule

  1. Select the “Delete Change” rule in the left Rules pane, check the “Enabled” checkbox in the lower right, and click Save.

You Better Shape Up

Reshaper offers a wealth of possible solutions to slice, dice, and julienne Burp Suite’s activity, allowing you to quickly solve web application pentesting problems without needing to open up Eclipse and write a new plugin. Reshaper may be found in the Burp Suite Extender BApp Store and on the author’s github page. Download the plugin and experiment with it on your next assessment! Once you’ve developed a general familiarity with its Whens, Thens, and variables, dealing with application nuisances becomes an easy affair and you can focus your time identifying vulnerabilities instead of wrestling with scan configurations.

MORE FROM OUR TECHNICAL BLOG

Cyber Advisors specializes in providing fully customizable cyber security solutions & services. Our knowledgeable, highly skilled, talented security experts are here to help design, deliver, implement, manage, monitor, put your defenses to the test, & strengthen your systems - so you don’t have to.

Read more from our technical experts...

Sources:

1. https://synfron.github.io/ReshaperForBurp/Examples.html – Reshaper examples from the author

2. https://synfron.github.io/ReshaperForBurp/Rules.html – Reshaper Rules documentation

3. https://synfron.github.io/ReshaperForBurp/Variables.html – Reshaper variables documentation.

4. https://synfron.github.io/ReshaperForBurp/MessageValues.html – Reshaper Message Values

5. https://github.com/synfron/ReshaperForBurp – Reshaper Official Github

6. https://portswigger.net/bappstore/7bcec7656b5746e9a85c427f243e6d5a – Reshaper on the official Burp Suite App Store
View full post