security:
contentSecurityPolicy:
enforce: trueThis page describes the restrictions that can be applied to the general Jenkins UI since Jenkins 2.539.
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 cross-site scripting (XSS) is largely, or entirely, mitigated.
| This page discusses configuration and customization of Content Security Policy for the general Jenkins UI. See 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 Resource Root URL feature. |
| Using Jenkins older than 2.539? Content Security Policy Plugin 1.x provides similar functionality. |
By default, CSP enforcement on Jenkins UI pages 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 incompatibilities in your setup below for instructions on how to view these reports.
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, CSP protection is disabled by default as of Jenkins 2.539.
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 now. Back on Manage Jenkins » Security, select the checkbox labeled Enforce Content Security Policy and save the configuration.
In certain environments, this configuration will not be available.
This includes controllers whose CSP enforcement is controlled by the Java system property jenkins.security.csp.CspHeader.headerName, as well as during Jenkins core and plugin development.
See below for more information how CSP enforcement is controlled in those environments.
|
| Jenkins serves user-generated content from the same domain by default. The 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 Resource Root URL for more complete protection. |
The following YAML snippet for Configuration as Code sets up CSP enforcement.
security:
contentSecurityPolicy:
enforce: trueYou can set the Java system property jenkins.security.csp.CspHeader.headerName to enforce CSP.
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.
Jenkins does not include advanced configuration out of the box. Additional options are available if Content Security Policy Plugin 2.x is installed. See that plugin’s documentation for more details.
Plugin compatibility is tracked in JENKINS-60865. This spreadsheet provides an assessment of their compatibility for most popular plugins.
This section highlights plugins that provide functionality that is inherently restricted by CSP. Individual plugins may implement workarounds or additional configuration options to mitigate these restrictions, but as of November 2025, some functionality in some configurations is affected. If you use these plugins, Content Security Policy Plugin 2.x can be used to customize the CSP directives enforced on a Jenkins controller for many of these cases.
This plugin allows build badges to include images from external URLs.
Administrators are advised to allow specific, known safe domains for the img-src directive.
This plugin allows administrators to specify image URLs for the Jenkins header. Administrators must ensure that the provided URLs are compatible with the CSP directives enforced on their Jenkins controller.
This plugin allows administrators to specify arbitrary snippets of HTML, CSS, and JavaScript to customize the login page. Administrators must ensure that the provided snippets are compatible with the CSP directives enforced on their Jenkins controller.
This plugin allows administrators to specify arbitrary URLs for JavaScript files to customize the Jenkins UI. Administrators must ensure that the provided URLs are compatible with the CSP directives enforced on their Jenkins controller.
Theme implementations may specify paths to CSS files outside of Jenkins, which is prohibited by CSP by default.
When using such a plugin, administrators must ensure that the provided URLs are compatible with the style-src directive enforced on their Jenkins controller.
This section highlight plugins that match all of the following criteria:
The plugin is installed on 5+% of Jenkins controllers.
The plugin is not marked as deprecated.
The plugin is not (fully) compatible with CSP as of November 2025.
This plugin is abandoned. Installations requiring this plugin cannot enforce CSP protection without breaking its functionality.
This plugin is looking for new maintainers. Installations requiring this plugin cannot enforce CSP protection without breaking its functionality.
The plugin does not periodically reload agent information in the "Agent statistics" portlet (#435).
Avatar images for organizations are not allowed (JENKINS-76302).
As a workaround, administrators can allow the domain avatars.githubusercontent.com for the img-src directive using Content Security Policy Plugin 2.x.
The user interface does not correctly update after selecting "Generate" or "Clear" for the "Secret token" (#1837).
Jenkins collects reports of violations encountered by users' browsers even while enforcement is disabled, allowing administrators to identify incompatible plugins and configurations. 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 Content Security Policy Plugin 2.x and navigate to Manage Jenkins » Content Security Policy Report, which provides an overview of reports received by Jenkins.
Please report problems with CSP compatibility encountered in the latest versions of Jenkins and plugins to the affected component’s issue tracker.
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).
|