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.

The JS Agent allows tCell to see all of the executed scripts and determine which scripts are XSS attacks. This feature is enabled by default. To verify that it’s enabled, log in to your tCell console and go to Policies > JS Agent. Ensure that Enabled and Enable automatic insertion of the JavaScript Agent are both checked.

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.

Events

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.

Add to Policy

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.

XSS Attacks

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.

Inline Script Events

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.

When it is more convenient to manage the returned documents, automatic insertion can be disabled and the jsagent script tags can be provided manually. For example, you could edit or insert the script tag in the header of the default page template. You can see the tag format to use in the tCell console by going to Admin -> Download Agent -> Javascript Agent. Under Step 2, this page displays the tag along with the API key required to transmit data to your tCell app environment.

Download Agent tab

If you are converting an existing app to provide the script tag itself or initially configuring an app to self-provide the script tag, go to Policies -> JS Agent and uncheck Enable automatic insertion of the JavaScript Agent to avoid double-execution of the JS Agent.

JS Agent sequence diagram

JavaScript Agent Workflow

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.
  • Honoring the script tag, the browser fetches JS Agent from a robust Content Delivery Network, and executes the JavaScript.
  • 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 (us, us2, us3, eu, and 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.