Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 38 ยท Authentication and Sessions Testing

Session Handling Rules and Macros

Learn how Burp session handling rules and macros keep scans and Intruder attacks logged in: expired sessions, CSRF tokens, re-login macros and a Python model of the logic.

Testing a logged-in application with automated tools hits a practical problem: the session keeps breaking. The server expires it after 15 minutes, or a CSRF token changes after every form, or a stray logout request kills it. Your scan then spends its time testing the login page instead of the application. Session handling rules and macros teach Burp how to stay logged in and keep tokens fresh.

Burp runs on the desktop, so the configuration screens here are labelled example descriptions. The Python blocks are stand-ins that model the logic offline with no network.

The idea

Burp applies session handling rules to requests sent by chosen tools (Scanner, Intruder, Repeater, Sequencer...). A rule has three parts:

  1. Scope: which tools and which URLs it applies to.
  2. Conditions / actions: what to do.
  3. Order: rules run top to bottom, so order matters.

You find them under Settings, Sessions, Session handling rules. Typical actions:

Action Use it for
Use cookies from Burp's cookie jar Keep the session cookie updated across tools
Set a specific cookie or parameter value Insert a known token
Check session is valid Detect an expired session by looking at a response
Run a macro Perform a login or fetch a fresh token
Run a post-request macro Do something after each request, such as refresh
Invoke a Burp extension Custom signing, header computation

Burp keeps a cookie jar of cookies seen in traffic from the Proxy, the Scanner, the Repeater and others. By default the jar updates from the Proxy and Scanner, and a session rule can enable it for Intruder or Repeater so those tools use the latest cookie automatically. This alone solves many problems: log in once in the browser, and your scan inherits the session.

Macros

A macro is a recorded sequence of requests that Burp can replay. Macro Recorder (Sessions, Macros, Add) lets you pick requests from the proxy history, for example:

  1. GET /login (to get the form and a CSRF token)
  2. POST /login (with username and password for your test account)

Then in the macro editor you configure parameters: which values to take from the previous response (for example the CSRF token from the form, extracted with a regular expression or by name) and which to take from the macro's original request. You can test the macro in the editor to see that the final response shows a logged-in page.

TEXT
Example macro "Login" (labelled example)
Request 1: GET  /login            -> extract hidden field csrf_token="(.*?)"
Request 2: POST /login            -> username=tester1 & password=****** & csrf_token=<from request 1>
Result:    302 -> /dashboard  and  Set-Cookie: sid=... (new session cookie goes in the cookie jar)

Detecting an expired session

A rule must know when to log in again. The Check session is valid action sends the request and looks at the response using a condition:

  • Does the response contain text such as "Please log in", or a redirect to /login?
  • Is the HTTP status 401 or 403?
  • Does it lack a marker such as "Logout", which appears only when logged in?

If invalid, run the macro and then retry the request. If still invalid after the macro, Burp can stop the scan, which protects you from testing a login page for an hour.

flowchart TD
  A["Request about to be sent<br/>by Scanner or Intruder"] --> B["Rule: cookie jar<br/>adds current cookies"]
  B --> C["Send request"]
  C --> D{"Response says<br/>logged out?"}
  D -- No --> E["Pass response<br/>to tool"]
  D -- Yes --> F["Run login macro"]
  F --> G["Update cookie jar<br/>and retry request"]
  G --> C

A session rule detects the logged-out state, runs the macro, then retries.

Model the logic in Python

This stand-in has a fake application whose session expires after a few requests and a client that behaves like a session rule with a macro. Everything is in memory.

Python Session rule with re-login macro (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Every third call the model session dies, and the rule transparently logs in again, so the "scan" always sees dashboard.

CSRF tokens in Intruder and Scanner

Many forms include a token that changes after every request. Without help, the second Intruder request would be rejected as a CSRF failure. Solutions in Burp:

  • A session rule with a macro that fetches the form page first and copies the new token into the request (using macro parameter handling).
  • The CSRF token tracker style extension, which updates the token automatically.
  • In the Scanner, Burp can often handle common anti-CSRF tokens, but custom ones need the macro approach.

Extracting a token the way a macro does

Python Extract a CSRF token with a regex (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical tips

  • Keep your scope tight so a rule never sends credentials to another site.
  • Use a low-privilege test account in macros; never a real admin.
  • Add the logout URL to the scan's exclude list so the crawler does not end the session itself.
  • Check the Dashboard event log: it says when a macro ran and whether a rule marked a session invalid.
  • Use the rule's Tester (Sessions, Session handling rules, Open sessions tracer) to watch what each rule did to a request.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What problem do session handling rules solve?

    Rules and macros refresh sessions and tokens so scans and attacks test the application, not the login page.
  2. 2. What is a macro in Burp?

    A macro replays one or more requests, extracting values such as tokens from responses.
  3. 3. How can a rule detect that a session has expired?

    Check session is valid uses response conditions such as a login redirect or a missing logout marker.
  4. 4. Why exclude the logout URL from a crawl?

    A crawler that follows every link will log itself out.
  5. 5. Which account should a macro use?

    Dedicated low-privilege accounts limit damage and keep the test authorised.

Summary

  • Session handling rules apply actions to requests from chosen Burp tools; order and scope matter.
  • The cookie jar shares cookies between tools; macros replay a login or token fetch.
  • A validity check detects expiry, runs the macro and retries.
  • CSRF tokens are handled by extracting them from the previous response.
  • The Burp configuration here is described as labelled example; the Python blocks model the logic offline.

Next: JWT and token testing