Content Security Policy

This page describes the restrictions applied to the general Jenkins UI since Jenkins 2.TODO.

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.

Motivation

From 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 cross-site scripting (XSS) is largely, or entirely, mitigated.

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.

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 to control CSP 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 sets up Content Security Policy enforcement.

security:
  contentSecurityPolicy:
    enforce: true

More advanced options are contributed by Content Security Policy Plugin 2.x.

Using a Java system property

You can set the Java system property 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 Script Console.

Configuration

Jenkins does not include advanced configuration. To customize the behavior of CSP beyond toggling it on and off, install Content Security Policy Plugin.

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.

Identifying incompatibility in your setup

Jenkins requests that browsers submit reports of any incompatibilities they encounter.

Administrators can view them in two different ways:

  • Set up a log recorder for the logger jenkins.security.csp.CspReceiver.LoggingReceiver on FINER (for reports by authenticated users) or FINEST (for reports by all users).

  • Install 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.

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