[JENKINS-76263] Add documentation for CSP in core, adapt existing docs

content/doc/book/managing/system-properties.adoc

@@ -1893,6 +1893,31 @@ properties:
     Setting this to `true` is unsafe.
     See link:/redirect/class-filter/[documentation].
 
+- name: jenkins.security.csp.CspHeader.headerName
+  tags:
+  - escape hatch
+  - security
+  def: |
+    `Content-Security-Policy`
+  since: 2.TODO
+  description: |
+    Defines the name of the Content Security Policy header.
+    The only possible value other than the default is `Content-Security-Policy-Report-Only`.
+    Choosing that value will disable enforcement of Content Security Policy.
+    See link:/doc/book/security/csp/[the documentation].
+
+- name: jenkins.security.csp.impl.DevelopmentHeaderDecider.DISABLED
+  tags:
+  - escape hatch
+  - security
+  def: |
+    `false`
+  since: 2.TODO
+  description: |
+    Disables the enforcement of Content Security Policy during development and testing.
+    If this is set to `true` (and `jenkins.security.csp.CspHeader.headerName` is not set), Jenkins will allow configuring CSP through the UI even in development mode.
+    See link:/doc/book/security/csp/[the documentation].
+
 - name: jenkins.security.DefaultConfidentialStore.file
   tags:
   - feature
@@ -1989,7 +2014,7 @@ properties:
     `false`
   since: 2.475
   description: |
-    Allow authenticated user access to link:/doc/book/security/user-content/#resource-root-url[Resource URLs].
+    Allow authenticated user access to link:/redirect/resource-root-url[Resource URLs].
     Escape hatch for a security improvement related to the link:/security/advisory/2024-01-24/#SECURITY-3314[2024-01-24 security advisory].
 
 - name: jenkins.security.ResourceDomainRootAction.validForMinutes

content/doc/book/security/_chapter.yml

@@ -12,6 +12,7 @@ sections:
 - controller-isolation
 - securing-builds
 - csrf-protection
+- csp
 - user-content
 - build-authorization
 - environment-variables

content/doc/book/security/configuring-content-security-policy.adoc

@@ -1,11 +1,14 @@
 ---
-title: Configuring Content Security Policy
+title: Configuring Content Security Policy for user content
 layout: documentation
 ---
 ifdef::backend-html5[]
 :toc: left
 endif::[]
 
+IMPORTANT: This page discusses customization of Content Security for serving user generated files, like files in workspaces, archived artifacts, or file parameters.
+See link:/doc/book/security/csp/[Content Security Policy] for documentation on Content Security Policy for the Jenkins UI in general.
+
 This page describes the restrictions applied by potentially untrusted files served by Jenkins by default and how to customize them.
 
 == The Default Rule Set
@@ -42,7 +45,7 @@ See https://content-security-policy.com/[content-security-policy.com] for a refe
 
 == Customizing Content Security Policy
 
-IMPORTANT: It is strongly recommended to set up the link:../user-content/#resource-root-url[Resource Root URL] instead of customizing Content-Security-Policy.
+IMPORTANT: It is strongly recommended to set up the link:/redirect/resource-root-url[Resource Root URL] instead of customizing Content-Security-Policy.
 Most of the documentation below was written when `Content-Security-Policy` was first introduced and is retained for use by administrators unable to set up Jenkins to serve user content from a different domain.
 
 === Considerations

content/doc/book/security/csp.adoc

@@ -0,0 +1,107 @@
+---
+title: Content Security Policy
+layout: documentation
+---
+ifdef::backend-html5[]
+:toc: left
+endif::[]
+
+This page describes the restrictions applied to the general Jenkins UI since Jenkins 2.TODO.
+
+NOTE: This page discusses configuration and customization of Content Security Policy for the general Jenkins UI.
+See link:/doc/book/security/configuring-content-security-policy/[Content Security Policy] for documentation on Content Security Policy for user generated files, like files in workspaces, archived artifacts, or file parameters, on controllers not using the link:/redirect/resource-root-url[Resource Root URL] feature.
+
+== Motivation
+
+From https://content-security-policy.com/[content-security-policy.com]:
+
+> _Content-Security-Policy_ is the name of a HTTP response header that modern browsers use to enhance the security of the document (or web page). The Content-Security-Policy header allows you to restrict which resources (such as JavaScript, CSS, Images, etc.) can be loaded, and the URLs that they can be loaded from.
+
+Content Security Policy (CSP) is a standard implemented in all modern web browsers.
+It allows web sites to restrict features and functionality that can be used on web pages.
+Using CSP, the impact of web vulnerabilities like link:/security/vulnerabilities/#xss[cross-site scripting (XSS)] is largely, or entirely, mitigated.
+
+== Getting started
+
+Jenkins includes a default Content Security Policy that is applied to all pages in the Jenkins UI.
+By default, enforcement is disabled, but administrators can enable it to protect their Jenkins instance.
+Jenkins collects reports of violations encountered by users' browsers even while enforcement is disabled, allowing administrators to identify incompatible plugins and configurations.
+
+See the section _Identifying incompatibility in your setup_ below for instructions on how to view these reports.
+
+== Setup
+
+=== Using the UI
+
+Among the more than 2000 Jenkins plugins distributed by the Jenkins project, many use features that are prohibited by the default CSP rule set.
+As a result, the UI provided by these plugins would break.
+
+To give plugin maintainers time to adapt their plugins, and Jenkins administrators time to migrate away from unmaintained, incompatible plugins, Content Security Policy protection is disabled by default as of Jenkins 2.TODO.
+
+To enable CSP in Jenkins, navigate to _Manage Jenkins » Security_, and look for the section _Content Security Policy_.
+By default, it links to a separate page explaining why this functionality is disabled by default.
+On that page, select _Set up Content-Security-Policy_.
+Back on _Manage Jenkins » Security_, select the checkbox labeled _Enforce Content Security Policy_ and save the configuration.
+
+NOTE: In certain environments, this configuration will not be available.
+This includes controllers whose CSP enforcement is controlled by the Java system property link:/doc/book/managing/system-properties/#jenkins-security-csp-cspheader-headername[`jenkins.security.csp.CspHeader.headerName`], as well as during Jenkins core and plugin development.
+See below for more information how to control CSP in those environments.
+
+IMPORTANT: Jenkins serves user-generated content from the same domain by default.
+The link:/doc/book/security/configuring-content-security-policy/[Content Security Policy for user generated files, like files in workspaces and archived artifacts] does not prevent attackers able to define these files from using them as part of an XSS vulnerability on the classic Jenkins UI.
+Set up a link:/redirect/resource-root-url[Resource Root URL] for more complete protection.
+
+=== Using Configuration as Code
+
+The following YAML snippet sets up Content Security Policy enforcement.
+
+```yaml
+security:
+  contentSecurityPolicy:
+    enforce: true
+```
+
+More advanced options are contributed by plugin:csp[Content Security Policy Plugin] 2.x.
+
+=== Using a Java system property
+
+You can set the Java system property link:/doc/book/managing/system-properties/#jenkins-security-csp-cspheader-headername[`jenkins.security.csp.CspHeader.headerName`] to enforce Content Security Policy.
+This prevents configuration through the UI.
+
+* The value `Content-Security-Policy` will enforce CSP and prevent administrators from configuring it.
+* The value `Content-Security-Policy-Report-Only` will disable enforcement, as well as prevent administrators from configuring CSP.
+
+All other values will be treated as if the Java system property is undefined.
+
+=== During development
+
+During development, Content Security Policy is always enabled by default, and cannot be disabled through the UI.
+To disable enforcement during development, set the Java system property `jenkins.security.csp.impl.DevelopmentHeaderDecider.DISABLED` to `true`.
+You can also run the script `jenkins.security.csp.impl.DevelopmentHeaderDecider.DISABLED = true` in the link:/doc/book/managing/script-console/[Script Console].
+
+== Advanced configuration
+
+Jenkins does not include advanced configuration.
+To customize the behavior of CSP beyond toggling it on and off, install plugin:csp[Content Security Policy Plugin].
+
+== Compatibility
+// Linked to by /redirect/csp-compatibility
+
+=== Known compatible and incompatible plugins
+
+Plugin compatibility is tracked in https://issues.jenkins.io/browse/JENKINS-60865[JENKINS-60865].
+https://docs.google.com/spreadsheets/d/1nSx4gQ2YUl-sKdY5u6biXmyDnkQ26wTaMBLSR8gr_-A[This spreadsheet] provides an assessment of their compatibility for most popular plugins.
+
+=== Identifying incompatibility in your setup
+
+Jenkins requests that browsers submit reports of any incompatibilities they encounter regardless of whether CSP enforcement is enabled or not.
+Administrators can view them in two different ways:
+
+* Set up a log recorder for the logger `jenkins.security.csp.impl.LoggingReceiver` on `FINE` (for reports by authenticated users) or `FINEST` (for reports by all users).
+* Install plugin:csp[Content Security Policy Plugin] and navigate to _Manage Jenkins » Content Security Policy Report_, which provides an overview of reports received by Jenkins.
+
+=== Reporting incompatible plugins
+
+Please report problems with CSP compatibility encountered in the latest versions of Jenkins and plugins to the affected component's issue tracker.
+
+NOTE: It may be difficult to identify the responsible component, e.g., when there's a view provided by one plugin, with additions by another plugin (e.g., `cloudbees-folder` configuration forms for multibranch pipelines hosting components from many other plugins, like `workflow-cps` or `branch-api`).

content/doc/book/security/index.adoc

@@ -24,7 +24,7 @@ This chapter will introduce the various security options available to Jenkins ad
 link:controller-isolation[Controller Isolation]::
 Builds should not be executed on the built-in node, but that is just the beginning:
 This section discusses what other steps can be taken to protect the controller from being impacted by running builds. +
-*This needs to be configured according to the needs of your environment.*
+*This must be configured according to the needs of your environment.*
 
 link:access-control[Access Control]::
 By default, Jenkins does not allow anonymous access, and a single admin user exists.
@@ -36,16 +36,16 @@ _This is set up securely by the setup wizard. If the setup wizard is disabled on
 
 link:build-authorization[Access Control for Builds]::
 Learn how to restrict what individual builds can do in Jenkins once they're running. +
-*This needs to be configured according to the needs of your environment.*
+*This must be configured according to the needs of your environment.*
 
 link:securing-builds[Securing Builds]::
 Learn about how builds can interfere with each other and your infrastructure, and what to do about it. +
-*This needs to be configured according to the needs of your environment.*
+*This must be configured according to the needs of your environment.*
 
 link:environment-variables[Handling Environment Variables]::
 Improperly written build scripts may be tricked into behaving differently than intended due to special environment variable names or values being injected as build parameters.
 This section discusses how to protect your builds. +
-*This needs to be configured according to the needs of your environment.*
+*This must be configured according to the needs of your environment.*
 
 link:securing-org-folders-and-multibranch-pipelines[Securing Organization Folder and Multibranch Pipeline Credentials]::
 Learn about how credentials for Organization Folder and Multibranch Pipeline Credentials may be accessible to unprivileged users in ways you did not anticipate, and what to do about it. +
@@ -59,6 +59,12 @@ This chapter explains how to work around any problems this may cause. +
 _This is set up securely by default._
 // TODO Confirm that skipping the setup wizard in 2.222 does no longer disable CSRF protection
 
+link:csp[Content Security Policy]::
+Jenkins 2.TODO and newer allows administrators to set up Content Security Policy protection.
+This chapter explains how to set it up, how to customize it, and how to identify potential problems. +
+*This must be configured according to the needs of your environment.*
+// TODO Remove version number once it's been in 1-2 LTS lines
+
 link:markup-formatter[Markup Formatter]::
 The default markup formatter renders text as entered (i.e. escaping HTML metacharacters).
 This chapter explains how to switch to a different markup formatter and explains what admins need to be aware of. +

content/doc/developer/security/csp.adoc

@@ -7,16 +7,12 @@ layout: developer
 
 From https://content-security-policy.com/[content-security-policy.com]:
 
-> _Content-Security-Policy_ is the name of a HTTP response header that modern browsers use to enhance the security of the document (or web page). The Content-Security-Policy header allows you to restrict how resources such as JavaScript, CSS, or pretty much anything that the browser loads.
+> _Content-Security-Policy_ is the name of a HTTP response header that modern browsers use to enhance the security of the document (or web page). The Content-Security-Policy header allows you to restrict which resources (such as JavaScript, CSS, Images, etc.) can be loaded, and the URLs that they can be loaded from.
 
-Using Content-Security-Policy (CSP), injection attacks like cross-site scripting can be prevented.
+Using Content-Security-Policy (CSP), injection attacks like link:/security/vulnerabilities/#xss[cross-site scripting (XSS)] can be prevented.
 
-// TODO Keep up to date with versions
-Unfortunately, as of Jenkins 2.372, the Jenkins classic UI is not yet compatible with the CSP directives that would allow preventing such injection attacks.
-
-This guide documents how to identify components that will be incompatible with CSP rules and how to write and adapt UI code in a manner that is expected to be compatible with future use of CSP directives on the Jenkins UI.
-
-NOTE: Most of this page focuses on problems caused by the `script-src` CSP directive as that is the most common issue across Jenkins plugins and non-compliant code is most likely to result in link:/blog/2020/07/15/xss-severity/[severe vulnerabilities].
+As of 2025, the Jenkins (core) UI is compatible with the CSP directives that would allow preventing such injection attacks, but many plugins are not.
+This guide documents how to identify components that will be incompatible with CSP rules and how to write and adapt UI code in a manner that is compatible with Jenkins enforcing CSP protections on its UI.
 
 
 == Statically Identifying Affected Code and Plugins
@@ -40,15 +36,23 @@ Check for the use of `eval` inside any JS resource files (potentially after appl
 This will break without `'unsafe-eval'` in the `script-src` CSP directive.
 Use of `FormApply#applyResponse`::
 This method expects as the argument a JavaScript snippet to be executed.
+Resources loaded from other domains::
+Any images, scripts, styles, etc. loaded from other domains cause problems.
+Resources should be hosted by Jenkins.
 
 
 == Dynamically Identifying Plugins
 
 When running Jenkins, you can use the following techniques to identify broken features and the component that defines them:
 
-=== Content Security Policy Plugin
+=== Built-in CSP protection in Jenkins 2.TODO+
+
+Running Jenkins 2.TODO or newer in development mode (e.g., `mvn hpi:run`) will have Content Security Policy protections enabled by default.
+link:/doc/book/security/csp/[Learn more.]
+
+=== Content Security Policy Plugin 1.x
 
-link:https://plugins.jenkins.io/csp/[Content Security Policy Plugin] lets you define a Content-Security-Policy that gets applied to the Jenkins web UI.
+In Jenkins before version 2.TODO, link:https://plugins.jenkins.io/csp/[Content Security Policy Plugin] (1.x) lets you define a Content-Security-Policy that gets applied to the Jenkins web UI.
 It can operate both as enforcing and to only gather reports.
 Both modes can be useful with identifying broken functionality.
 
@@ -57,16 +61,13 @@ When set to only report issues but not enforce, the UI can be used as usual whil
 Afterwards, the reported violations can be reviewed and affected functionality identified this way.
 Navigate to _Manage Jenkins » Content-Security-Policy Report_ and review the violations there.
 
-NOTE: As of Jenkins 2.372, functionality violating the plugin's default rule set is readily available in Jenkins, even without considering plugins, so the list should very rarely be empty.
-If the list of violations remains empty after navigating several pages of the Jenkins UI, review your browser's console for errors related to reporting CSP violations.
+NOTE: Make sure to review your browser's console for errors related to reporting CSP violations if you experience problems on the UI, but the report is empty.
 For example, some browser extensions will disable CSP reporting.
 
 ==== Enforcing
 
 When set to enforce the rules, the UI will more readily break if functionality being accessed is impacted by the rules.
 
-NOTE: As of Jenkins 2.372, functionality violating the plugin's default rule set is readily available in Jenkins, even without considering plugins; so enforcing rules like `script-src` that do not allow `'unsafe-inline' 'unsafe-eval'` is expected to result in problems.
-
 === Enabling Jelly tracing
 
 Run the following script in the script console:
@@ -189,10 +190,31 @@ window[callbackName](args);
 
 Use `FormApply#showNotification`, which was added in Jenkins 2.482.
 
+=== Resources loaded from other domains
+
+Move images, scripts, and styles into the resources of your plugin.
+This will also make Jenkins work better in environments without, or only limited, internet connectivity.
+
+Any dynamically determined images (e.g., "avatar" images based on user configuration, like GitHub orgs or user avatars based on the configured security realm) can be handled in the following ways:
+
+* Have Jenkins request (and possibly cache) these images, serving them through a local URL.
+  Be careful to not allow parameterization of the URL serving this image such that it accepts arbitrary parameter values, resulting in arbitrary URLs being proxied.
+* For compatibility with Content Security Policy in Jenkins 2.TODO and newer, implement `jenkins.security.csp.Contributor` (or `jenkins.security.csp.SimpleContributor` in simple cases).
+  This will allow Jenkins users' browsers to load images from a known safe domain.
+  In this case, make sure that only administrators can ultimately configure the domains that images can be loaded from.
+  For example, regular Jenkins users should not be able to, e.g., edit their user profile or configure a job in a certain way to allow a domain of their choice.
+
 == Testing
 
-link:https://plugins.jenkins.io/csp/[Content Security Policy Plugin] lets you define a Content-Security-Policy that gets applied to the Jenkins web UI.
+=== In Jenkins 2.TODO and newer
+
+Jenkins 2.TODO and newer supports Content Security Policy out of the box.
+See the link:/doc/book/security/csp/[documentation] for information how to set it up.
+
+NOTE: Running Jenkins in development mode will by default enforce Content Security Policy, so plugin maintainers will likely encounter incompatibilities in their own testing.
+
+=== In older releases of Jenkins
+
+link:https://plugins.jenkins.io/csp/[Content Security Policy Plugin] (1.x) lets you define a Content-Security-Policy that gets applied to the Jenkins web UI.
 It can operate both as enforcing and to only gather reports.
 Both modes can be useful with identifying broken functionality.
-
-NOTE: As of Jenkins 2.372, functionality violating the plugin's default rule set is readily available in Jenkins, even without considering plugins; so enforcing rules like `script-src` that do not allow `'unsafe-inline' 'unsafe-eval'` is expected to result in problems with basic Jenkins UI use.

content/redirect/csp-compatibility.adoc

@@ -0,0 +1,4 @@
+---
+layout: redirect
+redirect_url: /doc/book/security/csp/#compatibility
+---

content/redirect/resource-root-url.adoc

@@ -0,0 +1,4 @@
+---
+layout: redirect
+redirect_url: /doc/book/security/user-content/#resource-root-url
+---