QBR Usage and X=Troubleshooting
This page provides quick tips for QBR usage and common scenarios that you may encounter in script playback.
General QBR Usage
Save the script with the .xml extension or specify a location for saving the script
By default, QBR saves the file with a .html extension (it's still valid XML data - XHTML to be precise). If you enable "Ask where to save each file before downloading" in Chrome, then you can change the extension to .xml if desired, and also decide where to save the file. It does not matter if you save the file with the .xml or .html extension. Either will work for playback in QBR as well as Qualys WAS.
Element not found when playing back the script
When you record a script, targets are selected automatically. Occasionally, the resulting script will not find the target during playback. QBR allows you to choose a different representation of the target by selecting from the drop-down. See the screenshot below for an example.
Manually identifying targets for QBR commands
Identifying a target for your QBR commands can be challenging when manually editing a script. The easiest way is to continue recording your script after you authenticate. While still recording on a post-authentication page, click on an interactive element, such as a button or text. Stop the recording and replace the post-authentication "click" command you just recorded with the "waitForElementPresent" command.
You can also manually add the command. First, pick an element on your web page, such as a button or text. Use your mouse to right-click and select "Inspect". This will take you to a DOM view of the page, and from here, you can find a way to reference this element uniquely. Two common ways are by "id" or by CSS location.
In some applications, you will find buttons, labels, or form fields identified by id="name" where "name" is unique for that element. This is very often the easiest solution when available. For example:
Here you can clearly see there is an element in a span section called id=”ext-gen2095”. To use this in your script, set it as the target for your command:
| Command | Target | Value |
|---|---|---|
| waitForElementPresent | id=”ext-gen2095” |
If you are familiar with using your browser’s developer tools to access the console, you can use the following command to pull out all the id="name" references:
document.querySelectorAll('[id]:not([id=""])')
If you cannot find an id="name" element or need to target an element that does not use id, you can also use a css location and match against anything in quotes. This target will use the following format: css=<css_element>:contains("<some text>"). Using the same screenshot as above, you can also reference the same target using css=span:contains("section-panel-header-text") and leverage the class name.
In this example, our QBR script would look like this:
|
Command |
Target |
Value |
|---|---|---|
|
waitForElementPresent |
css=span:contains(“section-panel-header- text") |
|
Activating fields that require user action
Sometimes a user action, such as clicking, is required before the fields in a form become active. In this case, you need to use the mouse to click the field for it to get populated. In that scenario, the "keyPress" command can be used to activate the field as part of the script playback.
Below is an example script where the keyPress command is used.
Handling a popup window
Some applications may use a popup window during the authentication process or other activity. If so, you may need to add a "waitForPopUp" command with a target of title and the popup window's title. Also, add a "selectWindow" command to ensure the popup window is selected. Then, use the sendKeys and click commands as you normally would to submit the login form.
...
<tr>
<td>click</td>
<td>id=loginButton</td>
<td></td>
</tr>
<tr>
<td>waitForPopUp</td>
<td>title=Quick Login</td>
<td>50000</td>
</tr>
<tr>
Script playback in Qualys WAS scan
Review QID 150100 (Selenium Diagnostics) in your scan report
Once your WAS scan has finished, view the scan report and look under Information Gathered for QID 150100. This is where you will find diagnostic information for the script. You should see each command in your script executing. If the scanner runs into a problem, you will see it here and can take appropriate corrective action.
You may see an error, for example, that says an element could not be found. If that's the case, try adding the "waitForPageToLoad" command with a value of 50000 milliseconds to your script. Alternatively, it may help to add a "waitForElementPresent" command as explained in the next section.
Verifying that authentication was successful during the scan
After uploading the authentication script into Qualys WAS, you must specify a regular expression to verify that the authentication completed successfully. The regular expression must match against the very first response received after the script executes. For example, if the last command is to click on a submit button (generating a POST request to the server), the server response must have a match for the regex you have specified. This is how WAS verifies that authentication succeeded. It can match against the displayed text or even against content found in the HTML source code itself.
In older web applications, a simple regex of "logout" was often sufficient, as this was usually part of the initial response back. However, many new applications, including most dynamic/AJAX web apps, will often first respond back with a script that loads other content. Remember, only the first response back is checked for the regular expression match. In this case, your validation regular expression may fail even if you are successfully authenticated.
A more versatile method to ensure you are authenticated and pass the validation regular expression match is to leverage the QBR script itself to check for the presence of an element only available on an authenticated page, and use a "dummy" regular expression (such as ".*") within WAS for the validation regex. In this scenario, the script will run to completion only if it finds an element present on ANY post-authentication page that is loaded. You can check QID 150100 in the WAS scan report to see all script commands that were executed.
After this has occurred, the validation regular expression will match against ANYTHING, and QID 150094 will report that you are successfully authenticated. If, however, the QBR script fails to execute fully, and it cannot find the target element on the post-authentication page, then QID 150100 will report that the script did not execute fully, and QID 150095 will report that the QBR script failed to authenticate to the application.
To implement this method, please see the section for "The WaitForElementPresent Command" to adjust your QBR script, and use "*." (without the quotes) for your validation regex within WAS as shown in the screenshot below.
Leveraging "waitForElementPresent" for successful playback in WAS
The "waitForElementPresent" command in a QBR script can be used for a variety of practical and useful operations. For example, if you need to add a delay to a command to allow time for dynamic content on a web application to fully load, you can use the “waitForElementPresent” command to pause execution until the target element is loaded and available.
A good application of this is when attempting to use the “sendKeys” command to pass in the username for a WAS authentication record. After the page is accessed, instead of immediately going to the sendKeys command, you can first use the “waitForElementPresent” command to slow the script playback down until the necessary fields have loaded/rendered.
For example, if the form field for the username is identified by id=user, you could modify your QBR script to add a "waitForElementPresent" command after the initial open command. Another useful scenario is to use it at the end of your script to verify you have successfully authenticated. This is shown in bold below.
|
Command |
Target |
Value |
|---|---|---|
|
open |
https://www.myapp.com |
|
|
waitForElementPresent |
Id=user |
|
|
sendkeys |
Id=user |
John.Smith |
|
sendkeys |
Id=password |
P@$$w0rd123 |
|
click |
Id=submit |
|
|
waitForElementPresent |
Id=logout |
|
The script itself gives you greater flexibility in confirming authentication compared to the validation regex within WAS. You just need to find an element that only appears in the post-authentication page. You can use text or elements from the DOM.
For example, you may have a button on the page labeled "Log Out". To use this for the waitForElementPresent command, you have to identify this button by its element and not by the text itself. So "Log Out" won't work, but id=logout will if this is how the button is referenced.
In this example, you would add the waitForElementPresent as your final command in your QBR authentication script. For example:
See the issue on “Manually identifying targets for QBR commands" to better understand how to find elements for modifying your QBR scripts.
Prevent auto-login when recording an authentication script
When recording your authentication script using QBR, you may need to utilize Chrome's Incognito Mode. This is sometimes necessary because applications will seamlessly authenticate you due to existing cookies, local storage, Windows Integrated login, etc.
During a WAS scan, the scanner, of course, does not have access to this data. It interacts with the web application using a "clean" history, so it is important to record your script from that perspective.
Simply open a Chrome Incognito window and record your script there. Note, you may need to activate QBR for use in Incognito Mode by enabling the "Allow in incognito" setting for the extension in Chrome.
Using a single authentication script for different apps that use a common SSO
If you need to scan a web application that uses single sign-on (SSO), you will most likely need to use a Selenium script for Qualys WAS to successfully authenticate (more information). If you have multiple web apps that use the same SSO mechanism, you may find that your authentication scripts are identical except for the URL of the initial open command. If that's the case, you can edit the script manually using a text editor and replace the URL with "@@webappURL@@" (without the quotes). This is known as a WAS parameter. When the script is played back during the WAS scan, the scanner will recognize the WAS parameter and replace it with the web application's target URL.
This can greatly simplify the management of your scripts, as you can have a single authentication script that works across multiple web applications.
Below is a snippet of a Selenium script that uses a WAS parameter (highlighted).
...
<tr>
<td>open</td>
<td>@@webappURL@@</td>
<td></td>
</tr>
<tr>
<td>sendKeys</td>
<td>name=email</td>
</tr>
<tr>
<td>sendKeys</td>
<td>name=password</td>
<td>mypass</td>
</tr>
<tr>
<td>click</td>
<td>id=SignInButton</td>
<td></td>
</tr>
...