Content Security Policy

This page describes the restrictions that can be applied to the general Jenkins UI since Jenkins 2.539.

Motivation

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.

Getting started

By default, CSP enforcement on Jenkins UI pages is disabled, but administrators can enable it to protect their Jenkins instance.

Following the steps below should ensure a smooth introduction of Content Security Policy enforcement on your controller.

Upgrade Jenkins to 2.539+

As a first step, keep enforcement disabled after upgrading. Jenkins collects reports of violations encountered by users' browsers even while enforcement is disabled. This allows administrators to identify incompatible plugins and configurations on their controllers. Make sure you update installed plugins to their latest versions to benefit from recent fixes. This will lower the number of already fixed findings reported in the next step.

Identify incompatibilities in your setup

This step consists of two parallel activities:

  • Compare installed plugins with list of plugins with known incompatibilities.
    See the section Compatibility below for known incompatibilities in Jenkins plugins. Compare the plugins you have installed with the list of known incompatible plugins. Review the issues reported for those plugins to understand the potential impact. Not all incompatibilities affect all use cases. If unsure about the impact, set up a test controller with Content Security Policy enforcement enabled to test functionality of affected plugins.

  • Monitor and address violations reported by your users' browsers.
    See the section Identifying incompatibilities in your setup below for instructions on how to monitor reports of violations submitted by your users' web browsers. If violations are reported, identify the responsible plugin(s) and functionality. If the source of violations is not listed in the list of known incompatibilities linked above, report the issue to the responsible plugin and let the maintainers of the list know.

For each violation or known incompatibility, understand its impact on your controller. It’s possible you can adapt the configuration, work around the problem using CSP Plugin relaxing rules, or upgrade the plugin.

Start enforcing

Once all known incompatibilities and reported violations have been addressed, are deemed tolerable, or can be worked around through use of the CSP plugin, it’s time to start enforcing Content Security Policy. See the next sections for details about that. Still keep an eye on the violation reports — now they are for functionality that is actually broken.

Setting up

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.

Using the UI

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.

Using Configuration as Code

The following YAML snippet for Configuration as Code sets up CSP enforcement.

security:
  contentSecurityPolicy:
    enforce: true

Using a Java system property

You 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.

During development

During development, CSP 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.

Advanced configuration

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.

Compatibility

Known compatible and incompatible plugins

Plugin compatibility is tracked in JENKINS-60865. This spreadsheet provides an assessment of their compatibility for most popular plugins.

Notable plugins with functionality restricted by CSP

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.

Anything Goes Formatter

This plugin allows users to specify arbitrary HTML, CSS, and JavaScript in description fields across the Jenkins UI. Administrators must ensure that the provided (and trusted) descriptions are compatible with the CSP directives enforced on their Jenkins controller.

Badge

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. Compatibility discussion is in #316.

Dashboard View

This plugin provides the "Iframe Portlet" and "Image" portlets. These will only work if the frame-src and img-src directives respectively are set up to allow the specified URLs. Compatibility discussion is in #437.

Login Theme

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. Compatibility discussion is in #161.

Simple Theme

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. Compatibility discussion is in #280.

Notable plugins with known incompatibilities

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.

Artifactory

This plugin is abandoned. Installations requiring this plugin cannot enforce CSP protection without breaking its functionality.

Build Pipeline

This plugin is looking for new maintainers and has unresolved security vulnerabilities. Installations requiring this plugin cannot enforce CSP protection without breaking its functionality.

Dashboard View

The plugin does not periodically reload agent information in the "Agent statistics" portlet (#435).

Identifying incompatibilities in your setup

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.

Reporting incompatibilities

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).

Fixing incompatible plugins

See the developer documentation.