Application security

Burp Suite tutorial: Session handling mechanisms

Parul Garg
January 4, 2013 by
Parul Garg

Web applications, nowadays, handle sessions and state by implementing session expiration and sessionid lifecycle in a more secure manner to avoid security issues such as session hijacking. They will invalidate your session based on idle timeout or absolute timeout as suggested by OWASP. Also, there are different use cases where the sessionid changes because of privilege-level escalation. It's good to know that web applications are taking such preventive measures to avoid security issues.

But these measures also work against the person doing penetration testing on these web applications because maintaining an active session for the multiple requests sent to the server becomes difficult. The web application might terminate your session based on timeout conditions or other reasons and all the subsequent requests made to the server are invalidated.

While using Burp for web application active scanning, there may be a whole lot of requests pending in the "Active Scan Queue" but do all of these requests contain the active "Sessionid"? From where does Burp pick up the latest session information? I have often pondered these questions while looking at the big "Scan Queue" and wondered if all these requests were sent successfully to the server or if the response was "Session Expired. Please Login" and all the hard work spent crawling the application was in vain.

Session handling

With Burp v1.4, Burp introduced new module called "Sessions" to give you the control to oversee the application's session handling with Burp. Burp now provides three important configuration options to help you troubleshoot your sessions and state.

  1. Cookie Jar
  2. Session Handling Rules/Tracer
  3. Macro

We will look at all the three options in detail, later on followed by an example.

Cookie Jar

We will look into Cookie jar first because, even if you don't define any custom session handling rule/macro, this plays an important role in keeping your session active.

As the name suggests, this stores all the cookies issued by all the web applications you visited (obviously, in the browser where Burp is the proxy or through Burp tools).

Burp lets the user select which of the burp's tool traffic to monitor and, based on the selection, it updates the cookie jar with any newly set cookies. By default, it monitors "Proxy" and "Spider" tools. Monitoring "Proxy" reflects the active browser session's cookie in the cookie jar.

You can also view the contents of the cookies in the cookie jar by clicking on "Open cookie jar" and if necessary, you can update those cookies manually.


A macro is a set of instructions used to perform an action such as logging into an application, checking if a session is valid, etc. When you click on "Add" in the Macro section, it opens up a "Macro Recorder" for you, displaying the proxy history.

You can now select a single request or multiple requests for the operation you want the macro to perform. You can configure the macro further by clicking on "Configure Item" button.

It has three configurable sections: Cookie Handling, Parameter Handling, and Custom Parameter Locations.

Cookie handling lets you configure your macro request with the current cookies in the cookie jar and update the cookie jar with the response. For every parameter in the request, parameter handling lets you configure it to fixed value or value derived from previous response. Although Burp identifies parameter location in the response automatically, sometimes you would still want the ability to provide it and customize it. You just have to tell Burp the location of the parameter in the response and its name in the subsequent request.

Session Handling Rules

Burp gives its users the ability to define the session handling rules. Every rule comprises the actions to be taken and the scope of the rule. There are various actions user can define, such as add cookies to the cookie jar, run a macro, check if session is valid, etc. We will be looking at an example in the next section to see how to configure these rules.

By default, there is only one session handling rule which is defined: "Use cookies from Cookie jar for spider and scanner." As mentioned in the cookie jar section, with the default setting, cookies in the cookie jar are updated by monitoring the "Proxy" and "Spider" tools. By combining both the rules together, we get the answer to our question of how Burp's request from the scan queue maintains an active session. The cookies/session IDs in the active session on the browser are picked up by the cookie jar, and they in turn are reflected in the subsequent requests made by Scanner because of the session handling rule.

One issue with this configuration is that it requires us to always maintain an active session in the browser, which isn't feasible because you may want to crawl the application in one go on the browser, line up the requests in the active scan queue, and let Burp do its work without you interfering for hours.

Now Burp lets you define session handling rules and create macros to achieve this and make sure that your session remains valid throughout the testing.

Feature walkthrough with an example

1. Sample application

Consider a sample web application which displays a login form when you are not logged in, as shown below:

After logging in, it displays the form shown below:

2. Create session handling rule

Now we will be creating a rule to verify if the user is logged in before any request is sent to the server. If the response shows that the user hasn't yet signed into the application, we will create the rule to log him in.

Step 1: Click on the Add button in "Session Handling Rule" section. It will open up a rule editor window where you can provide the description of the rule and action to be performed. It gives you various options for the actions. Since we want to verify the validity of the session, click on option "Check Session is Valid."

Step 2: Next window which opens up is "Session handling action editor." Here we need to specify how to identify if session is valid and the actions to perform after the verification.

Coming to the first part, we need to make a request to validate the session either by issuing the current request or by some pre-defined steps in a macro. We will be going with the macro option. Select "Run Macro" and click on "Add."

Step 3: "Macro Recorder" will open. In the case of our sample application, if the user is not logged in, it throws the login form irrespective of the request which is made. Considering the behaviour of the application, our macro will contain the request made to the page "index.php" and examine the response to identify the validity.

Step 4: As said in the previous step , we will examine the response for the expression "Please enter your BugDB/GUID" and once we get this expression, our match indicates "Invalid session."

Step 5: Once it is established whether the session is valid/invalid, we need to direct Burp for further steps to be taken. In our case, once we identify that the user hasn't signed in or the current session is inactive, we want to log in the user again by sending the login request on his behalf. Hence, proceed with the option "If session is invalid, run a macro."

Step 6: Our application makes a POST request from the "login.php" page while sending the user's credentials to the server and the user is logged in. We will be making use of this request for our macro. If desired, you can select series of requests to define the action.

Step 7: Now define the scope of this rule in the "Scope" section.

Step 8: After the rule is created, it will take you back to first screen.

"ValidateSessionBefore" is the rule we have just created and is the first rule which will be applied to all the requests made through various Burp tools.

3. Verifying Rule with "Sessions Tracer"

Burp also provides you with an option to troubleshoot the custom rule with the help of "Sessions Tracer." Click on "Open Sessions Tracer."

Step 1: Go to the browser and try to open any PHP page from the application "othersExtract.php." At this time, the user is not logged in. Now see the tracer carefully.

There are multiple actions performed per request.

Let's check if our rule has been applied successfully. While processing the macro "CheckIfSessionIsValid," it identifies the session as invalid and looking at the response carefully, so we can see that it has applied the rule correctly.

As described in the rule, once the session is invalid, we want to create a valid session by running the macro "CreateValidSession" and then issue the current request. As seen, this time the response shows that the user has been logged in.

Step 2: Since there is no logout operation conducted, let's check how the rule behaves for the next immediate request sent to the server. "CheckIfSessionIsValid" macro identifies the next session as a valid session and hence there is no need to run the "CreateValidSession" macro.

When we check the response body of the macro, we can see that there is no login form and hence the session is valid. Therefore, there is no need to run the second macro and Burp proceeds with the request.


The session-handling mechanism with cookie jar, rules, and macros will require initial setup time to identify the macros and create the rules you need. It will also take more time to conclude, because it's sending multiple other requests in the background, but in the end, it's all for your good J.

11 courses, 8+ hours of training

11 courses, 8+ hours of training

Learn cybersecurity from Ted Harrington, the #1 best-selling author of "Hackable: How to Do Application Security Right."


Parul Garg
Parul Garg

Parul Garg works in the Information Security domain, currently as security analyst with a leading company in Hyderabad. A researcher with InfoSec Institute, her focus includes (but is not limited to) Web Application Penetration Testing and automation scripts.

Garg is also interested in PERL/Java/SQL automation.