[TASK] Allow site-specific Content-Security-Policy endpoints (#5334)

* [TASK] Allow site-specific Content-Security-Policy endpoints Resolves: TYPO3-Documentation/Changelog-To-Doc#1198 Releases: main, 13.4, 12.4 * Apply suggestions from code review --------- Co-authored-by: Stefan Frömken <[email protected]>
TYPO3-Documentation · Feb 13, 2025 · 22b8432 · 22b8432
1 parent fd0a44d
commit 22b8432
Show file tree

Hide file tree

Showing 5 changed files with 105 additions and 3 deletions.
diff --git a/Documentation/ApiOverview/ContentSecurityPolicy/Index.rst b/Documentation/ApiOverview/ContentSecurityPolicy/Index.rst
@@ -135,6 +135,42 @@ The Content Security Policy for a particular site can be disabled with the
     :caption: config/sites/<my_site>/csp.yaml | typo3conf/sites/<my_site>/csp.yaml
 
 
+..  _content-security-policy-site-endpoints:
+
+Site-specific Content-Security-Policy endpoints
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The disposition-specific property `reportingUrl` can either be:
+
+`true`
+    to enable the reporting endpoint
+`false`
+    to disable the reporting endpoint
+(string)
+    to use the given value as external reporting endpoint
+
+If defined, the site-specific configuration takes precedence over
+the global configuration :ref:`contentSecurityPolicyReportingUrl <content-security-policy-reporting-contentSecurityPolicyReportingUrl>`.
+
+In case the explicitly disabled endpoint still would be called, the
+server-side process responds with a 403 HTTP error message.
+
+..  _content-security-policy-site-endpoints-disable:
+
+Example: Disabling the reporting endpoint
+"""""""""""""""""""""""""""""""""""""""""
+
+..  literalinclude:: _csp_reporting_false.yaml
+    :caption: config/sites/<my-site>/csp.yaml | typo3conf/sites/<my_site>/csp.yaml
+
+..  _content-security-policy-site-endpoints-custom:
+
+Example: Using custom external reporting endpoint
+"""""""""""""""""""""""""""""""""""""""""""""""""
+
+..  literalinclude:: _csp_reporting_custom.yaml
+    :caption: config/sites/<my-site>/csp.yaml | typo3conf/sites/<my_site>/csp.yaml
+
 ..  _content-security-policy-modes:
 
 Modes
@@ -459,6 +495,7 @@ apply this suggestion, or to mute or delete the specific violation.
     :ref:`site-specific <content-security-policy-site>` CSP definitions
     manually.
 
+..  _content-security-policy-reporting-contentSecurityPolicyReportingUrl:
 
 Using a third-party service
 ---------------------------
@@ -467,6 +504,7 @@ As an alternative, the reporting URL can be configured to use a third-party
 service as well:
 
 ..  code-block:: php
+    :caption: config/system/additional.php
 
     // For backend
     $GLOBALS['TYPO3_CONF_VARS']['BE']['contentSecurityPolicyReportingUrl']
@@ -479,6 +517,31 @@ service as well:
 Violations are then sent to the third-party service instead of the TYPO3
 endpoint.
 
+..  _content-security-policy-reporting-disable:
+
+Disabling content security policy reporting globally
+----------------------------------------------------
+
+Administrators can disable the reporting endpoint globally or configure it per
+site as needed. (See :ref:`content-security-policy-site-endpoints-disable`).
+
+If defined, the site-specific configuration takes precedence over
+the global configuration.
+
+In case the explicitly disabled endpoint still would be called, the
+server-side process responds with a 403 HTTP error message.
+
+The global scope-specific setting `contentSecurityPolicyReportingUrl` can
+be set to zero ('0') to disable the CSP reporting endpoint:
+
+..  code-block:: php
+    :caption: config/system/additional.php
+
+    // For backend
+    $GLOBALS['TYPO3_CONF_VARS']['BE']['contentSecurityPolicyReportingUrl'] = '0';
+
+    // For frontend
+    $GLOBALS['TYPO3_CONF_VARS']['FE']['contentSecurityPolicyReportingUrl'] = '0';
 
 ..  _content-security-policy-events:
 

diff --git a/Documentation/ApiOverview/ContentSecurityPolicy/_csp_reporting_custom.yaml b/Documentation/ApiOverview/ContentSecurityPolicy/_csp_reporting_custom.yaml
@@ -0,0 +1,4 @@
+enforce:
+  inheritDefault: true
+  mutations: {}
+  reportingUrl: https://example.org/csp-report
diff --git a/Documentation/ApiOverview/ContentSecurityPolicy/_csp_reporting_false.yaml b/Documentation/ApiOverview/ContentSecurityPolicy/_csp_reporting_false.yaml
@@ -0,0 +1,4 @@
+enforce:
+  inheritDefault: true
+  mutations: {}
+  reportingUrl: false
diff --git a/Documentation/Configuration/Typo3ConfVars/BE.rst b/Documentation/Configuration/Typo3ConfVars/BE.rst
@@ -754,13 +754,29 @@ the TYPO3 backend:
     :ref:`Content Security Policy <content-security-policy>` violations in the
     backend; if it is empty, the TYPO3 endpoint will be used.
 
-    Example:
+    Setting this configuration to `'0'` disables Content Security Policy
+    reporting. If the endpoint is still called then, the
+    server-side process responds with a 403 HTTP error message.
+
+    If defined, the :ref:`site-specific configuration <content-security-policy-site-endpoints>`
+    in :file:`config/sites/my_site/csp.yaml` takes precedence over the global configuration.
 
     ..  code-block:: php
+        :caption: config/system/additional.php
 
+        // Set a custom endpoint for Content Security Policy reporting
         $GLOBALS['TYPO3_CONF_VARS']['BE']['contentSecurityPolicyReportingUrl']
             = 'https://csp-violation.example.org/';
 
+    ..  code-block:: php
+        :caption: config/system/additional.php
+
+        // Disables Content Security Policy reporting
+        $GLOBALS['TYPO3_CONF_VARS']['BE']['contentSecurityPolicyReportingUrl'] = '0';
+
+    Use :ref:`$GLOBALS['TYPO3_CONF_VARS']['FE']['contentSecurityPolicyReportingUrl'] <t3coreapi:confval-typo3-conf-vars-fe-contentsecuritypolicyreportingurl>`
+    to configure Content Security Policy reporting for the frontend.
+
 ..  _typo3ConfVars_be_entryPoint:
 
 ..  confval:: entryPoint

diff --git a/Documentation/Configuration/Typo3ConfVars/FE.rst b/Documentation/Configuration/Typo3ConfVars/FE.rst
@@ -725,7 +725,6 @@ the TYPO3 frontend:
 ..  _typo3ConfVars_fe_contentSecurityPolicyReportingUrl:
 
 ..  confval:: contentSecurityPolicyReportingUrl
-
     :Path: $GLOBALS['TYPO3_CONF_VARS']['FE']['contentSecurityPolicyReportingUrl']
     :name: typo3-conf-vars-fe-contentSecurityPolicyReportingUrl
     :type: string
@@ -735,9 +734,25 @@ the TYPO3 frontend:
     :ref:`Content Security Policy <content-security-policy>` violations in the
     frontend; if it is empty, the TYPO3 endpoint will be used.
 
-    Example:
+    Setting this configuration to `'0'` disables Content Security Policy
+    reporting. If the endpoint is still called then, the
+    server-side process responds with a 403 HTTP error message.
+
+    If defined, the :ref:`site-specific configuration <content-security-policy-site-endpoints>`
+    in :file:`config/sites/my_site/csp.yaml` takes precedence over the global configuration.
 
     ..  code-block:: php
+        :caption: config/system/additional.php
 
         $GLOBALS['TYPO3_CONF_VARS']['FE']['contentSecurityPolicyReportingUrl']
             = 'https://csp-violation.example.org/';
+
+    ..  code-block:: php
+        :caption: config/system/additional.php
+
+        // Disables Content Security Policy reporting
+        $GLOBALS['TYPO3_CONF_VARS']['BE']['contentSecurityPolicyReportingUrl'] = '0';
+
+
+    Use :ref:`$GLOBALS['TYPO3_CONF_VARS']['BE']['contentSecurityPolicyReportingUrl'] <t3coreapi:confval-globals-typo3-conf-vars-be-contentSecurityPolicyReportingUrl>`
+    to configure Content Security Policy reporting for the backend.