---
title: "Track CSP violations | Grafana Cloud documentation"
description: "Learn how to track CSP violations using the Faro CSP instrumentation"
---

# Track CSP violations

Faro provides a CSP instrumentation that automatically tracks [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
npm install @grafana/faro-web-sdk
```

The CSP violations instrumentation is automatically included with the standard web instrumentations when using `getWebInstrumentations()`.

ts ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```ts
import { initializeFaro, getWebInstrumentations } from '@grafana/faro-web-sdk';

initializeFaro({
  url: 'https://my-collector-url/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  instrumentations: [...getWebInstrumentations(/* ... */)],
});
```

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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy-Report-Only) 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](https://csp-evaluator.withgoogle.com/).
- Combine CSP tracking with session and release metadata in Faro to trace violations to specific deployments.

## Disabling the CSP instrumentation

You can disable the CSP violations instrumentation by excluding it from the web instrumentations.

ts ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```ts
import { initializeFaro, getWebInstrumentations } from '@grafana/faro-web-sdk';

initializeFaro({
  url: 'https://my-collector-url/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  instrumentations: [
    ...getWebInstrumentations({
      enableContentSecurityPolicyInstrumentation: false,
    }),
  ],
});
```