From 1a822c268e212192e1f17c3ab8350b24c365e5cb Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 11:48:20 -0700 Subject: [PATCH 01/21] add CSP config page to docs.json --- docs.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index a137f89a6..dfedee142 100644 --- a/docs.json +++ b/docs.json @@ -138,7 +138,8 @@ "pages": [ "advanced/subpath/cloudflare", "advanced/subpath/route53-cloudfront", - "advanced/subpath/vercel" + "advanced/subpath/vercel", + "guides/csp-configuration" ] }, { From f99b40a2e29defa54f14a1c429eb324801acb575 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 13:11:08 -0700 Subject: [PATCH 02/21] Create csp-configuration.mdx --- guides/csp-configuration.mdx | 170 +++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 guides/csp-configuration.mdx diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx new file mode 100644 index 000000000..eba147321 --- /dev/null +++ b/guides/csp-configuration.mdx @@ -0,0 +1,170 @@ +--- +title: "Content Security Policy (CSP) configuration" +sidebarTitle: "CSP configuration" +description: "TODO:Configure Content Security Policy headers to allow Mintlify documentation features to function properly in proxy and corporate environments." +--- + +Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. If you host your documentation behind a reverse proxy or firewall, you may need to configure these CSP headers for features to function properly. + +| Domain | Purpose | CSP Directive | Status | +|--------|---------|---------------|--------| +| d4tuoctqmanu0.cloudfront.net | KaTeX CSS, fonts | style-src, font-src | Active | +| *.mintlify.dev | Documentation content | connect-src | Active | +| d3gk2c5xim1je2.cloudfront.net | Icons, images, logos | img-src | Active | +| unpkg.com | Mintlify widget scripts | script-src | Active | +| www.googletagmanager.com | Google Analytics/GTM | script-src, connect-src | Optional | +| cdn.segment.com | Segment analytics | script-src, connect-src | Optional | +| plausible.io | Plausible analytics | script-src, connect-src | Optional | +| tag.clearbitscripts.com | Clearbit tracking | script-src | Optional | +| cdn.heapanalytics.com | Heap analytics | script-src | Optional | +| chat.cdn-plain.com | Plain chat widget | script-src | Optional | +| chat-assets.frontapp.com | Front chat widget | script-src | Optional | + +Features that require CSP allowlisting: +- KaTeX mathematical equations (requires CSS and font loading) +- Interactive API playground (requires script execution) +- Search functionality (requires API connections) +- Analytics integrations (requires third-party scripts) +- Chat widgets (requires third-party scripts) +- Custom fonts and styling (requires CSS loading) + +Without proper CSP configuration, users may experience broken styling, non-functional interactive elements, or security warnings in their browser console. + +## Example CSP configuration + + + Only include domains for services that you use. Remove any analytics domains that you have not configured for your documentation. + + +``` +Content-Security-Policy: +default-src 'self'; +script-src 'self' 'unsafe-inline' unpkg.com http://www.googletagmanager.com cdn.segment.com plausible.io tag.clearbitscripts.com cdn.heapanalytics.com +chat.cdn-plain.com chat-assets.frontapp.com; +style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; +font-src 'self' d4tuoctqmanu0.cloudfront.net; +img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; +connect-src 'self' *.mintlify.dev http://www.googletagmanager.com cdn.segment.com plausible.io; +frame-src 'self' *.mintlify.dev; +``` + +## Common configurations by proxy type + +Most reverse proxies support adding custom headers. Add this header to your proxy configuration: + +```apache +Header always set Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' unpkg.com; style-src 'self' 'unsafe-inline' +d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' +*.mintlify.dev; frame-src 'self' *.mintlify.dev;" +``` + +### Cloudflare configuration + +In your Cloudflare dashboard: + +1. Go to **Security** > **Transform Rules** > **Modify Response Header**. +2. Create a new rule for your documentation domain. +3. Add HTTP Response Header: + - **Operation**: Set static + - **Header name**: `Content-Security-Policy` + - **Value**: `default-src 'self'; script-src 'self' 'unsafe-inline' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;` + +### AWS CloudFront configuration + +Add a response headers policy in CloudFront: + +```json +{ +"ResponseHeadersPolicy": { + "Name": "MintlifyCSP", + "Config": { + "SecurityHeadersConfig": { + "ContentSecurityPolicy": { + "ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;", + "Override": true + } + } + } + } +} +``` + +### Vercel configuration + +Add to your `vercel.json`: + +```json +{ +"headers": [ + { + "source": "/(.*)", + "headers": [ + { + "key": "Content-Security-Policy", + "value": "default-src 'self'; script-src 'self' 'unsafe-inline' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;" + } + ] + } + ] +} +``` + +## Troubleshooting + +### Identifying CSP violations in browser console + +1. Open your browser's Developer Tools (F12) +2. Go to the **Console** tab +3. Look for errors starting with: + - `Content Security Policy: The page's settings blocked the loading of a resource` + - `Refused to load the script/stylesheet because it violates the following Content Security Policy directive` + - `Refused to connect to because it violates the following Content Security Policy directive` + +### Common error messages and solutions + +**Script loading errors:** +Refused to load the script 'https://unpkg.com/...' because it violates the following Content Security Policy directive: "script-src 'self'". +**Solution:** Add `unpkg.com` to your `script-src` directive. + +**Style loading errors:** +Refused to load the stylesheet 'https://d4tuoctqmanu0.cloudfront.net/...' because it violates the following Content Security Policy directive: "style-src +'self'". +**Solution:** Add `d4tuoctqmanu0.cloudfront.net` to your `style-src` directive. + +**Connection errors:** +Refused to connect to 'https://api.mintlify.dev/...' because it violates the following Content Security Policy directive: "connect-src 'self'". +**Solution:** Add `*.mintlify.dev` to your `connect-src` directive. + +**Image loading errors:** +Refused to load the image 'https://d3gk2c5xim1je2.cloudfront.net/...' because it violates the following Content Security Policy directive: "img-src 'self'". +**Solution:** Add `d3gk2c5xim1je2.cloudfront.net` to your `img-src` directive. + +### Testing methodology + +1. **Start minimal:** Begin with only essential domains and add others as needed +2. **Test incrementally:** Add one domain at a time to identify which fixes specific issues +3. **Use report-only mode:** Test CSP without blocking by using `Content-Security-Policy-Report-Only` header first +4. **Check all pages:** Test different pages that use various Mintlify features (search, math equations, API playground) + +### Gradual CSP implementation approach + +**Step 1: Report-only mode** +Content-Security-Policy-Report-Only: `default-src 'self'; script-src 'self' 'unsafe-inline'` + +**Step 2: Add essential domains** +Content-Security-Policy: `default-src 'self'; script-src 'self' 'unsafe-inline' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net` + +**Step 3: Add remaining domains based on features used** +Only add domains for analytics/chat services you actually have configured. + +### Verification steps + +1. **Check headers are applied:** Use browser dev tools Network tab to verify the CSP header is present +2. **Test core functionality:** Verify search, navigation, and styling work correctly +3. **Test interactive features:** Check API playground, math equations, and any enabled widgets +4. **Monitor console:** Ensure no CSP violations appear in browser console + + +Questions for eng: +- HTTPS vs HTTP - Some domains in the CSP might need https:// prefixes +- Wildcard domain support - *.mintlify.dev syntax may need verification across all proxy types \ No newline at end of file From 3b6eeab2a1f3ab789869a7d27be3d73d82567b7f Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 13:13:27 -0700 Subject: [PATCH 03/21] update description --- guides/csp-configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index eba147321..7727f3c0b 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -1,7 +1,7 @@ --- title: "Content Security Policy (CSP) configuration" sidebarTitle: "CSP configuration" -description: "TODO:Configure Content Security Policy headers to allow Mintlify documentation features to function properly in proxy and corporate environments." +description: "Domain whitelist and header configurations for reverse proxies, firewalls, and networks that enforce strict security policies." --- Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. If you host your documentation behind a reverse proxy or firewall, you may need to configure these CSP headers for features to function properly. From fe7f05e3c0c75bce2170d01c48256ab46bdc7a89 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 13:15:59 -0700 Subject: [PATCH 04/21] add CSP header definitions --- guides/csp-configuration.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 7727f3c0b..aa1ece4c4 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -6,6 +6,16 @@ description: "Domain whitelist and header configurations for reverse proxies, fi Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. If you host your documentation behind a reverse proxy or firewall, you may need to configure these CSP headers for features to function properly. +- `script-src` - Controls which scripts can be executed (JavaScript files, inline scripts) +- `style-src` - Controls which stylesheets can be loaded (CSS files, inline styles) +- `font-src` - Controls which fonts can be loaded (web fonts, font files) +- `img-src` - Controls which images can be loaded (images, icons, logos) +- `connect-src` - Controls which URLs can be connected to (API calls, WebSocket connections) +- `frame-src` - Controls which URLs can be embedded in frames or iframes +- `default-src` - Fallback for other directives when not explicitly set + +## Domain whitelist + | Domain | Purpose | CSP Directive | Status | |--------|---------|---------------|--------| | d4tuoctqmanu0.cloudfront.net | KaTeX CSS, fonts | style-src, font-src | Active | From 2b6fad42e46da1bd9810bf7394128f6a737d6908 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 13:30:50 -0700 Subject: [PATCH 05/21] update conceptual info --- guides/csp-configuration.mdx | 46 ++++++++++-------------------------- 1 file changed, 13 insertions(+), 33 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index aa1ece4c4..035e8d342 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -4,7 +4,11 @@ sidebarTitle: "CSP configuration" description: "Domain whitelist and header configurations for reverse proxies, firewalls, and networks that enforce strict security policies." --- -Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. If you host your documentation behind a reverse proxy or firewall, you may need to configure these CSP headers for features to function properly. +Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. If you host your documentation behind a reverse proxy or firewall, you may need to configure CSP headers for features to function properly. + +## CSP directives + +The following CSP directives are used to control which resources can be loaded: - `script-src` - Controls which scripts can be executed (JavaScript files, inline scripts) - `style-src` - Controls which stylesheets can be loaded (CSS files, inline styles) @@ -30,14 +34,6 @@ Content Security Policy (CSP) is a security standard that helps prevent cross-si | chat.cdn-plain.com | Plain chat widget | script-src | Optional | | chat-assets.frontapp.com | Front chat widget | script-src | Optional | -Features that require CSP allowlisting: -- KaTeX mathematical equations (requires CSS and font loading) -- Interactive API playground (requires script execution) -- Search functionality (requires API connections) -- Analytics integrations (requires third-party scripts) -- Chat widgets (requires third-party scripts) -- Custom fonts and styling (requires CSS loading) - Without proper CSP configuration, users may experience broken styling, non-functional interactive elements, or security warnings in their browser console. ## Example CSP configuration @@ -151,30 +147,14 @@ Refused to load the image 'https://d3gk2c5xim1je2.cloudfront.net/...' because it ### Testing methodology -1. **Start minimal:** Begin with only essential domains and add others as needed -2. **Test incrementally:** Add one domain at a time to identify which fixes specific issues -3. **Use report-only mode:** Test CSP without blocking by using `Content-Security-Policy-Report-Only` header first -4. **Check all pages:** Test different pages that use various Mintlify features (search, math equations, API playground) - -### Gradual CSP implementation approach - -**Step 1: Report-only mode** -Content-Security-Policy-Report-Only: `default-src 'self'; script-src 'self' 'unsafe-inline'` - -**Step 2: Add essential domains** -Content-Security-Policy: `default-src 'self'; script-src 'self' 'unsafe-inline' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net` - -**Step 3: Add remaining domains based on features used** -Only add domains for analytics/chat services you actually have configured. +1. **Start minimal:** Begin with only essential domains and add others as needed. +2. **Test incrementally:** Add one domain at a time to identify which fixes specific issues. +3. **Use report-only mode:** Test CSP without blocking by using `Content-Security-Policy-Report-Only` header first. +4. **Check all pages:** Test different pages that use various features. ### Verification steps -1. **Check headers are applied:** Use browser dev tools Network tab to verify the CSP header is present -2. **Test core functionality:** Verify search, navigation, and styling work correctly -3. **Test interactive features:** Check API playground, math equations, and any enabled widgets -4. **Monitor console:** Ensure no CSP violations appear in browser console - - -Questions for eng: -- HTTPS vs HTTP - Some domains in the CSP might need https:// prefixes -- Wildcard domain support - *.mintlify.dev syntax may need verification across all proxy types \ No newline at end of file +1. **Check headers are applied:** Use browser dev tools Network tab to verify the CSP header is present. +2. **Test core functionality:** Verify search, navigation, and styling work correctly. +3. **Test interactive features:** Check your API playground, KaTeX equations, and other features that your documentation uses. +4. **Monitor console:** Ensure no CSP violations appear in browser console. From 63ad984a4f37dece9b4984e6d481b4905a99c7b7 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 13:32:08 -0700 Subject: [PATCH 06/21] combine testing/verification --- guides/csp-configuration.mdx | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 035e8d342..3b22a6df0 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -145,16 +145,13 @@ Refused to connect to 'https://api.mintlify.dev/...' because it violates the fol Refused to load the image 'https://d3gk2c5xim1je2.cloudfront.net/...' because it violates the following Content Security Policy directive: "img-src 'self'". **Solution:** Add `d3gk2c5xim1je2.cloudfront.net` to your `img-src` directive. -### Testing methodology - -1. **Start minimal:** Begin with only essential domains and add others as needed. -2. **Test incrementally:** Add one domain at a time to identify which fixes specific issues. -3. **Use report-only mode:** Test CSP without blocking by using `Content-Security-Policy-Report-Only` header first. -4. **Check all pages:** Test different pages that use various features. - -### Verification steps - -1. **Check headers are applied:** Use browser dev tools Network tab to verify the CSP header is present. -2. **Test core functionality:** Verify search, navigation, and styling work correctly. -3. **Test interactive features:** Check your API playground, KaTeX equations, and other features that your documentation uses. -4. **Monitor console:** Ensure no CSP violations appear in browser console. +### Testing and verification + +1. **Use report-only mode first:** Test CSP without blocking by using `Content-Security-Policy-Report-Only` header initially. +2. **Check headers are applied:** Use browser dev tools Network tab to verify the CSP header is present. +3. **Start minimal:** Begin with only essential domains and add others as needed. +4. **Test incrementally:** Add one domain at a time to identify which fixes specific issues. +5. **Test core functionality:** Verify search, navigation, and styling work correctly. +6. **Test interactive features:** Check your API playground, KaTeX equations, and other features that your documentation uses. +7. **Monitor console:** Ensure no CSP violations appear in browser console. +8. **Check all pages:** Test different pages that use various features From b464ae51ca7e6c3a308a07bf27835d50fb87f974 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 13:34:38 -0700 Subject: [PATCH 07/21] update troubleshooting --- guides/csp-configuration.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 3b22a6df0..1eaef9c20 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -117,7 +117,7 @@ Add to your `vercel.json`: ## Troubleshooting -### Identifying CSP violations in browser console +Identify CSP violations in browser console 1. Open your browser's Developer Tools (F12) 2. Go to the **Console** tab @@ -154,4 +154,3 @@ Refused to load the image 'https://d3gk2c5xim1je2.cloudfront.net/...' because it 5. **Test core functionality:** Verify search, navigation, and styling work correctly. 6. **Test interactive features:** Check your API playground, KaTeX equations, and other features that your documentation uses. 7. **Monitor console:** Ensure no CSP violations appear in browser console. -8. **Check all pages:** Test different pages that use various features From f7ae744adf3ec6bc3c08008527b7e4d6a7ae2990 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 13:35:55 -0700 Subject: [PATCH 08/21] use accordions for troubleshooting --- guides/csp-configuration.mdx | 61 +++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 28 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 1eaef9c20..9434fde42 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -126,31 +126,36 @@ Identify CSP violations in browser console - `Refused to load the script/stylesheet because it violates the following Content Security Policy directive` - `Refused to connect to because it violates the following Content Security Policy directive` -### Common error messages and solutions - -**Script loading errors:** -Refused to load the script 'https://unpkg.com/...' because it violates the following Content Security Policy directive: "script-src 'self'". -**Solution:** Add `unpkg.com` to your `script-src` directive. - -**Style loading errors:** -Refused to load the stylesheet 'https://d4tuoctqmanu0.cloudfront.net/...' because it violates the following Content Security Policy directive: "style-src -'self'". -**Solution:** Add `d4tuoctqmanu0.cloudfront.net` to your `style-src` directive. - -**Connection errors:** -Refused to connect to 'https://api.mintlify.dev/...' because it violates the following Content Security Policy directive: "connect-src 'self'". -**Solution:** Add `*.mintlify.dev` to your `connect-src` directive. - -**Image loading errors:** -Refused to load the image 'https://d3gk2c5xim1je2.cloudfront.net/...' because it violates the following Content Security Policy directive: "img-src 'self'". -**Solution:** Add `d3gk2c5xim1je2.cloudfront.net` to your `img-src` directive. - -### Testing and verification - -1. **Use report-only mode first:** Test CSP without blocking by using `Content-Security-Policy-Report-Only` header initially. -2. **Check headers are applied:** Use browser dev tools Network tab to verify the CSP header is present. -3. **Start minimal:** Begin with only essential domains and add others as needed. -4. **Test incrementally:** Add one domain at a time to identify which fixes specific issues. -5. **Test core functionality:** Verify search, navigation, and styling work correctly. -6. **Test interactive features:** Check your API playground, KaTeX equations, and other features that your documentation uses. -7. **Monitor console:** Ensure no CSP violations appear in browser console. + + + **Error message:** + ``` + Refused to load the script 'https://unpkg.com/...' because it violates the following Content Security Policy directive: "script-src 'self'". + ``` + **Solution:** Add `unpkg.com` to your `script-src` directive. + + + + **Error message:** + ``` + Refused to load the stylesheet 'https://d4tuoctqmanu0.cloudfront.net/...' because it violates the following Content Security Policy directive: "style-src 'self'". + ``` + **Solution:** Add `d4tuoctqmanu0.cloudfront.net` to your `style-src` directive. + + + + **Error message:** + ``` + Refused to connect to 'https://api.mintlify.dev/...' because it violates the following Content Security Policy directive: "connect-src 'self'". + ``` + **Solution:** Add `*.mintlify.dev` to your `connect-src` directive. + + + + **Error message:** + ``` + Refused to load the image 'https://d3gk2c5xim1je2.cloudfront.net/...' because it violates the following Content Security Policy directive: "img-src 'self'". + ``` + **Solution:** Add `d3gk2c5xim1je2.cloudfront.net` to your `img-src` directive. + + From 93fc558cfae701a57edead347df642d965f259d4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 13:37:04 -0700 Subject: [PATCH 09/21] : isntead of - --- guides/csp-configuration.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 9434fde42..994ada6a5 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -10,13 +10,13 @@ Content Security Policy (CSP) is a security standard that helps prevent cross-si The following CSP directives are used to control which resources can be loaded: -- `script-src` - Controls which scripts can be executed (JavaScript files, inline scripts) -- `style-src` - Controls which stylesheets can be loaded (CSS files, inline styles) -- `font-src` - Controls which fonts can be loaded (web fonts, font files) -- `img-src` - Controls which images can be loaded (images, icons, logos) -- `connect-src` - Controls which URLs can be connected to (API calls, WebSocket connections) -- `frame-src` - Controls which URLs can be embedded in frames or iframes -- `default-src` - Fallback for other directives when not explicitly set +- `script-src`: Controls which scripts can be executed (JavaScript files, inline scripts) +- `style-src`: Controls which stylesheets can be loaded (CSS files, inline styles) +- `font-src`: Controls which fonts can be loaded (web fonts, font files) +- `img-src`: Controls which images can be loaded (images, icons, logos) +- `connect-src`: Controls which URLs can be connected to (API calls, WebSocket connections) +- `frame-src`: Controls which URLs can be embedded in frames or iframes +- `default-src`: Fallback for other directives when not explicitly set ## Domain whitelist From c39a3a469de70002327f56275c03828cba7013ac Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 13:39:44 -0700 Subject: [PATCH 10/21] update whitelist table --- guides/csp-configuration.mdx | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 994ada6a5..657ab6380 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -20,19 +20,19 @@ The following CSP directives are used to control which resources can be loaded: ## Domain whitelist -| Domain | Purpose | CSP Directive | Status | -|--------|---------|---------------|--------| -| d4tuoctqmanu0.cloudfront.net | KaTeX CSS, fonts | style-src, font-src | Active | -| *.mintlify.dev | Documentation content | connect-src | Active | -| d3gk2c5xim1je2.cloudfront.net | Icons, images, logos | img-src | Active | -| unpkg.com | Mintlify widget scripts | script-src | Active | -| www.googletagmanager.com | Google Analytics/GTM | script-src, connect-src | Optional | -| cdn.segment.com | Segment analytics | script-src, connect-src | Optional | -| plausible.io | Plausible analytics | script-src, connect-src | Optional | -| tag.clearbitscripts.com | Clearbit tracking | script-src | Optional | -| cdn.heapanalytics.com | Heap analytics | script-src | Optional | -| chat.cdn-plain.com | Plain chat widget | script-src | Optional | -| chat-assets.frontapp.com | Front chat widget | script-src | Optional | +| Domain | Purpose | CSP Directive | Required | +|:-------|:--------|:--------------|:-------| +| `d4tuoctqmanu0.cloudfront.net` | KaTeX CSS, fonts | style-src, font-src | Required | +| `*.mintlify.dev` | Documentation content | connect-src | Required | +| `d3gk2c5xim1je2.cloudfront.net` | Icons, images, logos | img-src | Required | +| `unpkg.com` | Mintlify widget scripts | script-src | Required | +| `www.googletagmanager.com` | Google Analytics/GTM | script-src, connect-src | Optional | +| `cdn.segment.com` | Segment analytics | script-src, connect-src | Optional | +| `plausible.io` | Plausible analytics | script-src, connect-src | Optional | +| `tag.clearbitscripts.com` | Clearbit tracking | script-src | Optional | +| `cdn.heapanalytics.com` | Heap analytics | script-src | Optional | +| `chat.cdn-plain.com` | Plain chat widget | script-src | Optional | +| `chat-assets.frontapp.com` | Front chat widget | script-src | Optional | Without proper CSP configuration, users may experience broken styling, non-functional interactive elements, or security warnings in their browser console. From aff666dd288be25608819326a8da3b2dbf590631 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 14:05:44 -0700 Subject: [PATCH 11/21] =?UTF-8?q?=F0=9F=92=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- guides/csp-configuration.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 657ab6380..e7de1f5ae 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -10,11 +10,11 @@ Content Security Policy (CSP) is a security standard that helps prevent cross-si The following CSP directives are used to control which resources can be loaded: -- `script-src`: Controls which scripts can be executed (JavaScript files, inline scripts) -- `style-src`: Controls which stylesheets can be loaded (CSS files, inline styles) -- `font-src`: Controls which fonts can be loaded (web fonts, font files) -- `img-src`: Controls which images can be loaded (images, icons, logos) -- `connect-src`: Controls which URLs can be connected to (API calls, WebSocket connections) +- `script-src`: Controls which scripts can be executed +- `style-src`: Controls which stylesheets can be loaded +- `font-src`: Controls which fonts can be loaded +- `img-src`: Controls which images, icons, and logos can be loaded +- `connect-src`: Controls which URLs can be connected to for API calls and WebSocket connections - `frame-src`: Controls which URLs can be embedded in frames or iframes - `default-src`: Fallback for other directives when not explicitly set From 1e3eef7f8250e4c49fde7a217e04ef7c403c45e5 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 14:07:38 -0700 Subject: [PATCH 12/21] style and concision --- guides/csp-configuration.mdx | 36 +++++++++++++++--------------------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index e7de1f5ae..d8300fe07 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -6,6 +6,8 @@ description: "Domain whitelist and header configurations for reverse proxies, fi Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. If you host your documentation behind a reverse proxy or firewall, you may need to configure CSP headers for features to function properly. +Without proper CSP configuration, users may experience broken styling, non-functional interactive elements, or security warnings in their browser console. + ## CSP directives The following CSP directives are used to control which resources can be loaded: @@ -20,21 +22,19 @@ The following CSP directives are used to control which resources can be loaded: ## Domain whitelist -| Domain | Purpose | CSP Directive | Required | +| Domain | Purpose | CSP directive | Required | |:-------|:--------|:--------------|:-------| -| `d4tuoctqmanu0.cloudfront.net` | KaTeX CSS, fonts | style-src, font-src | Required | -| `*.mintlify.dev` | Documentation content | connect-src | Required | -| `d3gk2c5xim1je2.cloudfront.net` | Icons, images, logos | img-src | Required | -| `unpkg.com` | Mintlify widget scripts | script-src | Required | -| `www.googletagmanager.com` | Google Analytics/GTM | script-src, connect-src | Optional | -| `cdn.segment.com` | Segment analytics | script-src, connect-src | Optional | -| `plausible.io` | Plausible analytics | script-src, connect-src | Optional | -| `tag.clearbitscripts.com` | Clearbit tracking | script-src | Optional | -| `cdn.heapanalytics.com` | Heap analytics | script-src | Optional | -| `chat.cdn-plain.com` | Plain chat widget | script-src | Optional | -| `chat-assets.frontapp.com` | Front chat widget | script-src | Optional | - -Without proper CSP configuration, users may experience broken styling, non-functional interactive elements, or security warnings in their browser console. +| `d4tuoctqmanu0.cloudfront.net` | KaTeX CSS, fonts | `style-src`, `font-src` | Required | +| `*.mintlify.dev` | Documentation content | `connect-src` | Required | +| `d3gk2c5xim1je2.cloudfront.net` | Icons, images, logos | `img-src` | Required | +| `unpkg.com` | Mintlify widget scripts | `script-src` | Required | +| `www.googletagmanager.com` | Google Analytics/GTM | `script-src`, `connect-src` | Optional | +| `cdn.segment.com` | Segment analytics | `script-src`, `connect-src` | Optional | +| `plausible.io` | Plausible analytics | `script-src`, `connect-src` | Optional | +| `tag.clearbitscripts.com` | Clearbit tracking | `script-src` | Optional | +| `cdn.heapanalytics.com` | Heap analytics | `script-src` | Optional | +| `chat.cdn-plain.com` | Plain chat widget | `script-src` | Optional | +| `chat-assets.frontapp.com` | Front chat widget | `script-src` | Optional | ## Example CSP configuration @@ -56,13 +56,7 @@ frame-src 'self' *.mintlify.dev; ## Common configurations by proxy type -Most reverse proxies support adding custom headers. Add this header to your proxy configuration: - -```apache -Header always set Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' unpkg.com; style-src 'self' 'unsafe-inline' -d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' -*.mintlify.dev; frame-src 'self' *.mintlify.dev;" -``` +Most reverse proxies support adding custom headers. ### Cloudflare configuration From b76ec6b9b4fe39f37118237886c3ca25ab111094 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 14:10:19 -0700 Subject: [PATCH 13/21] simplify troubleshooting --- guides/csp-configuration.mdx | 42 ++++-------------------------------- 1 file changed, 4 insertions(+), 38 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index d8300fe07..73e680402 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -42,7 +42,7 @@ The following CSP directives are used to control which resources can be loaded: Only include domains for services that you use. Remove any analytics domains that you have not configured for your documentation. -``` +```text wrap Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' unpkg.com http://www.googletagmanager.com cdn.segment.com plausible.io tag.clearbitscripts.com cdn.heapanalytics.com @@ -111,45 +111,11 @@ Add to your `vercel.json`: ## Troubleshooting -Identify CSP violations in browser console +Identify CSP violations in your browser console: -1. Open your browser's Developer Tools (F12) -2. Go to the **Console** tab +1. Open your browser's Developer Tools. +2. Go to the **Console** tab. 3. Look for errors starting with: - `Content Security Policy: The page's settings blocked the loading of a resource` - `Refused to load the script/stylesheet because it violates the following Content Security Policy directive` - `Refused to connect to because it violates the following Content Security Policy directive` - - - - **Error message:** - ``` - Refused to load the script 'https://unpkg.com/...' because it violates the following Content Security Policy directive: "script-src 'self'". - ``` - **Solution:** Add `unpkg.com` to your `script-src` directive. - - - - **Error message:** - ``` - Refused to load the stylesheet 'https://d4tuoctqmanu0.cloudfront.net/...' because it violates the following Content Security Policy directive: "style-src 'self'". - ``` - **Solution:** Add `d4tuoctqmanu0.cloudfront.net` to your `style-src` directive. - - - - **Error message:** - ``` - Refused to connect to 'https://api.mintlify.dev/...' because it violates the following Content Security Policy directive: "connect-src 'self'". - ``` - **Solution:** Add `*.mintlify.dev` to your `connect-src` directive. - - - - **Error message:** - ``` - Refused to load the image 'https://d3gk2c5xim1je2.cloudfront.net/...' because it violates the following Content Security Policy directive: "img-src 'self'". - ``` - **Solution:** Add `d3gk2c5xim1je2.cloudfront.net` to your `img-src` directive. - - From 42b6a038c8f9713326c124c74798cb491da6a4d4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 14:22:57 -0700 Subject: [PATCH 14/21] remove protocol --- guides/csp-configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 73e680402..38d431c82 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -45,7 +45,7 @@ The following CSP directives are used to control which resources can be loaded: ```text wrap Content-Security-Policy: default-src 'self'; -script-src 'self' 'unsafe-inline' unpkg.com http://www.googletagmanager.com cdn.segment.com plausible.io tag.clearbitscripts.com cdn.heapanalytics.com +script-src 'self' 'unsafe-inline' unpkg.com www.googletagmanager.com cdn.segment.com plausible.io tag.clearbitscripts.com cdn.heapanalytics.com chat.cdn-plain.com chat-assets.frontapp.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; From cc2044c6b77753299bdd9f48619d7b08b0432da1 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 14:23:07 -0700 Subject: [PATCH 15/21] remove protocol --- guides/csp-configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 38d431c82..e9bb52696 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -50,7 +50,7 @@ chat.cdn-plain.com chat-assets.frontapp.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; -connect-src 'self' *.mintlify.dev http://www.googletagmanager.com cdn.segment.com plausible.io; +connect-src 'self' *.mintlify.dev www.googletagmanager.com cdn.segment.com plausible.io; frame-src 'self' *.mintlify.dev; ``` From 6d7f497063c1f021a9591c9071bb116dff018169 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 14:24:40 -0700 Subject: [PATCH 16/21] add `'unsafe-eval'` --- guides/csp-configuration.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index e9bb52696..fd83a881d 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -45,7 +45,7 @@ The following CSP directives are used to control which resources can be loaded: ```text wrap Content-Security-Policy: default-src 'self'; -script-src 'self' 'unsafe-inline' unpkg.com www.googletagmanager.com cdn.segment.com plausible.io tag.clearbitscripts.com cdn.heapanalytics.com +script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com www.googletagmanager.com cdn.segment.com plausible.io tag.clearbitscripts.com cdn.heapanalytics.com chat.cdn-plain.com chat-assets.frontapp.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; @@ -67,7 +67,7 @@ In your Cloudflare dashboard: 3. Add HTTP Response Header: - **Operation**: Set static - **Header name**: `Content-Security-Policy` - - **Value**: `default-src 'self'; script-src 'self' 'unsafe-inline' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;` + - **Value**: `default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;` ### AWS CloudFront configuration @@ -80,7 +80,7 @@ Add a response headers policy in CloudFront: "Config": { "SecurityHeadersConfig": { "ContentSecurityPolicy": { - "ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;", + "ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;", "Override": true } } @@ -101,7 +101,7 @@ Add to your `vercel.json`: "headers": [ { "key": "Content-Security-Policy", - "value": "default-src 'self'; script-src 'self' 'unsafe-inline' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;" + "value": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;" } ] } From 3110072c10ba47bee0386b258d061dfdd2ce150a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 8 Sep 2025 14:28:33 -0700 Subject: [PATCH 17/21] add blob in img-src --- guides/csp-configuration.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index fd83a881d..47756cfe5 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -49,7 +49,7 @@ script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com www.googletagmanager.c chat.cdn-plain.com chat-assets.frontapp.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; -img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; +img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev www.googletagmanager.com cdn.segment.com plausible.io; frame-src 'self' *.mintlify.dev; ``` @@ -67,7 +67,7 @@ In your Cloudflare dashboard: 3. Add HTTP Response Header: - **Operation**: Set static - **Header name**: `Content-Security-Policy` - - **Value**: `default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;` + - **Value**: `default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;` ### AWS CloudFront configuration @@ -80,7 +80,7 @@ Add a response headers policy in CloudFront: "Config": { "SecurityHeadersConfig": { "ContentSecurityPolicy": { - "ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;", + "ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;", "Override": true } } @@ -101,7 +101,7 @@ Add to your `vercel.json`: "headers": [ { "key": "Content-Security-Policy", - "value": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;" + "value": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;" } ] } From 3b8810bed14048c42324e69cb0ebe242cc22eaf7 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 11 Sep 2025 09:43:14 -0700 Subject: [PATCH 18/21] make it more clear this is an edge case --- guides/csp-configuration.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 47756cfe5..c9f9eec2a 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -4,9 +4,7 @@ sidebarTitle: "CSP configuration" description: "Domain whitelist and header configurations for reverse proxies, firewalls, and networks that enforce strict security policies." --- -Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. If you host your documentation behind a reverse proxy or firewall, you may need to configure CSP headers for features to function properly. - -Without proper CSP configuration, users may experience broken styling, non-functional interactive elements, or security warnings in their browser console. +Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. Mintlify serves a default CSP that protects most sites. If you host your documentation behind a reverse proxy or firewall, that overwrites the default CSP, you may need to configure CSP headers for features to function properly. ## CSP directives From 0992263cffda74f62cfcc9ba28b34c49f0981591 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 11 Sep 2025 09:51:01 -0700 Subject: [PATCH 19/21] style --- guides/csp-configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index c9f9eec2a..40c3e1f6f 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -1,7 +1,7 @@ --- title: "Content Security Policy (CSP) configuration" sidebarTitle: "CSP configuration" -description: "Domain whitelist and header configurations for reverse proxies, firewalls, and networks that enforce strict security policies." +description: "Domain whitelist and header configurations for reverse proxies, firewalls, and networks that enforce strict security policies" --- Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. Mintlify serves a default CSP that protects most sites. If you host your documentation behind a reverse proxy or firewall, that overwrites the default CSP, you may need to configure CSP headers for features to function properly. From f1b7db310abdc64c7eb6b39c5bd79bdb34c52fc0 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 11 Sep 2025 10:04:21 -0700 Subject: [PATCH 20/21] update Cloudflare steps --- guides/csp-configuration.mdx | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 40c3e1f6f..2f6df56ae 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -58,14 +58,18 @@ Most reverse proxies support adding custom headers. ### Cloudflare configuration -In your Cloudflare dashboard: +Create a Response Header Transform Rule: -1. Go to **Security** > **Transform Rules** > **Modify Response Header**. -2. Create a new rule for your documentation domain. -3. Add HTTP Response Header: - - **Operation**: Set static +1. In your Cloudflare dashboard, go to **Rules > Overview**. +2. Select **Create rule > Response Header Transform Rule**. +3. Configure the rule: + - **Modify response header**: Set static - **Header name**: `Content-Security-Policy` - - **Value**: `default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;` + - **Header value**: + ```text wrap + default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev; + ``` +4. Deploy your rule. ### AWS CloudFront configuration From 65c2e260ba347a094469f92f90cdb9583b908dae Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 11 Sep 2025 11:20:19 -0700 Subject: [PATCH 21/21] remove deprecated widget --- guides/csp-configuration.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/guides/csp-configuration.mdx b/guides/csp-configuration.mdx index 2f6df56ae..5f4527f1a 100644 --- a/guides/csp-configuration.mdx +++ b/guides/csp-configuration.mdx @@ -25,7 +25,6 @@ The following CSP directives are used to control which resources can be loaded: | `d4tuoctqmanu0.cloudfront.net` | KaTeX CSS, fonts | `style-src`, `font-src` | Required | | `*.mintlify.dev` | Documentation content | `connect-src` | Required | | `d3gk2c5xim1je2.cloudfront.net` | Icons, images, logos | `img-src` | Required | -| `unpkg.com` | Mintlify widget scripts | `script-src` | Required | | `www.googletagmanager.com` | Google Analytics/GTM | `script-src`, `connect-src` | Optional | | `cdn.segment.com` | Segment analytics | `script-src`, `connect-src` | Optional | | `plausible.io` | Plausible analytics | `script-src`, `connect-src` | Optional | @@ -43,7 +42,7 @@ The following CSP directives are used to control which resources can be loaded: ```text wrap Content-Security-Policy: default-src 'self'; -script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com www.googletagmanager.com cdn.segment.com plausible.io tag.clearbitscripts.com cdn.heapanalytics.com +script-src 'self' 'unsafe-inline' 'unsafe-eval' www.googletagmanager.com cdn.segment.com plausible.io tag.clearbitscripts.com cdn.heapanalytics.com chat.cdn-plain.com chat-assets.frontapp.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; @@ -67,7 +66,7 @@ Create a Response Header Transform Rule: - **Header name**: `Content-Security-Policy` - **Header value**: ```text wrap - default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev; + default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev; ``` 4. Deploy your rule. @@ -82,7 +81,7 @@ Add a response headers policy in CloudFront: "Config": { "SecurityHeadersConfig": { "ContentSecurityPolicy": { - "ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;", + "ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;", "Override": true } } @@ -103,7 +102,7 @@ Add to your `vercel.json`: "headers": [ { "key": "Content-Security-Policy", - "value": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' unpkg.com; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;" + "value": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;" } ] }