JEP |
235 |
---|---|
Title |
Agent-To-Controller Security Simplification |
Sponsor |
|
Status |
Draft 💬 |
Type |
Standards |
Created |
2021-11-18 |
BDFL-Delegate |
TBD |
JIRA |
The agent-to-controller security subsystem is greatly simplified: it is always enabled and exceptions defined in 2014 for backwards compatibility with plugins are gone.
The agent-to-controller security subsystem is greatly simplified:
-
It is always enabled.
-
All UI related to this feature is removed.
-
The file-based configuration for both callables and file paths is removed.
-
The built-in allowlists for both callables and file paths are removed.
-
Class loading from agents is always disabled.
-
SlaveToMasterFileCallable
is deprecated and any implementations supporting methods ofFilePath
are changed toMasterToSlaveFileCallable
. -
All supporting types are removed, with the exception of
AdminWhitelistRule
, which now only prints log messages when the kill switch is set.
-
Deletions/removals:
-
jenkins.FilePathFilter
is deleted. -
jenkins.FilePathFilterAggregator
is deleted. -
jenkins.ReflectiveFilePathFilter
is deleted. -
jenkins.SoloFilePathFilter
is deleted. -
jenkins.security.s2m.AdminCallableMonitor
(symbolslaveToMasterAccessControl
) is deleted, including its resources. -
jenkins.security.s2m.AdminCallableWhitelist
(symboladmin
) is deleted. -
jenkins.security.s2m.AdminFilePathFilter
is deleted. -
jenkins.security.s2m.CallableRejectionConfig
is deleted. -
jenkins.security.s2m.CallableWhitelist
is deleted. -
jenkins.security.s2m.CallableWhitelistConfig
is deleted. -
jenkins.security.s2m.ConfigDirectory
is deleted. -
jenkins.security.s2m.ConfigFile
is deleted. -
jenkins.security.s2m.DefaultFilePathFilter
is deleted. -
jenkins.security.s2m.FilePathRule
is deleted. -
jenkins.security.s2m.FilePathRuleConfig
is deleted. -
jenkins.security.s2m.MasterKillSwitchConfiguration
is deleted, including its resources. -
jenkins.security.s2m.MasterKillSwitchWarning
is deleted, including its resources. -
jenkins.security.s2m.OpMatcher
is deleted. -
jenkins.security.s2m.RejectedCallable
is deleted. -
jenkins.security.s2m.RunningBuildFilePathFilter
is deleted. -
resources/jenkins/security/s2m/callable.conf
is deleted. -
resources/jenkins/security/s2m/filepath-filter.conf
is deleted.
-
-
AdminWhitelistRule
is deprecated, its resources deleted, and all functionality removed:-
The methods
#setMasterKillSwitch(boolean)
and#getMasterKillSwitch()
are changed so they only log messages informing about its new lack of functionality. -
Everything else is removed.
-
-
FilePath
is updated to no longer use anyFilePathFilter
functionality:-
The private
SecureFileCallable
(the marker interface forSlaveToMasterFileCallable
usingFilePathFilter
) is removed and everyFileCallable
inFilePath
now extendsMasterToSlaveFileCallable
instead. -
All private static functions like
#reading(File)
that perform access checks are removed, as well as#filterNonNull()
which supported them.
-
-
jenkins.security.s2m.CallableDirectionChecker
is simplified and now always enforces role checks and disables class loading from agents. -
SetupWizard
no longer sets theAdminWhitelistRule
kill switch, as protections are now always effective. -
The
jenkins.security.s2m.CallableDirectionChecker.allow
system property escape hatch is retained:-
It allows classloading from agents to the controller (as before).
-
It allows executing any callable regardless of its role check (as before).
-
All
FileCallable
implementations, including those inFilePath
, are allowed to act on any path.
-
The agent-to-controller security subsystem was added in 2014 to restrict the actions that agent processes can perform on the Jenkins controller as part of the SECURITY-144 security fix. This protection was comprised of three major, complementary parts:
- Disabled class loading
-
Controllers do not load classes from agents, which means all code on a controller must already be part of that environment. No new code can be injected from agents.
- Role checks
-
Every
Callable
declares through its role check whether it’s allowed to be sent from an agent to a controller. Legacy callables (built for Jenkins 1.565.3 or older, or Jenkins 1.586 or older) were rejected by default, but admins could allow their transmission from agents to the controller. - File path filters
-
To continue supporting various methods on
FilePath
that transparently access files on the other side of a remoting channel, file path filters limit which files and directories can be accessed.
This is largely unchanged, except insofar as there is no longer a UI option to disable it, just a Java system property escape hatch.
Callable
implementations can be separated into the following categories:
-
Implementations that allow their transmission from an agent to the controller (
SlaveToMasterCallable
or equivalent): These continue to be able to do this, and must be carefully reviewed for potential misuse. -
Implementations that prohibit their transmission from an agent to the controller (
MasterToSlaveCallable
or equivalent): Nothing changes, these always prohibited execution on the controller. -
Implementations that do not perform a permission check (empty body of
#checkRoles(RoleChecker)
): A security hardening in Jenkins 2.319 and 2.303.3 prohibits this. -
Implementations without a
RoleSensitive#checkRoles(RoleChecker)
implementation at all, in plugins built against Jenkins before 1.580.1 or 1.587: These have always been prohibited unless on the allowlist (built-in or custom).
With this proposal, the allowlist is removed, so any Callable
that needed allowlisting to work will break.
Few plugins should be affected; see below.
In addition to Callable
, FileCallable
is an interface with equivalent role checks for use with FilePath#act
(rather than Channel#call
).
The same four categories exist there.
Otherwise, no changes are implemented in this area.
While some code may legitimately require being implementing in a SlaveToMasterCallable
, only very few plugins require the ability to access files on the controller from agents.
File path filters (FilePathFilter
etc.) exist to support the transparent use of FilePath
methods in the agent-to-controller direction (i.e., allowing agents to operate on files on the controller file system).
This has been shown to be error-prone to implement, and rarely used.
To make it easier to reason about the impact of code sent through remoting channels on security, this feature is completely removed.
Going forward, all methods of FilePath
will only work locally (on controller or agent) or in the controller-to-agent direction.
All plugins in the default allowlist have long since been updated to not need these entries.
hudson.maven.MavenBuildProxy$Filter$AsyncInvoker
com.cloudbees.plugins.deployer.engines.Engine$FingerprintDecorator
-
The plugin is no longer being distributed by the Jenkins project.
hudson.scm.SubversionWorkspaceSelector$1
org.jenkinsci.plugins.gitclient.CliGitAPIImpl$GetPrivateKeys
com.cloudbees.jenkins.plugins.sshcredentials.SSHAuthenticator$1
com.synopsys.arc.jenkinsci.plugins.cygwinprocesskiller.CygwinProcessKiller$KillerRemoteCall
hudson.plugins.selenium.JenkinsCapabilityMatcher$LabelMatcherCallable
-
Fix released April 2016 in 2.53.0, and the plugin has an unresolved high severity security vulnerability published in June 2020 anyway.
All plugins built for Jenkins 1.587 or newer, LTS 1.580.1 or newer (released 2014) need to implement RoleSensitive
.
Since 2.319 and LTS 2.303.3, Callables need to perform an actual role check.
Only plugins targeting releases older than that would need to be added to a custom allowlist.
Since 2016, the agent-to-controller security subsystem has been enabled by default, so any plugins requiring an exception should have been updated long ago, as all new installations would need to be configured to allow those plugins to bypass this protection mechanism.
FilePath
transparently supporting agent-to-controller file access through its public methods has several problems:
-
The implementation of the allowlist using
FilePathFilter
and configuration files is error-prone (see SECURITY-2455 and the related 2.303.3 upgrade guide entry) and not flexible enough (see SECURITY-2428 and the related 2.303.3 upgrade guide entry). -
This behavior is transparent to plugin developers, not making it clear what goes on behind the scenes.
While allowing selective access to files on the controller may have been a good solution in 2014 for compatibility with then-existing plugins, few plugins seem to need this exception today.
Plugins should be restructured to not have agent-to-controller access where possible, or implement a SlaveToMasterCallable
with explicit input validation as described in the developer documentation instead of relying on FilePath
.
While SlaveToMasterCallable
is needed for some use cases, SlaveToMasterFileCallable
exists for convenience only (as an argument to FilePath#act
), and relies on the nontrivial custom (de)serialization of FilePath
.
To discourage the creation of new (File
)Callable
in the agent-to-controller direction, and make it easier to reason about security of any (File
)Callable
sent through a remoting channel, this type is deprecated, and warnings are logged whenever it is deserialized on a controller.
usage-in-plugins
is used to check access to any of the types removed or substantially altered.
The following can be used as an input file for its -i -C
/ --onlyIncludeSpecified --additionalClasses
mode:
# General jenkins/security/s2m/AdminWhitelistRule jenkins/security/s2m/ConfigDirectory jenkins/security/s2m/ConfigFile jenkins/security/s2m/MasterKillSwitchConfiguration jenkins/security/s2m/MasterKillSwitchWarning # FilePathFilter jenkins/security/s2m/AdminFilePathFilter jenkins/security/s2m/AdminFilePathFilter$ChannelConfiguratorImpl jenkins/security/s2m/DefaultFilePathFilter jenkins/security/s2m/FilePathRuleConfig jenkins/security/s2m/FilePathRule jenkins/security/s2m/OpMatcher jenkins/security/s2m/RunningBuildFilePathFilter jenkins/ReflectiveFilePathFilter jenkins/SoloFilePathFilter jenkins/ReflectiveFilePathFilter jenkins/FilePathFilterAggregator jenkins/FilePathFilter # Callables jenkins/security/s2m/AdminCallableMonitor jenkins/security/s2m/AdminCallableWhitelist jenkins/security/s2m/CallableDirectionChecker jenkins/security/s2m/CallableDirectionChecker$ChannelConfiguratorImpl jenkins/security/s2m/CallableDirectionChecker$DefaultWhitelist jenkins/security/s2m/CallableRejectionConfig jenkins/security/s2m/CallableWhitelist jenkins/security/s2m/CallableWhitelistConfig jenkins/security/s2m/RejectedCallable
The only plugin distributed by the Jenkins project that is using any of these types is Configuration as Code, which uses AdminWhitelistRule
in AdminWhitelistRuleConfigurator
.
All methods used there are retained, but no longer have an effect beyond producing log messages.
jenkinsci/jenkins#5890 adds telemetry from Jenkins 2.322 and LTS 2.319.1 until 2022-03-01 to identify any (expected to be rare) uses of FilePath
methods from agents to access files on the controller.
Issues will be filed and popular plugins, where possible, will be adapted.
The following plugins have been identified as incompatible with this proposal:
Plugin | Affected Feature | Workaround | Fix |
---|---|---|---|
"Publish Cobertura Coverage Report" post-build step fails |
n/a |
Update Cobertura Plugin to 1.17 |
|
Saving of source files (optional feature) in post-build step fails |
Do not use the feature |
Update Code Coverage API Plugin to 2.0.4 |
|
Saving to Change Log |
n/a |
Update GeneXus Plugin to 296.v7ea4debe37c9 |
|
TBD |
TBD |
n/a (JENKINS-67298) |
|
Log parsing fails |
n/a |
Update Log Parser Plugin to 2.2 |
|
Archiving Maven sites and Javadoc fails |
Do not archive Maven sites or Javadoc |
Update Maven Plugin to 3.15.1 or install one of the backports 3.12.1, 3.10.1, 3.8.1, 3.7.1, 3.6.1 |
|
TBD |
TBD |
n/a (JENKINS-67232) |
|
Reading SSH key files from controller file system fails |
Specify SSH keys inline |
n/a (JENKINS-67236) |
|
TBD |
TBD |
n/a (JENKINS-67255) |
|
TBD |
TBD |
Deprecated plugin, migrate to Warnings Next Generation |
|
TBD |
TBD |
n/a (JENKINS-67254) |
|
Warnings Next Generation (5.1.0 or older) |
TBD |
TBD |
Resolved by updating to version 5.2.0 (June 2019) or newer |
TBD |
TBD |
n/a (Already broken by security hardening in 2.319 and LTS 2.303.3) |
|
XUnit (2.0.2 or older) |
TBD |
TBD |
Expected to be resolved by updating to version 2.0.3 (June 2018) or newer |
There are no security risks related to this proposal beyond those applying to most changes of core Jenkins code.
The Jenkins test harness does not by default enable agent-to-controller security, so automated test coverage for agent-to-controller security is currently fairly low.
It is not straightforward to adapt JenkinsRule
for use with PCT, as changes to the default setup (e.g., disabling built-in node executors and adding a mock agent or cloud) would break numerous unrelated test assertions.
This limitation is deemed acceptable, as the behavior changes specified by this proposal are validated in other ways, and their associated risks are fairly minor:
- Removal of default callable allowlist
-
All plugins listed have been updated years ago, or are no longer distributed by the Jenkins project. It is unlikely this change will harm users in ways not resolved by updating long outdated plugins.
- Removal of admin-customizable callable allowlist
-
This is expected to only matter for plugins that have not been updated in several years (more likely closed source), for which the need to customize the allowlist was tolerated.
- Removal of default and admin-customizable file path allowlist, and support of
FilePath
method invocations in agent-to-controller direction -
Telemetry is expected to identify any such uses, so plugins can be adapted. Additionally, Remoting Security Workaround Plugin essentially implements an equivalent change, so all functionality affected by this plugin will also be affected by this proposal.
- Removal of ability to load classes from agents (when disabling agent-to-controller security)
-
There is no known use case for this, and the author is not aware of any issues related to this restriction.
- Removal of various Java classes and associated resources implementing removed features
-
usage-in-plugins
found no uses except one inconfiguration-as-code
, for which compatibility is retained.
Additionally, jenkinsci/jenkins#5890 adds telemetry identifying instances of FilePath
use in the agent-to-controller direction.