JS Agent Configuration
JS Agent Summary
tCell’s XSS feature can detect all types of successful XSS attacks by monitoring the DOM of a user’s browser for the presence of any new inline executable scripts. It does this by automatically inserting a script into the
<head> of each page of the application. The JS Agent script tag uses Subresource Integrity (SRI) to check the script's contents against a cryptographic hash before the script runs. You can enable or disable the SRI feature programmatically with the enable_js_agent_sri config option.
Inline Script Events
tCell uses a JS Agent to provide inline script attack detection by capturing DOM activity and pre-populated script loads. By default, your CSP allows inline scripts to execute. This allows the JS Agent to alert on malicious DOM activity that is not covered by the CSP.
To view inline script events, you will need to navigate to XSS from the left sidebar, click the Events link, and then click the Inline Script Events link. From this area, you can identify where the inline script is executing in the DOM, the clients that are executing it, and view the actual script source code.
If this script execution is expected, we can simply add it to the JS Agent Policy by clicking "Add to Policy" in the right hand corner of the expanded row.
The JS Agent allows for fine grained configuration and allowlisting of inline scripts based on the script content. If your application uses dynamic inline scripts where the content varies, you can also create a regular expression to allowlist its placement in the DOM. This can be accomplished in the JS Agent policy under Settings.
Inline Script Attack Identification
To see XSS events, in your tCell console, go to your application. From the left sidebar, choose XSS. When the "XSS" page appears, click the XSS Exploits card.
To get more details about a particular event, click the down arrow to the left of the Script ID. You will see the IPs of the affected users and the exact script that executed.
Note that tCell strips sensitive data, so the script will be mostly made up of function and variable names. You will see a
? everywhere that tCell strips data. On the top right, you can change the time range.
To get further details about a particular event, click on the small blue graph icon on the right. You will now see each time the script was executed and its exact script location within a page. To get the greatest level of detail about a particular event in this list, click on the right arrow next to the IP address for that event.
When a XSS attack occurs, it’s important to follow the security best practice and use the detailed information provided by tCell to quickly find and fix the vulnerability in the code.
JS Agent sequence diagram
This diagram describes the detail of how the JS Agent interacts with the components of the web application and the tCell service.
- On a normal page load, the App Server Agent, or the customer application, inserts a script tag into the header of the document.
- The JS Agent contacts the tCell service to fetch a policy to determine what scripts it should report and and what it should ignore.
- The JS Agent then scans the DOM at this early time to detect inline scripts already loaded before they can run and possibly interfere with the JS Agent.
- At the conclusion of the scan, an asynchronous transmission of general page information as well as unexpected inline scripts is started asynchronously.
- The agent registers itself to watch DOM changes, and continues to determine if inline scripts are added to the page contents before those scripts are started, potentially sending additional events over additional connections.
NOTE In the diagram, the region identifier
us located at the front of the hostnames (for example,
us.input.tcell.insight.rapid7.com) represents United States 1, one of five different data centers serving Rapid7 customers. For more information about all five region identifiers (
au) and their hostnames, see United States, European Union, and Australia.
JS Agent API keys
The API Keys used for the JS Agent are scoped separately from API keys used in other parts of the tCell service.
JS Agent API keys only permit retrieval of their configuration and reporting of inline script events. No configuration changes or other information retrieval is possible using such a key.