# Content Security Policy and headers

> The CSP directives the SDK needs, violation reports, monitored headers and how they relate to PCI DSS.

URL: https://docs.proteside.com/en/docs/integration/csp

If your checkout uses a Content Security Policy (CSP), it must allow the Proteside snippet. The dashboard doesn't
generate a CSP for you: this page lists what the SDK actually uses in the browser, so you can add it to your store's
policy.

## Required directives
| Directive     | Value                                                                     | Purpose                                                                        |
| ------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `script-src`  | hash, nonce or `'unsafe-inline'` for the snippet's inline `<script>` tags | Run the bootstrapper, which includes the inline rules when the store has them. |
| `script-src`  | `https://cdn.proteside.com`                                               | Load `shield.js`.                                                              |
| `connect-src` | `https://app.proteside.com`                                               | Fetch the configuration and send events.                                       |
| `connect-src` | `'self'`                                                                  | Read the page's own security headers (see below).                              |
| `connect-src` | origins of the page's external scripts (optional)                         | Compute the content hash of third-party scripts.                               |

Without `connect-src` for `app.proteside.com`, the SDK loads and runs, but no events reach the dashboard.

### The snippet's inline scripts
The bootstrapper is inline and must stay inline (see [Installing the snippet](https://docs.proteside.com/en/docs/integration/install)). Choose a way to
authorize it:

* **Hash** (`'sha256-…'`): authorizes exactly that content. The hash changes when the script's content changes: every
  time you paste a snippet from a new version and, if the store has inline rules, whenever you paste the snippet again
  after changing rules or Google Tag Manager containers, because the inline rules sit in the same script. Older
  snippets, with the inline configuration in a separate tag, need a second hash for it.
* **Nonce:** if your server already generates a nonce per response, add the `nonce` attribute to the snippet's
  `<script>` tags when you paste it into your template. The dashboard's snippet doesn't include a `nonce`.
* **`'unsafe-inline'`:** works, but allows any inline script and weakens the policy. Not recommended on payment pages.

The safest way to get the hash is to let the browser compute it: publish the CSP without the hash (preferably in
`Content-Security-Policy-Report-Only` mode), open the checkout and look at the violation message in the console. It
gives you the `'sha256-…'` value of the blocked script. To compute it locally, use exactly the content between
`<script>` and `</script>`, with no trailing newline:

```bash title="Compute the bootstrapper hash"
# bootstrapper.js = content between <script> and </script>, copied from the snippet
printf '%s' "$(cat bootstrapper.js)" | openssl dgst -sha256 -binary | openssl base64
```

## Example header
An example for a checkout on `mystore.com` with Stripe. Adapt the other origins to your store.

```http title="Checkout page response header"
Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'sha256-BOOTSTRAPPER_HASH' https://cdn.proteside.com https://js.stripe.com;
  connect-src 'self' https://app.proteside.com https://api.stripe.com;
  frame-src https://js.stripe.com;
  img-src 'self' data:;
  style-src 'self';
  report-uri https://app.proteside.com/api/sdk/csp-report?key=pk_live_YOUR_KEY;
  report-to proteside
Reporting-Endpoints: proteside="https://app.proteside.com/api/sdk/csp-report?key=pk_live_YOUR_KEY"
```

The real header goes on a single line; the line breaks above are only for readability. If your snippet uses the older
format, with the inline configuration in a separate `<script>` tag, add that tag's hash too.

> **Note**
>
> If you use the [Proteside badge](https://docs.proteside.com/en/docs/integration/badge), add `https://app.proteside.com` to `img-src`. The SDK itself doesn't
> need `style-src` or `img-src`.

## Violation reports
Proteside receives CSP reports at the address below. It doesn't appear on any dashboard screen; use your SDK key in
the `key` parameter:

```text
https://app.proteside.com/api/sdk/csp-report?key=pk_live_YOUR_KEY
```

* It accepts both formats: `report-uri` and `report-to` (Reporting API).
* The total shows up in **SDK Health**, in the **CSP reports (48 h)** card.
* A `script-src` or `connect-src` violation for a host that's **not** in the store's script inventory becomes a
  `CSP_VIOLATION` alert, with low severity. Violations of other directives are only counted.

To test a new policy without breaking the checkout, publish it first as `Content-Security-Policy-Report-Only`, watch
the reports, and then switch to `Content-Security-Policy`.

## Monitored security headers
To support detecting header changes, the SDK reads the payment page's security headers on every page load and every
`Proteside.pageChanged()`:

`Content-Security-Policy`, `Content-Security-Policy-Report-Only`, `Strict-Transport-Security`, `X-Frame-Options`,
`X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`, `Cross-Origin-Opener-Policy`,
`Cross-Origin-Embedder-Policy`, `Cross-Origin-Resource-Policy`, `Access-Control-Allow-Origin` and `Set-Cookie` (the
latter only as "not readable in the browser").

The value of each header that's present is sent to the dashboard. When a value changes, the dashboard creates the
`HEADER_CHANGED` alert. Headers appear in **PCI DSS Evidence**, on the **Headers** tab.

> **One extra GET request per pageview**
>
> To read the headers, the SDK makes an additional `GET` request to the page's own URL. If your checkout performs an
> action when it receives a `GET` (creating an order, reserving stock, generating a charge), that action will happen
> twice. Make sure the payment page's `GET` has no side effects.

## Subresource Integrity (SRI)
Don't use the `integrity` attribute on the `shield.js` tag. The URL is mutable: the same address receives every new
SDK version, so the hash would change with each release and the browser would start refusing the script.

As a preventive control, restrict `script-src` to `https://cdn.proteside.com` and authorize the inline bootstrapper by
hash or nonce. The Proteside inventory records which scripts on your page use `integrity` and `nonce`.

## How this relates to PCI DSS 4.0
| Requirement | What it asks for                                                                                                                             | How Proteside and CSP help                                                                                                                                                                |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 6.4.3       | Manage payment page scripts executed in the browser: an inventory with justification, authorization of each script, and integrity assurance. | The SDK builds the inventory with content hashes; authorization with justification happens in **Scripts**; rules block unauthorized scripts. CSP limits where scripts can be loaded from. |
| 11.6.1      | Detect and alert on unauthorized changes to the HTTP headers and content of the payment page, as received by the browser.                    | The SDK reads the security headers on every pageview and detects new or modified scripts; the dashboard raises `HEADER_CHANGED`, `SCRIPT_INTEGRITY_MISMATCH` and the other alerts.        |

Proteside generates evidence for these requirements in **PCI DSS Evidence**. The compliance assessment remains the
responsibility of your assessor (QSA) or your self-assessment questionnaire. See
[PCI DSS Evidence](https://docs.proteside.com/en/docs/guide/compliance). For background on both requirements, see
[PCI DSS 6.4.3 and 11.6.1](https://proteside.com/en/solutions/pci-compliance) on the website.

## Next steps
* [Privacy and LGPD](https://docs.proteside.com/en/docs/integration/privacy)
* [Troubleshooting](https://docs.proteside.com/en/docs/integration/troubleshooting)
