1. Support Center
  2. Documentation
  3. Desktop editions
  4. Options
  5. Sessions

Options: sessions

This tab contains settings for session handling rules, the cookie jar, and macros.

Note: Burp Scanner automatically handles sessions during crawling and crawl-driven auditing. Session handling rules will not be applied to requests made by these kind of scans.

Session handling challenges

When performing any kind of testing of web applications, you may encounter challenges relating to session handling and state. For example:

These challenges may arise when carrying out automated testing tasks, such as fuzzing or scanning, and may also arise when you are testing manually.

Burp's session handling functionality contains a range of features to help in all of these situations, letting you continue your manual and automated testing while Burp takes care of the problems for you in the background.

Session handling rules

Burp lets you define a list of session handling rules, giving you very fine-grained control over how Burp deals with an application's session handling mechanism and related functionality.

Each rule comprises a scope (what the rule applies to) and actions (what the rule does). For every outgoing request that Burp makes, it determines which of the defined rules are in-scope for the request, and performs all of those rules' actions in order (unless a condition-checking action determines that no further actions should be applied to the request).

The scope for each rule can be defined based on any or all of the following features of the request being processed:

Each rule can perform one or more actions, such as:

By creating multiple rules with different scopes and actions, you can define a hierarchy of behavior that Burp will apply to different applications and functions. For example, on a particular test you could define the following rules:

For more details of configuring session handling rules, see the Session handling rule editor help.

Session handling tracer

The configuration needed to apply Burp's session handling functionality to the features of real-world applications is often complex, and mistakes are easily made. You can use the session handling tracer to assist with troubleshooting your session handling configuration.

The tracer shows a listing of every request that has been handled by the session handling functionality (that is, where at least one session rule has been applied). For each handled request, the tracer shows the sequence of rules and actions that were carried out, and the changes made to the current request at each step in the sequence.

Note that the session handling tracer imposes a processing and storage overhead on all affected HTTP requests. You should only use the tracer when troubleshooting issues with session handling rules, and should not leave it running generally.

Burp maintains a cookie jar that stores all of the cookies issued by web sites you visit. The cookie jar is shared between all of Burp's tools.

You can configure which tools the cookie jar should monitor in order to update cookies. By default, the cookie jar is updated based on traffic from the Proxy and Spider tools. Burp monitors responses received by the configured tools, and updates the cookie jar with any new cookies that are set. In the case of the Proxy, incoming requests from the browser are also inspected. This is useful where an application has previously set a persistent cookie which is present in your browser, and which is required for proper handling of your session. Having Burp update its cookie jar based on requests through the Proxy means that all the necessary cookies will be added to the cookie jar even if the application does not update the value of this cookie during your current visit.

You can also view the contents of the cookie jar and edit cookies manually, using the "Open cookie jar" button.

The cookie jar can be used by session handling rules and macros to automatically update outgoing requests with cookies from the cookie jar.

The cookie jar honors the domain and path scope of cookies, in a way that mimics Internet Explorer's interpretation of cookie handling specifications.


A macro is a predefined sequence of one or more requests. You can use macros within session handling rules to perform various tasks. Typical use cases for macros include:

As well as the basic sequence of requests, each macro includes some important configuration about how cookies and parameters in the sequence should be handled, and any interdependencies between items.

For more details of configuring macros, see the Macro editor help.

Integration with Burp tools

Burp's session handling features interact with Burp's other functionality in some important ways: