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: https://portswigger.net/support/using-burp-suites-session-handling-rules-with-anti-csrf-tokens

Link 2: https://blog.nviso.eu/2019/08/29/using-burps-session-handling-rules-to-insert-authorization-cookies-into-intruderrepeater-and-even-sqlmap/

Shortcomings:

• 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: https://citadelo.com/en/blog/extendedmacro-burpsuite-plugin/

Link 2: https://github.com/FrUh/ExtendedMacro

Shortcomings:

• 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

Implementation:

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:

[Installation]

Link to the source: https://github.com/synopsys-sig/ATOR-Burp

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

[Usage]

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)

Step 2 — Error Pattern :

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.

Step 4 — Regex with samples

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

Acknowledgments

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.

Authors

Ashwath Reddy (@ka3hk) — Principal Consultant at Synopsys

Manikandan Rajappan (www.linkedin.com/in/mani2raj) — 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.

https://medium.com/@kashwathkumar/authentication-token-obtain-and-replace-ator-burp-plugin-fast-and-reliable-plugin-to-handle-1d9a0b3054e