Skip to content

Latest commit

 

History

History
397 lines (297 loc) · 20.7 KB

README.adoc

File metadata and controls

397 lines (297 loc) · 20.7 KB
Raw

JEP-235: Agent-To-Controller Security Simplification

Table 1. Metadata

JEP

235

Title

Agent-To-Controller Security Simplification

Sponsor

Daniel Beck

Status

Draft 💬

Type

Standards

Created

2021-11-18

BDFL-Delegate

TBD

JIRA

JENKINS-67173
Table of Contents

Abstract

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.

Specification

Overview

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 of FilePath are changed to MasterToSlaveFileCallable.

  • All supporting types are removed, with the exception of AdminWhitelistRule, which now only prints log messages when the kill switch is set.

Details

  • Deletions/removals:

    • jenkins.FilePathFilter is deleted.

    • jenkins.FilePathFilterAggregator is deleted.

    • jenkins.ReflectiveFilePathFilter is deleted.

    • jenkins.SoloFilePathFilter is deleted.

    • jenkins.security.s2m.AdminCallableMonitor (symbol slaveToMasterAccessControl) is deleted, including its resources.

    • jenkins.security.s2m.AdminCallableWhitelist (symbol admin) 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 any FilePathFilter functionality:

    • The private SecureFileCallable (the marker interface for SlaveToMasterFileCallable using FilePathFilter) is removed and every FileCallable in FilePath now extends MasterToSlaveFileCallable 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 the AdminWhitelistRule 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 in FilePath, are allowed to act on any path.

Motivation

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.

Disabled class loading

This is largely unchanged, except insofar as there is no longer a UI option to disable it, just a Java system property escape hatch.

Role checks

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.

File path filters

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.

Reasoning

Removal of built-in Callable allowlist

All plugins in the default allowlist have long since been updated to not need these entries.

hudson.maven.MavenBuildProxy$Filter$AsyncInvoker

Fix released Oct 2014 in 2.7.1.

com.cloudbees.plugins.deployer.engines.Engine$FingerprintDecorator

The plugin is no longer being distributed by the Jenkins project.

hudson.scm.SubversionWorkspaceSelector$1

Fix released June 2016 in 2.6.0.

org.jenkinsci.plugins.gitclient.CliGitAPIImpl$GetPrivateKeys

Fix released Oct 2014 in 1.11.0.

com.cloudbees.jenkins.plugins.sshcredentials.SSHAuthenticator$1

Fix released May 2016 in 1.12.

com.synopsys.arc.jenkinsci.plugins.cygwinprocesskiller.CygwinProcessKiller$KillerRemoteCall

Fix released Jan 2018 in 0.2.

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.

Removal of customizable Callable allowlist

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.

Removal of agent-to-controller support for FilePath

FilePath transparently supporting agent-to-controller file access through its public methods has several problems:

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.

Deprecation of SlaveToMasterFileCallable

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.

Backwards Compatibility

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.

Incompatible Plugins

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

Cobertura

"Publish Cobertura Coverage Report" post-build step fails

n/a

Update Cobertura Plugin to 1.17

Code Coverage API

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

Genexus

Saving to Change Log

n/a

Update GeneXus Plugin to 296.v7ea4debe37c9

Job Cacher

TBD

TBD

n/a (JENKINS-67298)

Log Parser

Log parsing fails

n/a

Update Log Parser Plugin to 2.2

Maven Integration

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

Micro Focus Application Automation Tools

TBD

TBD

n/a (JENKINS-67232)

Publish Over SSH

Reading SSH key files from controller file system fails

Specify SSH keys inline

n/a (JENKINS-67236)

Selenium

TBD

TBD

n/a (JENKINS-67255)

Static Analysis Plugins

TBD

TBD

Deprecated plugin, migrate to Warnings Next Generation

Violations

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

Wildfly Deployer

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

Security

There are no security risks related to this proposal beyond those applying to most changes of core Jenkins code.

Infrastructure Requirements

There are no new infrastructure requirements related to this proposal.

Testing

Core

Automated tests for the new enabled-by-default protections are added to Jenkins.

Plugins

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 in configuration-as-code, for which compatibility is retained.

Prototype Implementation