Session Handler Help
Session handling challenges
Some problems commonly encountered when performing any kind of fuzzing or scanning of web applications are:
- The application terminates the session being used for testing, either defensively or for other reasons, and the remainder of the testing exercise is ineffective.
- Some functions use changing tokens that must be supplied with each request (for example, to prevent request forgery attacks).
- Some functions require a series of other requests to be made before the request being tested, to get the application into a suitable state for it to accept the request being tested.
All of these problems can also arise when you are testing manually, and resolving them manually is often tedious, reducing your appetite for further testing.
Burp 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. All of the session-related configuration can be found in the "sessions" tab, within the main "options" tab.
Burp's cookie jar
Burp maintains a cookie jar which tracks the cookies being used in your various application sessions. The cookie jar is shared between all Burp's tools. Cookies set in responses are stored in the cookie jar, and can be automatically added to outgoing requests.
All of this is configurable so, for example, you can update the cookie jar for cookies received by the Proxy and Spider, and have Burp automatically add cookies to requests sent by the Scanner and Repeater. The cookie jar configuration is shown in the "sessions" tab within the main "options" tab:
As shown, by default the cookie jar is updated based on traffic from the Proxy and Spider tools. You can view the contents of the cookie jar and edit cookies manually if you wish:
For all tools other than the Proxy, HTTP responses are examined to identify new cookies. 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.
Burp's cookie jar honours the domain scope of cookies, in a way that mimics Internet Explorer's interpretation of cookie handling specifications. Path scope is not honoured.
Session handling rules
Burp lets you define a list of session handling rules, which give you very fine-grained control over how Burp deals with an application's session handling mechanism and related functionality. These rules are configured in the "sessions" tab within the main "options" tab:
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:
- The Burp tool that is making the request.
- The URL of the request.
- The names of parameters within the request.
Each rule can perform one or more actions. The following actions are implemented:
- Add cookies from the session handling cookie jar.
- Set a specific cookie or parameter value.
- Check whether the current session is valid, and perform sub-actions conditionally on the result.
- Prompt the user for in-browser session recovery.
- Run a macro.
- Run a post-request macro (this issues the current request, and then executes a further macro).
All of these actions are highly configurable, and can be combined in arbitrary ways to handle virtually any session handling mechanism. Being able to run arbitrary macros (defined request sequences), and update specified cookie and parameter values based on the result, allows you to automatically log back in to an application part way through an automated scan or Intruder attack. Being able to prompt for in-browser session recovery enables you to work with login mechanisms that involve keying a number from a physical token, or solving a CAPTCHA-style puzzle.
By creating multiple rules with different scopes and actions, you can define a hierarchy of behaviour that Burp will apply to different applications and functions. For example, on a particular test you could define the following rules:
- For all requests, add cookies from Burp's cookie jar.
- For requests to a specific domain, validate that the current session with that application is still active, and if not, run a macro to log back in to the application, and update the cookie jar with the resulting session token.
- For requests to a specific URL containing the __csrftoken parameter, first run a macro to obtain a valid __csrftoken value, and use this when making the request.
The details of how to configure Burp to achieve this are described in later sections.
Macros
A key part of Burp's session handling functionality is the ability to run macros, as defined in session handling rules. A macro is a predefined sequence of one or more requests. Typical use cases for macros include:
- Fetching a page of the application (such as the user's home page) to check that the current session is still valid.
- Performing a login to obtain a new valid session.
- Obtaining a token or nonce to use as a parameter in another request.
- When scanning or fuzzing a request in a multi-step process, performing the necessary preceding requests, to get the application into a state where the targeted request will be accepted.
- In a multi-step process, after the "attack" request, completing the remaining steps of the process, to confirm the action being performed, or obtain the result or error message from the conclusion of that process.
Macros are recorded using your browser. When defining a macro, Burp displays a view of the Proxy history, from which you can select the requests to be used for the macro. You can select from previously made requests, or record the macro afresh and select the new items from the history.
When you have recorded the macro, the macro editor shows the details of the items in the macro, which you can review and configure as required:
As well as the basic sequence of requests, each macro includes some important configuration about how items in the sequence should be handled, and any interdependencies between items:
For each item in the macro, the following settings can be configured:
- Whether cookies from the session handling cookie jar should be added to the request.
- Whether cookies received in the response should be added to the session handling cookie jar.
- For each parameter in the request, whether it should use a preset value, or a value derived from a previous response in the macro.
- Whether key characters should be URL-encoded in updated parameter values.
The ability to derive a parameter's value from a previous response in the macro is particularly useful in some multi-stage processes, and in situations where applications make aggressive use of anti-CSRF tokens. When a new macro is defined, Burp tries to automatically find any relationships of this kind, by identifying parameters whose values can be determined from the preceding response (form field values, redirection targets, query strings in links, etc.). You can easily review and edit the default macro configuration applied by Burp before the macro is used. Further, the configured macro can be tested in isolation, and the full request/response sequence reviewed, to check that it is functioning in the way you require.
Worked example
Let's look at an application function which can only be accessed within an authenticated session, and employs a further token to defend against CSRF attacks. You want to test this function for various input-based vulnerabilities like XSS and SQL injection. Performing automated (and some manual) testing of this function faces two challenges: (a) ensuring that the session being used remained valid; and (b) obtaining a valid token to use in each request. Burp's session handling functionality can take care of both these challenges.
To do this, we're going to define some session handling rules. These rules will be applied to each request that is made to the function we are testing by the Intruder, Scanner and Repeater tools:
- Check whether the current session is valid, by requesting the user's landing page in the application, and inspecting the response to confirm that the user is still logged in.
- If the user is not logged in, log them back in to obtain a valid session.
- Request the page containing the form whose submission we are going to test. This form contains the anti-CSRF token that we need, within a hidden field.
- Update the request to the function we are testing with the value of the anti-CSRF token.
In most situations, we need to make use of Burp's own session handling cookie jar, so the first rule we define tells Burp to add cookies from the cookie jar to every request. This is, in fact, the default rule for the Scanner and Spider tools, so we'll just modify the default rule to apply to the Intruder and Repeater tools as well. This rule performs a single action, shown below:
The rule's scope is defined to include the relevant tools, and apply to all URLs:
Next, we need to check that the user's current session on the target application is valid. Assuming we want to apply this rule to all requests within the target application, we can define it to be in-scope for the whole of the application's domain:
We then add a suitable description and add an action of the type "check session is valid":
This opens the editor for this type of action, which contains a lot of configuration options:
The first set of options determines which request Burp uses to validate the current session. The options are:
- Issue the actual request that is currently being processed. This option is ideal if the application always responds to out-of-session requests with a common response signature, such as a redirection to the login.
- Run a macro, to make one or more other requests. This option is ideal if, to identify whether the session is valid, you need to request a standard item, such as the user's home page. It is also the best option if you need to apply further rules to modify the request currently being processed - for example (as in the present case) to update an anti-CSRF token in the request. If the option to run a macro is selected, you have a further option whether to do this every for every request, or only every N requests. If the application is aggressive in terminating sessions in response to unexpected input, it is recommended that you validate the session every time; otherwise, you can speed things up by only validating the session periodically.
For the current example, we are going to run a macro to fetch the user's landing page in the application, to check that their session is valid. To do this, we need to define our macro, by clicking on the "new" button in the previous screenshot. This opens the macro recorder, enabling us to select the request(s) that we wish to include in the macro. In the present case, we only need to select the GET request for the user's landing page:
The second set of options in the "check session is valid" action controls how Burp inspects the (final) response from the macro to determine whether the session is valid. Various options are available, and the configuration we need in the present case is shown below:
The final set of options for this action determines how Burp will behave depending on whether the current session is valid:
- You can tell Burp not to perform any further actions for this request if the session is valid. Using this option lets you define subsequent, separate actions to recover a valid session. This option is mandatory if the request itself has already been issued in order to determine whether the session is valid.
- You can tell Burp to perform a sub-action if the session is invalid, and then continue to process subsequent actions. This is useful when you need to define subsequent actions in any case, following the session validity check, for example to run a macro to obtain a request token or modify the application's state.
In the present example, we need to use the second option. If the session is invalid, we will run a macro to log the user back in. We need to record a further macro, to perform the actual login, and tell Burp to run this macro and update the session handling cookie jar based on the results:
At this point, we have configured Burp to update requests with cookies from its cookie jar, and to log the user back in to the target application when their session is invalid. To complete the required configuration, we need to define a further rule to deal with the anti-CSRF token used in the function we want to test. The request we are testing looks like this:
POST /auth/4/NewUserStep2.ashx HTTP/1.1 Content-Type: application/x-www-form-urlencoded Host: mdsec.net Content-Length: 137 Cookie: SessionId=39DD9F0CB979BFB431005524A4010244 realname=testuser&username=testuser&userrole=user&password=letmein1&confirmpassword=letmein1&nonce=938549246127349541173
To ensure that our requests to this function are properly handled, we need to ensure that a valid nonce is supplied with each request. The value of this nonce is supplied by the application in a hidden field within the form that generates the above request. So our rule needs to run a macro to fetch the page containing the form, and update the current request with the value of the nonce parameter. We add a further rule with an action of the type "run macro" and configure it as follows:
In the above configuration, we have specified that Burp should run a new macro, which fetches the form containing the anti-CSRF token, and then obtain the nonce parameter from the (final) macro response, and update this in the request. Alternatively, we could select the "update all parameters" option, and Burp would automatically attempt to match parameters in the request with those specified in the macro response.
In terms of the scope for this rule, this obviously needs to be defined more narrowly than the whole application domain. For example, we could define the rule to apply only to the exact URL in the above request. This is the best option if the application only employs anti-CSRF tokens in a few locations. However, in some applications, tokens are used for a large number of functions, and a token obtained within one function can be submitted within a different function. In this situation, we could define a rule that applies to the whole domain, but only to requests containing a specified parameter name. In this way, any time a request is made to the application that contains an anti-CSRF token, the rule will execute and Burp will fetch a new valid token to use in the request.
The full configuration, with its three session handling rules and three macros, looks like this within the main Burp UI:
You can test the configuration is working by logging out of the application, sending the authenticated, token-protected request to Burp Repeater, and verifying that it performs the required action. The request will probably take longer to return than normal, because behind the scenes Burp is making several other requests, to validate your session, log in again if necessary, and obtain a token to use in the request.
If you find your rules are not working in the way you intended, you can use the session handling tracer to troubleshoot the problem.
Once you are happy that your session handling rules are working correctly, you can send the request to Burp Intruder or Scanner, to perform your automated testing in the normal way.
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. Burp provides a tracer function for troubleshooting the session handling configuration. This shows you all of the steps performed when Burp applies session handling rules to a request, allowing you to see exactly how requests are being updated and issued. You can access the session handling tracer via options / sessions / view sessions tracer:
Integration with Burp tools
It is worth noting a few points about how the session handling features affect some of Burp's other functionality:
- There is a default session handling rule which updates all requests made by the Scanner and Spider with cookies from Burp's cookie jar. This ensures that all spidering and sanning requests are made in-session, provided you maintain a valid session using your browser. It also means that items in the active scan queue that are loaded from a state file will be scanned within your current session, not the session that was active when the state file was saved. If this is not the behaviour you require, you should disable the default session handling rule before performing any scanning.
- In cases where session handling rules modify a request before it is made (for example, to update a cookie or other parameter), some of Burp's tools will show the final, updated request, for purposes of clarity. This applies to the Intruder, Repeater and Spider tools. Requests that are shown within reported Scanner issues continue to show the original request, to facilitate clear comparison with the base request, where necessary. To observe the final request for a scan issue, as modified by the session handler, you can send the request to Burp Repeater and issue it there.
- When the Scanner or Intruder makes a request that manipulates a cookie or parameter that is affected by a session handling action, the action is not applied to that request, to avoid interfering with the test that is being performed. For example, if you are using Intruder to fuzz all the parameters in a request, and you have configured a session handing rule to update the "sessid" cookie in that request, then the "sessid" cookie will be updated when Intruder is fuzzing other parameters. When Intruder is fuzzing the "sessid" cookie itself, Burp will send the Intruder payload string as the "sessid" value, and will not update it as is done normally.