Recorded login sequences
When configuring application logins for a scan, you can choose to import a recorded login sequence rather than just supplying basic user credentials. A recorded login sequence is essentially a set of instructions that tell Burp Scanner exactly how to log in to the website. Providing recorded login sequences allows Burp to successfully handle more complex authentication mechanisms, including:
- Single sign-on
- Multi-step login where the username and password are not entered in the same form
- Login forms that contain extra fields, checkboxes, and so on
To enable Burp to handle some of these cases, the crawler will temporarily be allowed to follow out-of-scope links that are necessary for performing the login sequence. However, these locations will not be crawled or audited as part of the scan.
You can create recorded login sequences quickly and easily using our dedicated Chrome extension. The extension captures your interactions with the website while you perform the login sequence manually in your browser. It automatically generates a JSON-based "script", which you can then import in the "Application login" section of the scan launcher. When the scan begins an authenticated crawl, it will open a new browser session and use this script to replicate your actions, performing the full login sequence from scratch.
Limitations for recorded login sequences
Please be aware of the following limitations before deciding to use recorded login sequences:
- Recorded logins are not compatible with two-factor authentication, character-select passwords, or CAPTCHA.
Burp Scanner is currently unable to replay login sequences that rely on popups or
- Recorded logins are only compatible with browser-powered scans. If Burp fails to initialize its embedded browser during the crawl, it will fall back to the previous crawler engine and ignore any recorded logins that you have created. You should check the event log and run an embedded browser health check for details.
- When using recorded logins, Burp Scanner will not be able to self-register users or deliberately trigger login failures by submitting invalid credentials. As a result, any "Login functions" crawl settings from your scan configuration will be ignored.
- Depending on your authentication system, the repeated logins made during the scan may be flagged as suspicious. This could trigger additional authentication steps or anti-robot measures that the crawler is unable to handle. In this case, we recommend running the scan on a test instance with these checks disabled.
How to record a login sequence for Burp Scanner
To record a login sequence that Burp Scanner can use for authenticated crawls, you use the Burp Suite Navigation Recorder extension. This comes preinstalled and ready to use with Burp's embedded browser. If you prefer to work with an external browser, you need to manually install and configure the extension.
- Open Burp's embedded browser or an external version of Chrome on which you've installed the Burp Suite Navigation Recorder extension.
- Click on the extension again and select "Start recording". A new incognito window opens.
- In the incognito window, browse to the target website. A red outline indicates that the window is being recorded.
- Complete the login sequence that you want to capture. Make sure that you enter the credentials that you want Burp to use during scans.
- Perform the rest of the login sequence as required. Make sure that you finish on a page that will be in scope for your scan.
- When you're done, click the extension icon again and select "Stop recording". The generated script is automatically copied to your clipboard. If you made a mistake, you can click the icon again to re-record the login sequence. If you accidentally lose the script from your clipboard, you can also copy the last recorded sequence.
- In Burp, go to the scan launcher and open the application login settings. Select the "Use recorded login sequences" option and click "New".
- Add a label to help you remember which login sequence this is. Finally, paste the data from your clipboard into the "Paste Script" field and click "OK". The recorded sequence is added to the list of application logins.
You can now repeat this process for each set of credentials that you want Burp to use. For example, you might record one login sequence in which you log in as a normal user and another sequence in which you log in as an administrator.
Recording login sequences using an external browser
Instead of using Burp's embedded browser to record login sequences, you can use an external version of Chrome. You just need to perform a couple of quick steps to install and configure the extension.
- Open Chrome and add the Burp Suite Navigation Recorder extension.
- In the upper-right corner of the browser, click on the icon for the extension. When prompted, click "Open settings".
- On the extension settings page, use the switch to enable the "Allow in Incognito" option. You can now use this browser to record a login sequence.
How to test a recorded login sequence
After you save a recorded login sequence, you can replay it to check that the recording accurately captured your interactions with the browser. This is useful for checking that new recordings are working as expected and for troubleshooting existing ones that are failing during scans.
- Go to the scan launcher and open the application login settings. Select "Use recorded login sequences".
- Either upload a new recorded login sequence or load an existing one from your configuration library.
- Select the login sequence that you want to test and click the "Replay" button. Burp's embedded browser will open.
- In the embedded browser, you should see Burp automatically navigate to the target website and begin performing the login sequence that you recorded. This all happens fairly quickly. You should avoid any manual interaction with the browser while it is replaying the sequence as this could interfere with the test.
- When Burp finishes replaying the recording, it will pause on the final page for several seconds before closing the browser window. This should be long enough for you to see where the login sequence stopped. If everything worked correctly, this will be the page that you normally see after successfully logging in. Otherwise, it may provide clues as to which stage of the process is causing problems.
Troubleshooting recorded login sequences
You might find that Burp Scanner is sometimes unable to replay a recorded login sequence during the scan. Although this won't cause the scan to fail completely, it will prevent it from performing an authenticated crawl. There are several steps you can take to troubleshoot these issues.
- Check the list of limitations to make sure that the login mechanism you are crawling is compatible with the recorded logins feature.
- Check the event log. The error messages might tell you whether the issue was with the login sequence itself or whether there was a general issue with the embedded browser. Please be aware that some log entries may only represent temporary failures that were later resolved. For example, if the target site imposes rate limits, you might see many entries saying that the crawler was unable to log in. However, it may have logged in successfully later in the scan.
- From the "Help" menu, run an embedded browser health check to make sure there are no issues with Burp's embedded browser. Recorded logins are only compatible with browser-powered scans, so if there's an issue with the browser, Burp Scanner will be unable to use your recorded login sequence.
- Use the "Replay" function to test the recorded login sequence. Make sure that the sequence finishes on the expected page having successfully logged in. If not, you may be able to determine the final action that Burp was able to perform successfully. Try re-recording the login sequence and run another test. If this new recording also seems to fail at the same stage, the next action in the sequence may not be supported by Burp Scanner.
- Double-check that the login sequence finishes on a page that is in scope for the scan. Although the crawler will temporarily be allowed to follow out-of-scope links during the login process, after you complete the final action, the login sequence must redirect you to a page that is in scope.