Options: macro editor

The macro editor lets you configure all the details of a macro.

Record macro

Macros are recorded using your browser, which must be configured to use the current instance of Burp as its proxy server.

When recording a macro, Burp displays a view of the Proxy history, from which you can select the requests to be used for the macro. You can select from previously made requests, or record the macro afresh and select the new items from the history. Note that to record a new macro using your browser you will need to turn off Proxy interception.

When you have selected the items you wish to include in the macro, click "OK", and the items are shown in the macro editor.

Configuring macro items

The macro editor displays the list of items in the macro. You can modify these by changing the order, removing items, or re-recording the macro. You can modify any individual request by selecting it in the list, and editing it directly in in the request viewer.

As well as the basic sequence of requests, each macro includes some important configuration about how items in the sequence should be handled, and any interdependencies between items. To edit the configuration of a macro item, select it in the list and click the "Configure item" button.

Cookie handling

You can configure:

• Whether cookies received in the response should be added to the session handling cookie jar.
• Whether cookies from the session handling cookie jar should be added to the request.

Parameter handling

For each parameter in the request, you can configure whether it should be assigned a fixed preset value, or a value derived from a previous response in the macro.

The ability to derive a request parameter's value from a previous response in the macro is particularly useful in some multi-stage processes, and in situations where applications make aggressive use of CSRF tokens. Parameter derivation is based on the parameter name, and the URL being requested. If you specify that a parameter's value should be derived from a previous response, Burp will examine that response for any source of the named parameter being submitted to the relevant URL (for example, a form using the given action URL, and containing a field with the given name). If found, Burp will extract the parameter's value from that response, and update it in the request being processed.

When a new macro is defined, Burp tries to automatically find any relationships of this kind, by identifying parameters whose values can be determined from the preceding response (form field values, redirection targets, query strings in links, etc.). You can manually override the automatic analysis as required.

Custom parameter locations in response

Burp's matching of parameters between macro items works automatically for known "normal" parameter locations within responses, such as form field values, and query strings in links. In some cases, you need more flexibility than this, and the ability to specify an arbitrary location within a response as containing a parameter. For example, an application might define a CSRF token within a JavaScript string, and dynamically add this to a script-generated request. To create a macro capable of deriving this parameter, you will need to tell Burp the location of the parameter within the response containing the script, and the name used for that parameter in subsequent requests.

Use the "Define custom parameter" dialog to specify the name of the custom parameter, its location within the response item being configured, and whether the value extracted from the response is URL-encoded. This is done using the response extraction rule dialog. When this has been done, the named parameter will be available for use in subsequent macro requests (or the request being processed by a session handling rule) in the normal way as described in Parameter Handling.

It is important to configure whether the value extracted from the response is URL-encoded. This ensures that Burp can correctly encode the value when it is used in subsequent requests, reflecting whether the context into which it is being placed needs to be URL-encoded.

Re-analyze macro

When a new macro is defined, Burp tries to automatically find any relationships between macro items, by identifying parameters whose values can be determined from the preceding response. If you have manually modified the items in the macro, you can repeat the automatic analysis using the "Re-analyze macro" button.

Test macro

When you have configured a macro, including any derivations of request parameters from earlier responses, you can use the "Test macro" feature to verify that the configuration is working as intended. This will issue the macro requests in sequence, and attempt to derive any parameter values according to your configuration. Burp will display all requests and responses, the values of any cookies received, and the details of any parameters whose values it succeeded or failed to derive.