Content security policy

Content Security Policy (CSP) is a browser-enforced security mechanism that controls which external resources like scripts, styles, images, fonts, frames, and more are allowed to load on your Knowledge base site. When CSP is enabled in Document360, a content security policy dir ective is embedded in your site's page source, restricting resource loading to only the domains you explicitly configure. This helps protect your Knowledge Base from common web vulnerabilities such as Cross-Site Scripting (XSS), clickjacking, and data injection attacks.

Why you need CSP

Without CSP, browsers permit any resource to load on your page — including scripts, images, and frames from domains you didn't intend to allow. This creates openings for:

• Cross-Site Scripting (XSS): Attackers injecting malicious scripts that steal session tokens or manipulate page content.

• Clickjacking: Your Knowledge Base being embedded inside an invisible iframe on a malicious site, tricking users into unintended clicks.

• Data injection: Unauthorised third-party scripts silently exfiltrating user data or analytics.

CSP lets you define an allowlist of trusted domains for each resource type. The browser enforces it automatically, no change to your application code is required.

When to use CSP?

CSP is most valuable when your Knowledge Base embeds third-party content (videos, chat widgets, analytics), uses custom HTML or inline scripts, is deployed in a compliance-sensitive or enterprise environment, or needs to be protected from being framed by external sites.

How CSP works in Document360

Document360 implements CSP via a meta element embedded in your site's page source, rather than via an HTTP response header. This means:

• All CSP rules are applied at the page level through a <meta http-equiv="Content-Security-Policy"> tag.

• If you validate CSP by inspecting the HTTP response header, it will appear absent and this is expected behaviour.

• To confirm CSP is active, right-click your Knowledge Base site, select View page source, and search for "Content-Security-Policy".

Why the meta element approach?

HTTP response headers require server-side configuration. Document360 uses a meta element so you can configure CSP entirely from the settings UI without any infrastructure changes. The security protection is equivalent for the vast majority of directives, with the exception of frame-ancestors, which is only supported via HTTP headers in some browsers. Document360 handles this automatically.

Enabling Content security policy

1. Navigate to Settings () > Knowledge base site > Security.

2. Toggle on to Enable content security policy.

3. Configure the required directive groups. You can find the following source fields:
   a. Code policy
   b. Resource control
   c. Embedding & Security
   d. Reporting

4. Click Save.

NOTE

When CSP is enabled, ensure that the nonce attribute placeholder is added to all custom HTML script sections. Example:

<script nonce="{{Document360-Nonce}}">

NOTE

• The character limit for each field is 5000.

• Use commas (,) to separate multiple domains.

• Keep the URLs in the following format: https://example.com.

• Existing CSP configurations remain preserved when toggling CSP off and on.

CSP directive groups

The CSP settings are organized into four logical groups. Each group contains specific directives controlling different resource types. All fields accept comma-separated domain URLs in the format  https://example.com.

1. Code policy

This group governs the sources from which code and styling resources are loaded. It forms the foundation of your CSP configuration, the Default source directive acts as a fallback for any resource type that does not have a more specific rule defined.

2. Resource control

This group controls which external domains are allowed to supply media and data resources such as images, fonts, API calls, and background worker scripts on your Knowledge Base site.

3. Embedding & Security

This group controls how your Knowledge Base embeds external content and how it can itself be embedded on other websites. It is particularly important for preventing clickjacking attacks and managing third-party content such as videos, widgets, and portals.

4. Reporting

The Reporting group enables you to monitor your CSP in practice by instructing browsers to send violation reports to a designated endpoint whenever a resource is blocked by your policy. This is essential for identifying misconfigurations and potential attack attempts without disrupting your site.

NOTE

Ensure endpoint URLs entered in the Reporting fields are valid and publicly reachable before saving. The report endpoint must also accept POST requests and respond with a 2xx status code.

X-Frame protection

The X-Frame protection option is available alongside CSP settings on the Security page. When enabled, it adds an X-Frame-Options: SAMEORIGIN response header to your Knowledge Base pages, preventing them from being loaded inside an iframe on any external domain.

This provides clickjacking protection for browsers and tools that process HTTP headers rather than meta-tag CSP. It is a simpler, blunter control than frame-ancestors. It does not allow you to permit specific trusted domains

NOTE

X-Frame Options and the frame-ancestors CSP directive both govern frame embedding behaviour. If you configure both, ensure they are consistent to avoid conflicting rules.

For example, do not enable X-Frame Protection while also adding an external domain to frame-ancestors - the X-Frame header will override the CSP directive in browsers that support both.

Use cases for Content security policy

Embedded videos

If your articles include videos from YouTube or Vimeo, use the Frame source directive to allow only those trusted domains.

• Add to Frame source: https://www.youtube.com, https://player.vimeo.com

• This ensures embedded media loads correctly while blocking unauthorised iframe content.

Third-party analytics and feedback tools

If your Knowledge Base uses Google Analytics, Mixpanel, or a feedback widget, add their script and data collection domains to Script source and Connect source.

• Script source example: https://www.google-analytics.com, https://cdn.mixpanel.com

• Connect source example: https://api.mixpanel.com

Live chat widgets

Chat widgets like Intercom or Zendesk typically need permissions across multiple directives because they load scripts, make API calls, and serve their own UI.

• Script source: https://widget.intercom.io, https://js.intercomcdn.com

• Connect source: https://api.intercom.io, https://nexus-websocket-a.intercom.io

• Image source: https://static.intercomassets.com

Custom fonts

Google Fonts and Adobe Typekit load from two different domains - one for the stylesheet and one for the actual font files. Both must be listed.

• Style source: https://fonts.googleapis.com

• Font source: https://fonts.gstatic.com

Embedding your Knowledge Base in a customer portal

If you need to display your Knowledge Base inside an iframe within your own product or SaaS application, use the Frame ancestors directive to permit that specific domain.

• Frame ancestors example: https://app.yourcompany.com

• Setting Frame ancestors to 'none' blocks all external framing. Only change this if you have a legitimate embedding requirement.

Custom HTML and inline scripts

If your articles or theme include custom HTML sections with inline <script> tags, those scripts will be blocked by a strict CSP unless they carry a nonce attribute. Use the Document360 nonce placeholder:

<script nonce="{{Document360-Nonce}}"> 

  // Your custom inline script 

</script> 

The {{Document360-Nonce}} placeholder is replaced at render time with a unique per-request value that matches the nonce listed in the CSP. This allows the trusted inline script to run without needing to weaken your policy with 'unsafe-inline'.

Compliance and security-hardened environments

Teams operating under frameworks such as SOC 2, ISO 27001, or HIPAA often require a documented resource-loading policy. CSP provides a machine-enforced version of that policy. The Reporting directives additionally give you an audit trail of any attempted policy violations.

Best practices

Start with a restrictive default

Set Default source to 'self' first. This creates a secure baseline, only resources from your own domain are allowed unless explicitly permitted elsewhere. Add specific domains in the targeted fields rather than broadening Default source.

Use specific directives instead of broad allowlists

Rather than adding many domains to Default source, use the targeted fields: Script source, Frame source, Connect source, and so on. This keeps the policy easier to maintain and reduces accidental overexposure.

Avoid wildcards

Using *.example.com allows any subdomain of that domain, including ones you don't control or that may be compromised. Only use wildcard subdomains when you own all subdomains of that domain and have no alternative. Never use a bare (allow all) in any directive.

Use reporting before enforcing

Configure Report endpoint first so you can monitor blocked resources before the policy affects your readers. Review violation reports for several days or weeks before tightening the policy.

Use nonce for custom inline scripts

Always use the {{Document360-Nonce}} placeholder in custom HTML script sections. This allows trusted inline scripts to run securely without using 'unsafe-inline', which would undermine your entire script policy.

Keep frame settings aligned

If X-Frame Protection and frame-ancestors are both configured, ensure they follow the same intended behaviour. Misaligned settings may cause unexpected iframe blocking or allow framing when you intended to block it.

Review quarterly

Third-party tools change CDN domains over time. Revisit your CSP settings after any integration change and on a regular schedule (at minimum quarterly) to catch changes that might have silently broken embedded content.

Testing Your Content Security Policy

After configuring and saving your CSP settings, verify that the policy is working as expected using one of the following methods.

Method 1: Via Page Source

• Open your Knowledge Base site in a browser.

• Right-click anywhere on the page and select View page source.

• Use Ctrl+F (Windows) or Cmd+F (Mac) and search for "Content-Security-Policy".

• If found, the full CSP configuration will appear next to this term, confirming it is active.

Method 2: Via Browser Developer Tools

1. Open your browser's developer tools (F12 or right-click > Inspect).

2. Navigate to the Network tab.

3. Visit your Knowledge Base and select any page request.

4. Review the page HTML for the CSP meta tag.

Method 3: Via Online Tools

You can also use external tools such as securityheaders.com to analyse your site's security configuration. Keep in mind that since Document360 uses a meta element rather than a response header, some tools may report CSP as absent at the header level, this is expected.

Troubleshooting

Step 1: Read the browser console error

When CSP blocks a resource, the browser logs a specific error in the developer console (F12 > Console tab). The error message tells you exactly what was blocked and which directive was violated.

For example: Refused to load the script 'https://cdn.example.com/widget.js' because it violates the following CSP directive: "script-src 'self'".  This error tells you to add https://cdn.example.com to the Script source field. Read the domain from the error message and add it to the corresponding directive field in Document360 settings.

Step 2: Identify the right directive

Match the resource type in the console error to the correct directive field:

Common issues

Video shows as 'This content is blocked' in one article but not another

The domain serving the video is not in your Frame source allowlist, or the domain differs between embed types (for example, https://www.youtube.com for standard embeds vs https://www.youtube-nocookie.com for privacy-enhanced embeds). Add both to Frame source.

Custom font displays incorrectly or falls back to system font

Font providers typically use two different domains - one for the CSS stylesheet and one for the actual font files. Both must be listed. For Google Fonts, add https://fonts.googleapis.com to Style source and https://fonts.gstatic.com to Font source.

Chat widget loads but doesn't function

Chat widgets often load scripts, make API calls, and load images from multiple domains. Check the browser console for all blocked requests- there may be several. Add all required domains to the appropriate directive fields (Script source, Connect source, Image source).

Form submission is blocked

If a form on your Knowledge base submits to an external service, add that service's domain to the Form action field.

Violation reports are not arriving at the Report endpoint

Verify that:

• The endpoint URL is publicly reachable (not behind a VPN or firewall).

• The endpoint accepts POST requests and returns a 2xx response.

• The endpoint supports the Content-Type: application/csp-report request format.

• If using the Report to directive, the named reporting group is correctly configured in your infrastructure.

CSP validation tool reports CSP as missing

Document360 implements CSP via a meta element in the page source, not via an HTTP response header. Tools that only check response headers will report CSP as missing. To confirm CSP is enabled, view the page source and search for Content-Security-Policy.

Browser differences

Most modern browsers (Chrome, Firefox, Edge, Safari) support the CSP meta element. Known differences to be aware of:

• frame-ancestors is ignored when delivered via a meta element in some older browser versions. If frame embedding protection is critical, also enable X-Frame Protection.

• Safari may handle some CSP directives differently from Chrome and Firefox. Test your configuration in Safari if your users are on Apple devices.

• Very old browsers (Internet Explorer 11 and below) do not support CSP. If you have IE11 users, CSP will be silently ignored.

NOTE

Private Knowledge Base projects cannot be embedded in iframes. Authentication cookies are not set correctly inside iframes, which causes repeated login attempts and redirect errors. If you need to embed the Knowledge Base in another application, use a Knowledge base widget instead.

{ 
"csp-report": 
{"document-uri": "https://docs.yourcompany.com/article", 
"violated-directive": "script-src 'self'", 
"blocked-uri": "https://cdn.example.com/widget.js", 
"original-policy": "default-src 'self'; script-src 'self'"} 
}