Controller Isolation

This site is the new docs site currently being tested. For the actual docs in use please go to

What exactly happens during a build is often controlled by people less trusted than a Jenkins administrator:

  • Jenkins users with Job/Configure permission

  • Build script authors (pom.xml, Makefile, etc.)

  • Code authors (for example test code executed during a build)

They all have some control over commands executed during a build. This does not even consider issues like supply chain attacks on build dependencies, whereby attackers take over control of NPM or Maven packages and insert malicious code.

To ensure the stability of the Jenkins controller, builds should be executed on other nodes than the built-in node. This concept is called distributed builds in Jenkins, and you can learn more about this here. Setting up distributed builds in Jenkins is a great start for protecting the Jenkins controller from malicious (or just broken) build scripts, but care needs to be taken for protections to be effective.

Most Jenkins environments grow over time requiring their trust models to evolve as the environment grows. Please consider scheduling regular "check-ups" to review whether any disabled security settings should be re-enabled.

Not building on the built-in node

Out of the box, Jenkins is set up to run builds on the built-in node. This is to make it easier to get started with Jenkins, but is inadvisable longer term: Any builds running on the built-in node have the same level of access to the controller file system as the Jenkins process.

It is therefore highly advisable to not run any builds on the built-in node, instead using agents (statically configured or provided by clouds) to run builds.

To prevent builds from running on the built-in node directly, navigate to Manage Jenkins » Nodes and Clouds. Select Built-In Node in the list, then select Configure in the menu. Set the number of executors to 0 and save. Make sure to also set up clouds or build agents to run builds on, otherwise builds won’t be able to start.

Alternatively, use a plugin such as Job Restrictions Plugin to limit which jobs can be run on certain nodes (like the built-in node), independent of what your less trusted users may use as label expression in their jobs' configurations.

If you do not have any other computers to run agents on, you can also run an agent process as a different operating system user on the same system to achieve a similar isolation effect. In this case, ensure that the agent process has no file system access (neither read nor write) to the Jenkins home directory, and that the agent process cannot use sudo or similar methods to elevate its own permissions.

Agent → Controller Access Control

The Jenkins controller and agents can be thought of as a distributed process which executes across multiple discrete processes and machines. This allows an agent to ask the controller process for information available to it, for example, the contents of files, etc., and even to have the controller run certain commands when requested by the agent.

So while not building on the built-in node is a good general practice to protect from bugs and less sophisticated attackers, an agent process taken over by a malicious user would still be able to obtain data or execute commands on the Jenkins controller. To prevent this, the Agent → Controller Access Control system prevents agent processes from being able to send malicious commands to the Jenkins controller.

This system is always enabled since Jenkins 2.326 (see Agent → Controller Security Changes in 2.326). In Jenkins 2.325 and earlier, it is enabled by default, but can be disabled in the web UI by un-checking the box on the Manage Jenkins » Security page.

It is strongly recommended that you not disable the Agent → Controller Access Control system.
Security - Enable Agent ⇒ Controller Access Control

As an alternative to disabling Agent → Controller Access Control, in Jenkins 2.325 and earlier, administrators can selectively allow greater access.