Burp Macros - How to use them correctly

Burp Macros

How to use them correctly

Andrea Hauser
by Andrea Hauser
on July 13, 2023
time to read: 13 minutes


Burp Macros and their functionalities

  • In the beginning of using Burp, I have struggled with Burp macros
  • They can be used to fetch CSRF tokens
  • Furthermore, they can be used to scan request in the middle of a process
  • Or when session tokens are only valid for a very short amount of time
  • Burp macros can greatly help a tester to simplify their testing experience

In the beginning of using Burp, I have always found Burp macros to be kind of a hassle. In this article, I would like to share my insights on how to use macros, so that testing can be simplified and automated further. After reading this article you should no longer find Burp macros quite as tedious as before.

Before we dive into the details of how to use Burp macros, let’s first define what use cases they are good for:

The Burp macros configuration area can be found in the Settings > Sessions tab. In the session tab there is an area to define macros and after defining them they can be used in the sessions handling rules area. Let’s walk through some examples of common use cases.

Fetching CSRF tokens

Following is a sample request with an invalid CSRF token sent from Repeater, an Active Scan, the Intruder or other tools from Burp:

POST /post/comment HTTP/2
Host: example.com
Cookie: session=8SBvBwMjQsrORhTzZP7UPjyzm1DC37Sk
X-CSRF-Token: invalid
Content-Length: 44
Content-Type: application/x-www-form-urlencoded


Which results in the following response:

HTTP/2 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 20

"Invalid CSRF token"

With a valid CSRF token the following response would have been expected:

HTTP/2 302 Found
Location: /post/comment/confirmation?postId=6
Content-Length: 0

A valid CSRF token for this example application is generated every time a specific blog post is loaded with the following request:

GET /post?postId=6 HTTP/2
Host: example.com
Cookie: session=8SBvBwMjQsrORhTzZP7UPjyzm1DC37Sk

The response then contains:

HTTP/2 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 7795

<snipped for brevity>
<!DOCTYPE html>
<html> <body>
  <h2>Leave a comment</h2>
  <form action="/post/comment" method="POST" enctype="application/x-www-form-urlencoded">
    <input required type="hidden" name="csrf" value="BDy7eKqX0YE1SfNi4aPtuXcDktU4EMvB">
    <input required type="hidden" name="postId" value="6">
    <input required name="comment">
    <button class="button" type="submit">Post Comment</button>
</body> </html>

So, to be able to use tools like the Repeater, Intruder, Sequencer and possibly Extensions without problems, a macro needs to be defined that fetches the CSRF token with the previously identified GET request that returns a valid CSRF token. For that a new macro can be added in the Settings > Sessions area. Once the add button is clicked, a Macro Recorder view is shown where the previously identified request must be selected. In the Macro Editor view we now need to let Burp know how to extract the CSRF token from the response. This can be done with Configure Item and adding a Custom Parameter. Since the example application we are using is expecting the CSRF token once in the request body as the parameter CSRF as well as in the request headers as X-CSRF-Token, we need to define two custom parameters one named CSRF and the other named X-CSRF-Token.

Custom Parameter defined as CSRF

Now that the macro is defined and Burp knows how to fetch a CSRF token, we need to let Burp know in which areas and for which scope to use the newly defined macro. This can be done with the session handling rules, which are also in the Settings > Sessions area.

For that we are adding a new session handling rule and define the rule action to run the macro that we have previously created. In the next step we define the scope and with that we let Burp know for which specific tools and URLs the macro should be executed. Furthermore, we can define that the macro should only be executed when specific parameters like CSRF and X-CSRF-Token in our example are present in the request. In that way we minimize the macro execution to only necessary areas so that we don’t send unnecessary requests to the application.

Scope which triggers only when CSRF token is effectively needed

We usually check whether the newly defined macro works as expected in the Repeater before we start a scan or let Intruder run.

Common pitfalls

We have created a macro and the repeated request is containing the CSRF token, but all other user specified values which should not have been changed have also been overwritten by the macro. This can happen with the default behavior of Burp. In that case you should change the session handling rule from the default Update all parameters and headers ... to Update only the following parameters and headers and define the parameters that should be overwritten, in our example application that would be CSRF and X-CSRF-Token.

Default behavior that leads to the overwriting of wrong parameters:

Wrongly configured session handling rule

Correctly configured session handling rule so that only specific parameters are overwritten:

Correctly configured session handling rule

A second area for issues could be that the used macro is indeed correctly updating the CSRF token, but the cookie is outdated, and requests fails due to this. This can happen when in the session handling rule the checkmark from the default setting Update current request with cookies from session handling cookie jar is erroneously removed. Since cookies are not updated from the cookie jar, if the cookie has been changed in the meantime, the request is no longer valid.

Erroneously removed default behavior in the cookie handling area:

Wrongly configured session handling rule

The correct default behavior would be:

Correctly configured session handling rule

Request in the middle of a process

Secondly, let’s look at a process which needs to be started from the beginning for scanning a request in the middle of the process to be valid. For that, the macro creation starts as discussed before, but instead of only one request more than one request is selected in the Macro Recorder view. It makes sense to have tested the sequence of needed requests manually in the Repeater beforehand, to be sure all requests need to be involved in the process are selected. After selecting the needed requests in the Macro Recorder, we need to make sure the parameters are correctly derived from each other. Burp tries to derive the parameters itself and shows automatically derived parameters in the derived parameters column, but if one of the expected values is not automatically derived, you can define a custom parameter as before and then use this custom parameter in the next request to set a parameter to derived from previous request.

If on the other hand a process needs to be finished to see the results of a scan or other attack technique, the same principle with selecting multiple requests in the Macro Recorder as discussed before can be used. But in the session handling area the created macro should be run as a post-request macro. So, the macro will be executed every time after a request you define is sent.

Short session timeouts

And lastly, there is the use case with very short session timeouts which don’t allow scans to finish or a manual analysis in the repeater to be efficient. Since this is a common use case, Burp even has a built-in function in the session handling area called Check session is valid to allow for the workflow to be executed easily. When choosing that function, you can specify what to look for in an invalid request and what kind of login request should be performed to receive a new cookie as soon as logout happened. That way, you as tester don’t need to manually refresh the session every time the session expires.

For parameters that have not been discussed in this article it is recommended to consult Burps documentation, which has a section about macros as well as session handling rules.


Burp macros take a bit to get used to but once you understand the options presented, they are a great tool for your arsenal to allow more efficient testing. They can be a great tool to automate the scanning of otherwise non-automatable requests, where for example a CSRF token needs to be prefetched or a process needs to be started or finished for a scanned request to make sense. Even session tokens which expire in a very short amount of time are no longer a problem. Every tester that would like to make their life easier should look into Burp macros and getting used to them. In general it is always sensible to fully use all of one’s tools provided functionalities to make one’s life easier.

About the Author

Andrea Hauser

Andrea Hauser graduated with a Bachelor of Science FHO in information technology at the University of Applied Sciences Rapperswil. She is focusing her offensive work on web application security testing and the realization of social engineering campaigns. Her research focus is creating and analyzing deepfakes. (ORCID 0000-0002-5161-8658)


You want more than a simple security test with Nessus und Nmap?

Our experts will get in contact with you!

Ways of attacking Generative AI

Ways of attacking Generative AI

Andrea Hauser

XML Injection

XML Injection

Andrea Hauser

WebSocket Fuzzing

WebSocket Fuzzing

Andrea Hauser

Prototype Pollution

Prototype Pollution

Andrea Hauser

You want more?

Further articles available here

You need support in such a project?

Our experts will get in contact with you!

You want more?

Further articles available here