Authentication Token Obtain and Replace (ATOR) Burp Plugin: Fast and Reliable plugin to handle Complex Login Sequences

Problem Statement:

Automated scanners require a constant flow of requests and most tools have built-in session handling logic. Automated scanning/Session Handling for web applications is tricky these days especially because of the following vectors:

  1. CSRF Tokens
  2. JS-based apps (React, Angular) — APIs using authentication tokens
  3. Header values instead of cookies (JWT)
  4. Use of double tokens (access/refresh tokens) — mostly for mobile apps

Existing Solutions:

Burp sessions, macros — Burp has sessions, macros, and invoking extenders on scenarios that help with CSRF tokens (most scenarios), cookie-based session handling, and a few API based scenarios.

Link 1:

Link 2:


  • Not all scenarios are supported — cookies can be replaced in most scenarios, XML, JSON body replacement not supported
  • Usability — This is hard to setup in complex scenarios
  • Slow — the speed is reduced because of duplicate requests (especially in header replacement scenarios)

Custom Macro Extender — This plugin provided a UI based workflow to select and replace tokens. UI was great and was a superb start to solve a tough problem. There were a few bugs that made the plugin unreliable. Also, multiple login requests were sent which made the plugin slow.

Link 1:

Link 2:


  • Error condition was hard to select — when the login sequence should be triggered was a problem. The login sequence would get triggered for every request.
  • Very Slow — the speed is reduced because of repeated login requests for every request
  • Unreliable — The replacement of tokens would not work at times

Objectives for our solution:

We wanted to build a plugin which had the following features:

  1. Easy to use: A plugin which is easy to use and is intuitive
  2. Support complex scenarios: Make the plugin generic so that it would support complex scenarios
  3. Fast: Avoid duplicate requests and change parameters in memory wherever possible


To achieve the above, we thought of building on the great work done by Fruh (Custom Macro Extender). The work done by us can be summarized in the following points:

  • Ease of use: Custom Macro Extender was already easy to use, we have added another tab to handle error conditions. We have also written blog posts to handle complex scenarios.
  • Bugs: We had to make the Custom Extender Plugin more reliable, once the bugs were fixed we could automatically start seeing value.
  • Speed: We use in-memory replacement of tokens instead of sending extra network traffic.
  • Support Complex Scenarios: Regex is used for both figuring out error conditions and also in the replacement of tokens. Using Regex makes handling replacement in JSON, XML, Body, Cookie, URL super easy
  • Configurations: In-Scope and Targets option is added. Targets is the option for content discovery, simulate manual testing options provided by Burp

Working of the Plugin:

Let us breakdown the working of the plugin using an example: let us say an access token is valid for 30 min and expires after 30 min (a new access token has to be fetched).

  1. Scenario 1 — (0–29th min) — Token valid. ATOR sees that the request is valid and request is forwarded to the server.
  2. Scenario 2 — (30th min) — Token is expired. ATOR sees that the error condition is hit. Login sequence is played and the new access token (say AT2) is fetched. This access token is saved in memory
  3. Scenario 3 — (31st min — 59th min) — New access token needs to be used. ATOR has an access token (AT2 saved in memory), it keeps replacing the header with AT2 till the error condition is hit. Once the error condition is hit say on the 60th min, step 2 takes over
Plugin Workflow

How to Use:


Link to the source:

Install the Authentication Token Obtain and Replace (ATOR) Plugin

Setup in settings

[Recommended]: Install Flow or Logger++ Extenders on Burp and enable the traffic from Extender


Follow the 4 step process for any application/API

  1. Identify the login sequence (from proxy or repeater) and send to ATOR
  2. Identify the Error Pattern (details in section below)
  3. Obtain the data from the response using regex (see sample regex values)
  4. Replace this data on the request (use same regex as step 3 along with the variable name)

Totally there are 4 different ways you can specify the error condition.

  1. Status Code: 401, 400
  2. Error in Body: give any text from the body content (Example: Access token expired)
  3. Error in Header: give any text from header(Example: Unauthorized)
  4. Free Form: use this to give multiple conditions status code is 400 and the body contains “Access token expired” (st=400 && bd=Access token expired || hd=Unauthorized). This is useful in scenarios where 400 can be thrown in multiple scenarios.
  1. Use Authorization: Bearer \w* to match Authorization: Bearer AXXFFPPNSUSSUSSNSUSN
  2. Use Authentication: Bearer ([\w+_-.]*) to match Authorization: Bearer AXX-F+FPPNS.USSUSSNSUSN

Testing with a sample application:

Let us use a sample application TiredfulAPI by Payatu Labs for walkthrough purposes. They have a dockerized version which works reliably, we highly recommend doing a sample setup once.

Access token generation
API Access with the generated token
API Access with an invalid token

Configure ATOR for the Tiredful application

Step 1: Identify the login sequence

In this example, a simple one step login can be used to fetch access token

Send login sequence to ATOR
Pull the response and extract the access token

Step 2: Identify error pattern

In this example, a 401 is returned every time the access token is invalid

Response on an invalid token (401)
Adding error codes in ATOR

Step 3: Specify Regex pattern for replacement of token

In this example, the access token is fetched from the response

Authorization header contains the access token
Give pattern as Authorization: Bearer \w*

You could use regex patterns here. Refer to regex examples above.

Step 4: Replace this data on the request

In this example, we replace the token in the header. Here we use the regex

Give replacement area as Authorization: Bearer token (here “token” came from extraction configuration in Step 1)

Regex for replacement in request

Video walkthrough


  1. Massive shout out to Fruh for coming up with Custom Macro Extender
  2. Thanks to Synopsys for letting us open source the plugin. Also thanks to many of our colleagues at Synopsys who tested and provided feedback on the plugin.


Ashwath Reddy (@ka3hk) — Principal Consultant at Synopsys

Manikandan Rajappan ( — Consultant at Synopsys

Part 2

We talk about handling complex login scenarios (multi step login), multiple token replacement and regex (with examples) in the next post.




Love podcasts or audiobooks? Learn on the go with our new app.

Reshape (Numpy) in Python

Solving the Final IT Dilemma

How To Develop A Port Scanner Using Python | Develop Port Scanner Like Nmap Just Using Python

EMQ X Cloud launches sub-account management, powering efficient enterprise management

Exam Prep: 70–532 Developing Microsoft Azure Solutions

Creating Atlassian Confluence pages with Postman

Managing Terraform Code

Building a distributed ETL pipeline for a monolithic data warehouse

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
ashwath kumar

ashwath kumar

More from Medium

Vulnerability Management is the Key to Stopping Attacks

Vulnerability Management

A pragmatic guide to building your bug bounty program

Runner Up at BPJS Kesehatan Security Hackathon

Thread Local Storage

TLS message box