Track CSP violations
Grafana Cloud

Track CSP violations

Faro provides a CSP instrumentation that automatically tracks Content Security Policy (CSP) violations using the browser’s native securitypolicyviolation event.

CSP violations typically indicate that a page attempted to load a disallowed resource or executed inline code that violates your policy. Capturing these violations helps you identify potential security misconfigurations or malicious content injection.

The CSP instrumentation listens for browser-emitted securitypolicyviolation events and sends them as structured Faro events to your collector.

What is collected

When a CSP violation occurs, the following properties are captured and sent as part of the securitypolicyviolation event:

  • blockedURI: The URI that was blocked by the policy
  • documentURI: The URI of the document where the violation occurred
  • sourceFile: The file that contained the violating code
  • statusCode: The HTTP status code of the resource
  • lineNumber, columnNumber: The line and column number in the source file
  • disposition: Whether the policy was enforced or reported only
  • effectiveDirective: The effective directive that was violated
  • violatedDirective: The original directive that triggered the violation
  • originalPolicy: The full policy as delivered by the server
  • referrer: The document referrer, if any
  • sample: A snippet of the violating code, if available

The CSP instrumentation tags these events with the current session and page metadata, and then stores them as events in Loki.

Enable the CSP instrumentation

To use the CSP instrumentation, install and add it to your Faro initialization configuration.

bash
npm install @grafana/faro-web-sdk
npm install @grafana/faro-web-sdk:instrumentation-csp

Next, add it to the SDK setup:

ts
import { initializeFaro } from '@grafana/faro-web-sdk';
import { CSPInstrumentation } from '@grafana/faro-web-sdk:instrumentation-csp';

initializeFaro({
  url: 'https://my-collector-url/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  instrumentations: [new CSPInstrumentation()],
});

That’s it. No further configuration is needed. As long as your page has a CSP policy in place, violations are tracked automatically.

Note

This instrumentation uses the browser’s built-in securitypolicyviolation event. If your CSP prevents loading the SDK itself, violations may not be captured.

Tips

  • Use report-only mode during development to monitor violations without enforcing the policy.
  • Since Faro does not currently support a report-to ingestion endpoint, this instrumentation is the recommended way to monitor CSP violations through Faro.
  • You can test your CSP setup using online tools like CSP Evaluator.
  • Combine CSP tracking with session and release metadata in Faro to trace violations to specific deployments.