Automate Login with Burp Suite Session Macros (2026)

Session macros are Burp Suite’s secret weapon for keeping your authenticated sessions alive during active scans.

Here’s a typical scenario: you’re scanning a web application, and after a few requests, you get logged out. Burp’s scanner, which is just blindly making requests, suddenly starts hitting unauthenticated pages and generating a ton of false positives. This happens because most applications use session tokens that expire after a certain time or a number of requests. You need a way for Burp to automatically refresh that token before it expires.

Let’s look at how to set up a session macro to handle this.

The Goal: To have Burp automatically re-authenticate (or refresh a session token) when it detects an expired session.

The Setup:

1. Identify the Re-authentication Flow: First, you need to manually perform the steps required to log in or refresh your session. This usually involves sending a username/password or submitting a form that generates a new session token. Record this sequence of requests in Burp’s HTTP history.

2. Create a Macro:

   • Go to the "Project" tab in Burp.
   • Navigate to "Sessions" -> "Macros".
   • Click "New".
   • Give your macro a descriptive name, e.g., "AppLoginMacro".

3. Define the Macro Requests:

   • In the "Macro definition" section, click "New" to add a request.
   • Paste the first request from your recorded re-authentication flow into the request editor. This is typically the login request.
   • If your re-authentication requires multiple steps (e.g., a CSRF token fetch followed by a login), add those subsequent requests using "New" again, ensuring they are in the correct order.
   • Crucially, you need to tell Burp how to extract the new session token from the response.

4. Extracting the Session Token:

   • After adding your re-authentication request(s) to the macro, click "New" under "Macro body -> Response processing".
   • Select "1. Extract value from all previous responses".
   • In the "Extract value" dialog, select the part of the response that contains the new session token. This might be a cookie (Set-Cookie header) or a hidden form field in the HTML body.
   • Choose the extraction method: "Extract value from header" for cookies, or "Extract value from body" for HTML content.
   • Use regular expressions to precisely target the token. For example, if your response includes Set-Cookie: SESSIONID=abcdef123456; Path=/, you’d use ^SESSIONID=([^;]+); to capture abcdef123456.
   • Give this extracted value a meaningful name, like session_token. This name will be used later to refer to the extracted value.

5. Configuring the Macro to Run:

   • Go back to the "Sessions" tab.
   • In the "Session Handling Rules" section, click "New".
   • Give your rule a name, e.g., "HandleAppSessions".
   • Under "When to run this rule", select "Do macro substitution (apply macro to all requests)". This tells Burp to run the macro before every request if needed.
   • Under "Macro to run", select the macro you created ("AppLoginMacro").
   • Now, you need to tell Burp when to run this macro. This is usually triggered by an error or a specific response indicating an expired session.
   • Under "If macro returns a value", select "Use value for subsequent requests".
   • Under "Check for errors", check "Response is an error" and enter a regular expression that matches your application’s "logged out" page or error message. For example, if your logout page has the title "Please Login", you might use <title>Please Login</title>.

6. Updating Subsequent Requests:

   • In your macro definition, you’ve extracted a session_token. Now you need to tell Burp to use this token in subsequent requests.
   • Go back to your macro definition ("AppLoginMacro").
   • For each request in your macro, you need to ensure that the session token is correctly included. If it’s a cookie, Burp usually handles this automatically if you’ve defined the macro correctly. If it’s a header or part of the request body, you might need to explicitly add it using Burp’s macro substitution syntax: $<session_token>.

7. Testing the Macro:

   • Go to the "Target" tab and initiate a scan on the application.
   • Observe the "Session Handling" logs in Burp’s "Dashboard" or "Project" -> "Sessions" tab. You should see your macro being executed when Burp encounters an expired session.
   • You can also manually trigger the macro by right-clicking a request in HTTP history, selecting "Do session handling", and choosing your macro.

The most surprising thing about session macros is how infrequently they are configured correctly, leading to scans that are either incomplete or generate mountains of irrelevant data because the scanner is operating without a valid session.

This mechanism allows Burp to dynamically adapt to the application’s authentication state, ensuring that active scans are performed against an authenticated user, thereby yielding more accurate and meaningful results. Without it, many authenticated scans would effectively become unauthenticated scans after the initial session expires, rendering the results largely useless for finding vulnerabilities specific to authenticated functionality.

The next hurdle you’ll likely face is handling applications that use multiple, independent session tokens or complex multi-factor authentication flows.