---
title: "Content Security Policy - Serpwise Documentation"
description: "Build, test, and enforce a Content Security Policy with report-only mode, violation reports, and automatic source detection."
url: "https://serpwise.ai/docs/content-security-policy/"
source: "https://serpwise.ai/docs/content-security-policy/"
---
[Back to Serpwise](/)

Serpwise Documentation

Connect · Configure · Execute

Search documentation

`/`

No documentation found.

↑↓ Navigate Enter to open

Browse documentation

**Content Security Policy (CSP)** controls which external resources - scripts, styles, images, fonts, iframes - browsers are allowed to load on your pages. It is the most effective defense against XSS attacks, but getting it wrong breaks your site. Serpwise’s CSP Builder lets you build a policy visually, test it in report-only mode, and auto-detect the sources your pages actually use - without touching your origin server.

The CSP Builder is configured from the **CSP Builder** tab in your domain’s Security settings. Violation reports and detected sources are in the **CSP Reports** tab.

## Recommended Workflow

Most sites should follow this order:

1. **Enable Auto-Detect** - the gateway scans your proxied pages and catalogs every external script, stylesheet, image, font, and iframe source
2. **Review detected sources** - check the CSP Reports tab to see what your pages actually load
3. **Apply a preset** - start with “Standard” (includes Google Analytics, YouTube, Google Fonts) and adjust
4. **Switch to Report-Only** - browsers log violations without blocking anything
5. **Review violation reports** - check the CSP Reports tab for resources that would be blocked
6. **Whitelist legitimate sources** - add missing origins to the relevant directives
7. **Switch to Enforce** - once violations are clean, enforce the policy

## CSP Builder

### Mode Selector

| Mode            | Header                                | Behavior                                           |
|-----------------|---------------------------------------|----------------------------------------------------|
| **Disabled**    | *(none)*                              | No CSP header is sent                              |
| **Report-Only** | `Content-Security-Policy-Report-Only` | Browsers log violations but do not block resources |
| **Enforce**     | `Content-Security-Policy`             | Browsers block resources that violate the policy   |

### Presets

Click a preset to populate all directives at once. You can then customize individual directives before saving.

| Preset       | Best for                                                     | Key characteristics                                        |
|--------------|--------------------------------------------------------------|------------------------------------------------------------|
| **Basic**    | Simple sites with no third-party scripts                     | `default-src 'self'`, allows inline styles, blocks objects |
| **Standard** | Marketing sites with Google Analytics, YouTube, Google Fonts | Includes common Google and YouTube origins                 |
| **Strict**   | High-security applications                                   | No inline scripts, no frames, strict form targets          |

### Directives

Each directive controls which sources are allowed for a specific resource type. If a directive is not set, the browser falls back to `default-src`.

| Directive         | Controls                                | Common sources                           |
|-------------------|-----------------------------------------|------------------------------------------|
| `default-src`     | Fallback for all resource types         | `'self'`                                 |
| `script-src`      | JavaScript                              | `'self'`, `'unsafe-inline'`, CDN origins |
| `style-src`       | CSS stylesheets                         | `'self'`, `'unsafe-inline'`, font CDNs   |
| `img-src`         | Images                                  | `'self'`, `data:`, `https:`              |
| `font-src`        | Web fonts                               | `'self'`, `data:`, Google Fonts          |
| `connect-src`     | Fetch, XHR, WebSocket                   | `'self'`, API endpoints, analytics       |
| `media-src`       | Audio and video                         | `'self'`, media CDNs                     |
| `frame-src`       | Iframes                                 | `'self'`, YouTube, payment providers     |
| `frame-ancestors` | Who can embed your page in an iframe    | `'self'`, `'none'`                       |
| `object-src`      | Plugins, embeds (`<object>`, `<embed>`) | `'none'` (recommended)                   |
| `base-uri`        | Allowed `<base>` tag URLs               | `'self'`                                 |
| `form-action`     | Form submission targets                 | `'self'`                                 |
| `worker-src`      | Web Workers and Service Workers         | `'self'`                                 |

### Common Source Values

| Value                     | Meaning                                                             |
|---------------------------|---------------------------------------------------------------------|
| `'self'`                  | Same origin as the page                                             |
| `'none'`                  | Block all sources for this directive                                |
| `'unsafe-inline'`         | Allow inline `<script>` and `<style>` tags (weakens XSS protection) |
| `'unsafe-eval'`           | Allow `eval()` and similar dynamic code execution                   |
| `data:`                   | Allow `data:` URIs (common for inline images and fonts)             |
| `blob:`                   | Allow `blob:` URIs                                                  |
| `https:`                  | Allow any HTTPS origin                                              |
| `https://cdn.example.com` | Allow a specific origin                                             |

### Adding Sources

For each directive, you can:

- **Select from common sources** - dropdown with `'self'`, `'none'`, `'unsafe-inline'`, etc.
- **Type a custom origin** - enter a URL like `https://cdn.example.com` and press Enter
- **Remove a source** - click the X on any source badge

### Policy Preview

The bottom of the CSP Builder shows the compiled policy header value in real-time. This is exactly what the gateway will send to browsers.

* * *

## Report-Only Mode

Report-Only mode is the safe way to test a CSP. The gateway sends the `Content-Security-Policy-Report-Only` header instead of `Content-Security-Policy`. Browsers evaluate the policy and report violations, but **do not block any resources**. Your site continues to work normally.

When Report-Only mode is active, the gateway automatically includes a `report-uri` directive pointing to a per-domain collection endpoint (`/__sw/csp-report/{domainId}`). Browsers POST violation reports to this endpoint as JSON, and the gateway stores them for display in the CSP Reports tab.

### What Browsers Report

Each violation report includes:

- **Blocked URI** - the resource that would be blocked
- **Violated directive** - which CSP directive was violated (e.g., `script-src`)
- **Document URI** - the page where the violation occurred
- **Source file, line, column** - where in the page the violating code appears

* * *

## CSP Violation Reports

The **CSP Reports** tab shows violation reports grouped by directive. Use these to identify:

- **Third-party scripts** you forgot to whitelist (e.g., analytics, chat widgets, A/B testing tools)
- **Inline scripts or styles** that need `'unsafe-inline'` or should be refactored
- **Legacy resources** loaded over HTTP that need `upgrade-insecure-requests`

* * *

## Auto-Detect Sources

When **Auto-detect sources** is enabled in the CSP Builder, the gateway scans every proxied HTML response and catalogs all external resource URLs. These are aggregated per-domain and displayed in the **CSP Reports** tab under “Detected External Sources.”

### What Gets Detected

| HTML element                             | CSP directive |
|------------------------------------------|---------------|
| `<script src="...">`                     | `script-src`  |
| `<link rel="stylesheet" href="...">`     | `style-src`   |
| `<img src="...">`, `<img srcset="...">`  | `img-src`     |
| `<link as="font" href="...">`            | `font-src`    |
| `<iframe src="...">`                     | `frame-src`   |
| `<video src="...">`, `<audio src="...">` | `media-src`   |

Only **cross-origin** sources are reported. Same-origin resources (matching your domain) are excluded since they are covered by `'self'`.

### Using Detected Sources

Each detected source shows:

- **Source origin** - e.g., `https://www.googletagmanager.com`
- **Sample page** - an example page where the source was found
- **Hit count** - how frequently this source appears across your pages

Use this data to populate your CSP directives. If you see `https://www.googletagmanager.com` under `script-src`, add it to the `script-src` directive in your CSP Builder.

* * *

## Relationship to Security Headers

The **Security Headers** tab includes a raw `Content-Security-Policy` text field. The structured **CSP Builder** is a separate, more powerful tool:

- When **both** are configured, the **CSP Builder takes precedence** - the raw text field is ignored
- When only the raw text field is set (CSP Builder is Disabled), the raw text field is used
- The CSP Builder supports Report-Only mode and violation reporting; the raw text field does not

We recommend migrating from the raw text field to the CSP Builder for new setups.

## Relationship to Rules

Rule actions (`set_response_header`, `remove_response_header`) can override any header, including CSP. The injection order is:

1. Origin server returns its response headers
2. Security Headers are injected (overwrites origin headers)
3. CSP Builder policy is applied (overwrites Security Headers CSP if active)
4. Rule actions execute (can override anything above)

This means you can use the CSP Builder for a global baseline and use rules to tighten or relax CSP on specific pages.