close search bar

Sorry, not available in this language yet

close language selection

Authentication Token Obtain and Replace (ATOR) Burp plugin to handle complex login sequences

Synopsys Editorial Team

Jun 11, 2020 / 11 min read

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

  • CSRF tokens
  • JavaScript-based apps (React, Angular) and APIs using authentication tokens
  • Header values instead of cookies (JWT)
  • Use of double tokens (access/refresh tokens), mostly for mobile apps

Existing solutions

Burp sessions and macros

Burp has sessions, macros, and the ability to invoke extenders, which help with CSRF tokens (most scenarios), cookie-based session handling, and a few API-based scenarios. Shortcomings:

  • Lack of support. Not all scenarios are supported. Cookies can be replaced in most scenarios. XML and JSON body replacement is not supported.
  • Difficult to use. It’s hard to set up in complex scenarios.
  • Slow. The speed drops because of duplicate requests (especially in header replacement scenarios).

Custom macro extender

The ExtendedMacro plugin (GitHub) provides a UI-based workflow to select and replace tokens. The UI is great and is a superb start to solve a tough problem. But the plugin has a few bugs that make it unreliable. It’s also slow because it sends multiple login requests. Shortcomings:

  • Difficult to set up. It’s hard to select the error condition that triggers the login sequence. Instead, every request triggers the login sequence.
  • Very slow. The speed is reduced because of repeated login requests for every request.
  • Unreliable. Sometimes the replacement of tokens doesn’t work.

Our solution: ATOR Burp plugin

We wanted to build a Burp plugin supporting complex login sequences with the following features:

  • Easy to use. The plugin should be easy to use and intuitive.
  • Support for complex scenarios. The plugin should be generic so that it could support complex scenarios.
  • Fast. The plugin should avoid duplicate requests and, instead, change parameters in memory wherever possible.

To achieve the above, we built on the great work done by Fruh (ExtendedMacro) to create the Authentication Token Obtain and Replace (ATOR) plugin. Our work can be summarized in the following points:

  • Ease of use. ExtendedMacro was already easy to use, but we added another tab to handle error conditions. We also wrote blog posts about how to handle complex scenarios.
  • Bugs. We made ExtendedMacro more reliable. Once we fixed the bugs, we immediately started seeing value.
  • Speed. We used in-memory replacement of tokens instead of sending extra network traffic.
  • Support for complex scenarios. We used regex for both figuring out error conditions and replacing tokens. Using regex makes it super easy to handle replacement in JSON, XML, the body, cookies, and URLs.
  • Configurations. We added In-Scope and Targets options. The Targets option is for content discovery and simulates manual testing options provided by Burp.

How the ATOR plugin works

Diagram Illustrating How ATOR Burp Plugin Works in Software Security

Let’s break down how the ATOR plugin works using an example. Say an access token is valid for 30 minutes and then expires (after which a new access token has to be fetched). We have three scenarios:

1. Token is valid (Minute 0–29). ATOR sees that the request is valid and forwards the request to the server.

2. Token is expired (Minute 30). ATOR sees that the error condition is met. It triggers the login sequence, fetches a new access token (AT2), and saves the new access token in memory.

3. New access token needs to be used (Minute 31–59). ATOR replaces the token in request headers with AT2 till the error condition is met again. At that time—in this case, on Minute 60—ATOR goes back to Step 2 to fetch a new access token to store in memory.

How to use the ATOR plugin

Before using ATOR

1. Install the ATOR plugin.

Step-by-Step Guide to Install ATOR Burp Plugin for Software Security

2. Recommended: Install the Flow or Logger++ extender on Burp, and enable traffic from the extender.

Screenshot of Enabling Extender Traffic in Software Security Application

Using ATOR

Follow this four-step process for any application or API:

  1. Identify the login sequence (from the proxy or repeater) and configure it in ATOR.
  2. Specify the error pattern.
  3. Specify the regex pattern to replace in the request.
  4. Specify the new data to use in the request.

Testing ATOR with a sample application

Let’s use the sample application TiredfulAPI by Payatu Labs for a walkthrough. The dockerized version works reliably. We highly recommend doing a sample setup once.

1. Generate an access token:

Generating an Access Token in Tiredful API for Software Security

2. Test API access with the generated token:

Successful API Access Test Using Valid Security Token

3. Test API access with an invalid token:

Error Message Displaying Invalid API Access Test Result

Configure ATOR for the Tiredful application

In this example, we’ll fetch each new access token using a simple one-step login.

1. Identify the login sequence and configure it in ATOR.

We send an existing login response to ATOR:

Software Security Diagram Illustrating Sending Existing Login Response to ATOR

We configure ATOR to extract the access token from the login response. Here, the variable “token” will contain the token string:


2. Specify the error pattern.

You can specify the error condition in four ways:

  1. Status Code: 401, 400
  2. Error in Body: specific text from the body (e.g., “Access token expired”)
  3. Error in Header: specific text from the header (e.g., “Unauthorized”)
  4. Free Form: combination of multiple conditions (e.g., status code is 400, body contains “Access token expired”: st=400 && bd=Access token expired || hd=Unauthorized). This is useful when 400 can be thrown in multiple scenarios.

In this example, the server returns a status code of 401 when the access token is invalid:


So we specify the error type as “Status Code” and the message / status code value as “401”:

Unauthorized Access Error Message Displaying Status Code 401

3. Specify the regex pattern to replace in the request.

Sample regex patterns:

  • Use Authorization: Bearer \w* to match Authorization: Bearer AXXFFPPNSUSSUSSNSUSN
  • Use Authentication: Bearer ([\w+_-.]*) to match Authorization: Bearer AXX-F+FPPNS.USSUSSNSUSN

In this example, we can see where the access token appears in the request:

Diagram Illustrating the Process of Access Token Request in Software Security

So we specify the replacement pattern as Authorization: Bearer \w*.

Software Security Specify Replacement Pattern Screenshot

4. Specify the new data to use in the request.

We set the replacement area as Authorization: Bearer token (we created the variable “token” in Step 1):


Scenario walkthrough

Using the same example as above, where the access token is valid for 30 minutes, let’s walk through the different scenarios:

1. Token is valid (Minute 0–29)

The repeater sends a request with a valid token (AT1). ATOR checks the status code in the response. It’s OK (200), so ATOR sends the response to the repeater:

ATOR Software Security System Sending Valid Response

2: Token is expired (Minute 30)

The Tiredful application allows us to revoke a token. Let’s use this feature to expire AT1:

Expired Access Token Error Message in Tiredful API Security Software

The next repeater request contains AT1, which we just revoked:

Diagram Illustrating Request with Revoked Security Token

So the server returns a status code of 401. ATOR senses that the error condition is met, invokes the login sequence, and extracts and stores a new token (AT2). Then it checks the flow, finds the last request, replaces the token with AT2, and resends the request:

ATOR Cybersecurity Software Retrieving and Sending New Token

3. New access token needs to be used (Minute 31–59)

The next repeater request is still using the expired token:

Security Software Screenshot Showing Request with Expired Token Error Message

So ATOR replaces it with AT2 (the token currently stored in memory):

ATOR Software Security System Replacing Token

Revoking the new token (AT2) and generating a new one (AT3)

For the sake of completion, let’s run through another revocation of the token:

Expired Access Token Error Message in Tiredful API Security Software

The next request uses the expired token (AT2):

Diagram Illustrating Request with Revoked Security Token in Software Security

When the server returns a status code of 401, ATOR invokes the login sequence again and stores the newest token (AT3) in memory. It checks the flow for the last request and resends it with AT3:

ATOR Cybersecurity Software Retrieving and Sending New Security Token

The next repeater request uses an expired token:

Diagram Illustrating Request Process with Expired Security Token

This time, ATOR just replaces the expired token with AT3 (the token currently stored in memory) instead of invoking the login sequence:

Ator replaces token 2

Continue Reading

Explore Topics