BurpSuite - Session Manager

The Importance of Automated Session Management in BurpSuite

Efficient cybersecurity testing almost always requires automated session management in the testing tool.

Automating allows, for example, the ability to leave the scanner scanning the application's various functions overnight, and Burp knows how to automatically log the test user back in when the session expires.

With automation, you can also at any time take a request from the sitemap, put it in the repeater and send it to the application, letting Burp take care of cookies, tokens or whatever session management method is - update.

Components of automated session management

In order to be realized, automated session management requires the following components:

• Session database: The mechanism for keeping track of the current session.
• Update Mechanism: Mechanism for updating the cookies/headers/other (depends on the application) of an HTTP request with the current session information.
• Detection mechanism: Mechanism to detect that the current session has expired.
• Authentication mechanism: Mechanism for logging in when necessary.

The capability of Burp Suite for automated session handling - Session Handling Rules

Burp Suite has built-in capability to create session handling rules that implement all four aforementioned requirements.

The session management rules can be found in the Burp settings and by default, there is one rule already prepared in the project:

• It is called "Use cookies from Burp's cookie jar".
• It is enabled.
• It is restricted to the Scanner tool only.
• Contains only one rule, which is "Use cookies from Burp's cookie jar".

How are Burp Suite session management rules built?

Burp session management rules are built upon description, scope, and a series of steps that are executed in order from start to finish, unless the execution is interrupted.

Description (Rule description)

The session management policy has a description that can be defined by oneself.

Tools scope

Tools scope once again defines to which Burp tools the session handling rules are applied. If you want, for example, the Repeater tool to stay automatically logged in the way you want, set it in the Repeater scope. If it's not in the scope, session handling won't affect Repeater and cookies, etc., won't be updated automatically.

A proxy tool is rarely included in scope, but it also has valid use cases. One typical use case is running a third-party testing tool (such as sqlmap) through Burp, with the idea that Burp will ensure that the session remains valid throughout the entire scan.

URL scope

URL scope determines to which URL addresses the session management policy is applied. Typically, one of the following is used:

• Use suite scope: Use this when you have set only those URLs in Burp suite scope to which outgoing requests you want to be processed with this session management rule, and the scope does not have multiple targets, for example.
• Use custom scope: Use this when there are multiple targets in the Burp scope and you want the Burp session handling automation to behave differently depending on the target.

There is also an option "Include all URLs", but its use is not recommended due to high risk of damage (sending authentication credentials of the target application to a completely wrong application by mistake).

Rules (Rule actions)

The rule consists of individual rules that are executed for each HTTP request within the scope one at a time from top to bottom, until completion or interruption of the execution.

• Use cookies from Burp's cookie jar: Updates all HTTP request cookies from Burp's cookie storage.
• Set a specific cookie or parameter value: Set a specific URL parameter, body parameter, or cookie.
• Check session is valid: Checks if the current session is valid.
• Option 1: Infer from the current HTTP request and response.
• Option 2: Run a recorded HTTP request or sequence (Macro) with current session data and infer from it.
• Prompt for in-browser session recovery: Prompt the user manually to notify if the session expires so that you can manually log in again.
• Run a macro: Run a Macro (which actually is a stack recorded with one or more HTTP requests).
• Run a post-request macro: Run after the Macro request.
• Invoke a Burp extension: Launch a Burp extension that implements the ISessionHandlingAction interface.
• Set a specific header value: Set the value of a specific HTTP header.

How do Burp session management rules work?

A typical rule set could work as follows.

• You send an HTTP request with a repeater to the address https://www.example.com.
• Burp checks for enabled session management rules
• Burp checks if there is a rule in the enabled session handling rules that has Tool scope as Repeater.
• Burp checks these rules to see if any of them have a URL scope that is "https://www.example.com".
• If such a rule is found, Burp will start executing its rules. Let's imagine that the rules are as follows:
• Use cookies from the session handling cookie jar
• Tarkista, onko istunto voimassa
• Retrieve the Location header from the current HTTP response for the HTTP request at hand
• Burp updates the cookies of the HTTP request from Burp's cookie jar.
• Burp sends a modified HTTP request to the web server.
• Burp checks the HTTP response and determines if the session is still valid.
• The HTTP response contains a "Location" header that redirects to the login page, which means that the session is not valid.
• Execute a recorded Macro that sends a POST request to the login page with the username and password.
• Take the cookies received from the response and save them in Burp's cookie jar.
• Go back to the first step.

Burp Cookie Jar - How cookies are updated to the jar and where to find the jar?

The Burp cookie jar can be used and updated from the session management rules.

The cookie jar can also be set to automatically update from certain tools seen in Burp's HTTP responses, and the jar can be manually modified and inspected. This is done through Burp's "Sessions" section in the settings.

Check session is valid

This

Session Tracer tool

Session management rules can become complex and sometimes it can be difficult to say why a rule does not work as desired. For this reason, Burp includes a tool called "Session Tracer" (found in the same "Sessions" section of the settings) which allows you to track the execution of session management rules rule by rule.

Practical Example: Tick a Box

Next, we will use a real application as an example and build a functional session management policy! If you want, you can launch the task page at the bottom of this stage and do it yourself.

Step 1 - Research work

First, you need to figure out how the application identifies the user and manages sessions. After completing the research phase, you will know all four necessary components (session database, update mechanism, detection mechanism, and authentication mechanism).

Let's start by opening Burp's browser and setting the scope appropriately.

Let's then log in and examine HTTP traffic with Burp.

Login has clearly occurred in the POST request to the /login path.

A request has been made with a username and password. In return, a cookie named session and a redirect to the homepage have been received.

POST /login HTTP/2
Host: www-qx8lkdutu3.ha-target.com
Content-Length: 47
...

username=john.doe%40example.com&password=s3cr3t

HTTP/2 302 Found
Date: Tue, 05 Dec 2023 18:09:31 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 189
Location: /
Vary: Cookie
Set-Cookie: session=eyJ1c2VybmFtZSI6ImpvaG4uZG9lQGV4YW1wbGUuY29tIn0.ZW9nWw.eEmhY6OJL5xMqCtbJkDltvUfBHU; HttpOnly; Path=/
Strict-Transport-Security: max-age=15724800; includeSubDomains

<!doctype html>
<html lang=en>
<title>Redirecting...</title>
<h1>Redirecting...</h1>
<p>You should be redirected automatically to the target URL: <a href="/">/</a>. If not, click the link.

The following GET request to the homepage includes the "session" cookie and the response is 200 OK.

GET / HTTP/2
Host: www-qx8lkdutu3.ha-target.com
Cookie: session=c9164eb9-186b-4020-8e01-07344c700b38
...

HTTP/2 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 15644
Vary: Cookie
Strict-Transport-Security: max-age=15724800; includeSubDomains

<!DOCTYPE html>
<html lang="en">
  <head>
  ...

Next, let's investigate the detection mechanism for when the session is no longer valid. Send this latest HTTP request to the repeater and send it, ensuring that the response is still 200 OK.

Now logging out of the application (which typically expires the session) and sending the same request again. Let's see what happens.

The response is no longer 200 and contains a redirection to the login page in the Location header. Redirecting to the login page is often a great way to identify an expired session.

Let's reiterate the components:

• Session database: Used to store the currently valid session cookie in Burp's cookie jar.
• Update mechanism: Uses the "Use cookies from the session handling cookie jar" rule to update the current HTTP request by replacing the value of the session cookie with the one stored in the cookie jar.
• Detection mechanism: Used "Check session is valid" rule to always read the response of an HTTP request and deduce an expired session from the Location header containing the word "login".
• Authentication mechanism: Used for "Check session is valid" reauthentication if the detection mechanism determines that the session has expired. This is done by recording a macro that sends a POST request to the /login path.

Step 2 - Building Session Management Policy

Open Burp settings and go to the "Sessions" section.

Cookie container configuration

As mentioned, Burp can automatically update the cookie jar based on HTTP responses detected in various tools. However, we do not want this to happen uncontrollably, as otherwise browsing the application through Burp's proxy could interfere with an ongoing scan or intruder run.

If "Proxy" is checked, then remove it.

Now we have the session database ready.

Removing default rules

Removing the default ruleset completely and creating a new one. So click on "Remove" to make the list empty.

Create a new rule

Create a new rule using the "Add" button. Give it a description, such as "My session handling rules".

Set scope

Then open the "Scope" tab and add the "Repeater" and "Intruder" tools to the scope.

You can choose "Use suite scope" for the URL scope. However, please note that you need to have the target URL address added to the scope as discussed earlier in the course.

First rule - Using cookies from the Burp cookie jar

Add rule "Use cookies from the session handling cookie jar". This always updates the cookies of the HTTP request in scope from Burp's cookie jar.

You can at this stage restrict which cookies you want to update. You can leave these blank and all cookies will be updated.

Now we also have the update mechanism connected. We still need the detection mechanism and the authentication mechanism.

Second Rule - Session Validation

Add the rule "Check session is valid". There is some tinkering to do in this box, let's go piece by piece.

Make request(s) to validate session: The first step is to:

• Issue current request: Determine the session state from the current HTTP request's HTTP response (instead of sending a completely separate HTTP request. Sometimes this is necessary, but not now).
• Checking the situation for each HTTP request: That is, leave uncheck "Validate session only every N requests".

Inspect response to determine session validity: Then select that:

• Location(s): URL of the redirection target, in other words, the information of interest to us is located in the HTTP response header Location.
• Match type: Literal string (so not a Regex pattern, although that can sometimes be desired).
• Case-sensitivity: Letter case does not matter.
• Match indicates: Invalid session, which means that if there is a hit similar to the described one in the HTTP response, it means that the session is not valid. This could be done reversely if it is easier for the specific application.

Define behavior on session validity: Next, choose that:

• If session is invalid, perform the action below (If the session is not valid, do the following):
• Run a macro (Execute Macro)

Then you need to record the Macro.

Recording Macron

Click "Add" to record a new Macron.

The opening view is essentially only HTTP proxy history. The view updates in real-time as you make more HTTP requests through Burp.

Before recording a macro, it is generally advisable to log out of the application and clear your browser's cookies and other data. This way, you will be able to record a clean starting state for the macro.

Then you can update the application page and log in. This should generate at least:

• One GET request without cookies (in the Cookie header of the HTTP request) but with a session cookie returned in the Set-Cookie header of the HTTP response).
• One POST request to /login page with a session cookie included (in the HTTP request Cookie header) and the response is a 302 redirect to the homepage.

Select these two HTTP requests from the list. The order matters. Press "Ok".

Name the Macro "Login". Do not click "Ok" yet because the Macro needs to be both configured and tested first.

Select the first HTTP request from the list (GET request without cookies) and click "Configure".

It is important not to use cookies from the cookie jar in this HTTP request in the future, so that an expired cookie is not accidentally used when trying to log in again.

Leave a checkmark on "Add cookies received in responses to the session handling cookie jar" because it is necessary to immediately save the "session" cookie returned by the application on the first page load.

Instead, uncheck "Use cookies from the session handling cookie jar" because the purpose is to create a fresh, clean login and not use old cookies.

Press "Ok" to finish.

Test the following Macro next.

If everything goes well, the last HTTP message of the test sequence should contain a redirect to the homepage.

Click "Ok" and "Ok" to return back. Macro is now recorded and set to run if the session is no longer valid.

Finally, just check the boxes for "Update current request with parameters matched from the final macro response" and "Update current request with cookies from session handling cookie jar".

Click "Ok" and "Ok". Your policy is ready.

Testing the Regulations

Login to the application and click on one of the checkboxes. Take a look at the HTTP message that the click leaves behind and then send an HTTP request to the repeater.

Send the request with a repeater. Try removing the entire cookie and send the request again with a repeater.

If the rule set is working, the cookie magically reappears on every new HTTP request and the HTTP request goes through.

Debugging the rule set with session tracer

You can debug the problem or simply confirm that the rule set is functioning as expected using the aforementioned session tracer tool. Click "Open sessions tracer".

The view is always initially empty.

Send a message with Repeater. Then check the session tracer.

You should see that:

• Rules and regulations are used
• Checking if the session is valid
• Notice that it is not valid
• Run Macro "Login"
• Add a cookie to the cookie jar
• Sending updated HTTP request

Session Management Extensions ("Invoke a Burp Extension")

In this module, we do not discuss the creation of custom extensions, but briefly, these can be done with Java or similar languages like Python, enabling more versatile handling of various scenarios. Unfortunately, it is not possible to automate every application's login and session management solely with Burp's pre-built tools.

Practice

Start the "Tick a Box" application from here and complete the task.