CSP Errors in instrumented JS Frontend Apps

Problem

When using Sealights static instrumentation in a JavaScript frontend application, you may encounter a Content Security Policy (CSP) error in the browser's developer console. A typical error message looks like:

Failed to load the script <XXX-sealights-related-XXX> because it violates the following Content Security Policy directive [...]

Cause

This error occurs because the Sealights instrumentation attempts to:

• Load scripts from external domains, such as your Sealights account URL.

• Inject inline scripts, like the sl-preamble-config.js file.

These actions may violate your application's Content Security Policy (CSP), which is a security feature implemented by modern browsers to prevent cross-site scripting (XSS), data injection, and other vulnerabilities. CSP works by restricting the sources from which content (scripts, styles, images, etc.) can be loaded.

If your CSP configuration does not explicitly allow these external sources or inline scripts, the browser will block them, resulting in the error message seen above.

To learn more about how CSP works and how it affects script loading, refer to this helpful resource: Content Security Policy Reference

Solutions

Option 1 (Recommended): Whitelist Sealights Domains in CSP

Update your CSP configuration to allow Sealights scripts. This typically involves:

• Adding Sealights domains to the script-src directive.

• Allowing inline scripts if required by the Sealights dashboard.

If your organization uses HTTP headers to enforce CSP, coordinate with your IT or DevOps team to update the policy.

In some cases, it may be possible to use a <meta> tag in your HTML to define the CSP policy. See this example: Example a CSP header with a meta tag

Option 2: Use the Sealights HTTP Collector

This approach is ideal for environments with strict CSP policies that cannot be modified easily.

Deploy the Sealights HTTP Collector within your network domain. This acts as a middleware/proxy, allowing instrumentation scripts to be served from a trusted internal domain, thereby avoiding CSP violations.

To use this approach, you must update your frontend app's Sealights instrumentation command to include the --collectorUrl parameter, pointing to your deployed collector instance. For example:

npx slnodejs instrument [...] --collectorUrl https://<ServerFQDN>:16500/api

This ensures that the browser agent communicates with the collector instead of directly with the Sealights backend.

For setup instructions and configuration details, refer to the dedicated Sealights HTTP Collector Documentation