From fe478ea1ab09244acdbd8bf06fca9c73369cad01 Mon Sep 17 00:00:00 2001 From: Shelley Nason Date: Wed, 6 May 2026 17:52:25 -0400 Subject: [PATCH 1/2] Update CSP instructions in README. --- README.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 7c2e202..844bf71 100644 --- a/README.md +++ b/README.md @@ -74,13 +74,22 @@ Together, HTTPS and HSTS offer a strong, necessary level of transport security a #### Content Security Policy -A Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks to your website, including Cross-Site Scripting (XSS) and data injection attacks. In order to incorporate the DAP JS into your site which includes a Content Security Policy, add the DAP domain and necessary Google domains to your allowed script sources. Also add the Google Analytics domain to your allowed connect sources. Example follows: +A Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks to your website, including Cross-Site Scripting (XSS) and data injection attacks. If your site has a CSP, you will need to relax it slightly to allow the DAP code to load and function properly. -``` -Content-Security-Policy: script-src https://dap.digitalgov.gov https://www.google-analytics.com https://www.googletagmanager.com; connect-src https://www.google-analytics.com; -``` +If you are loading the centrally-hosted DAP script with the default configuration, you will need to add the following directives to your CSP: + +|Directive|Content| Justification | +|-|-|----------------------------------------------------------------------------------------------------------------------| +|`script-src`|`https://dap.digitalgov.gov https://www.googletagmanager.com`| The DAP script is served from `dap.digitalgov.gov` and it loads the GA4 tag library from `www.googletagmanager.com`. | +|`connect-src`|`https://www.google-analytics.com`| The GA4 tag connects to `www.google-analytics.com` to send analytics data from your site to Google Analytics. | + +If you are self-hosting the DAP code, then you can leave off the `dap.digitalgov.gov` domain from the `script-src` directive. Note that the DAP code attempts to load an additional third-party script from our https://dap.digitalgov.gov server and +it will fail to load if you don't include our server in your CSP. This additional, optional script is for tracking [Core Web Vitals](https://web.dev/articles/vitals#core_web_vitals) and DAP will work fine without it. + +If you have configured YouTube tracking (with the `yt` query parameter set to `true`), you will also need to add `https://www.youtube.com` to your `script-src` directive, because DAP uses the [YouTube Iframe API](https://www.youtube.com/iframe_api) to track interaction with YouTube videos. -This whitelists the DAP domain and necessary Google domains as trusted sources for JavaScript downloads to your site. In order to make your CSP as restrictive and secure as possible, use `script-src` rather than `default-src` to only permit JavaScript to be included from these domains and no other file types. The `connect-src` directive allows the DAP JavaScript code to connect to the Google Analytics domain in order to send analytics data from your site to Google Analytics. +Note that Google [documentation](https://developers.google.com/tag-platform/security/guides/csp#google_analytics_4_google_analytics) claims that additional directives are needed for the GA4 tag, but the DAP team has not found that to be the case. This is the CSP that we use on https://analytics.usa.gov/, as an example. +If your team encounters any situation where the additional directives seem to be necessary, we'd love to hear about it at [dap@gsa.gov](mailto:dap@gsa.gov). #### Data integrity From 413e37f39a297b8ff3cb286b93eb876880f70ed7 Mon Sep 17 00:00:00 2001 From: Shelley Nason Date: Thu, 7 May 2026 16:20:13 -0400 Subject: [PATCH 2/2] Further updates to README --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 844bf71..446b3b8 100644 --- a/README.md +++ b/README.md @@ -74,21 +74,21 @@ Together, HTTPS and HSTS offer a strong, necessary level of transport security a #### Content Security Policy -A Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks to your website, including Cross-Site Scripting (XSS) and data injection attacks. If your site has a CSP, you will need to relax it slightly to allow the DAP code to load and function properly. +A [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks to your website, including Cross-Site Scripting (XSS) and data injection attacks. If your site has a CSP, you will need to relax it slightly to allow the DAP code to load and function properly. If you are loading the centrally-hosted DAP script with the default configuration, you will need to add the following directives to your CSP: |Directive|Content| Justification | |-|-|----------------------------------------------------------------------------------------------------------------------| -|`script-src`|`https://dap.digitalgov.gov https://www.googletagmanager.com`| The DAP script is served from `dap.digitalgov.gov` and it loads the GA4 tag library from `www.googletagmanager.com`. | -|`connect-src`|`https://www.google-analytics.com`| The GA4 tag connects to `www.google-analytics.com` to send analytics data from your site to Google Analytics. | +|script-src|https://dap.digitalgov.gov https://www.googletagmanager.com| The DAP script is served from `dap.digitalgov.gov` and it loads the GA4 tag library from `www.googletagmanager.com`. | +|connect-src|https://www.google-analytics.com| The GA4 tag connects to `www.google-analytics.com` to send analytics data from your site to Google Analytics. | If you are self-hosting the DAP code, then you can leave off the `dap.digitalgov.gov` domain from the `script-src` directive. Note that the DAP code attempts to load an additional third-party script from our https://dap.digitalgov.gov server and -it will fail to load if you don't include our server in your CSP. This additional, optional script is for tracking [Core Web Vitals](https://web.dev/articles/vitals#core_web_vitals) and DAP will work fine without it. +it will fail to load if you don't include our server in your CSP. This additional, optional script is for tracking [Core Web Vitals](https://web.dev/articles/vitals#core_web_vitals) and DAP will work without it. If you have configured YouTube tracking (with the `yt` query parameter set to `true`), you will also need to add `https://www.youtube.com` to your `script-src` directive, because DAP uses the [YouTube Iframe API](https://www.youtube.com/iframe_api) to track interaction with YouTube videos. -Note that Google [documentation](https://developers.google.com/tag-platform/security/guides/csp#google_analytics_4_google_analytics) claims that additional directives are needed for the GA4 tag, but the DAP team has not found that to be the case. This is the CSP that we use on https://analytics.usa.gov/, as an example. +Note that Google [documentation](https://developers.google.com/tag-platform/security/guides/csp#google_analytics_4_google_analytics) claims that additional directives are needed for the GA4 tag, but the DAP team has not found that to be the case. What we've described here is what we use on https://analytics.usa.gov/, as an example. If your team encounters any situation where the additional directives seem to be necessary, we'd love to hear about it at [dap@gsa.gov](mailto:dap@gsa.gov). #### Data integrity