Tiredful API is an intentionally vulnerable REST API. I am going to use it to practice a bunch of Burp tricks.
In this part, I want to show how to use Burp macros to detect invalid session and add a custom bearer token header to the requests.
I used the instructions to spin up a docker container and used it with the free Burp Community Edition 1.7.36.
Session Validation Using Macros
Often times the session times out in the middle of testing or scanning. I only use Burp's scanner on individual requests but session can still time out. Sometimes the application log users out after sending funny payloads. Burp allows you to detect invalidated sessions and run a macro (which is a series of requests) to update the session automagically.
Usually, the session is maintained by cookies and Burp's cookie jar can be automatically updated to refresh the session. In the case of this API, we are using a Bearer token. But this method can be used for any custom header containing a token.
The login request is simple. While this example has only one request, the process for multiple-step requests is similar. The application has two registered users. We are using
access_token must be added to every authenticated request like
Authorization : Bearer [token].
Invalid Session Response
We also need to detect invalidate sessions. To do so, navigate to http://192.168.99.100:8000/api/v1/advertisements/ to see the response.
We are going to use the header
401 Unauthorized to detect invalid requests.
We should create a login macro to login as
batman. This macro will be executed when Burp detects an invalid/expired session.
- Go to
Project Options > Sessionsand scroll down to
Addto create a new macro. Macros are created from existing requests.
- Select a successful login request (for multi-step logins, select all steps in the login flow) and press
- Select a name and press
Macro Editorto create the macro. If the request had specific parameters (e.g. a CSRF token), we could designate it in
Configure item. This example does not need it.
We need to make Burp perform two action:
- Create a session handling rule. Burp should run the macro whenever a session is invalid.
- Add the
access_tokenas a custom header to that request and resend it.
Add Custom Header Extension
In order to accomplish number two, we need to use an extension. Burp vanilla does not support adding headers to requests in session validation rules. However, cookies and normal GET/POST parameters (e.g.
form-urlencoded ) can be updated.
- Install the
Add Custom Headerextension at https://github.com/lorenzog/burpAddCustomHeader. It's also available in the Burp App Store.
- Navigate to the
Add Custom Headertab. It's pre-populated with some sane defaults.
- The original regex is
access_token":"(.*?)". The underline does not show up in the input field but you can click on
Update Previewto see it.
- We need to change the regex. Our response is a bit different. Ours has an extra space after
access_token":. Our regex will be
Session Handling Rule
- In the same screen (
Project Options > Sessions) click
Session Handling Rules.
- Type in a rule description. E.g.,
Check session is valid.
- In the next screen, select
Issue current requestunder
Make request(s) to validate session. This tells Burp to modify the same request with the new header and resend it.
Inspect response to determine session validity, select
HTTP headersand enter
401 Unauthorizedin the
Look for expressionfield. This section determines how Burp detects invalid sessions. We are telling Burp that the session is invalid if
401 Unauthorizedappears in the response header.
- Keep the rest of the options. We want exact match and case-insensitive.
Match indicatesmust be set to
invalid session. We are telling Burp how to detect invalid sessions after all.
Define behavior dependent on session validitycheck
If session is invalid, perform the action below, check
Run a macroand select the login macro.
- Uncheck both
Update current requestboxes (doesn't matter in this example, we are not using cookies or parameters).
- And finally, check
After running the macro, invoke a Burp extension action handler:and select
Add Custom Header. Response of the last request in the macro is passed to
Add Custom Header. The extension extract sthe token using the regex (remember the match group) and adds it as a header to the request.
Okand we're back at the first screen. Now we need to select the scope.
- Click the
scopetab and select any tool that needs this rule under
Tools Scope. We will go with the default.
Use suite scope. We will set it later.
Alternate Session Handling Rule
Instead of detecting the session, we can use an easier rule and run the macro and add the header to every request. I went with the more complicated process because I wanted to practice setting it up.
- The alternate rule is the same in every aspect, except the
Rule Actionswhich is
Add (button) > Run a Macro.
- Select the macro.
- Uncheck both update checkboxes.
After running the macroand select
Add Custom Header.
Setting the Scope
In this example, we do not have to set the scope. But usually, we want to only operate in a specific scope. In my VM, the address is
http://192.168.99.100:8000 so I added it in
Target > Scope tab. I also excluded the login and logout API endpoints.
Burp in Action
Now it's time to see the fruit of our labor. Right click the request to
http://192.168.99.100:8000/api/v1/advertisements/ in Burp history and send it to Repeater. Click
Send and see the header added to the request and get a valid response. It's empty but it's valid.
Tune in for the next section, where I talk about using Burp's sitemap comparison.