From 9703d7bb0ba5f186c4ddd7b873fd16e0701bd501 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 5 Oct 2021 01:51:57 -0700 Subject: [PATCH 01/59] [4564] Add conceptual info to security introduction --- content/doc/book/security/index.adoc | 131 +++++++++++++++++- .../doc/book/security/managing-security.adoc | 14 +- 2 files changed, 125 insertions(+), 20 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index e131351f350b..9bcf2d859adf 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -9,15 +9,132 @@ ifdef::backend-html5[] :sectanchors: endif::[] -Jenkins is used everywhere from workstations on corporate intranets, to high-powered servers connected to the public internet. -To safely support this wide spread of security and threat profiles, Jenkins offers many configuration options for enabling, customizing, or disabling various security features. - -Many of the security options are enabled by default when passing the interactive setup wizard to ensure that Jenkins is secure. -Others involve environment-specific setup and trade-offs and depend on specific use cases supported in individual Jenkins instances. - -This chapter will introduce the various security options available to Jenkins administrators and users, explaining the protections offered, and trade-offs to disabling some of them. +Jenkins is used everywhere -- from workstations on corporate intranets +to high-powered servers connected to the public internet. +It is critically important to keep your Jenkins instance secure, +both to protect your information and to avoid executing malicious code from your Jenkins instance. + +Your Jenkins environment is a fully-distributed build system. +Each network connection is a potential point of entry. +Remember that the code that runs your builds can be perverted to run anything! + +Jenkins and the Pipelines it runs must be able to do almost anything. +This means that a malicious Pipeline could reconfigure the Jenkins instance, +delete files, or launch various forms of mischief +such as a DDoS attack pr a bot. +In addition to deliberate and direct attacks on your environment, +a trusted user could visit an infected web site +and accidentally introduce malicious code into the Jenkins instance. + +Jenkins includes configurable features to secure your Jenkins instance +against the various security and threat profiles. +The setup wizard enables many of the security options by default, +to ensure that Jenkins is secure. +Other security options involve environment-specific setup and trade-offs +and depend on specific use cases supported for individual Jenkins instances. +Configuration options allow you to enable, customize, or disable security features. + +This chapter introduces the various security options available to Jenkins administrators and users, +explaining the protections offered, and trade-offs to disabling some of them. + +[NOTE] +.Enable Security +==== +Versions before Jenkins 2.214 and Jenkins LTS 2.222.1 +included an *Enable Security* checkbox on the *Configure Global Security* page. +This checkbox was selected by default +with the recommendation that it never be unchecked, +especially on production systems. +This enforced that only users who were authenticated +(in other words, logged in with with a username and password, +enforced either by Jenkins or by alernate Security Realm) +could access Jenkins. +The Jenkins user database was defined as the default security realm in these same releases. + +The "Enable Security" checkbox has been removed from current releases +(beginning with Jenkins 2.214 and Jenkins LTS 2.222.1) +because it should never be disabled. +==== + +== Security Principles + +Security principles should guide the practices and tools used to fight and prevent threats. +The major principles for security are: + +* *Least privilege:* +Give people the privileges required to do their jobs +but do not give everyone permission to do everything +and do not open ports that are not required for your work. + +* *Know the system:* +The more you understand about how your system works, +the more you are prepared to protect the integrity of your system. + +* *Defense in depth:* +Systems are layered. +Put security on all layers. + +* *Prevention is good, but detection is better:* +Monitor your Jenkins installation constantly +so that you quickly detect signs of a security breach. + +* *Keep your system current:* +Pay attention to +link:https://www.jenkins.io/security/advisories/[Security Advisories] +and apply +link:https://www.jenkins.io/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] +as soon as possible! +Keeping the Jenkins software and all plugins current +also helps ensure that your system is secure. + +== How Jenkins Executes a Pipeline + +A simple overview of how Jenkins executes a Pipeline +helps to understand the security considerations. + +By default, a Pipeline executes with the full privileges of the Jenkins administrator, +although you can configure Jenkins to execute Pipelines with fewer privileges. +All of the Pipeline logic, the Groovy conditionals, loops, and so forth execute on the controller. + +When a Pipeline runs: + +* For each build that runs, Jenkins creates a _workspace_ on the controller +where files for that build are stored. +* The Pipeline calls a series of _steps_, +each of which is a script or command that does the real work +and mostly executes using an _executor_ on an _agent_. + +The agent: + +* Writes some files to the local node. +* Sends data back to the controller. +* May also request information from the controller. + +== Agents and Security + +Never run builds on the Jenkins controller in production environments. +A build job that uses an agent running on the built-in controller node +has access to Jenkins controller files and configuration, which poses a security risk. +Configuring Jenkins as a distributed system, +where builds execute on agents that are separate from the controller +instead of the built-in node on the controller, +enhances the security of your Jenkins instance +as well as improving its performance and making it more stable. + +An agent that executes on the Jenkins controller +may be able to access Jenkins configuration files and the workspaces of other builds. +An agent could also request information +that belongs to other teams or organizations that share the controller. + +An agent can also write malicious code to its local disk so that the node is tainted. +For maximum security, run all builds on ephemeral agents in the cloud +that are destroyed at the end of each build job. + +NOTE: A job that performs administrative tasks such as backups may run on the controller, +but be sure to label the executor and only allow it to be used by jobs that specify that label. // TODO the following only makes sense on the web site, not the PDF. Can it be disabled there? +// TODO the material below should be moved to other sections in this chapter. == Basic Setup diff --git a/content/doc/book/security/managing-security.adoc b/content/doc/book/security/managing-security.adoc index bedeea793ca3..12bed80502b6 100644 --- a/content/doc/book/security/managing-security.adoc +++ b/content/doc/book/security/managing-security.adoc @@ -36,19 +36,7 @@ This section will introduce the various security options available to a Jenkins administrator, explaining the protections offered, and trade-offs to disabling some of them. - -== Enabling Security - -Beginning with Jenkins 2.214 and Jenkins LTS 2.222.1, the "Enable Security" checkbox has been removed. -Jenkins own user database is used as the default security realm. - -In versions before Jenkins 2.214 and Jenkins LTS 2.222.1, when the *Enable Security* checkbox is checked, -users can log in with a username and password in order to -perform operations not available to anonymous users. Which operations require -users to log in depends on the chosen authorization strategy and its configuration; -by default anonymous users have no permissions, and logged in users have full -control. The "Enable Security" checkbox should *always* be enabled for any non-local (test) Jenkins -environment. +== Configure Global Security page The "Configure Global Security" section of the web UI allows a Jenkins administrator to enable, configure, or disable key security features which apply to the entire From 6c727c3b25c6f3ed5af3b9dc43af46e208550c48 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 5 Oct 2021 02:26:24 -0700 Subject: [PATCH 02/59] move note about "Enable Security" checkbox back to "Managing Security" --- content/doc/book/security/index.adoc | 19 ------------------ .../doc/book/security/managing-security.adoc | 20 +++++++++++++++++++ 2 files changed, 20 insertions(+), 19 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 9bcf2d859adf..c42d48400993 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -37,25 +37,6 @@ Configuration options allow you to enable, customize, or disable security featur This chapter introduces the various security options available to Jenkins administrators and users, explaining the protections offered, and trade-offs to disabling some of them. -[NOTE] -.Enable Security -==== -Versions before Jenkins 2.214 and Jenkins LTS 2.222.1 -included an *Enable Security* checkbox on the *Configure Global Security* page. -This checkbox was selected by default -with the recommendation that it never be unchecked, -especially on production systems. -This enforced that only users who were authenticated -(in other words, logged in with with a username and password, -enforced either by Jenkins or by alernate Security Realm) -could access Jenkins. -The Jenkins user database was defined as the default security realm in these same releases. - -The "Enable Security" checkbox has been removed from current releases -(beginning with Jenkins 2.214 and Jenkins LTS 2.222.1) -because it should never be disabled. -==== - == Security Principles Security principles should guide the practices and tools used to fight and prevent threats. diff --git a/content/doc/book/security/managing-security.adoc b/content/doc/book/security/managing-security.adoc index 12bed80502b6..85e0c2308ca9 100644 --- a/content/doc/book/security/managing-security.adoc +++ b/content/doc/book/security/managing-security.adoc @@ -21,6 +21,25 @@ Pages to mark as deprecated by this document: https://github.com/jenkinsci/jenkins/blob/master/core/src/main/resources/jenkins/security/s2m/MasterKillSwitchConfiguration/help-masterToagentAccessControl.html#L2 /content/redirect/security-144 +[NOTE] +.Enable Security +==== +Versions before Jenkins 2.214 and Jenkins LTS 2.222.1 +included an *Enable Security* checkbox on the *Configure Global Security* page. +This checkbox was selected by default +with the recommendation that it never be unchecked, +especially on production systems. +This enforced that only users who were authenticated +(in other words, logged in with with a username and password, +enforced either by Jenkins or by alernate Security Realm) +could access Jenkins. +The Jenkins user database was defined as the default security realm in these same releases. + +The "Enable Security" checkbox has been removed from current releases +(beginning with Jenkins 2.214 and Jenkins LTS 2.222.1) +because it should never be disabled. +==== + //// Jenkins is used everywhere from workstations on corporate intranets, to @@ -43,6 +62,7 @@ enable, configure, or disable key security features which apply to the entire Jenkins environment. image::security/configure-global-security.png["Configure Global Security", role=center] +https://github.com/jenkins-infra/jenkins.io/pull/4612 === TCP Port From 8163c74609ba921ff56bdbb7c0bba5706707862a Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 5 Oct 2021 11:13:43 -0700 Subject: [PATCH 03/59] delete bogus link to a PR --- content/doc/book/security/managing-security.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/content/doc/book/security/managing-security.adoc b/content/doc/book/security/managing-security.adoc index 85e0c2308ca9..f98b927854f0 100644 --- a/content/doc/book/security/managing-security.adoc +++ b/content/doc/book/security/managing-security.adoc @@ -62,7 +62,6 @@ enable, configure, or disable key security features which apply to the entire Jenkins environment. image::security/configure-global-security.png["Configure Global Security", role=center] -https://github.com/jenkins-infra/jenkins.io/pull/4612 === TCP Port From 708997b96430ca116fc273ab13ddedf64f68b097 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Thu, 7 Oct 2021 01:46:06 -0700 Subject: [PATCH 04/59] Moved info about who affects Pipeline from controller-isolation.adoc --- .../book/security/controller-isolation.adoc | 9 ------ content/doc/book/security/index.adoc | 28 +++++++++++++++++-- 2 files changed, 26 insertions(+), 11 deletions(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 5e556d308f49..a1ecd22d7de8 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -9,15 +9,6 @@ ifndef::env-github[:imagesdir: ../../resources] :hide-uri-scheme: endif::[] -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 https://wiki.jenkins.io/display/JENKINS/Distributed+builds[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. diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index c42d48400993..b0278a7fb61e 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -79,8 +79,9 @@ All of the Pipeline logic, the Groovy conditionals, loops, and so forth execute When a Pipeline runs: -* For each build that runs, Jenkins creates a _workspace_ on the controller -where files for that build are stored. +* Jenkins creates a _workspace_ on the controller +for each build that runs. +Files for that build are stored in the workspace.. * The Pipeline calls a series of _steps_, each of which is a script or command that does the real work and mostly executes using an _executor_ on an _agent_. @@ -91,8 +92,31 @@ The agent: * Sends data back to the controller. * May also request information from the controller. +Many different people have some control over +the commands that are executed during a build: + +* Jenkins users with Job/Configure permission +* Authors of build scripts such as `pom.xml` and `Makefile` +* Authors of code, such as test suites that are executed during a build + +Any of these could introduce security issues, either deliberately or accidentally. +In addition, supply chain attacks can occur on build dependencies, +whereby attackers take over control of NPM or Maven packages and insert malicious code. + +You can see the complexity of keeping your Jenkins instance secure. +In the following sections we discuss specific protections that Jenkins provides +and practices that you can implement to protect Jenkins from intrusions. + == Agents and Security +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; +you can learn more about this https://wiki.jenkins.io/display/JENKINS/Distributed+builds[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. + Never run builds on the Jenkins controller in production environments. A build job that uses an agent running on the built-in controller node has access to Jenkins controller files and configuration, which poses a security risk. From 721f907c5a4e660988216d21410d56ddf6472387 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 12 Oct 2021 18:38:06 -0700 Subject: [PATCH 05/59] minor edits --- content/doc/book/security/index.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index b0278a7fb61e..bc365947d461 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -21,7 +21,7 @@ Remember that the code that runs your builds can be perverted to run anything! Jenkins and the Pipelines it runs must be able to do almost anything. This means that a malicious Pipeline could reconfigure the Jenkins instance, delete files, or launch various forms of mischief -such as a DDoS attack pr a bot. +such as a DDoS attack or a bot. In addition to deliberate and direct attacks on your environment, a trusted user could visit an infected web site and accidentally introduce malicious code into the Jenkins instance. @@ -64,7 +64,7 @@ Pay attention to link:https://www.jenkins.io/security/advisories/[Security Advisories] and apply link:https://www.jenkins.io/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] -as soon as possible! +as soon as possible. Keeping the Jenkins software and all plugins current also helps ensure that your system is secure. From 0ffb5102da17d490786e0d022b12d5d916f81f67 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 13 Oct 2021 20:46:33 -0700 Subject: [PATCH 06/59] Pipelines -> jobs --- content/doc/book/security/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index bc365947d461..f2f57a567abd 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -18,7 +18,7 @@ Your Jenkins environment is a fully-distributed build system. Each network connection is a potential point of entry. Remember that the code that runs your builds can be perverted to run anything! -Jenkins and the Pipelines it runs must be able to do almost anything. +Jenkins and the jobs it runs must be able to do almost anything. This means that a malicious Pipeline could reconfigure the Jenkins instance, delete files, or launch various forms of mischief such as a DDoS attack or a bot. From 7fb49ce2d0677c81706504951a8c1d5ad68ff5fe Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 19 Oct 2021 16:47:34 -0700 Subject: [PATCH 07/59] Add concepts-security page --- content/doc/book/security/_chapter.yml | 22 ++--- .../doc/book/security/concepts-security.adoc | 83 +++++++++++++++++++ content/doc/book/security/index.adoc | 73 +--------------- 3 files changed, 96 insertions(+), 82 deletions(-) create mode 100644 content/doc/book/security/concepts-security.adoc diff --git a/content/doc/book/security/_chapter.yml b/content/doc/book/security/_chapter.yml index f7a36d799c28..a6b66179307f 100644 --- a/content/doc/book/security/_chapter.yml +++ b/content/doc/book/security/_chapter.yml @@ -2,19 +2,21 @@ sections: # index - implied overview -- access-control +# General information + - concepts-security + - controller-isolation + - access-control # Legacy sections -- securing-jenkins -- managing-security + - securing-jenkins + - managing-security # Individual how-to pages -- controller-isolation -- csrf-protection -- user-content -- build-authorization -- environment-variables -- markup-formatter + - csrf-protection + - user-content + - build-authorization + - environment-variables + - markup-formatter # Further references -- services + - services diff --git a/content/doc/book/security/concepts-security.adoc b/content/doc/book/security/concepts-security.adoc new file mode 100644 index 000000000000..d320bbdb7d3f --- /dev/null +++ b/content/doc/book/security/concepts-security.adoc @@ -0,0 +1,83 @@ +--- +title: Background Concepts +layout: section +--- + +To properly manage the security of your Jenkins instance, you should be familiar with: + +* Security principles that should guide all your decisions +* How Jenkins executes a Pipeline +If you understand the vulnerabilities that an intrusion could exploit, you can better understand how to protect against those intrusions. + +## Security Principles + +Security principles should guide the practices and tools used to fight and prevent threats. +The major principles for security are: + +* *Least privilege:* +Give people the privileges required to do their jobs +but do not give everyone permission to do everything +and do not open ports that are not required for your work. + +* *Know the system:* +The more you understand about how your system works, +the more you are prepared to protect the integrity of your system. + +* *Defense in depth:* +Systems are layered. +Put security on all layers. + +* *Prevention is good, but detection is better:* +Monitor your Jenkins installation constantly +so that you quickly detect signs of a security breach. + +* *Keep your system current:* +Pay attention to +link:https://www.jenkins.io/security/advisories/[Security Advisories] +and apply +link:https://www.jenkins.io/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] +as soon as possible. +Keeping the Jenkins software and all plugins current +also helps ensure that your system is secure. + +== How Jenkins Executes a Pipeline + +A simple overview of how Jenkins executes a Pipeline +helps to understand the security considerations. + +By default, a Pipeline executes with the full privileges of the Jenkins administrator, +although you can configure Jenkins to execute Pipelines with fewer privileges. +All of the Pipeline logic, the Groovy conditionals, loops, and so forth execute on the controller. + +When a Pipeline runs: + +* Jenkins creates a _workspace_ on the controller +for each build that runs. +Files for that build are stored in the workspace.. +* The Pipeline calls a series of _steps_, +each of which is a script or command that does the real work +and mostly executes using an _executor_ on an _agent_. + +The agent: + +* Writes some files to the local node. +* Sends data back to the controller. +* May also request information from the controller. + +Many different people have some control over +the commands that are executed during a build: + +* Jenkins users with Job/Configure permission +* Authors of build scripts such as `pom.xml` and `Makefile` +* Authors of code, such as test suites that are executed during a build + +Any of these could introduce security issues, either deliberately or accidentally. +In addition, supply chain attacks can occur on build dependencies, +whereby attackers take over control of NPM or Maven packages and insert malicious code. + +You can see the complexity of keeping your Jenkins instance secure. +In the following sections we discuss specific protections that Jenkins provides +and practices that you can implement to protect Jenkins from intrusions. + + + diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index f2f57a567abd..e81eaf26294d 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -37,76 +37,6 @@ Configuration options allow you to enable, customize, or disable security featur This chapter introduces the various security options available to Jenkins administrators and users, explaining the protections offered, and trade-offs to disabling some of them. -== Security Principles - -Security principles should guide the practices and tools used to fight and prevent threats. -The major principles for security are: - -* *Least privilege:* -Give people the privileges required to do their jobs -but do not give everyone permission to do everything -and do not open ports that are not required for your work. - -* *Know the system:* -The more you understand about how your system works, -the more you are prepared to protect the integrity of your system. - -* *Defense in depth:* -Systems are layered. -Put security on all layers. - -* *Prevention is good, but detection is better:* -Monitor your Jenkins installation constantly -so that you quickly detect signs of a security breach. - -* *Keep your system current:* -Pay attention to -link:https://www.jenkins.io/security/advisories/[Security Advisories] -and apply -link:https://www.jenkins.io/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] -as soon as possible. -Keeping the Jenkins software and all plugins current -also helps ensure that your system is secure. - -== How Jenkins Executes a Pipeline - -A simple overview of how Jenkins executes a Pipeline -helps to understand the security considerations. - -By default, a Pipeline executes with the full privileges of the Jenkins administrator, -although you can configure Jenkins to execute Pipelines with fewer privileges. -All of the Pipeline logic, the Groovy conditionals, loops, and so forth execute on the controller. - -When a Pipeline runs: - -* Jenkins creates a _workspace_ on the controller -for each build that runs. -Files for that build are stored in the workspace.. -* The Pipeline calls a series of _steps_, -each of which is a script or command that does the real work -and mostly executes using an _executor_ on an _agent_. - -The agent: - -* Writes some files to the local node. -* Sends data back to the controller. -* May also request information from the controller. - -Many different people have some control over -the commands that are executed during a build: - -* Jenkins users with Job/Configure permission -* Authors of build scripts such as `pom.xml` and `Makefile` -* Authors of code, such as test suites that are executed during a build - -Any of these could introduce security issues, either deliberately or accidentally. -In addition, supply chain attacks can occur on build dependencies, -whereby attackers take over control of NPM or Maven packages and insert malicious code. - -You can see the complexity of keeping your Jenkins instance secure. -In the following sections we discuss specific protections that Jenkins provides -and practices that you can implement to protect Jenkins from intrusions. - == Agents and Security To ensure the stability of the Jenkins controller, @@ -133,8 +63,7 @@ that belongs to other teams or organizations that share the controller. An agent can also write malicious code to its local disk so that the node is tainted. For maximum security, run all builds on ephemeral agents in the cloud -that are destroyed at the end of each build job. - +that are destroyed at the end of each build job. NOTE: A job that performs administrative tasks such as backups may run on the controller, but be sure to label the executor and only allow it to be used by jobs that specify that label. From bdf825b296c1e611ea6ba975b4a277909623106f Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 19 Oct 2021 19:53:24 -0700 Subject: [PATCH 08/59] moving files in _chapter.yml --- content/doc/book/security/_chapter.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/book/security/_chapter.yml b/content/doc/book/security/_chapter.yml index a6b66179307f..4a67d2f8fea4 100644 --- a/content/doc/book/security/_chapter.yml +++ b/content/doc/book/security/_chapter.yml @@ -12,11 +12,11 @@ sections: - managing-security # Individual how-to pages + - markup-formatter - csrf-protection - user-content - build-authorization - environment-variables - - markup-formatter # Further references - services From 033a397d38d2f5ca970604bf2b4f8f173ecc2f15 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 19 Oct 2021 21:09:55 -0700 Subject: [PATCH 09/59] Add rewritten controller-isolation from PR4635 --- .../book/security/controller-isolation.adoc | 218 +++++++++++++++--- content/doc/book/security/index.adoc | 12 + .../doc/book/security/managing-security.adoc | 43 +--- 3 files changed, 202 insertions(+), 71 deletions(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index a1ecd22d7de8..f878f17cd029 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -1,5 +1,5 @@ --- -title: Controller Isolation +title: Distributed Build Architecture layout: section --- ifdef::backend-html5[] @@ -9,55 +9,199 @@ ifndef::env-github[:imagesdir: ../../resources] :hide-uri-scheme: endif::[] -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 https://wiki.jenkins.io/display/JENKINS/Distributed+builds[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. +Never run builds on the Jenkins controller in production environments. +Out of the box, Jenkins is set up to run builds on the built-in controller node. +This makes it easier to get started with Jenkins, +but, on production instances, +builds should only be executed on nodes that are external to the controller. + +A build job that uses an agent running on the built-in controller node +may be able to access Jenkins configuration files and the workspaces of other builds. +An agent could also request information +that belongs to other teams or organizations that share the controller. +Configuring Jenkins as a +link:/doc/book/scaling/architecting-for-scale/#distributed-builds-architecture[distributed build system] +enhances the security of your Jenkins instance +as well as improving its performance and making it more stable. +This is because builds that run on the built-in node +have the same level of access to the controller file system as the Jenkins process itself. +Configuring your Jenkins instance so that builds +execute on agents running on separate nodes +protects the Jenkins controller from malicious (or just broken) build scripts. + +When distributed builds are implemented, +the Jenkins controller serves HTTP requests +and stores all important information related to the builds. +Nodes are separate physical or virtual machines that are configured. +The Jenkins controller manages these nodes, +but the agents manage the task execution on behalf of the Jenkins controller +and supply most of the computing power required to build and test the software. +Different nodes can run different operating systems and different tools, +enabling one Pipeline to build and test the same software +for a variety of platforms. -[CAUTION] +[NOTE] ==== -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. +A job that performs administrative tasks such as backups may run on the controller, +but be sure to label the executor with a hard-to-guess label +and only allow it to be used by jobs that specify that label. +An executor can be temporarily configured on the controller +long enough to run the administrative task +but no executors should be configured on the controller at other times +to ensure that no builds execute on the controller +since a clever Pipeline author may be able to work around the label restriction. + +You can install the plugin:job-restrictions[Job Restrictions Plugin] +to ensure that builds do not run on the controller +even if executors are configured. ==== +An agent can also write malicious code to its local disk so that the node is tainted +and can infect a later build. +For maximum security, run all builds on ephemeral agents in the cloud +so that they are destroyed at the end of each build job. -== 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. - -// TODO Fix this once https://github.com/jenkinsci/jenkins/pull/5425 is merged and released: - -To prevent builds from running on the built-in node directly, navigate to _Manage Jenkins » Manage Nodes and Clouds_. -Select _master_ 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 plugin:job-restrictions[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. - -[NOTE] -==== -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. -==== +By extension, you also should not run agents on the same Docker host as the controller. + +== Distributed Components +A Jenkins distributed builds instance includes the following components: + +Jenkins controller:: + +The Jenkins controller is the Jenkins service itself +and is where Jenkins is installed. +It is a webserver that also acts as a "brain" +for deciding how, when and where to run tasks. +Management tasks (configuration, authorization, and authentication) +are executed on the controller, which serves HTTP requests. +Files written when a Pipeline executes are written to the filesystem on the controller +unless they are off-loaded to an artifact repository such as Nexus or Artifactory. + +Nodes:: + +Nodes are the "machines" on which build agents run. +Jenkins monitors each attached node for +disk space, free temp space, free swap, +clock time/sync and response time. +A node is taken offline if any of these values +go outside the configured threshold. + +Agents:: + +Agents manage the task execution on behalf of the Jenkins controller +by using executors. +An agent is actually a small (170KB single jar) Java client process +that connects to a Jenkins controller and is assumed to be unreliable. +An agent can use any operating system that supports Java. +Tools required for builds and tests are installed on the node where the agent runs; +they can be installed directly or in a container (Docker or Kubernetes). +Each agent is effectively a process with its own PID (Process Identifier) on the host machine. + +Executors:: + +An executor is a slot for execution of tasks; +effectively, it is a thread in the agent. +The number of executors on a node defines the number of concurrent tasks +that can be executed on that node at one time. +In other words, the number of concurrent Pipeline `stages` +that can execute on that node at one time. + +The proper number of executors per build node must be determined +based on the resources available on the node +and the resources required for the workload. +When determining how many executors to run on a node, +consider CPU and memory requirements +as well as the amount of I/O and network activity: + +* One executor per node is the safest configuration. +* One executor per CPU core may work well +if the tasks being run are small. +* Monitor I/O performance, CPU load, memory usage, and I/O throughput carefully +when running multiple executors on a node. + +== Implementing Distributed Builds + +To implement distributed builds on your Jenkins instance, +you must do the following: + +* Create nodes and agents where the builds can run. +* Prevent builds from running on the controller. + +This section also includes other tips and tricks you can use. + +=== Create Nodes and Agents for Builds + +To implement a distributed builds architecture for your Jenkins instance, +you must configure nodes and agents to use for your builds. +See +link:https:/doc/book/managing/nodes/[Managing Nodes] +for instructions. + +=== Prevent Builds from Running on the Controller + +You must also prevent builds from running on the built-in controller node. +To do this: + +. Navigate to _Manage Jenkins » Manage Nodes and Clouds_. +. Select _master_ in the list, then select _Configure_ in the menu. +. Set the number of executors to 0. +. Save the configuration. + +NOTE: A job that performs administrative tasks such as backup may run on the controller, +but be sure to label the executor with a hard-to-guess label +and only allow it to be used by jobs that use that label. +Jenkins should normally be configured to have 0 executors on the controller, +and then be temporarily reconfigured to have 1 executor +long enough to run the backup or other administrative task. +Unless the number of executors is 0, +it is possible for a build to run on the controller. + +=== Other Tips and Tricks + +Another way to prevent builds from running on the controller +is to use a plugin such as the plugin:job-restrictions[Job Restrictions Plugin] +to limit which jobs can be run on certain nodes (like the built-in controller node), +independent of what your less trusted users may use as label expression in their job configurations. + +If you do not have any other computers on which to run agents, +you can run an agent process as a different operating system user on the same system +to achieve a similar isolation effect. +In this case, +be sure that the agent process has neither read nor write file system access +to the Jenkins home directory, +and that the agent process cannot use `sudo` or other practices to elevate its own permissions. //== Infrastructure -// TODO Don't run agents on the same Docker host as the controller etc. == 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. +The Jenkins controller and agents can be thought of as a distributed process +which executes across multiple discrete processes and machines. +Not building on the built-in controller node is an essential practice +to protect the controller from bugs and less sophisticated attackers. +However, an agent can stil ask the controller process for information such as the contents of files, +and can even request that the controller run certain commands. +This means that an agent process taken over by a malicious user could still obtain data +or execute commands on the Jenkins controller. +To prevent this, Jenkins implements the **Agent → Controller Access Control** filter +that prevents agent processes from sending malicious commands to the Jenkins controller. + +This filter may prevent your builds from executing legitimate operations. + +* If builds are failing because of the agent-to-controller access control, +you should first ensure that you have upgraded to the latest version of all plugins, +since older versions of plugins may not work correctly with this feature. -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. -It is enabled by default, but can be disabled in the web UI by un-checking the box on the _Manage Jenkins » Configure Global Security_ page. +* You can also tweak the filter's rules by adding `allow/deny` rules +to specify the commands that you need and the type of access that is allowed for the agent. +See +link:/doc/book/security/controller-isolation/agent-to-controller/[Customizing Agent -> Controller Security] +for more information. -IMPORTANT: It is strongly recommended not to disable the Agent → Controller Access Control system. +It is also possible (but strongly discouraged) to disable this filter +by un-checking the box on the _Manage Jenkins » Configure Global Security_ page: image::security/configure-global-security-agent-controller-toggle.png["Configure Global Security - Enable Agent => Controller Access Control", role=center] -As an alternative to disabling Agent → Controller Access Control, administrators can selectively allow greater access. -See link:/doc/book/security/controller-isolation/agent-to-controller/[the documentation] for details. +IMPORTANT: It is strongly recommended that you not disable the Agent → Controller Access Control filter. diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index e81eaf26294d..29565c25fec6 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -37,6 +37,18 @@ Configuration options allow you to enable, customize, or disable security featur This chapter introduces the various security options available to Jenkins administrators and users, explaining the protections offered, and trade-offs to disabling some of them. +[CAUTION] +==== +Most Jenkins environments grow over time, +requiring their trust models to evolve as the environment grows. +You should schedule regular "check-ups" of your security settings +to ensure that they are still appropriate for your instance. +In particular, if you had to disable some of the default protections that Jenkins provides, +perhaps because you were using a plugin that had not been updated to support that protection, +you may be able to re-enable that protection +to increase the security of your instance. +==== + == Agents and Security To ensure the stability of the Jenkins controller, diff --git a/content/doc/book/security/managing-security.adoc b/content/doc/book/security/managing-security.adoc index f98b927854f0..e1acccacdb89 100644 --- a/content/doc/book/security/managing-security.adoc +++ b/content/doc/book/security/managing-security.adoc @@ -1,4 +1,5 @@ --- +title: Configure Global Security layout: section --- ifdef::backend-html5[] @@ -21,45 +22,19 @@ Pages to mark as deprecated by this document: https://github.com/jenkinsci/jenkins/blob/master/core/src/main/resources/jenkins/security/s2m/MasterKillSwitchConfiguration/help-masterToagentAccessControl.html#L2 /content/redirect/security-144 -[NOTE] -.Enable Security -==== -Versions before Jenkins 2.214 and Jenkins LTS 2.222.1 -included an *Enable Security* checkbox on the *Configure Global Security* page. -This checkbox was selected by default -with the recommendation that it never be unchecked, -especially on production systems. -This enforced that only users who were authenticated -(in other words, logged in with with a username and password, -enforced either by Jenkins or by alernate Security Realm) -could access Jenkins. -The Jenkins user database was defined as the default security realm in these same releases. - -The "Enable Security" checkbox has been removed from current releases -(beginning with Jenkins 2.214 and Jenkins LTS 2.222.1) -because it should never be disabled. -==== - //// -Jenkins is used everywhere from workstations on corporate intranets, to -high-powered servers connected to the public internet. To safely support this -wide spread of security and threat profiles, Jenkins offers many configuration -options for enabling, editing, or disabling various security features. +The _Manage Jenkins >> Configure Global Security_ page allows a Jenkins administrator +to enable, configure, or disable key security features that apply to the entire +Jenkins environment. -As of Jenkins 2.0, many of the security options were enabled by default to +In Jenkins 2.0 and later, many of the security options are enabled by default to ensure that Jenkins environments remained secure unless an administrator -explicitly disabled certain protections. - -This section will introduce the various security options available to a Jenkins -administrator, explaining the protections offered, and trade-offs to disabling -some of them. +explicitly disables certain protections. -== Configure Global Security page - -The "Configure Global Security" section of the web UI allows a Jenkins administrator to -enable, configure, or disable key security features which apply to the entire -Jenkins environment. +This section introduces fields available on the _Configure Global Security_ page +and provides links to other pages that explain +the protections offered. ways to tweak the protection, and trade-offs for disabling some of them. image::security/configure-global-security.png["Configure Global Security", role=center] From db5a03e1d097419fc923b3ec5178fc744b193811 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 19 Oct 2021 21:51:43 -0700 Subject: [PATCH 10/59] Move TCP port info into its own page --- content/doc/book/security/_chapter.yml | 9 +++-- .../doc/book/security/managing-security.adoc | 18 --------- content/doc/book/security/tcp-port.adoc | 39 +++++++++++++++++++ 3 files changed, 44 insertions(+), 22 deletions(-) create mode 100644 content/doc/book/security/tcp-port.adoc diff --git a/content/doc/book/security/_chapter.yml b/content/doc/book/security/_chapter.yml index 4a67d2f8fea4..371c772ed1af 100644 --- a/content/doc/book/security/_chapter.yml +++ b/content/doc/book/security/_chapter.yml @@ -5,18 +5,19 @@ sections: # General information - concepts-security - controller-isolation - - access-control - -# Legacy sections - - securing-jenkins - managing-security # Individual how-to pages + - access-control + - tcp-port - markup-formatter - csrf-protection - user-content - build-authorization - environment-variables +# Legacy sections + - securing-jenkins + # Further references - services diff --git a/content/doc/book/security/managing-security.adoc b/content/doc/book/security/managing-security.adoc index e1acccacdb89..6ed5d98a592a 100644 --- a/content/doc/book/security/managing-security.adoc +++ b/content/doc/book/security/managing-security.adoc @@ -38,24 +38,6 @@ the protections offered. ways to tweak the protection, and trade-offs for disabl image::security/configure-global-security.png["Configure Global Security", role=center] -=== TCP Port - -Jenkins can use a TCP port to communicate with inbound (formerly known as “JNLP”) agents, -such as Windows-based agents. -As of Jenkins 2.0, by default this port is disabled. - -For administrators wishing to use inbound TCP agents, the two port options are: - - -. *Random*: The TCP port is chosen at random to avoid collisions on the Jenkins <<../glossary#controller,controller>>. - The downside to randomized ports is that they are chosen during the boot of the Jenkins controller, - making it difficult to manage firewall rules allowing TCP traffic. -. *Fixed*: The port is chosen by the Jenkins administrator and is consistent across reboots of the Jenkins controller. - This makes it easier to manage firewall rules allowing TCP-based agents to connect to the controller. - -As of Jenkins 2.217, inbound agents may instead be configured to use WebSocket transport to connect to Jenkins. -In this case no extra TCP port need be enabled and no special security configuration is needed. - === Access Control Access Control is the primary mechanism for securing a Jenkins environment diff --git a/content/doc/book/security/tcp-port.adoc b/content/doc/book/security/tcp-port.adoc new file mode 100644 index 000000000000..efe19b7d5d54 --- /dev/null +++ b/content/doc/book/security/tcp-port.adoc @@ -0,0 +1,39 @@ +--- +title: TCP Port for Inbound Agents +layout: section +--- + +Jenkins can use a TCP port to communicate with inbound (formerly known as “JNLP”) agents. +such as Windows-based agents. +The port for inbound agents can be used to launch an application on a client desktop +by using resources that are hosted on a remote web server. +In older Jenkins releases, +this was called the port for The JNLP (Java Network Launch Protocol), +which is used primarily by Windows-based agents. + +Other options for implenting this functionality include: + +* Modern versions of Windows can use SSH, which is a better option for connecting to agents in most cases. +* As of Jenkins 2.217, inbound agents may instead be configured to use WebSocket transport to connect to Jenkins. +In this case no extra TCP port need be enabled and no special security configuration is needed. + +As of Jenkins 2.0, this port is disabled by default +and you should leave this port disabled unless you have an explicit need for it. +If, however, you need to use inbound TCP agents, +you can enable this port in the *Agents* section of the _Configure Global Security_ page. +Two port options are available: + +. *Random*: The TCP port is chosen at random to avoid collisions on the Jenkins <<../glossary#controller,controller>>. + The downside to randomized ports is that they are chosen during the boot of the Jenkins controller. +This means that firewalls may no be able to secure a random port, +which makes it difficult to manage firewall rules allowing TCP traffic. +. *Fixed*: The port is chosen by the Jenkins administrator and is consistent across reboots of the Jenkins controller. +This is the more secure option, +because it makes it easier to manage firewall rules that allow TCP-based agents to connect to the controller. + +However, firewalls may not be able to secure a random port, +so the more secure option is to choose the btn:[Fixed] option +and define a TCP port to use for JNLP. +You can then configure your firewall accordingly. + + From 6639fec2b4ff96a56d8ef531da1b12a951bff4a0 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 19 Oct 2021 21:54:58 -0700 Subject: [PATCH 11/59] Removed a bit of crud --- content/doc/book/security/tcp-port.adoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/content/doc/book/security/tcp-port.adoc b/content/doc/book/security/tcp-port.adoc index efe19b7d5d54..a6a189da3767 100644 --- a/content/doc/book/security/tcp-port.adoc +++ b/content/doc/book/security/tcp-port.adoc @@ -31,9 +31,5 @@ which makes it difficult to manage firewall rules allowing TCP traffic. This is the more secure option, because it makes it easier to manage firewall rules that allow TCP-based agents to connect to the controller. -However, firewalls may not be able to secure a random port, -so the more secure option is to choose the btn:[Fixed] option -and define a TCP port to use for JNLP. -You can then configure your firewall accordingly. From 5e0b5030ccf4c738b21459d62976fa6652667354 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 19 Oct 2021 22:16:14 -0700 Subject: [PATCH 12/59] Rename securing-jenkins to be a placeholder for those wiki links --- content/doc/book/security/access-control.adoc | 6 ++--- .../doc/book/security/securing-jenkins.adoc | 26 ++----------------- 2 files changed, 5 insertions(+), 27 deletions(-) diff --git a/content/doc/book/security/access-control.adoc b/content/doc/book/security/access-control.adoc index 70c56aebfeaf..fc325aa17323 100644 --- a/content/doc/book/security/access-control.adoc +++ b/content/doc/book/security/access-control.adoc @@ -1,5 +1,5 @@ --- -title: Access Control +title: Jenkins Access Control layout: section --- :toc: @@ -7,9 +7,9 @@ layout: section Jenkins access control is split into two parts: -* Authentication (users prove who they are) is done using a _security realm_. +* Authentication (control who can access the Jenkins instance) is done using a _security realm_. The security realm determines user identity and group memberships. -* Authorization (users are permitted to do something) is done by an _authorization strategy_. +* Authorization (determine who is allowed to do what on the Jenkins instance) is done by an _authorization strategy_. This controls whether a user (directly or through group memberships) has a permission. These can be independent, or work in combination. diff --git a/content/doc/book/security/securing-jenkins.adoc b/content/doc/book/security/securing-jenkins.adoc index 822484068846..b81fa911344b 100644 --- a/content/doc/book/security/securing-jenkins.adoc +++ b/content/doc/book/security/securing-jenkins.adoc @@ -1,4 +1,5 @@ --- +title: Other Security Topics layout: section wip: true --- @@ -12,30 +13,7 @@ ifndef::env-github[:imagesdir: ../../resources] :toc: left endif::[] -= Securing Jenkins - -Securing Jenkins has two aspects to it. - -* Access control, which ensures users are authenticated when accessing Jenkins - and their activities are authorized. -* Protecting Jenkins against external threats - -== Access Control - -You should lock down the access to Jenkins UI so that users are authenticated -and appropriate set of permissions are given to them. This setting is -controlled mainly by two axes: - -* *Security Realm*, which determines users and their passwords, as well as what - groups the users belong to. -* *Authorization Strategy*, which determines who has access to what. - -These two axes are orthogonal, and need to be individually configured. For -example, you might choose to use external LDAP or Active Directory as the -security realm, and you might choose "everyone full access once logged in" mode -for authorization strategy. Or you might choose to let Jenkins run its own user -database, and perform access control based on the permission/user matrix. - +This page is a placeholder for links to some old Wiki pages until we can properly dispose of this information. * https://wiki.jenkins.io/display/JENKINS/Quick+and+Simple+Security[Quick and Simple Security] --- if you are running Jenkins like `java -jar jenkins.war` and only need a very simple setup * https://wiki.jenkins.io/display/JENKINS/Standard+Security+Setup[Standard Security Setup] --- discusses the most common setup of letting Jenkins run its own user database and do finer-grained access control From 5f4e5d4f5cc4bf0708a0f06286fcc5c01ca9ec84 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 20 Oct 2021 01:36:24 -0700 Subject: [PATCH 13/59] Remove "Agents and Security" info from index.ado --- content/doc/book/security/index.adoc | 30 ---------------------------- 1 file changed, 30 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 29565c25fec6..8fa9307b63fe 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -49,36 +49,6 @@ you may be able to re-enable that protection to increase the security of your instance. ==== -== Agents and Security - -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; -you can learn more about this https://wiki.jenkins.io/display/JENKINS/Distributed+builds[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. - -Never run builds on the Jenkins controller in production environments. -A build job that uses an agent running on the built-in controller node -has access to Jenkins controller files and configuration, which poses a security risk. -Configuring Jenkins as a distributed system, -where builds execute on agents that are separate from the controller -instead of the built-in node on the controller, -enhances the security of your Jenkins instance -as well as improving its performance and making it more stable. - -An agent that executes on the Jenkins controller -may be able to access Jenkins configuration files and the workspaces of other builds. -An agent could also request information -that belongs to other teams or organizations that share the controller. - -An agent can also write malicious code to its local disk so that the node is tainted. -For maximum security, run all builds on ephemeral agents in the cloud -that are destroyed at the end of each build job. -NOTE: A job that performs administrative tasks such as backups may run on the controller, -but be sure to label the executor and only allow it to be used by jobs that specify that label. - // TODO the following only makes sense on the web site, not the PDF. Can it be disabled there? // TODO the material below should be moved to other sections in this chapter. From 557c68de1c92acac3b05c9f74d6e81c037942898 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 20 Oct 2021 01:50:22 -0700 Subject: [PATCH 14/59] Move Access Control info from managing-security to access-control --- content/doc/book/security/access-control.adoc | 137 ++++++++++++++++++ .../doc/book/security/managing-security.adoc | 124 +--------------- 2 files changed, 139 insertions(+), 122 deletions(-) diff --git a/content/doc/book/security/access-control.adoc b/content/doc/book/security/access-control.adoc index fc325aa17323..0020717a6853 100644 --- a/content/doc/book/security/access-control.adoc +++ b/content/doc/book/security/access-control.adoc @@ -84,3 +84,140 @@ For more details about the various permissions in Jenkins and the level of acces == Disabling Access Control See link:/doc/book/security/access-control/disable/[Disable Access Control]. + +== From managing-jenkins + +=== Access Control + +Access Control is the primary mechanism for securing a Jenkins environment +against unauthorized usage. Two facets of configuration are necessary for +configuring Access Control in Jenkins: + +. A *Security Realm* which informs the Jenkins environment how and where to + pull user (or identity) information from. Also commonly known as "authentication." +. *Authorization* configuration which informs the Jenkins environment as to + which users and/or groups can access which aspects of Jenkins, and to what + extent. + + +Using both the Security Realm and Authorization configurations it is possible +to configure very relaxed or very rigid authentication and authorization +schemes in Jenkins. + +Additionally, some plugins such as the +plugin:role-strategy[Role-based Authorization Strategy] +plugin can extend the Access Control capabilities of Jenkins to support even +more nuanced authentication and authorization schemes. + +==== Security Realm + +By default Jenkins includes support for a few different Security Realms: + +Delegate to servlet container:: For delegating authentication a servlet +container running the Jenkins controller, such as +link:https://www.eclipse.org/jetty/[Jetty]. If using this option, please consult +the servlet container's authentication documentation. +Jenkins’ own user database:: Use Jenkins's own built-in user data store for +authentication instead of delegating to an external system. This is enabled by +default with new Jenkins 2.0 or later installations and is suitable for smaller +environments. +LDAP:: Delegate all authentication to a configured LDAP server, including both +users and groups. This option is more common for larger installations in +organizations which already have configured an external identity provider such +as LDAP. This also supports Active Directory installations. + + +[NOTE] +==== +This feature is provided by the plugin:ldap[LDAP plugin] +that may not be installed on your instance. +==== + +Unix user/group database:: Delegates the authentication to the underlying Unix +OS-level user database on the Jenkins controller. This mode will also allow re-use +of Unix groups for authorization. For example, Jenkins can be configured such +that "Everyone in the `developers` group has administrator access." To support this feature, Jenkins relies on +link:https://en.wikipedia.org/wiki/Pluggable_Authentication_Modules[PAM] +which may need to be configured external to the Jenkins environment. + + +[CAUTION] +==== +Unix allows an user and a group to have the same name. In order to +disambiguate, use the `@` prefix to force the name to be interpreted as +a group. For example, `@dev` would mean the `dev` group and not the `dev` user. +==== + +--- + + +Plugins can provide additional security realms which may be useful for +incorporating Jenkins into existing identity systems, such as: + +* plugin:active-directory[Active Directory] +* plugin:github-oauth[GitHub Authentication] +* plugin:crowd2[Atlassian Crowd 2] + +==== Authorization + + +The Security Realm, or authentication, indicates _who_ can access the Jenkins +environment. The other piece of the puzzle is *Authorization*, which indicates +_what_ they can access in the Jenkins environment. By default Jenkins supports +a few different Authorization options: + + +Anyone can do anything:: Everyone gets full control of Jenkins, including +anonymous users who haven't logged in. *Do not use this setting* for anything +other than local test Jenkins controllers. +Legacy mode:: Behaves exactly the same as Jenkins <1.164. Namely, if a user has +the "admin" role, they will be granted full control over the system, and otherwise +(including anonymous users) will only have the read access. *Do not use this +setting* for anything other than local test Jenkins controllers. +Logged in users can do anything:: In this mode, every logged-in user gets full +control of Jenkins. Depending on an advanced option, anonymous users get read +access to Jenkins, or no access at all. This mode is useful to force users to +log in before taking actions, so that there is an audit trail of users' actions. +Matrix-based security:: This authorization scheme allows for granular control +over which users and groups are able to perform which actions in the Jenkins +environment (see the screenshot below). +Project-based Matrix Authorization Strategy:: This authorization scheme is an +extension to Matrix-based security which allows additional access control lists +(ACLs) to be defined for *each project* separately in the Project configuration +screen. This allows granting specific users or groups access only to specified +projects, instead of all projects in the Jenkins environment. The ACLs defined +with Project-based Matrix Authorization are additive such that access grants +defined in the Configure Global Security screen will be combined with +project-specific ACLs. + +[NOTE] +==== +Matrix-based security and Project-based Matrix Authorization Strategy are provided +by the plugin:matrix-auth[Matrix Authorization Strategy Plugin] +and may not be installed on your Jenkins. +==== + + +For most Jenkins environments, Matrix-based security provides the most security +and flexibility so it is recommended as a starting point for "production" +environments. + +.Matrix-based security +image::security/configure-global-security-matrix-authorization.png["Configure Global Security - Matrix authorization", role=center] + + +The table shown above can get quite wide as each column represents a permission +provided by Jenkins core or a plugin. Hovering the mouse over a permission will +display more information about the permission. + +Each row in the table represents a user or group (also known as a "role"). This +includes special entries named "anonymous" and "authenticated." The "anonymous" +entry represents permissions granted to all unauthenticated users accessing the +Jenkins environment. Whereas "authenticated' can be used to grant permissions +to all authenticated users accessing the environment. + +The permissions granted in the matrix are additive. For example, if a user +"kohsuke" is in the groups "developers" and "administrators", then the +permissions granted to "kohsuke" will be a union of all those permissions +granted to "kohsuke", "developers", "administrators", "authenticated", and +"anonymous." diff --git a/content/doc/book/security/managing-security.adoc b/content/doc/book/security/managing-security.adoc index 6ed5d98a592a..d968f26b3c11 100644 --- a/content/doc/book/security/managing-security.adoc +++ b/content/doc/book/security/managing-security.adoc @@ -38,7 +38,7 @@ the protections offered. ways to tweak the protection, and trade-offs for disabl image::security/configure-global-security.png["Configure Global Security", role=center] -=== Access Control +== Access Control Access Control is the primary mechanism for securing a Jenkins environment against unauthorized usage. Two facets of configuration are necessary for @@ -50,131 +50,11 @@ configuring Access Control in Jenkins: which users and/or groups can access which aspects of Jenkins, and to what extent. - Using both the Security Realm and Authorization configurations it is possible to configure very relaxed or very rigid authentication and authorization schemes in Jenkins. -Additionally, some plugins such as the -plugin:role-strategy[Role-based Authorization Strategy] -plugin can extend the Access Control capabilities of Jenkins to support even -more nuanced authentication and authorization schemes. - - -==== Security Realm - -By default Jenkins includes support for a few different Security Realms: - -Delegate to servlet container:: For delegating authentication a servlet -container running the Jenkins controller, such as -link:https://www.eclipse.org/jetty/[Jetty]. If using this option, please consult -the servlet container's authentication documentation. -Jenkins’ own user database:: Use Jenkins's own built-in user data store for -authentication instead of delegating to an external system. This is enabled by -default with new Jenkins 2.0 or later installations and is suitable for smaller -environments. -LDAP:: Delegate all authentication to a configured LDAP server, including both -users and groups. This option is more common for larger installations in -organizations which already have configured an external identity provider such -as LDAP. This also supports Active Directory installations. - - -[NOTE] -==== -This feature is provided by the plugin:ldap[LDAP plugin] -that may not be installed on your instance. -==== - -Unix user/group database:: Delegates the authentication to the underlying Unix -OS-level user database on the Jenkins controller. This mode will also allow re-use -of Unix groups for authorization. For example, Jenkins can be configured such -that "Everyone in the `developers` group has administrator access." To support this feature, Jenkins relies on -link:https://en.wikipedia.org/wiki/Pluggable_Authentication_Modules[PAM] -which may need to be configured external to the Jenkins environment. - - -[CAUTION] -==== -Unix allows an user and a group to have the same name. In order to -disambiguate, use the `@` prefix to force the name to be interpreted as -a group. For example, `@dev` would mean the `dev` group and not the `dev` user. -==== - ---- - - -Plugins can provide additional security realms which may be useful for -incorporating Jenkins into existing identity systems, such as: - -* plugin:active-directory[Active Directory] -* plugin:github-oauth[GitHub Authentication] -* plugin:crowd2[Atlassian Crowd 2] - -==== Authorization - - -The Security Realm, or authentication, indicates _who_ can access the Jenkins -environment. The other piece of the puzzle is *Authorization*, which indicates -_what_ they can access in the Jenkins environment. By default Jenkins supports -a few different Authorization options: - - -Anyone can do anything:: Everyone gets full control of Jenkins, including -anonymous users who haven't logged in. *Do not use this setting* for anything -other than local test Jenkins controllers. -Legacy mode:: Behaves exactly the same as Jenkins <1.164. Namely, if a user has -the "admin" role, they will be granted full control over the system, and otherwise -(including anonymous users) will only have the read access. *Do not use this -setting* for anything other than local test Jenkins controllers. -Logged in users can do anything:: In this mode, every logged-in user gets full -control of Jenkins. Depending on an advanced option, anonymous users get read -access to Jenkins, or no access at all. This mode is useful to force users to -log in before taking actions, so that there is an audit trail of users' actions. -Matrix-based security:: This authorization scheme allows for granular control -over which users and groups are able to perform which actions in the Jenkins -environment (see the screenshot below). -Project-based Matrix Authorization Strategy:: This authorization scheme is an -extension to Matrix-based security which allows additional access control lists -(ACLs) to be defined for *each project* separately in the Project configuration -screen. This allows granting specific users or groups access only to specified -projects, instead of all projects in the Jenkins environment. The ACLs defined -with Project-based Matrix Authorization are additive such that access grants -defined in the Configure Global Security screen will be combined with -project-specific ACLs. - -[NOTE] -==== -Matrix-based security and Project-based Matrix Authorization Strategy are provided -by the plugin:matrix-auth[Matrix Authorization Strategy Plugin] -and may not be installed on your Jenkins. -==== - - -For most Jenkins environments, Matrix-based security provides the most security -and flexibility so it is recommended as a starting point for "production" -environments. - -.Matrix-based security -image::security/configure-global-security-matrix-authorization.png["Configure Global Security - Matrix authorization", role=center] - - -The table shown above can get quite wide as each column represents a permission -provided by Jenkins core or a plugin. Hovering the mouse over a permission will -display more information about the permission. - -Each row in the table represents a user or group (also known as a "role"). This -includes special entries named "anonymous" and "authenticated." The "anonymous" -entry represents permissions granted to all unauthenticated users accessing the -Jenkins environment. Whereas "authenticated' can be used to grant permissions -to all authenticated users accessing the environment. - -The permissions granted in the matrix are additive. For example, if a user -"kohsuke" is in the groups "developers" and "administrators", then the -permissions granted to "kohsuke" will be a union of all those permissions -granted to "kohsuke", "developers", "administrators", "authenticated", and -"anonymous." - -=== Markup Formatter +== Markup Formatter See link:/doc/book/security/markup-formatter/[Markup Formatter]. From 0eeeb0b3dadc03cdbf95a10b0c94fbcb9824ac14 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 20 Oct 2021 02:49:53 -0700 Subject: [PATCH 15/59] Add "story" (outline of chapter) to index.adoc --- .../book/security/controller-isolation.adoc | 2 +- content/doc/book/security/index.adoc | 61 ++++++++++++------- 2 files changed, 40 insertions(+), 23 deletions(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index f878f17cd029..efee3b423479 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -1,5 +1,5 @@ --- -title: Distributed Build Architecture +title: Distributed Builds layout: section --- ifdef::backend-html5[] diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 8fa9307b63fe..601d7122ef7a 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -34,9 +34,6 @@ Other security options involve environment-specific setup and trade-offs and depend on specific use cases supported for individual Jenkins instances. Configuration options allow you to enable, customize, or disable security features. -This chapter introduces the various security options available to Jenkins administrators and users, -explaining the protections offered, and trade-offs to disabling some of them. - [CAUTION] ==== Most Jenkins environments grow over time, @@ -52,20 +49,48 @@ to increase the security of your instance. // TODO the following only makes sense on the web site, not the PDF. Can it be disabled there? // TODO the material below should be moved to other sections in this chapter. -== Basic Setup +This chapter introduces the various security options available to Jenkins administrators and users, +explaining the protections offered, and trade-offs to disabling some of them: -link:controller-isolation[Controller Isolation]:: +link:concepts-security[Background Concepts]:: +Discusses security principles that should guide all your decisions about security +and explains how Jenkins executes a Pipeline so you understand where intrusions can occur if your security configuration is lax. + +link:controller-isolation[Distributed Builds]:: Builds should not be executed on the built-in node, but that is just the beginning: This section discusses what other steps can be taken to protect the controller from being impacted by running builds. + *This needs to be configured according to the needs of your environment.* -link:access-control[Access Control]:: +link:controller-isolation[Configure Global Security]:: +Much of the basic security configuration is implemented on the _Manage Jenkins >> Configure Global Security_ page. +Here you see the fields that are configured on that page and get links to other sections that explain each field in detail. + +link:access-control[Jenkins Access Control]:: By default, Jenkins does not allow anonymous access, and a single admin user exists. This chapter discusses which level of access is provided by permissions and how to safely grant access to more users. + _This is set up securely by the setup wizard. If the setup wizard is disabled on first launch, this may not be configured securely by default._ +link:tcp-port[TCP Port for InBound Agents]:: +If you are using TCP for inbound agents (previously called JNLP), +you must configure a TCP port to use. +This section discusses how to configure the TCP port and discusses alternative implementations that do not require the TCP port. + +*The TCP Port is disabled by default and should only be enabled if you need it.* -== Build Behavior +link:markup-formatter[Markup Formatter]:: +The default markup formatter renders text as entered (i.e. escaping HTML metacharacters). +This chapter explains how to switch to a different markup formatter and explains what admins need to be aware of. + +_This is set up securely by default._ + +link:csrf-protection[CSRF Protection]:: +Jenkins protects from cross-site request forgery (CSRF) by default. +This chapter explains how to work around any problems this may cause. + +_This is set up securely by default._ +// TODO Confirm that skipping the setup wizard in 2.222 does no longer disable CSRF protection + +link:user-content[Rendering User Content]:: +By default, Jenkins strictly limits the features useable in user content (files from workspaces, archived artifacts, etc.) it serves. +This chapter discusses how to customize this and make HTML reports and similar content both functional and safe to view. + +_This is set up securely by default._ link:build-authorization[Access Control for Builds]:: Learn how to restrict what individual builds can do in Jenkins once they're running. + @@ -76,21 +101,13 @@ Improperly written build scripts may be tricked into behaving differently than i This section discusses how to protect your builds. + *This needs to be configured according to the needs of your environment.* +link:securing-jenkins[Other Security Topics]:: +This is a placeholder for links to old Wiki articles relevant to Security. +These pages are not currently available. +Some of these articles are obsolete or irrelevant and others need to be rewritten and incorporated into the documentation. -== User Interface +link:services[Exposed Services and Ports]:: +Jenkins is a complex application that may expose services on the network. +This chapter provides information about these services. -link:csrf-protection[CSRF Protection]:: -Jenkins protects from cross-site request forgery (CSRF) by default. -This chapter explains how to work around any problems this may cause. + -_This is set up securely by default._ -// TODO Confirm that skipping the setup wizard in 2.222 does no longer disable CSRF protection -link:markup-formatter[Markup Formatter]:: -The default markup formatter renders text as entered (i.e. escaping HTML metacharacters). -This chapter explains how to switch to a different markup formatter and explains what admins need to be aware of. + -_This is set up securely by default._ - -link:user-content[Rendering User Content]:: -By default, Jenkins strictly limits the features useable in user content (files from workspaces, archived artifacts, etc.) it serves. -This chapter discusses how to customize this and make HTML reports and similar content both functional and safe to view. + -_This is set up securely by default._ From 70098e6706953ab851e1eee020eadb7fba3a2ccd Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 22 Oct 2021 22:04:12 -0700 Subject: [PATCH 16/59] Consolidate access control info in one page --- content/doc/book/security/access-control.adoc | 247 ++++++++++-------- .../doc/book/security/managing-security.adoc | 19 +- 2 files changed, 154 insertions(+), 112 deletions(-) diff --git a/content/doc/book/security/access-control.adoc b/content/doc/book/security/access-control.adoc index 0020717a6853..86c91b97d15f 100644 --- a/content/doc/book/security/access-control.adoc +++ b/content/doc/book/security/access-control.adoc @@ -4,129 +4,62 @@ layout: section --- :toc: :toclevels: 4 +link:access-control[Jenkins Access Control]:: -Jenkins access control is split into two parts: +Jenkins access control is split into two parts, both configured on the _Manage Jenkins >> Configure Global Security_ page.: * Authentication (control who can access the Jenkins instance) is done using a _security realm_. The security realm determines user identity and group memberships. * Authorization (determine who is allowed to do what on the Jenkins instance) is done by an _authorization strategy_. This controls whether a user (directly or through group memberships) has a permission. -These can be independent, or work in combination. -An independent configuration would be plugin:active-directory[Active Directory] or plugin:ldap[LDAP] as security realm, and something like plugin:matrix-auth[Matrix Authorization Strategy] as authorization strategy. -An example for related security realm and authorization strategy configuration is plugin:github-oauth[GitHub Authentication]: -While its security realm can be used with a generic authorization strategy, it also provides an authorization strategy that looks up a user's repository permissions on GitHub, and grants or denies permissions to related jobs in Jenkins based on that. +These can be independent, or work in combination: -[NOTE] -==== -Jenkins could be set up to have basic access control happen outside of it. +* An example of an independent configuration is using plugin:active-directory[Active Directory] or plugin:ldap[LDAP] as security realm, and something like plugin:matrix-auth[Matrix Authorization Strategy] as the authorization strategy. +* An example of a related security realm and authorization strategy configuration is plugin:github-oauth[GitHub Authentication]. +While the Github Authentication security realm can be used with a generic authorization strategy, it also provides an authorization strategy that looks up a user's repository permissions on GitHub, and grants or denies permissions to related jobs in Jenkins based on that. + +Jenkins can be set up to have basic access control happen outside of it. Some examples: * The built-in https://github.com/jenkinsci/winstone[Winstone/Jetty servlet container wrapper] provides options that implement a basic security realm outside Jenkins. * If Jenkins is running behind a reverse proxy like Nginx or Apache, those can limit access to Jenkins. An advantage of these approaches is that they do not allow any access to Jenkins unless a user is authorized, reducing the impact of security issues in Jenkins or plugins especially when accessible from the internet. -A disadvantage is the lack of integration with Jenkins access controls and potentially even interfering with it (e.g. when trying to authenticate scripted clients). -==== - -== Common Configuration Mistakes - -When configuring authentication and authorization in Jenkins, it is easy to accidentally allow far more access than intended. -See link:/doc/book/security/access-control/permissions/#administer[the documentation on the access given to administrators] about the impact of unintentionally granting Administer permission. +A disadvantage is the lack of integration with Jenkins access controls and potentially even interfering with it (such as when trying to authenticate scripted clients). -_Anyone can do anything_:: -This authorization strategy is very rarely a good choice, as it allows even anonymous users to administer Jenkins. -As a rule of thumb, it should not be used. -Never rely on the Jenkins URL to not be known outside your team or organization alone for security. - -_Logged-in users can do anything_:: -This authorization strategy can be a sensible choice as long as only fully trusted users have accounts to access Jenkins. -This is the default with Jenkins's single admin user when setting up Jenkins with the setup wizard. -+ -Switching to an authentication realm that allows untrusted users to have an account later will result in those users getting administrative access to Jenkins if you keep this authorization stategy. -Examples include enabling account signup for _Jenkins' own user database_, or various other authorization realms, many of which (GitHub, Google, GitLab, etc.) allow anyone to sign up for an account. - -Anonymous and authenticated users:: -Similar to the previous items, you should generally not grant significant permissions to `anonymous` (the anonymous user) or authenticated (any authenticated user) when using an authorization strategy that allows finer-grained control (like plugin:matrix-auth[Matrix Authorization Strategy]). -Granting Overall/Administer permission to _anonymous_ is similar to _Anyone can do anything_, while granting that permission to _authenticated_ is essentially the same as _Logged-in users can do anything_. - -Built-in node:: -Users with limited permissions link:/doc/book/security/controller-isolation/[must not be able to configure jobs that run on the built-in node]. -When setting up a new Jenkins instance, adding users and switching authorization strategies, it is important to also set up distributed builds and limit what jobs are able to run on the built-in node. - -//In addition to the above items that discuss who may (effectively) be granted administrative access to Jenkins, you should be careful who you give any read access to Jenkins. -//See link:/doc/book/security/access-control/permissions/#overall-read[the documentation of the level of access that granting basic read access gives]. - -== Permissions - -At a very basic level, the _Overall/Read_ permission provides users some basic access to Jenkins. -This permission is a prerequisite for more substantial access to Jenkins. -Without this permission, only very few features explicitly intended to be used without authentication are available. - -The highest level of permissions is _Overall/Administer_. -With this permission, users can upload and install plugins and have access to the link:/doc/book/managing/script-console/[Script Console]. - -Between these two extremes is finer-grained permission control involving other permissions. -Permissions in Jenkins have a _scope_: They can be granted globally, on an item (like a folder or job), on a build, etc. -Whenever a user attempts to do something that is protected by permissions, the authorization strategy is checked for whether the current user has the specific permission (e.g., _Job/Read_) on the specific object (e.g., a job). -Exactly how permissions are assigned and whether and how they're inherited is controlled by the specific authorization strategy. - -As an example, plugin:matrix-auth[Matrix Authorization Strategy] provides two different authorization strategies: - -* One provides a single global configuration of all permissions. - A user granted _Item/Read_ will be granted that permission everywhere. -* One provides a project-based configuration. - In this model, permissions can be granted globally (as in the previous strategy), or only on specific folders, jobs, or agents. - Permissions are by default inherited, but that can be customized as well, so that users granted _Item/Read_ globally or on a parent folder may be excluded from access to a job. - -For more details about the various permissions in Jenkins and the level of access they grant, see link:/doc/book/security/access-control/permissions/[Permissions]. - -== Disabling Access Control - -See link:/doc/book/security/access-control/disable/[Disable Access Control]. - -== From managing-jenkins - -=== Access Control - -Access Control is the primary mechanism for securing a Jenkins environment -against unauthorized usage. Two facets of configuration are necessary for -configuring Access Control in Jenkins: - -. A *Security Realm* which informs the Jenkins environment how and where to - pull user (or identity) information from. Also commonly known as "authentication." -. *Authorization* configuration which informs the Jenkins environment as to - which users and/or groups can access which aspects of Jenkins, and to what - extent. - - -Using both the Security Realm and Authorization configurations it is possible -to configure very relaxed or very rigid authentication and authorization -schemes in Jenkins. - -Additionally, some plugins such as the -plugin:role-strategy[Role-based Authorization Strategy] -plugin can extend the Access Control capabilities of Jenkins to support even -more nuanced authentication and authorization schemes. +Using both the Security Realm and Authorization configurations, +you can configure very relaxed or very rigid authentication and authorization schemes +with different degrees of granularity in Jenkins. ==== Security Realm +The *Security Realm* defines the source of authenticated user (or identity) information. By default Jenkins includes support for a few different Security Realms: Delegate to servlet container:: For delegating authentication a servlet container running the Jenkins controller, such as link:https://www.eclipse.org/jetty/[Jetty]. If using this option, please consult the servlet container's authentication documentation. + Jenkins’ own user database:: Use Jenkins's own built-in user data store for authentication instead of delegating to an external system. This is enabled by default with new Jenkins 2.0 or later installations and is suitable for smaller environments. +When this is implemented, use the _Manage Jenkins >> Manage Users_ page +to define users in the Jenkins user database. +By default, users and groups come from the Jenkins internal user database. +Smaller, more informal installations can use this internal database, +but Enterprise installations usually use a corporate service +(LDAP, AD, or UNIX), +so that users can log into Jenkins with their usual username and password. + LDAP:: Delegate all authentication to a configured LDAP server, including both users and groups. This option is more common for larger installations in organizations which already have configured an external identity provider such as LDAP. This also supports Active Directory installations. - +// Isn't LDAP now a suggested plugin? Delete this note? [NOTE] ==== This feature is provided by the plugin:ldap[LDAP plugin] @@ -150,34 +83,70 @@ a group. For example, `@dev` would mean the `dev` group and not the `dev` user. --- - Plugins can provide additional security realms which may be useful for incorporating Jenkins into existing identity systems, such as: +// Let's discuss what to do with this list, etc + * plugin:active-directory[Active Directory] * plugin:github-oauth[GitHub Authentication] +* plugin:role-strategy[Role-based Authorization Strategy] * plugin:crowd2[Atlassian Crowd 2] +* SAML 2.0 Single Sign On facility -==== Authorization +To see a list of all plugins for alternate security realms +and other authentication tools: +. Go to menu:Manage Jenkins[Manage Plugins]. +. Select the *Available* tab. +. Enter "Authentication and User Management" into the search box. + +This displays a list of relevant plugins. +You can right-click the name of any plugin to read more about it. + +For demonstrations and testing, consider using the +link:https://plugins.jenkins.io/mock-security-realm/[Mock Security Realm]. +This provides an insecure security realm that is easy to set up. + +== Authorization The Security Realm, or authentication, indicates _who_ can access the Jenkins environment. The other piece of the puzzle is *Authorization*, which indicates _what_ they can access in the Jenkins environment. By default Jenkins supports a few different Authorization options: - Anyone can do anything:: Everyone gets full control of Jenkins, including -anonymous users who haven't logged in. *Do not use this setting* for anything +anonymous users who haven't logged in. + +*Do not use this setting* for anything other than local test Jenkins controllers. + +This authorization strategy is very rarely a good choice, as it allows even anonymous users to administer Jenkins. +As a rule of thumb, it should not be used. +Never rely on the Jenkins URL to not be known outside your team or organization alone for security. + Legacy mode:: Behaves exactly the same as Jenkins <1.164. Namely, if a user has the "admin" role, they will be granted full control over the system, and otherwise (including anonymous users) will only have the read access. *Do not use this setting* for anything other than local test Jenkins controllers. -Logged in users can do anything:: In this mode, every logged-in user gets full -control of Jenkins. Depending on an advanced option, anonymous users get read -access to Jenkins, or no access at all. This mode is useful to force users to + +Logged in users can do anything:: +In this mode, every logged-in user gets full control of Jenkins. +Depending on an advanced option, anonymous users get read +access to Jenkins, or no access at all. +This mode is useful to force users to log in before taking actions, so that there is an audit trail of users' actions. + +This authorization strategy is the default with Jenkins's single admin user when setting up Jenkins with the setup wizard. +It can be a sensible choice as long as only fully trusted users have accounts to access Jenkins. +//// +Need to look at this more closely. I'm not sure why "later" is relevant +(unless assuming that you do this initially and then move onto a different option. +Isn't the gating factor whether the security realm is one that is restricted +or allows anyone to create their own account? +//// +However, if you later switch to an authentication realm that allows untrusted users to have an account, those users may get administrative access to Jenkins if you keep this authorization stategy. +Examples include enabling account signup for _Jenkins' own user database_, or various other authorization realms, many of which (GitHub, Google, GitLab, etc.) allow anyone to sign up for an account. + Matrix-based security:: This authorization scheme allows for granular control over which users and groups are able to perform which actions in the Jenkins environment (see the screenshot below). @@ -187,28 +156,36 @@ extension to Matrix-based security which allows additional access control lists screen. This allows granting specific users or groups access only to specified projects, instead of all projects in the Jenkins environment. The ACLs defined with Project-based Matrix Authorization are additive such that access grants -defined in the Configure Global Security screen will be combined with -project-specific ACLs. +defined in the Configure Global Security screen will be combined with project-specific ACLs. -[NOTE] -==== -Matrix-based security and Project-based Matrix Authorization Strategy are provided -by the plugin:matrix-auth[Matrix Authorization Strategy Plugin] -and may not be installed on your Jenkins. -==== +//// +If we're including Project-based, should we also include role-based authorization strategy (the open source one)? +I think both are now installed as part of suggested plugins but need to verify. +//// +== Matrix-based security +//// +Need to expand this section but it can be in a separate PR +//// For most Jenkins environments, Matrix-based security provides the most security and flexibility so it is recommended as a starting point for "production" environments. .Matrix-based security +// I can't figure out why this image is not playing out image::security/configure-global-security-matrix-authorization.png["Configure Global Security - Matrix authorization", role=center] +[NOTE] +==== +Matrix-based security and Project-based Matrix Authorization Strategy are provided +by the plugin:matrix-auth[Matrix Authorization Strategy Plugin] +and may not be installed on your Jenkins. +==== The table shown above can get quite wide as each column represents a permission -provided by Jenkins core or a plugin. Hovering the mouse over a permission will -display more information about the permission. +provided by Jenkins core or a plugin. Hovering the mouse over a permission +displays more information about the permission. Each row in the table represents a user or group (also known as a "role"). This includes special entries named "anonymous" and "authenticated." The "anonymous" @@ -221,3 +198,59 @@ The permissions granted in the matrix are additive. For example, if a user permissions granted to "kohsuke" will be a union of all those permissions granted to "kohsuke", "developers", "administrators", "authenticated", and "anonymous." + +== Permissions + +//// +Need to expand this section with some "basics" about how permissions are grouped +by object, and columns can be added by plugins, etc. +//// + +At a very basic level, the _Overall/Read_ permission provides users some basic access to Jenkins. +This permission is a prerequisite for more substantial access to Jenkins. +Without this permission, only very few features explicitly intended to be used without authentication are available. + +The highest level of permissions is _Overall/Administer_. +With this permission, users can upload and install plugins and have access to the link:/doc/book/managing/script-console/[Script Console]. + +Between these two extremes is finer-grained permission control involving other permissions. +Permissions in Jenkins have a _scope_: They can be granted globally, on an item (like a folder or job), on a build, etc. +Whenever a user attempts to do something that is protected by permissions, the authorization strategy is checked for whether the current user has the specific permission (e.g., _Job/Read_) on the specific object (e.g., a job). +Exactly how permissions are assigned and whether and how they're inherited is controlled by the specific authorization strategy. + +As an example, plugin:matrix-auth[Matrix Authorization Strategy] provides two different authorization strategies: + +* One provides a single global configuration of all permissions. + A user granted _Item/Read_ will be granted that permission everywhere. +* One provides a project-based configuration. + In this model, permissions can be granted globally (as in the previous strategy), or only on specific folders, jobs, or agents. + Permissions are by default inherited, but that can be customized as well, so that users granted _Item/Read_ globally or on a parent folder may be excluded from access to a job. + +For more details about the various permissions in Jenkins and the level of access they grant, see link:/doc/book/security/access-control/permissions/[Permissions]. + +== Common Configuration Mistakes + +//// +I integrated a couple of these into the descriptions of the authorization strategies. +The others persist here, for now. +//// + +When configuring authentication and authorization in Jenkins, it is easy to accidentally allow far more access than intended. +See link:/doc/book/security/access-control/permissions/#administer[the documentation on the access given to administrators] about the impact of unintentionally granting Administer permission. + +Anonymous and authenticated users:: +Similar to the previous items, you should generally not grant significant permissions to `anonymous` (the anonymous user) or authenticated (any authenticated user) when using an authorization strategy that allows finer-grained control (like plugin:matrix-auth[Matrix Authorization Strategy]). +Granting Overall/Administer permission to _anonymous_ is similar to _Anyone can do anything_, while granting that permission to _authenticated_ is essentially the same as _Logged-in users can do anything_. + +Built-in node:: +// What about doing the link for "distributed builds" in next sentence? +Users with limited permissions link:/doc/book/security/controller-isolation/[must not be able to configure jobs that run on the built-in node]. +When setting up a new Jenkins instance, adding users and switching authorization strategies, it is important to also set up distributed builds and limit what jobs are able to run on the built-in node. + +//In addition to the above items that discuss who may (effectively) be granted administrative access to Jenkins, you should be careful who you give any read access to Jenkins. +//See link:/doc/book/security/access-control/permissions/#overall-read[the documentation of the level of access that granting basic read access gives]. + +== Disabling Access Control + +See link:/doc/book/security/access-control/disable/[Disable Access Control]. + diff --git a/content/doc/book/security/managing-security.adoc b/content/doc/book/security/managing-security.adoc index d968f26b3c11..7ee110d33260 100644 --- a/content/doc/book/security/managing-security.adoc +++ b/content/doc/book/security/managing-security.adoc @@ -34,17 +34,26 @@ explicitly disables certain protections. This section introduces fields available on the _Configure Global Security_ page and provides links to other pages that explain -the protections offered. ways to tweak the protection, and trade-offs for disabling some of them. +the protections offered, ways to tweak the protection, and trade-offs for disabling some of them. -image::security/configure-global-security.png["Configure Global Security", role=center] +\\ Do we want screen shots or not? +\\ image::security/configure-global-security.png["Configure Global Security", role=center] + +link:access-control[Jenkins Access Control]:: +Use the *Security Realm* and *Authorization* blocks on this page +to add and manage additional users. == Access Control -Access Control is the primary mechanism for securing a Jenkins environment -against unauthorized usage. Two facets of configuration are necessary for +link:access-control[Jenkins Access Control] +is the primary mechanism for managing users and securing a Jenkins environment against unauthorized usage. +During installation, Jenkins creates the "admin" user who has full permissions to do everything. +Here is where + +Two facets of configuration are necessary for configuring Access Control in Jenkins: -. A *Security Realm* which informs the Jenkins environment how and where to +. A *Security Realm* that informs the Jenkins environment how and where to pull user (or identity) information from. Also commonly known as "authentication." . *Authorization* configuration which informs the Jenkins environment as to which users and/or groups can access which aspects of Jenkins, and to what From da01b2528e141336f4dab3da6d69957c8dcea8fd Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 26 Oct 2021 02:44:59 -0700 Subject: [PATCH 17/59] fix link to security advisories Co-authored-by: Mark Waite --- content/doc/book/security/concepts-security.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/book/security/concepts-security.adoc b/content/doc/book/security/concepts-security.adoc index d320bbdb7d3f..431859512a54 100644 --- a/content/doc/book/security/concepts-security.adoc +++ b/content/doc/book/security/concepts-security.adoc @@ -33,7 +33,7 @@ so that you quickly detect signs of a security breach. * *Keep your system current:* Pay attention to -link:https://www.jenkins.io/security/advisories/[Security Advisories] +link:/security/advisories/[Security Advisories] and apply link:https://www.jenkins.io/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] as soon as possible. From 6f81a40c64878986a09a8bafea4a9a5934ec407d Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 26 Oct 2021 02:45:37 -0700 Subject: [PATCH 18/59] fix link to security advisories Co-authored-by: Mark Waite --- content/doc/book/security/concepts-security.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/book/security/concepts-security.adoc b/content/doc/book/security/concepts-security.adoc index 431859512a54..30ff479fa1c9 100644 --- a/content/doc/book/security/concepts-security.adoc +++ b/content/doc/book/security/concepts-security.adoc @@ -35,7 +35,7 @@ so that you quickly detect signs of a security breach. Pay attention to link:/security/advisories/[Security Advisories] and apply -link:https://www.jenkins.io/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] +link:/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] as soon as possible. Keeping the Jenkins software and all plugins current also helps ensure that your system is secure. From b8d7c1e16efb1cf98c1d105fffe002cdd5a7a36c Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 26 Oct 2021 02:49:32 -0700 Subject: [PATCH 19/59] fix link to managing-security --- content/doc/book/security/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 601d7122ef7a..9f5d08e82471 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -61,7 +61,7 @@ Builds should not be executed on the built-in node, but that is just the beginni This section discusses what other steps can be taken to protect the controller from being impacted by running builds. + *This needs to be configured according to the needs of your environment.* -link:controller-isolation[Configure Global Security]:: +link:managing-security[Configure Global Security]:: Much of the basic security configuration is implemented on the _Manage Jenkins >> Configure Global Security_ page. Here you see the fields that are configured on that page and get links to other sections that explain each field in detail. From 28e443a63ef8862f1825062b0711635e9d1f93f7 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 26 Oct 2021 02:54:06 -0700 Subject: [PATCH 20/59] remove solopsistic link Co-authored-by: Mark Waite --- content/doc/book/security/access-control.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/book/security/access-control.adoc b/content/doc/book/security/access-control.adoc index 86c91b97d15f..df90a8d9095e 100644 --- a/content/doc/book/security/access-control.adoc +++ b/content/doc/book/security/access-control.adoc @@ -4,7 +4,7 @@ layout: section --- :toc: :toclevels: 4 -link:access-control[Jenkins Access Control]:: +Jenkins Access Control:: Jenkins access control is split into two parts, both configured on the _Manage Jenkins >> Configure Global Security_ page.: From e7f51658e592f0fee3dd1c8c1ae22fd705f9ead5 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 26 Oct 2021 02:55:26 -0700 Subject: [PATCH 21/59] delete extraneous title --- content/doc/book/security/access-control.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/content/doc/book/security/access-control.adoc b/content/doc/book/security/access-control.adoc index df90a8d9095e..25520e6fd8e1 100644 --- a/content/doc/book/security/access-control.adoc +++ b/content/doc/book/security/access-control.adoc @@ -4,7 +4,6 @@ layout: section --- :toc: :toclevels: 4 -Jenkins Access Control:: Jenkins access control is split into two parts, both configured on the _Manage Jenkins >> Configure Global Security_ page.: From f7d4100df3b1e8df34c5a89d760a8dc5476b0089 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 26 Oct 2021 02:56:31 -0700 Subject: [PATCH 22/59] an user -> an user --- content/doc/book/security/access-control.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/book/security/access-control.adoc b/content/doc/book/security/access-control.adoc index 25520e6fd8e1..bc32b9197569 100644 --- a/content/doc/book/security/access-control.adoc +++ b/content/doc/book/security/access-control.adoc @@ -75,7 +75,7 @@ which may need to be configured external to the Jenkins environment. [CAUTION] ==== -Unix allows an user and a group to have the same name. In order to +Unix allows a user and a group to have the same name. In order to disambiguate, use the `@` prefix to force the name to be interpreted as a group. For example, `@dev` would mean the `dev` group and not the `dev` user. ==== From b1519f34b1aef7fa30518b61f8a23b8cc5e2ed90 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 26 Oct 2021 03:05:02 -0700 Subject: [PATCH 23/59] Draft "Configure Global Security" page --- content/doc/book/security/_chapter.yml | 1 + .../security/agent-controller-access.adoc | 45 +++++++++++ .../book/security/controller-isolation.adoc | 33 -------- .../doc/book/security/managing-security.adoc | 80 +++++++++++-------- 4 files changed, 91 insertions(+), 68 deletions(-) create mode 100644 content/doc/book/security/agent-controller-access.adoc diff --git a/content/doc/book/security/_chapter.yml b/content/doc/book/security/_chapter.yml index 371c772ed1af..2c1ce0581f89 100644 --- a/content/doc/book/security/_chapter.yml +++ b/content/doc/book/security/_chapter.yml @@ -14,6 +14,7 @@ sections: - csrf-protection - user-content - build-authorization + - agent-controller-access - environment-variables # Legacy sections diff --git a/content/doc/book/security/agent-controller-access.adoc b/content/doc/book/security/agent-controller-access.adoc new file mode 100644 index 000000000000..19bd678cc9b4 --- /dev/null +++ b/content/doc/book/security/agent-controller-access.adoc @@ -0,0 +1,45 @@ +--- +title: Agent → Controller Access Control +layout: section +--- +ifdef::backend-html5[] +:notitle: +:description: +:author: +:email: jenkinsci-docs@googlegroups.com +:sectanchors: +:toc: +ifdef::env-github[:imagesdir: ../resources] +ifndef::env-github[:imagesdir: ../../resources] +:hide-uri-scheme: +endif::[] + +The Jenkins controller and agents can be thought of as a distributed process +which executes across multiple discrete processes and machines. +Not building on the built-in controller node is an essential practice +to protect the controller from bugs and less sophisticated attackers. +However, an agent can stil ask the controller process for information such as the contents of files, +and can even request that the controller run certain commands. +This means that an agent process taken over by a malicious user could still obtain data +or execute commands on the Jenkins controller. +To prevent this, Jenkins implements the **Agent → Controller Access Control** filter +that prevents agent processes from sending malicious commands to the Jenkins controller. + +This filter may prevent your builds from executing legitimate operations. + +* If builds are failing because of the agent-to-controller access control, +you should first ensure that you have upgraded to the latest version of all plugins, +since older versions of plugins may not work correctly with this feature. + +* You can also tweak the filter's rules by adding `allow/deny` rules +to specify the commands that you need and the type of access that is allowed for the agent. +See +link:/doc/book/security/controller-isolation/agent-to-controller/[Customizing Agent -> Controller Security] +for more information. + +It is also possible (but strongly discouraged) to disable this filter +by un-checking the box on the _Manage Jenkins » Configure Global Security_ page: + +image::security/configure-global-security-agent-controller-toggle.png["Configure Global Security - Enable Agent => Controller Access Control", role=center] + +IMPORTANT: It is strongly recommended that you not disable the Agent → Controller Access Control filter. diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index efee3b423479..74da8c376738 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -172,36 +172,3 @@ be sure that the agent process has neither read nor write file system access to the Jenkins home directory, and that the agent process cannot use `sudo` or other practices to elevate its own permissions. -//== Infrastructure - -== 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. -Not building on the built-in controller node is an essential practice -to protect the controller from bugs and less sophisticated attackers. -However, an agent can stil ask the controller process for information such as the contents of files, -and can even request that the controller run certain commands. -This means that an agent process taken over by a malicious user could still obtain data -or execute commands on the Jenkins controller. -To prevent this, Jenkins implements the **Agent → Controller Access Control** filter -that prevents agent processes from sending malicious commands to the Jenkins controller. - -This filter may prevent your builds from executing legitimate operations. - -* If builds are failing because of the agent-to-controller access control, -you should first ensure that you have upgraded to the latest version of all plugins, -since older versions of plugins may not work correctly with this feature. - -* You can also tweak the filter's rules by adding `allow/deny` rules -to specify the commands that you need and the type of access that is allowed for the agent. -See -link:/doc/book/security/controller-isolation/agent-to-controller/[Customizing Agent -> Controller Security] -for more information. - -It is also possible (but strongly discouraged) to disable this filter -by un-checking the box on the _Manage Jenkins » Configure Global Security_ page: - -image::security/configure-global-security-agent-controller-toggle.png["Configure Global Security - Enable Agent => Controller Access Control", role=center] - -IMPORTANT: It is strongly recommended that you not disable the Agent → Controller Access Control filter. diff --git a/content/doc/book/security/managing-security.adoc b/content/doc/book/security/managing-security.adoc index 7ee110d33260..d40391c94365 100644 --- a/content/doc/book/security/managing-security.adoc +++ b/content/doc/book/security/managing-security.adoc @@ -36,42 +36,52 @@ This section introduces fields available on the _Configure Global Security_ page and provides links to other pages that explain the protections offered, ways to tweak the protection, and trade-offs for disabling some of them. -\\ Do we want screen shots or not? -\\ image::security/configure-global-security.png["Configure Global Security", role=center] - -link:access-control[Jenkins Access Control]:: -Use the *Security Realm* and *Authorization* blocks on this page -to add and manage additional users. +//// +Do we want screen shots or not? +image::security/configure-global-security.png["Configure Global Security", role=center] +//// -== Access Control +//// +TODO: Justify this with the actual UI page so it includes all fields in a reasonable order. +//// -link:access-control[Jenkins Access Control] -is the primary mechanism for managing users and securing a Jenkins environment against unauthorized usage. +link:/doc/book/security/access-control[Jenkins Access Control]:: During installation, Jenkins creates the "admin" user who has full permissions to do everything. -Here is where - -Two facets of configuration are necessary for -configuring Access Control in Jenkins: - -. A *Security Realm* that informs the Jenkins environment how and where to - pull user (or identity) information from. Also commonly known as "authentication." -. *Authorization* configuration which informs the Jenkins environment as to - which users and/or groups can access which aspects of Jenkins, and to what - extent. - -Using both the Security Realm and Authorization configurations it is possible -to configure very relaxed or very rigid authentication and authorization -schemes in Jenkins. - -== Markup Formatter - -See link:/doc/book/security/markup-formatter/[Markup Formatter]. - - -== CSRF Protection - -See link:/doc/book/security/csrf-protection[CSRF Protection]. - -== Agent/Master Access Control +Use the *Security Realm* and *Authorization* blocks on this page +to define the scheme used to add and manage additional users. + +link:/doc/book/security/tcp-port[TCP Port for Inbound Agents]:: +Inbound agents (such as Windows agents) require a TCP port. +By default, this port is disabled. +If your builds use inbound agents, you must configure this port. +If your builds do not use inbound agents, you should leave this port disabled. + +The **Global Security Settings** screen +also includes fields to configure or enable +filters that protect against common types of intrusion. +By default, Jenkins is installed in "locked-down" mode so that +all of these filters are turned on. +You should leave these filters enabled unless they interfere with the jobs you need to run, +although in many cases you can tweak the filter +but still leave it enabled. +In many cases, plugins and practices are available +to reduce the security vulnerability of these features. + +link:/doc/book/security/markup-formatter/[Markup Formatters]:: +Controls how HTML formatting in descriptions is handled. +Some of these characters can be used maliciously, +so the default is _Plain text_ +but plugins are available that allow some of the formatting to be rendered. + +link:/doc/book/security/csrf-protection[CSRF Protection]:: +CSRF is an exploit that enables an unauthorized third party +to perform requests against a web application +by impersonating another, authenticated user. +In a Jenkins environment, a CSRF attack could allow +a malicious actor to delete projects, +alter builds, or modify the system configuration of the Jenkins instance. + + +link:/doc/book/security/agent-controller-access[Agent → Controller Access Control]:: +Prevents an agent from sending malicious commands to the controller. -See link:/doc/book/security/controller-isolation[Isolating the Controller from Builds]. From 6109f6a25a4ef7567d44aeaacac6086012c7254d Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 26 Oct 2021 15:51:32 -0700 Subject: [PATCH 24/59] Refine definitions of nodes and executors --- content/doc/book/security/controller-isolation.adoc | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 74da8c376738..24b185e8444a 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -87,6 +87,11 @@ clock time/sync and response time. A node is taken offline if any of these values go outside the configured threshold. +The Jenkins controller itself runs on a special _built-in node_. +It is possible to run agents and executors on this built-in node +although this can degrade performance, reduce scalability of the Jenkins instance, and create serious security problems +and is strongly discouraged, especially for production environments. + Agents:: Agents manage the task execution on behalf of the Jenkins controller @@ -98,13 +103,15 @@ Tools required for builds and tests are installed on the node where the agent ru they can be installed directly or in a container (Docker or Kubernetes). Each agent is effectively a process with its own PID (Process Identifier) on the host machine. +In practice, nodes and agents are essentially the same but it is good to remember that they are conceptually distinct. + Executors:: An executor is a slot for execution of tasks; effectively, it is a thread in the agent. The number of executors on a node defines the number of concurrent tasks that can be executed on that node at one time. -In other words, the number of concurrent Pipeline `stages` +In other words, this determines the number of concurrent Pipeline `stages` that can execute on that node at one time. The proper number of executors per build node must be determined From 52b9f64ebaa0ed92ce660d4e044ebfc405f3eabe Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Thu, 9 Dec 2021 02:21:39 -0800 Subject: [PATCH 25/59] remove details about nodes --- content/doc/book/security/controller-isolation.adoc | 5 ----- 1 file changed, 5 deletions(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 24b185e8444a..477fc690a873 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -81,11 +81,6 @@ unless they are off-loaded to an artifact repository such as Nexus or Artifactor Nodes:: Nodes are the "machines" on which build agents run. -Jenkins monitors each attached node for -disk space, free temp space, free swap, -clock time/sync and response time. -A node is taken offline if any of these values -go outside the configured threshold. The Jenkins controller itself runs on a special _built-in node_. It is possible to run agents and executors on this built-in node From b750b914a6a0044b142dccea287a2eeeb87a7a46 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Thu, 9 Dec 2021 02:23:39 -0800 Subject: [PATCH 26/59] remove details about agents/exectors on controller --- content/doc/book/security/controller-isolation.adoc | 3 --- 1 file changed, 3 deletions(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 477fc690a873..9a996d80f1ef 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -83,9 +83,6 @@ Nodes:: Nodes are the "machines" on which build agents run. The Jenkins controller itself runs on a special _built-in node_. -It is possible to run agents and executors on this built-in node -although this can degrade performance, reduce scalability of the Jenkins instance, and create serious security problems -and is strongly discouraged, especially for production environments. Agents:: From 228fb0fd82127b5b759d2bb28e9f3ba2ea433ecf Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Thu, 9 Dec 2021 03:17:12 -0800 Subject: [PATCH 27/59] remove some details about number of executors --- content/doc/book/security/controller-isolation.adoc | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 9a996d80f1ef..fa1aad7565b0 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -107,11 +107,7 @@ In other words, this determines the number of concurrent Pipeline `stages` that can execute on that node at one time. The proper number of executors per build node must be determined -based on the resources available on the node -and the resources required for the workload. -When determining how many executors to run on a node, -consider CPU and memory requirements -as well as the amount of I/O and network activity: + * One executor per node is the safest configuration. * One executor per CPU core may work well From 1a084757375ef0fea355ac6eb00496dab05b2222 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 13:39:51 -0800 Subject: [PATCH 28/59] one sentence per line --- content/doc/book/security/index.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 9f5d08e82471..5c843cceb97d 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -9,8 +9,7 @@ ifdef::backend-html5[] :sectanchors: endif::[] -Jenkins is used everywhere -- from workstations on corporate intranets -to high-powered servers connected to the public internet. +Jenkins is used everywhere -- from workstations on corporate intranets to high-powered servers connected to the public internet. It is critically important to keep your Jenkins instance secure, both to protect your information and to avoid executing malicious code from your Jenkins instance. From c6eff48210c8f2cdc0848e8f7cf9f8596370ec7a Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 13:41:14 -0800 Subject: [PATCH 29/59] one sentence per line --- content/doc/book/security/index.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 5c843cceb97d..012ad82381ca 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -10,8 +10,7 @@ ifdef::backend-html5[] endif::[] Jenkins is used everywhere -- from workstations on corporate intranets to high-powered servers connected to the public internet. -It is critically important to keep your Jenkins instance secure, -both to protect your information and to avoid executing malicious code from your Jenkins instance. +It is critically important to keep your Jenkins instance secure,both to protect your information and to avoid executing malicious code from your Jenkins instance. Your Jenkins environment is a fully-distributed build system. Each network connection is a potential point of entry. From 23c078f830255b2f6c86f3888ecbdae0202d359c Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 13:42:54 -0800 Subject: [PATCH 30/59] one sentence per line --- content/doc/book/security/index.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 012ad82381ca..e15513ec5e6d 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -17,9 +17,7 @@ Each network connection is a potential point of entry. Remember that the code that runs your builds can be perverted to run anything! Jenkins and the jobs it runs must be able to do almost anything. -This means that a malicious Pipeline could reconfigure the Jenkins instance, -delete files, or launch various forms of mischief -such as a DDoS attack or a bot. +This means that a malicious Pipeline could reconfigure the Jenkins instance, delete files, or launch various forms of mischief such as a DDoS attack or a bot. In addition to deliberate and direct attacks on your environment, a trusted user could visit an infected web site and accidentally introduce malicious code into the Jenkins instance. From 27429db1a71743fb1df9d777cda779303f3e88b9 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 13:43:57 -0800 Subject: [PATCH 31/59] one sentence per line --- content/doc/book/security/index.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index e15513ec5e6d..5e0de6456964 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -18,9 +18,7 @@ Remember that the code that runs your builds can be perverted to run anything! Jenkins and the jobs it runs must be able to do almost anything. This means that a malicious Pipeline could reconfigure the Jenkins instance, delete files, or launch various forms of mischief such as a DDoS attack or a bot. -In addition to deliberate and direct attacks on your environment, -a trusted user could visit an infected web site -and accidentally introduce malicious code into the Jenkins instance. +In addition to deliberate and direct attacks on your environment, a trusted user could visit an infected web site and accidentally introduce malicious code into the Jenkins instance. Jenkins includes configurable features to secure your Jenkins instance against the various security and threat profiles. From 9f431b87cc8c4126e78a4df4259118d8f57a34bf Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 13:44:56 -0800 Subject: [PATCH 32/59] one sentence per line --- content/doc/book/security/index.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 5e0de6456964..b2226156adba 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -20,8 +20,7 @@ Jenkins and the jobs it runs must be able to do almost anything. This means that a malicious Pipeline could reconfigure the Jenkins instance, delete files, or launch various forms of mischief such as a DDoS attack or a bot. In addition to deliberate and direct attacks on your environment, a trusted user could visit an infected web site and accidentally introduce malicious code into the Jenkins instance. -Jenkins includes configurable features to secure your Jenkins instance -against the various security and threat profiles. +Jenkins includes configurable features to secure your Jenkins instance against the various security and threat profiles. The setup wizard enables many of the security options by default, to ensure that Jenkins is secure. Other security options involve environment-specific setup and trade-offs From 184cd91b63626125d8a3e1b575486cca343c1c46 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 13:45:54 -0800 Subject: [PATCH 33/59] one sentence per line --- content/doc/book/security/index.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index b2226156adba..a952a5c8337c 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -23,8 +23,7 @@ In addition to deliberate and direct attacks on your environment, a trusted user Jenkins includes configurable features to secure your Jenkins instance against the various security and threat profiles. The setup wizard enables many of the security options by default, to ensure that Jenkins is secure. -Other security options involve environment-specific setup and trade-offs -and depend on specific use cases supported for individual Jenkins instances. +Other security options involve environment-specific setup and trade-offs and depend on specific use cases supported for individual Jenkins instances. Configuration options allow you to enable, customize, or disable security features. [CAUTION] From cd21cade6fbe1ae4a13fa9f20dd9eff47b9bcdb3 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 13:47:54 -0800 Subject: [PATCH 34/59] one sentence per line --- content/doc/book/security/index.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index a952a5c8337c..9184e21a3f04 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -30,8 +30,7 @@ Configuration options allow you to enable, customize, or disable security featur ==== Most Jenkins environments grow over time, requiring their trust models to evolve as the environment grows. -You should schedule regular "check-ups" of your security settings -to ensure that they are still appropriate for your instance. +You should schedule regular "check-ups" of your security settings to ensure that they are still appropriate for your instance. In particular, if you had to disable some of the default protections that Jenkins provides, perhaps because you were using a plugin that had not been updated to support that protection, you may be able to re-enable that protection From 35b4ed8f06407bf80d600e0c5346703e75522518 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 13:49:27 -0800 Subject: [PATCH 35/59] Update content/doc/book/security/index.adoc --- content/doc/book/security/index.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 9184e21a3f04..b46707006457 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -32,9 +32,7 @@ Most Jenkins environments grow over time, requiring their trust models to evolve as the environment grows. You should schedule regular "check-ups" of your security settings to ensure that they are still appropriate for your instance. In particular, if you had to disable some of the default protections that Jenkins provides, -perhaps because you were using a plugin that had not been updated to support that protection, -you may be able to re-enable that protection -to increase the security of your instance. +perhaps because you were using a plugin that had not been updated to support that protection, you may be able to re-enable that protection to increase the security of your instance. ==== // TODO the following only makes sense on the web site, not the PDF. Can it be disabled there? From 87c2ab8f0cdcd8e9565219849341047f09faef4f Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 13:50:48 -0800 Subject: [PATCH 36/59] one sentence per line --- content/doc/book/security/index.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index b46707006457..1bcb5e863852 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -38,8 +38,7 @@ perhaps because you were using a plugin that had not been updated to support tha // TODO the following only makes sense on the web site, not the PDF. Can it be disabled there? // TODO the material below should be moved to other sections in this chapter. -This chapter introduces the various security options available to Jenkins administrators and users, -explaining the protections offered, and trade-offs to disabling some of them: +This chapter introduces the various security options available to Jenkins administrators and users, explaining the protections offered, and trade-offs to disabling some of them: link:concepts-security[Background Concepts]:: Discusses security principles that should guide all your decisions about security From 808d2aaa3a7be157fb2a088243fa00d2b09ccf5b Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 13:51:33 -0800 Subject: [PATCH 37/59] one sentence per line --- content/doc/book/security/index.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 1bcb5e863852..ebdc3a890ac9 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -28,8 +28,7 @@ Configuration options allow you to enable, customize, or disable security featur [CAUTION] ==== -Most Jenkins environments grow over time, -requiring their trust models to evolve as the environment grows. +Most Jenkins environments grow over time, requiring their trust models to evolve as the environment grows. You should schedule regular "check-ups" of your security settings to ensure that they are still appropriate for your instance. In particular, if you had to disable some of the default protections that Jenkins provides, perhaps because you were using a plugin that had not been updated to support that protection, you may be able to re-enable that protection to increase the security of your instance. From b061d8dd96bbd4d88107c18443422c8ffe1d5ea2 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 13:57:41 -0800 Subject: [PATCH 38/59] one sentence per line --- content/doc/book/security/controller-isolation.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index fa1aad7565b0..ce2cb42a0dc4 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -56,8 +56,7 @@ to ensure that builds do not run on the controller even if executors are configured. ==== -An agent can also write malicious code to its local disk so that the node is tainted -and can infect a later build. +An agent can also write malicious code to its local disk so that the node is tainted and can infect a later build. For maximum security, run all builds on ephemeral agents in the cloud so that they are destroyed at the end of each build job. From 7f614505270ab368614e0b8ae49b45bc6ac9faad Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 14:07:52 -0800 Subject: [PATCH 39/59] one sentence per line --- content/doc/book/security/controller-isolation.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index ce2cb42a0dc4..7ee07f627c7c 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -57,8 +57,7 @@ even if executors are configured. ==== An agent can also write malicious code to its local disk so that the node is tainted and can infect a later build. -For maximum security, run all builds on ephemeral agents in the cloud -so that they are destroyed at the end of each build job. +For maximum security, run all builds on ephemeral agents in the cloud so that they are destroyed at the end of each build job. By extension, you also should not run agents on the same Docker host as the controller. From 0bc82cd7464a14e6ad3c0a8afbc1095158431e42 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 16:18:01 -0800 Subject: [PATCH 40/59] Pare down description of distributed components --- .../book/security/controller-isolation.adoc | 39 ++++--------------- 1 file changed, 8 insertions(+), 31 deletions(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 7ee07f627c7c..14cff59345f5 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -63,36 +63,24 @@ By extension, you also should not run agents on the same Docker host as the cont == Distributed Components -A Jenkins distributed builds instance includes the following components: +A Jenkins distributed builds instance includes the following components. +For more details about these components, see +link:/doc/book/managing/nodes/[Managing Nodes]. Jenkins controller:: -The Jenkins controller is the Jenkins service itself -and is where Jenkins is installed. -It is a webserver that also acts as a "brain" -for deciding how, when and where to run tasks. -Management tasks (configuration, authorization, and authentication) -are executed on the controller, which serves HTTP requests. -Files written when a Pipeline executes are written to the filesystem on the controller -unless they are off-loaded to an artifact repository such as Nexus or Artifactory. +The Jenkins controller is a webserver where Jenkins is installed. +It schedules tasks, executes management tasks (configuration, authorization, and authentication). +Files written when a Pipeline executes are written to the filesystem on the controller unless they are off-loaded to an artifact repository such as Nexus or Artifactory. Nodes:: Nodes are the "machines" on which build agents run. - The Jenkins controller itself runs on a special _built-in node_. Agents:: -Agents manage the task execution on behalf of the Jenkins controller -by using executors. -An agent is actually a small (170KB single jar) Java client process -that connects to a Jenkins controller and is assumed to be unreliable. -An agent can use any operating system that supports Java. -Tools required for builds and tests are installed on the node where the agent runs; -they can be installed directly or in a container (Docker or Kubernetes). -Each agent is effectively a process with its own PID (Process Identifier) on the host machine. - +Agents are small Java client processes that use executors to manage the task execution on behalf of the Jenkins controller. In practice, nodes and agents are essentially the same but it is good to remember that they are conceptually distinct. Executors:: @@ -101,17 +89,6 @@ An executor is a slot for execution of tasks; effectively, it is a thread in the agent. The number of executors on a node defines the number of concurrent tasks that can be executed on that node at one time. -In other words, this determines the number of concurrent Pipeline `stages` -that can execute on that node at one time. - -The proper number of executors per build node must be determined - - -* One executor per node is the safest configuration. -* One executor per CPU core may work well -if the tasks being run are small. -* Monitor I/O performance, CPU load, memory usage, and I/O throughput carefully -when running multiple executors on a node. == Implementing Distributed Builds @@ -128,7 +105,7 @@ This section also includes other tips and tricks you can use. To implement a distributed builds architecture for your Jenkins instance, you must configure nodes and agents to use for your builds. See -link:https:/doc/book/managing/nodes/[Managing Nodes] +link:/doc/book/managing/nodes/[Managing Nodes] for instructions. === Prevent Builds from Running on the Controller From f6096fdc5d68d3c68649388064e3c3daa09ac6e6 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Mon, 10 Jan 2022 16:26:11 -0800 Subject: [PATCH 41/59] Clarify that only 0 executors on controller guarantees no builds --- content/doc/book/security/controller-isolation.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 14cff59345f5..398c176c03c5 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -42,9 +42,11 @@ for a variety of platforms. [NOTE] ==== -A job that performs administrative tasks such as backups may run on the controller, -but be sure to label the executor with a hard-to-guess label +A job that performs administrative tasks such as backups may run on the controller. +To reduce the chance of someone using this executor to run a job, +label the executor with a hard-to-guess label and only allow it to be used by jobs that specify that label. + An executor can be temporarily configured on the controller long enough to run the administrative task but no executors should be configured on the controller at other times From ca895cd343f54b3318dfd120e19f0876ddd5a39c Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Thu, 20 Jan 2022 09:57:53 -0800 Subject: [PATCH 42/59] Resolving some dbeck comments --- content/doc/book/security/_chapter.yml | 2 +- .../{concepts-security.adoc => concepts.adoc} | 16 ++++++++-------- .../doc/book/security/controller-isolation.adoc | 5 ++--- 3 files changed, 11 insertions(+), 12 deletions(-) rename content/doc/book/security/{concepts-security.adoc => concepts.adoc} (84%) diff --git a/content/doc/book/security/_chapter.yml b/content/doc/book/security/_chapter.yml index 2c1ce0581f89..7504cf475bc4 100644 --- a/content/doc/book/security/_chapter.yml +++ b/content/doc/book/security/_chapter.yml @@ -3,7 +3,7 @@ sections: # index - implied overview # General information - - concepts-security + - concepts - controller-isolation - managing-security diff --git a/content/doc/book/security/concepts-security.adoc b/content/doc/book/security/concepts.adoc similarity index 84% rename from content/doc/book/security/concepts-security.adoc rename to content/doc/book/security/concepts.adoc index 30ff479fa1c9..a37e0956bfd6 100644 --- a/content/doc/book/security/concepts-security.adoc +++ b/content/doc/book/security/concepts.adoc @@ -6,7 +6,7 @@ layout: section To properly manage the security of your Jenkins instance, you should be familiar with: * Security principles that should guide all your decisions -* How Jenkins executes a Pipeline +* How Jenkins executes a Freestyle or Pipeline job If you understand the vulnerabilities that an intrusion could exploit, you can better understand how to protect against those intrusions. ## Security Principles @@ -40,21 +40,21 @@ as soon as possible. Keeping the Jenkins software and all plugins current also helps ensure that your system is secure. -== How Jenkins Executes a Pipeline +== How Jenkins Executes Jobs -A simple overview of how Jenkins executes a Pipeline +A simple overview of how Jenkins executes a Freestyle or Pipeline job helps to understand the security considerations. -By default, a Pipeline executes with the full privileges of the Jenkins administrator, -although you can configure Jenkins to execute Pipelines with fewer privileges. -All of the Pipeline logic, the Groovy conditionals, loops, and so forth execute on the controller. +By default, a job executes with the full privileges of the Jenkins administrator, +although you can configure Jenkins to execute jobs with fewer privileges. +All of the job's logic, the Groovy conditionals, loops, and so forth execute on the controller. -When a Pipeline runs: +When the job runs: * Jenkins creates a _workspace_ on the controller for each build that runs. Files for that build are stored in the workspace.. -* The Pipeline calls a series of _steps_, +* The job calls a series of _steps_, each of which is a script or command that does the real work and mostly executes using an _executor_ on an _agent_. diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 54d8645deaf7..85b98c57e5af 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -132,8 +132,7 @@ it is possible for a build to run on the controller. 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. -// TODO Also mention first LTS once it's known -This system is always enabled since Jenkins 2.326 (see link:jep-235[Agent → Controller Security Changes in 2.326]). +This system is always enabled Jenkins 2.326 and later (see link:jep-235[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 » Configure Global Security_ page. IMPORTANT: It is strongly recommended that you not disable the Agent → Controller Access Control system. @@ -154,4 +153,4 @@ to achieve a similar isolation effect. In this case, be sure that the agent process has neither read nor write file system access to the Jenkins home directory, -and that the agent process cannot use `sudo` or other practices to elevate its own permissions. \ No newline at end of file +and that the agent process cannot use `sudo` or other practices to elevate its own permissions. From ba6730b9311241dd638ef89fb1eb8b77d6fff07f Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Thu, 20 Jan 2022 23:43:07 -0800 Subject: [PATCH 43/59] Remove admonition to not configure TCP port if you don't need it --- content/doc/book/security/index.adoc | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index ebdc3a890ac9..9c3e731efbe4 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -45,7 +45,7 @@ and explains how Jenkins executes a Pipeline so you understand where intrusions link:controller-isolation[Distributed Builds]:: Builds should not be executed on the built-in node, but that is just the beginning: -This section discusses what other steps can be taken to protect the controller from being impacted by running builds. + +This section discusses what other steps can be taken to protect the controller from being impacted by running builds. *This needs to be configured according to the needs of your environment.* link:managing-security[Configure Global Security]:: @@ -54,38 +54,37 @@ Here you see the fields that are configured on that page and get links to other link:access-control[Jenkins Access Control]:: By default, Jenkins does not allow anonymous access, and a single admin user exists. -This chapter discusses which level of access is provided by permissions and how to safely grant access to more users. + +This chapter discusses which level of access is provided by permissions and how to safely grant access to more users. _This is set up securely by the setup wizard. If the setup wizard is disabled on first launch, this may not be configured securely by default._ link:tcp-port[TCP Port for InBound Agents]:: If you are using TCP for inbound agents (previously called JNLP), you must configure a TCP port to use. -This section discusses how to configure the TCP port and discusses alternative implementations that do not require the TCP port. + -*The TCP Port is disabled by default and should only be enabled if you need it.* +This section discusses how to configure the TCP port and discusses alternative implementations that do not require the TCP port. link:markup-formatter[Markup Formatter]:: The default markup formatter renders text as entered (i.e. escaping HTML metacharacters). -This chapter explains how to switch to a different markup formatter and explains what admins need to be aware of. + +This chapter explains how to switch to a different markup formatter and explains what admins need to be aware of. _This is set up securely by default._ link:csrf-protection[CSRF Protection]:: Jenkins protects from cross-site request forgery (CSRF) by default. -This chapter explains how to work around any problems this may cause. + +This chapter explains how to work around any problems this may cause. _This is set up securely by default._ // TODO Confirm that skipping the setup wizard in 2.222 does no longer disable CSRF protection link:user-content[Rendering User Content]:: By default, Jenkins strictly limits the features useable in user content (files from workspaces, archived artifacts, etc.) it serves. -This chapter discusses how to customize this and make HTML reports and similar content both functional and safe to view. + +This chapter discusses how to customize this and make HTML reports and similar content both functional and safe to view. _This is set up securely by default._ link:build-authorization[Access Control for Builds]:: -Learn how to restrict what individual builds can do in Jenkins once they're running. + +Learn how to restrict what individual builds can do in Jenkins once they're running. *This needs to be configured according to the needs of your environment.* link:environment-variables[Handling Environment Variables]:: Improperly written build scripts may be tricked into behaving differently than intended due to special environment variable names or values being injected as build parameters. -This section discusses how to protect your builds. + +This section discusses how to protect your builds. *This needs to be configured according to the needs of your environment.* link:securing-jenkins[Other Security Topics]:: From 9849ee647f96a165bffd70b3323936abf5ee7180 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 21 Jan 2022 00:03:25 -0800 Subject: [PATCH 44/59] rephrase material about jobs being able to do anything --- content/doc/book/security/index.adoc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 9c3e731efbe4..9b515092a2f1 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -14,10 +14,9 @@ It is critically important to keep your Jenkins instance secure,both to protect Your Jenkins environment is a fully-distributed build system. Each network connection is a potential point of entry. -Remember that the code that runs your builds can be perverted to run anything! -Jenkins and the jobs it runs must be able to do almost anything. -This means that a malicious Pipeline could reconfigure the Jenkins instance, delete files, or launch various forms of mischief such as a DDoS attack or a bot. +Jenkins and the jobs it runs must be able to do almost anything, which means that the code that runs your builds can be perverted to run anything! +For example, a malicious Pipeline could reconfigure the Jenkins instance, delete files, or launch various forms of mischief such as a DDoS attack or a bot. In addition to deliberate and direct attacks on your environment, a trusted user could visit an infected web site and accidentally introduce malicious code into the Jenkins instance. Jenkins includes configurable features to secure your Jenkins instance against the various security and threat profiles. From 27afddd967945898c99088d82fb233d71d68f0e8 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 21 Jan 2022 00:05:03 -0800 Subject: [PATCH 45/59] one sentence per line -- part 1 --- .../security/agent-controller-access.adoc | 26 ++--- content/doc/book/security/concepts.adoc | 43 +++---- .../book/security/controller-isolation.adoc | 110 +++++------------- content/doc/book/security/index.adoc | 5 +- 4 files changed, 55 insertions(+), 129 deletions(-) diff --git a/content/doc/book/security/agent-controller-access.adoc b/content/doc/book/security/agent-controller-access.adoc index 19bd678cc9b4..bd9a7323b302 100644 --- a/content/doc/book/security/agent-controller-access.adoc +++ b/content/doc/book/security/agent-controller-access.adoc @@ -14,28 +14,18 @@ ifndef::env-github[:imagesdir: ../../resources] :hide-uri-scheme: endif::[] -The Jenkins controller and agents can be thought of as a distributed process -which executes across multiple discrete processes and machines. -Not building on the built-in controller node is an essential practice -to protect the controller from bugs and less sophisticated attackers. -However, an agent can stil ask the controller process for information such as the contents of files, -and can even request that the controller run certain commands. -This means that an agent process taken over by a malicious user could still obtain data -or execute commands on the Jenkins controller. -To prevent this, Jenkins implements the **Agent → Controller Access Control** filter -that prevents agent processes from sending malicious commands to the Jenkins controller. +The Jenkins controller and agents can be thought of as a distributed process that executes across multiple discrete processes and machines. +Not building on the built-in controller node is an essential practice to protect the controller from bugs and less sophisticated attackers. +However, an agent can stil ask the controller process for information such as the contents of files, and can even request that the controller run certain commands. +This means that an agent process taken over by a malicious user could still obtain data or execute commands on the Jenkins controller. +To prevent this, Jenkins implements the **Agent → Controller Access Control** filter that prevents agent processes from sending malicious commands to the Jenkins controller. This filter may prevent your builds from executing legitimate operations. -* If builds are failing because of the agent-to-controller access control, -you should first ensure that you have upgraded to the latest version of all plugins, -since older versions of plugins may not work correctly with this feature. +* If builds are failing because of the agent-to-controller access control, you should first ensure that you have upgraded to the latest version of all plugins, since older versions of plugins may not work correctly with this feature. -* You can also tweak the filter's rules by adding `allow/deny` rules -to specify the commands that you need and the type of access that is allowed for the agent. -See -link:/doc/book/security/controller-isolation/agent-to-controller/[Customizing Agent -> Controller Security] -for more information. +* You can also tweak the filter's rules by adding `allow/deny` rules to specify the commands that you need and the type of access that is allowed for the agent. +See link:/doc/book/security/controller-isolation/agent-to-controller/[Customizing Agent -> Controller Security] for more information. It is also possible (but strongly discouraged) to disable this filter by un-checking the box on the _Manage Jenkins » Configure Global Security_ page: diff --git a/content/doc/book/security/concepts.adoc b/content/doc/book/security/concepts.adoc index a37e0956bfd6..218a4939e211 100644 --- a/content/doc/book/security/concepts.adoc +++ b/content/doc/book/security/concepts.adoc @@ -15,48 +15,34 @@ Security principles should guide the practices and tools used to fight and preve The major principles for security are: * *Least privilege:* -Give people the privileges required to do their jobs -but do not give everyone permission to do everything -and do not open ports that are not required for your work. +Give people the privileges required to do their jobs but do not give everyone permission to do everything and do not open ports that are not required for your work. * *Know the system:* -The more you understand about how your system works, -the more you are prepared to protect the integrity of your system. +The more you understand about how your system works, the more you are prepared to protect the integrity of your system. * *Defense in depth:* Systems are layered. Put security on all layers. * *Prevention is good, but detection is better:* -Monitor your Jenkins installation constantly -so that you quickly detect signs of a security breach. +Monitor your Jenkins installation constantly so that you quickly detect signs of a security breach. * *Keep your system current:* -Pay attention to -link:/security/advisories/[Security Advisories] -and apply -link:/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] -as soon as possible. -Keeping the Jenkins software and all plugins current -also helps ensure that your system is secure. +Pay attention to link:/security/advisories/[Security Advisories] and apply link:/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] as soon as possible. +Keeping the Jenkins software and all plugins current also helps ensure that your system is secure. == How Jenkins Executes Jobs -A simple overview of how Jenkins executes a Freestyle or Pipeline job -helps to understand the security considerations. +A simple overview of how Jenkins executes a Freestyle or Pipeline job helps to understand the security considerations. -By default, a job executes with the full privileges of the Jenkins administrator, -although you can configure Jenkins to execute jobs with fewer privileges. +By default, a job executes with the full privileges of the Jenkins administrator, although you can configure Jenkins to execute jobs with fewer privileges. All of the job's logic, the Groovy conditionals, loops, and so forth execute on the controller. When the job runs: -* Jenkins creates a _workspace_ on the controller -for each build that runs. -Files for that build are stored in the workspace.. -* The job calls a series of _steps_, -each of which is a script or command that does the real work -and mostly executes using an _executor_ on an _agent_. +* Jenkins creates a _workspace_ on the controller for each build that runs. +Files for that build are stored in the workspace. +* The job calls a series of _steps_, each of which is a script or command that does the real work and mostly executes using an _executor_ on an _agent_. The agent: @@ -64,20 +50,17 @@ The agent: * Sends data back to the controller. * May also request information from the controller. -Many different people have some control over -the commands that are executed during a build: +Many different people have some control over the commands that are executed during a build: * Jenkins users with Job/Configure permission * Authors of build scripts such as `pom.xml` and `Makefile` * Authors of code, such as test suites that are executed during a build Any of these could introduce security issues, either deliberately or accidentally. -In addition, supply chain attacks can occur on build dependencies, -whereby attackers take over control of NPM or Maven packages and insert malicious code. +In addition, supply chain attacks can occur on build dependencies, whereby attackers take over control of NPM or Maven packages and insert malicious code. You can see the complexity of keeping your Jenkins instance secure. -In the following sections we discuss specific protections that Jenkins provides -and practices that you can implement to protect Jenkins from intrusions. +In the following sections we discuss specific protections that Jenkins provides and practices that you can implement to protect Jenkins from intrusions. diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 85b98c57e5af..7411b1ff57dd 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -11,51 +11,27 @@ endif::[] Never run builds on the Jenkins controller in production environments. Out of the box, Jenkins is set up to run builds on the built-in controller node. -This makes it easier to get started with Jenkins, -but, on production instances, -builds should only be executed on nodes that are external to the controller. - -A build job that uses an agent running on the built-in controller node -may be able to access Jenkins configuration files and the workspaces of other builds. -An agent could also request information -that belongs to other teams or organizations that share the controller. -Configuring Jenkins as a -link:/doc/book/scaling/architecting-for-scale/#distributed-builds-architecture[distributed build system] -enhances the security of your Jenkins instance -as well as improving its performance and making it more stable. -This is because builds that run on the built-in node -have the same level of access to the controller file system as the Jenkins process itself. -Configuring your Jenkins instance so that builds -execute on agents running on separate nodes -protects the Jenkins controller from malicious (or just broken) build scripts. - -When distributed builds are implemented, -the Jenkins controller serves HTTP requests -and stores all important information related to the builds. -Nodes are separate physical or virtual machines that are configured. -The Jenkins controller manages these nodes, -but the agents manage the task execution on behalf of the Jenkins controller -and supply most of the computing power required to build and test the software. -Different nodes can run different operating systems and different tools, -enabling one Pipeline to build and test the same software -for a variety of platforms. +This makes it easier to get started with Jenkins, but, on production instances, builds should only be executed on nodes that are external to the controller. + +A build job that uses an agent running on the built-in controller node may be able to access Jenkins configuration files and the workspaces of other builds. +An agent could also request information that belongs to other teams or organizations that share the controller. +Configuring Jenkins as a link:/doc/book/scaling/architecting-for-scale/#distributed-builds-architecture[distributed build system] enhances the security of your Jenkins instance as well as improving its performance and making it more stable. +This is because builds that run on the built-in node have the same level of access to the controller file system as the Jenkins process itself. +Configuring your Jenkins instance so that builds execute on agents running on separate nodes protects the Jenkins controller from malicious (or just broken) build scripts. + +When distributed builds are implemented, the Jenkins controller serves HTTP requests and stores all important information related to the builds. +Nodes are separate physical or virtual machines that are configured. The Jenkins controller manages these nodes, but the agents manage the task execution on behalf of the Jenkins controller and supply most of the computing power required to build and test the software. +Different nodes can run different operating systems and different tools, enabling one Pipeline to build and test the same software for a variety of platforms. [NOTE] ==== A job that performs administrative tasks such as backups may run on the controller. -To reduce the chance of someone using this executor to run a job, -label the executor with a hard-to-guess label -and only allow it to be used by jobs that specify that label. - -An executor can be temporarily configured on the controller -long enough to run the administrative task -but no executors should be configured on the controller at other times -to ensure that no builds execute on the controller -since a clever Pipeline author may be able to work around the label restriction. - -You can install the plugin:job-restrictions[Job Restrictions Plugin] -to ensure that builds do not run on the controller -even if executors are configured. +To reduce the chance of someone using this executor to run a job, label the executor with a hard-to-guess label and only allow it to be used by jobs that specify that label. + +An executor can be temporarily configured on the controller long enough to run the administrative task but no executors should be configured on the controller at other times +This ensures that no builds execute on the controller since a clever Pipeline author may be able to work around the label restriction. + +You can install the plugin:job-restrictions[Job Restrictions Plugin] to ensure that builds do not run on the controller even if executors are configured. ==== An agent can also write malicious code to its local disk so that the node is tainted and can infect a later build. @@ -66,8 +42,7 @@ By extension, you also should not run agents on the same Docker host as the cont == Distributed Components A Jenkins distributed builds instance includes the following components. -For more details about these components, see -link:/doc/book/managing/nodes/[Managing Nodes]. +For more details about these components, see link:/doc/book/managing/nodes/[Managing Nodes]. Jenkins controller:: @@ -87,15 +62,12 @@ In practice, nodes and agents are essentially the same but it is good to remembe Executors:: -An executor is a slot for execution of tasks; -effectively, it is a thread in the agent. -The number of executors on a node defines the number of concurrent tasks -that can be executed on that node at one time. +An executor is a slot for execution of tasks; effectively, it is a thread in the agent. +The number of executors on a node defines the number of concurrent tasks that can be executed on that node at one time. == Implementing Distributed Builds -To implement distributed builds on your Jenkins instance, -you must do the following: +To implement distributed builds on your Jenkins instance, you must do the following: * Create nodes and agents where the builds can run. * Prevent builds from running on the controller. @@ -104,11 +76,8 @@ This section also includes other tips and tricks you can use. === Create Nodes and Agents for Builds -To implement a distributed builds architecture for your Jenkins instance, -you must configure nodes and agents to use for your builds. -See -link:/doc/book/managing/nodes/[Managing Nodes] -for instructions. +To implement a distributed builds architecture for your Jenkins instance, you must configure nodes and agents to use for your builds. +See link:/doc/book/managing/nodes/[Managing Nodes] for instructions. === Prevent Builds from Running on the Controller @@ -120,37 +89,22 @@ To do this: . Set the number of executors to 0. . Save the configuration. -NOTE: A job that performs administrative tasks such as backup may run on the controller, -but be sure to label the executor with a hard-to-guess label -and only allow it to be used by jobs that use that label. -Jenkins should normally be configured to have 0 executors on the controller, -and then be temporarily reconfigured to have 1 executor -long enough to run the backup or other administrative task. -Unless the number of executors is 0, -it is possible for a build to run on the controller. +NOTE: A job that performs administrative tasks such as backup may run on the controller, but be sure to label the executor with a hard-to-guess label and only allow it to be used by jobs that use that label. +Jenkins should normally be configured to have 0 executors on the controller, and then be temporarily reconfigured to have 1 executor long enough to run the backup or other administrative task. +Unless the number of executors is 0, it is possible for a build to run on the controller. 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 Jenkins 2.326 and later (see link:jep-235[Agent → Controller Security Changes in 2.326]). +This system is always enabled in Jenkins 2.326 and later (see link:jep-235[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 » Configure Global Security_ page. -IMPORTANT: It is strongly recommended that you not disable the Agent → Controller Access Control system. - -As an alternative to disabling Agent → Controller Access Control, in Jenkins 2.325 and earlier, administrators can selectively allow greater access. +It is possible for administrators to selectively allow greater access. See link:/doc/book/security/controller-isolation/agent-to-controller/[the documentation] for details. === Other Tips and Tricks -Another way to prevent builds from running on the controller -is to use a plugin such as the plugin:job-restrictions[Job Restrictions Plugin] -to limit which jobs can be run on certain nodes (like the built-in controller node), -independent of what your less trusted users may use as label expression in their job configurations. - -If you do not have any other computers on which to run agents, -you can run an agent process as a different operating system user on the same system -to achieve a similar isolation effect. -In this case, -be sure that the agent process has neither read nor write file system access -to the Jenkins home directory, -and that the agent process cannot use `sudo` or other practices to elevate its own permissions. +Another way to prevent builds from running on the controller is to use a plugin such as the plugin:job-restrictions[Job Restrictions Plugin] to limit which jobs can be run on certain nodes (like the built-in controller node), independent of what your less trusted users may use as label expression in their job configurations. + +If you do not have any other computers on which to run agents, you can run an agent process as a different operating system user on the same system to achieve a similar isolation effect. +In this case, be sure that the agent process has neither read nor write file system access to the Jenkins home directory, and that the agent process cannot use `sudo` or other practices to elevate its own permissions. diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 9c3e731efbe4..9c7c7622b066 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -44,7 +44,7 @@ Discusses security principles that should guide all your decisions about securit and explains how Jenkins executes a Pipeline so you understand where intrusions can occur if your security configuration is lax. link:controller-isolation[Distributed Builds]:: -Builds should not be executed on the built-in node, but that is just the beginning: +Builds should not be executed on the built-in node, but that is just the beginning. This section discusses what other steps can be taken to protect the controller from being impacted by running builds. *This needs to be configured according to the needs of your environment.* @@ -58,8 +58,7 @@ This chapter discusses which level of access is provided by permissions and how _This is set up securely by the setup wizard. If the setup wizard is disabled on first launch, this may not be configured securely by default._ link:tcp-port[TCP Port for InBound Agents]:: -If you are using TCP for inbound agents (previously called JNLP), -you must configure a TCP port to use. +If you are using TCP for inbound agents (previously called JNLP), you must configure a TCP port to use. This section discusses how to configure the TCP port and discusses alternative implementations that do not require the TCP port. link:markup-formatter[Markup Formatter]:: From c545ed7443c69924a567ea20faa8635afd684b46 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 21 Jan 2022 00:10:13 -0800 Subject: [PATCH 46/59] restore TODO about Agent -> Controller version --- content/doc/book/security/controller-isolation.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 7411b1ff57dd..8f8dd1022702 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -96,6 +96,7 @@ Unless the number of executors is 0, it is possible for a build to run on the co 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. +// TODO Also mention first LTS once it's known This system is always enabled in Jenkins 2.326 and later (see link:jep-235[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 » Configure Global Security_ page. From dd7768ae4176a1d3ff58757464f785417a2c384d Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 21 Jan 2022 00:38:16 -0800 Subject: [PATCH 47/59] details about agent->controller in that page; disabling is history --- .../doc/book/security/agent-controller-access.adoc | 13 +++++++++---- content/doc/book/security/controller-isolation.adoc | 10 +--------- 2 files changed, 10 insertions(+), 13 deletions(-) diff --git a/content/doc/book/security/agent-controller-access.adoc b/content/doc/book/security/agent-controller-access.adoc index bd9a7323b302..932a30287e98 100644 --- a/content/doc/book/security/agent-controller-access.adoc +++ b/content/doc/book/security/agent-controller-access.adoc @@ -1,5 +1,5 @@ --- -title: Agent → Controller Access Control +title: Agent → Controller Security layout: section --- ifdef::backend-html5[] @@ -27,9 +27,14 @@ This filter may prevent your builds from executing legitimate operations. * You can also tweak the filter's rules by adding `allow/deny` rules to specify the commands that you need and the type of access that is allowed for the agent. See link:/doc/book/security/controller-isolation/agent-to-controller/[Customizing Agent -> Controller Security] for more information. -It is also possible (but strongly discouraged) to disable this filter -by un-checking the box on the _Manage Jenkins » Configure Global Security_ page: +[NOTE] +==== +// TODO Add mention of first LTS once it's known +In releases prior to Jenkins 2.326 (see link:jep-235[Agent → Controller Security Changes in 2.326]), this protection could be +disabled in the web UI by un-checking the box on the _Manage Jenkins » Configure Global Security_ page, although this was strongly discouraged. image::security/configure-global-security-agent-controller-toggle.png["Configure Global Security - Enable Agent => Controller Access Control", role=center] -IMPORTANT: It is strongly recommended that you not disable the Agent → Controller Access Control filter. +See link:/doc/book/security/controller-isolation/agent-to-controller/[the documentation] for details. +==== + diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 8f8dd1022702..85db4336bf3c 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -93,15 +93,7 @@ NOTE: A job that performs administrative tasks such as backup may run on the con Jenkins should normally be configured to have 0 executors on the controller, and then be temporarily reconfigured to have 1 executor long enough to run the backup or other administrative task. Unless the number of executors is 0, it is possible for a build to run on the controller. -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. - -// TODO Also mention first LTS once it's known -This system is always enabled in Jenkins 2.326 and later (see link:jep-235[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 » Configure Global Security_ page. - -It is possible for administrators to selectively allow greater access. -See link:/doc/book/security/controller-isolation/agent-to-controller/[the documentation] for details. +The link:http://localhost:4242/doc/book/security/agent-controller-access/[Agent → Controller Access Control system] provides additional protections for the controller. === Other Tips and Tricks From bc3212ca3cfa15670408107f5bf479052594d1bf Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 21 Jan 2022 00:51:03 -0800 Subject: [PATCH 48/59] Advice to revisit security configuration moved from index to concepts --- content/doc/book/security/concepts.adoc | 7 +++++++ content/doc/book/security/index.adoc | 8 -------- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/content/doc/book/security/concepts.adoc b/content/doc/book/security/concepts.adoc index 218a4939e211..9b40d0997cca 100644 --- a/content/doc/book/security/concepts.adoc +++ b/content/doc/book/security/concepts.adoc @@ -31,6 +31,13 @@ Monitor your Jenkins installation constantly so that you quickly detect signs of Pay attention to link:/security/advisories/[Security Advisories] and apply link:/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] as soon as possible. Keeping the Jenkins software and all plugins current also helps ensure that your system is secure. +* *Revisit your security configuration periodically:* +Most Jenkins environments grow over time, requiring their trust models to evolve as the environment grows. +Schedule regular "check-ups" of your security settings to ensure that they are still appropriate for your instance. +In particular, if you had to disable some of the default protections that Jenkins provides, +perhaps because you were using a plugin that had not been updated to support that protection, you may be able to re-enable that protection to increase the security of your instance. + + == How Jenkins Executes Jobs A simple overview of how Jenkins executes a Freestyle or Pipeline job helps to understand the security considerations. diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index b16559332455..b756a3dbeb83 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -25,14 +25,6 @@ to ensure that Jenkins is secure. Other security options involve environment-specific setup and trade-offs and depend on specific use cases supported for individual Jenkins instances. Configuration options allow you to enable, customize, or disable security features. -[CAUTION] -==== -Most Jenkins environments grow over time, requiring their trust models to evolve as the environment grows. -You should schedule regular "check-ups" of your security settings to ensure that they are still appropriate for your instance. -In particular, if you had to disable some of the default protections that Jenkins provides, -perhaps because you were using a plugin that had not been updated to support that protection, you may be able to re-enable that protection to increase the security of your instance. -==== - // TODO the following only makes sense on the web site, not the PDF. Can it be disabled there? // TODO the material below should be moved to other sections in this chapter. From aec1a092cb0062e1c73dab68586c340a760b2604 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 21 Jan 2022 00:53:07 -0800 Subject: [PATCH 49/59] one sentence per line --- content/doc/book/security/index.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index b756a3dbeb83..f740dd2c26a8 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -31,8 +31,7 @@ Configuration options allow you to enable, customize, or disable security featur This chapter introduces the various security options available to Jenkins administrators and users, explaining the protections offered, and trade-offs to disabling some of them: link:concepts-security[Background Concepts]:: -Discusses security principles that should guide all your decisions about security -and explains how Jenkins executes a Pipeline so you understand where intrusions can occur if your security configuration is lax. +Discusses security principles that should guide all your decisions about security and explains how Jenkins executes a Pipeline so you understand where intrusions can occur if your security configuration is lax. link:controller-isolation[Distributed Builds]:: Builds should not be executed on the built-in node, but that is just the beginning. From 2c46b5a7fb1207713326de81f9a440fb91348620 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 21 Jan 2022 01:05:24 -0800 Subject: [PATCH 50/59] delete securing-jenkins.adoc -- dbeck says these wiki links are obsolete --- content/doc/book/security/index.adoc | 5 ---- .../doc/book/security/securing-jenkins.adoc | 24 ------------------- 2 files changed, 29 deletions(-) delete mode 100644 content/doc/book/security/securing-jenkins.adoc diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index b756a3dbeb83..9e36938673c7 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -77,11 +77,6 @@ Improperly written build scripts may be tricked into behaving differently than i This section discusses how to protect your builds. *This needs to be configured according to the needs of your environment.* -link:securing-jenkins[Other Security Topics]:: -This is a placeholder for links to old Wiki articles relevant to Security. -These pages are not currently available. -Some of these articles are obsolete or irrelevant and others need to be rewritten and incorporated into the documentation. - link:services[Exposed Services and Ports]:: Jenkins is a complex application that may expose services on the network. This chapter provides information about these services. diff --git a/content/doc/book/security/securing-jenkins.adoc b/content/doc/book/security/securing-jenkins.adoc deleted file mode 100644 index b81fa911344b..000000000000 --- a/content/doc/book/security/securing-jenkins.adoc +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Other Security Topics -layout: section -wip: true ---- -ifdef::backend-html5[] -:notitle: -:description: -:author: -:email: jenkinsci-users@googlegroups.com -ifdef::env-github[:imagesdir: ../resources] -ifndef::env-github[:imagesdir: ../../resources] -:toc: left -endif::[] - -This page is a placeholder for links to some old Wiki pages until we can properly dispose of this information. - -* https://wiki.jenkins.io/display/JENKINS/Quick+and+Simple+Security[Quick and Simple Security] --- if you are running Jenkins like `java -jar jenkins.war` and only need a very simple setup -* https://wiki.jenkins.io/display/JENKINS/Standard+Security+Setup[Standard Security Setup] --- discusses the most common setup of letting Jenkins run its own user database and do finer-grained access control -* https://wiki.jenkins.io/display/JENKINS/Apache+frontend+for+security[Apache frontend for security] --- run Jenkins behind Apache and perform access control in Apache instead of Jenkins -* https://wiki.jenkins.io/display/JENKINS/Authenticating+scripted+clients[Authenticating scripted clients] --- if you need to programmatically access security-enabled Jenkins web UI, use BASIC auth -* https://wiki.jenkins.io/display/JENKINS/Matrix-based+security[Matrix-based security|Matrix-based security] --- Granting and denying finer-grained permissions - -In addition to access control of users, link:build-authorization[access control for builds] limits what builds can do, once started. From d512ff777674874c2ffcdeef614d2f0a1edbae50 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 21 Jan 2022 01:08:18 -0800 Subject: [PATCH 51/59] InBound -> Inbound Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com> --- content/doc/book/security/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index f740dd2c26a8..d356270a87ff 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -47,7 +47,7 @@ By default, Jenkins does not allow anonymous access, and a single admin user exi This chapter discusses which level of access is provided by permissions and how to safely grant access to more users. _This is set up securely by the setup wizard. If the setup wizard is disabled on first launch, this may not be configured securely by default._ -link:tcp-port[TCP Port for InBound Agents]:: +link:tcp-port[TCP Port for Inbound Agents]:: If you are using TCP for inbound agents (previously called JNLP), you must configure a TCP port to use. This section discusses how to configure the TCP port and discusses alternative implementations that do not require the TCP port. From 2549d42a5a78ad29cdfd274e942e6d4b6c374a73 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 21 Jan 2022 01:26:07 -0800 Subject: [PATCH 52/59] fix indentation Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com> --- content/doc/book/security/access-control.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/book/security/access-control.adoc b/content/doc/book/security/access-control.adoc index bc32b9197569..93869c5f63ec 100644 --- a/content/doc/book/security/access-control.adoc +++ b/content/doc/book/security/access-control.adoc @@ -16,7 +16,7 @@ These can be independent, or work in combination: * An example of an independent configuration is using plugin:active-directory[Active Directory] or plugin:ldap[LDAP] as security realm, and something like plugin:matrix-auth[Matrix Authorization Strategy] as the authorization strategy. * An example of a related security realm and authorization strategy configuration is plugin:github-oauth[GitHub Authentication]. -While the Github Authentication security realm can be used with a generic authorization strategy, it also provides an authorization strategy that looks up a user's repository permissions on GitHub, and grants or denies permissions to related jobs in Jenkins based on that. + While the Github Authentication security realm can be used with a generic authorization strategy, it also provides an authorization strategy that looks up a user's repository permissions on GitHub, and grants or denies permissions to related jobs in Jenkins based on that. Jenkins can be set up to have basic access control happen outside of it. Some examples: From 8b9af000ef1fc5cc78935bfba7e13b7a9a25882c Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 21 Jan 2022 01:32:14 -0800 Subject: [PATCH 53/59] "Jenkins Access Control" -> "Access Control" --- content/doc/book/security/access-control.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/book/security/access-control.adoc b/content/doc/book/security/access-control.adoc index 93869c5f63ec..aa088585fc2d 100644 --- a/content/doc/book/security/access-control.adoc +++ b/content/doc/book/security/access-control.adoc @@ -1,5 +1,5 @@ --- -title: Jenkins Access Control +title: Access Control layout: section --- :toc: From ed0e59704c6fbda9b1a7066af950aacae23e098b Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Sun, 23 Jan 2022 01:32:40 -0800 Subject: [PATCH 54/59] How Jenkins executes Pipeline -> job --- content/doc/book/security/concepts.adoc | 14 +++++++++----- content/doc/book/security/index.adoc | 2 +- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/content/doc/book/security/concepts.adoc b/content/doc/book/security/concepts.adoc index 9b40d0997cca..859acb72c640 100644 --- a/content/doc/book/security/concepts.adoc +++ b/content/doc/book/security/concepts.adoc @@ -37,13 +37,19 @@ Schedule regular "check-ups" of your security settings to ensure that they are s In particular, if you had to disable some of the default protections that Jenkins provides, perhaps because you were using a plugin that had not been updated to support that protection, you may be able to re-enable that protection to increase the security of your instance. - -== How Jenkins Executes Jobs +== How Jenkins executes jobs A simple overview of how Jenkins executes a Freestyle or Pipeline job helps to understand the security considerations. +The execution sequence is similar for Freestyle and Pipeline jobs, with the following differences: + +* Pipelines are controlled by a _Jenkinsfile_ that is written in a scripting language whereas Freestyle jobs are controlled from a configuration defined in the UI. +The scripting language supports features such as loops and allows more flexibility about when and where a build script executes; +these features also provide additional opportunities to do mischief. +* The _Jenkinsfile_ is stored under SCM, which can initiate its execution, so securing the SCM is also an important part of protecting the integrity of your Jenkins installation. By default, a job executes with the full privileges of the Jenkins administrator, although you can configure Jenkins to execute jobs with fewer privileges. -All of the job's logic, the Groovy conditionals, loops, and so forth execute on the controller. + +All of the job's logic as well as a Pipeline's Groovy conditionals, loops, and so forth execute on the controller. When the job runs: @@ -69,5 +75,3 @@ In addition, supply chain attacks can occur on build dependencies, whereby attac You can see the complexity of keeping your Jenkins instance secure. In the following sections we discuss specific protections that Jenkins provides and practices that you can implement to protect Jenkins from intrusions. - - diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index 1b5b4061842f..bc7fc8d630bc 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -31,7 +31,7 @@ Configuration options allow you to enable, customize, or disable security featur This chapter introduces the various security options available to Jenkins administrators and users, explaining the protections offered, and trade-offs to disabling some of them: link:concepts-security[Background Concepts]:: -Discusses security principles that should guide all your decisions about security and explains how Jenkins executes a Pipeline so you understand where intrusions can occur if your security configuration is lax. +Discusses security principles that should guide all your decisions about security and explains how Jenkins executes a job so you understand where intrusions can occur if your security configuration is lax. link:controller-isolation[Distributed Builds]:: Builds should not be executed on the built-in node, but that is just the beginning. From 89adbc6da07a852c623a401b78985546b7e57ec0 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Sun, 23 Jan 2022 04:18:23 -0800 Subject: [PATCH 55/59] Deleted securing-jenkins from _chapter.yml --- content/doc/book/security/_chapter.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/content/doc/book/security/_chapter.yml b/content/doc/book/security/_chapter.yml index 7504cf475bc4..14f47fcc5a19 100644 --- a/content/doc/book/security/_chapter.yml +++ b/content/doc/book/security/_chapter.yml @@ -17,8 +17,5 @@ sections: - agent-controller-access - environment-variables -# Legacy sections - - securing-jenkins - # Further references - services From d5b6325216fded6f4315716038c13c768e666b59 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 25 Jan 2022 17:42:30 -0800 Subject: [PATCH 56/59] new file for "How Jenkins Executes a Job"; rename "Security Concepts" --- content/doc/book/security/_chapter.yml | 1 + content/doc/book/security/concepts.adoc | 56 +++---------------- .../doc/book/security/how-jobs-execute.adoc | 41 ++++++++++++++ 3 files changed, 49 insertions(+), 49 deletions(-) create mode 100644 content/doc/book/security/how-jobs-execute.adoc diff --git a/content/doc/book/security/_chapter.yml b/content/doc/book/security/_chapter.yml index 14f47fcc5a19..368ead572d5b 100644 --- a/content/doc/book/security/_chapter.yml +++ b/content/doc/book/security/_chapter.yml @@ -4,6 +4,7 @@ sections: # General information - concepts + - how-jobs-execute - controller-isolation - managing-security diff --git a/content/doc/book/security/concepts.adoc b/content/doc/book/security/concepts.adoc index 859acb72c640..583699a0c945 100644 --- a/content/doc/book/security/concepts.adoc +++ b/content/doc/book/security/concepts.adoc @@ -1,17 +1,9 @@ --- -title: Background Concepts +title: Security Concepts layout: section --- -To properly manage the security of your Jenkins instance, you should be familiar with: - -* Security principles that should guide all your decisions -* How Jenkins executes a Freestyle or Pipeline job -If you understand the vulnerabilities that an intrusion could exploit, you can better understand how to protect against those intrusions. - -## Security Principles - -Security principles should guide the practices and tools used to fight and prevent threats. +Security concepts should guide the practices and tools used to fight and prevent threats. The major principles for security are: * *Least privilege:* @@ -19,6 +11,7 @@ Give people the privileges required to do their jobs but do not give everyone pe * *Know the system:* The more you understand about how your system works, the more you are prepared to protect the integrity of your system. +See link:/doc/book/security/how-jobs-execute/[How Jenkins Executes Jobs] for a summary of the Jenkins execution sequence. * *Defense in depth:* Systems are layered. @@ -27,9 +20,12 @@ Put security on all layers. * *Prevention is good, but detection is better:* Monitor your Jenkins installation constantly so that you quickly detect signs of a security breach. +Good practices that help keep your instance secure include: + * *Keep your system current:* -Pay attention to link:/security/advisories/[Security Advisories] and apply link:/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] as soon as possible. +Pay attention to Jenkins link:/security/advisories/[Security Advisories] and apply link:/security/for-administrators/#how-quickly-should-i-apply-security-updates[Security Updates] as soon as possible. Keeping the Jenkins software and all plugins current also helps ensure that your system is secure. +Also be sure to keep all other software up to date, including the underlying operating system software, build tools, and test tools that you use. * *Revisit your security configuration periodically:* Most Jenkins environments grow over time, requiring their trust models to evolve as the environment grows. @@ -37,41 +33,3 @@ Schedule regular "check-ups" of your security settings to ensure that they are s In particular, if you had to disable some of the default protections that Jenkins provides, perhaps because you were using a plugin that had not been updated to support that protection, you may be able to re-enable that protection to increase the security of your instance. -== How Jenkins executes jobs - -A simple overview of how Jenkins executes a Freestyle or Pipeline job helps to understand the security considerations. -The execution sequence is similar for Freestyle and Pipeline jobs, with the following differences: - -* Pipelines are controlled by a _Jenkinsfile_ that is written in a scripting language whereas Freestyle jobs are controlled from a configuration defined in the UI. -The scripting language supports features such as loops and allows more flexibility about when and where a build script executes; -these features also provide additional opportunities to do mischief. -* The _Jenkinsfile_ is stored under SCM, which can initiate its execution, so securing the SCM is also an important part of protecting the integrity of your Jenkins installation. - -By default, a job executes with the full privileges of the Jenkins administrator, although you can configure Jenkins to execute jobs with fewer privileges. - -All of the job's logic as well as a Pipeline's Groovy conditionals, loops, and so forth execute on the controller. - -When the job runs: - -* Jenkins creates a _workspace_ on the controller for each build that runs. -Files for that build are stored in the workspace. -* The job calls a series of _steps_, each of which is a script or command that does the real work and mostly executes using an _executor_ on an _agent_. - -The agent: - -* Writes some files to the local node. -* Sends data back to the controller. -* May also request information from the controller. - -Many different people have some control over the commands that are executed during a build: - -* Jenkins users with Job/Configure permission -* Authors of build scripts such as `pom.xml` and `Makefile` -* Authors of code, such as test suites that are executed during a build - -Any of these could introduce security issues, either deliberately or accidentally. -In addition, supply chain attacks can occur on build dependencies, whereby attackers take over control of NPM or Maven packages and insert malicious code. - -You can see the complexity of keeping your Jenkins instance secure. -In the following sections we discuss specific protections that Jenkins provides and practices that you can implement to protect Jenkins from intrusions. - diff --git a/content/doc/book/security/how-jobs-execute.adoc b/content/doc/book/security/how-jobs-execute.adoc new file mode 100644 index 000000000000..b2d97cd59fa8 --- /dev/null +++ b/content/doc/book/security/how-jobs-execute.adoc @@ -0,0 +1,41 @@ +--- +title: How Jenkins Executes Jobs +layout: section +--- + +A simple overview of how Jenkins executes a Freestyle or Pipeline job helps to understand the security considerations. +The execution sequence is similar for Freestyle and Pipeline jobs, with the following differences: + +* Pipelines are controlled by a _Jenkinsfile_ that is written in a scripting language whereas Freestyle jobs are controlled from a configuration defined in the UI. +The scripting language supports features such as loops and allows more flexibility about when and where a build script executes; +these features also provide additional opportunities to do mischief. +* The _Jenkinsfile_ is stored under SCM, which can initiate its execution, so securing the SCM is also an important part of protecting the integrity of your Jenkins installation. + +By default, a job executes with the full privileges of the Jenkins administrator, although you can configure Jenkins to execute jobs with fewer privileges. + +All of the job's logic as well as a Pipeline's Groovy conditionals, loops, and so forth execute on the controller. + +When the job runs: + +* Jenkins creates a _workspace_ on the controller for each build that runs. +Files for that build are stored in the workspace. +* The job calls a series of _steps_, each of which is a script or command that does the real work and mostly executes using an _executor_ on an _agent_. + +The agent: + +* Writes some files to the local node. +* Sends data back to the controller. +* May also request information from the controller. + +Many different people have some control over the commands that are executed during a build: + +* Jenkins users with Job/Configure permission +* Authors of build scripts such as `pom.xml` and `Makefile` +* Authors of code, such as test suites that are executed during a build + +Any of these could introduce security issues, either deliberately or accidentally. +In addition, supply chain attacks can occur on build dependencies, whereby attackers take over control of NPM or Maven packages and insert malicious code. + +You can see the complexity of keeping your Jenkins instance secure. +In the following sections we discuss specific protections that Jenkins provides and practices that you can implement to protect Jenkins from intrusions. + From 1d349e8fcf173b5cb653a59cece2a2d1fa4acd12 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 25 Jan 2022 20:36:04 -0800 Subject: [PATCH 57/59] Remove links to pages for fields on Configure Security page from index.adoc --- content/doc/book/security/index.adoc | 45 +++++-------------- .../doc/book/security/managing-security.adoc | 28 +++++++----- 2 files changed, 29 insertions(+), 44 deletions(-) diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index bc7fc8d630bc..d3ff298ba0e6 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -15,7 +15,7 @@ It is critically important to keep your Jenkins instance secure,both to protect Your Jenkins environment is a fully-distributed build system. Each network connection is a potential point of entry. -Jenkins and the jobs it runs must be able to do almost anything, which means that the code that runs your builds can be perverted to run anything! +Jenkins and the jobs it runs must be able to do almost anything, which means that the code that runs your builds can be perverted to run almost anything! For example, a malicious Pipeline could reconfigure the Jenkins instance, delete files, or launch various forms of mischief such as a DDoS attack or a bot. In addition to deliberate and direct attacks on your environment, a trusted user could visit an infected web site and accidentally introduce malicious code into the Jenkins instance. @@ -28,53 +28,32 @@ Configuration options allow you to enable, customize, or disable security featur // TODO the following only makes sense on the web site, not the PDF. Can it be disabled there? // TODO the material below should be moved to other sections in this chapter. -This chapter introduces the various security options available to Jenkins administrators and users, explaining the protections offered, and trade-offs to disabling some of them: +This chapter introduces the various security options available to Jenkins administrators and users, explaining the protections offered, and what to do if a security feature blocks legitimate tasks required in your environment: -link:concepts-security[Background Concepts]:: +link:concepts-security[Security Concepts]:: Discusses security principles that should guide all your decisions about security and explains how Jenkins executes a job so you understand where intrusions can occur if your security configuration is lax. +link:/doc/book/security/how-jobs-execute/[How Jenkins Executes Jobs]:: +Gives an overview of the internal steps Jenkins takes to execute a job so you can better understand how how malicious code can compromise a Jenkins instance if it is not configured properly. + link:controller-isolation[Distributed Builds]:: Builds should not be executed on the built-in node, but that is just the beginning. -This section discusses what other steps can be taken to protect the controller from being impacted by running builds. -*This needs to be configured according to the needs of your environment.* +This section discusses what other steps can be taken to protect the controller from being impacted by running builds and the protections Jenkins itself provides.. link:managing-security[Configure Global Security]:: Much of the basic security configuration is implemented on the _Manage Jenkins >> Configure Global Security_ page. -Here you see the fields that are configured on that page and get links to other sections that explain each field in detail. - -link:access-control[Jenkins Access Control]:: -By default, Jenkins does not allow anonymous access, and a single admin user exists. -This chapter discusses which level of access is provided by permissions and how to safely grant access to more users. -_This is set up securely by the setup wizard. If the setup wizard is disabled on first launch, this may not be configured securely by default._ - -link:tcp-port[TCP Port for Inbound Agents]:: -If you are using TCP for inbound agents (previously called JNLP), you must configure a TCP port to use. -This section discusses how to configure the TCP port and discusses alternative implementations that do not require the TCP port. - -link:markup-formatter[Markup Formatter]:: -The default markup formatter renders text as entered (i.e. escaping HTML metacharacters). -This chapter explains how to switch to a different markup formatter and explains what admins need to be aware of. -_This is set up securely by default._ - -link:csrf-protection[CSRF Protection]:: -Jenkins protects from cross-site request forgery (CSRF) by default. -This chapter explains how to work around any problems this may cause. -_This is set up securely by default._ -// TODO Confirm that skipping the setup wizard in 2.222 does no longer disable CSRF protection +Here you see the fields that are configured on that page and get links to other pages that explain each field in detail. link:user-content[Rendering User Content]:: -By default, Jenkins strictly limits the features useable in user content (files from workspaces, archived artifacts, etc.) it serves. -This chapter discusses how to customize this and make HTML reports and similar content both functional and safe to view. -_This is set up securely by default._ +By default, Jenkins strictly limits the features that are served in user content (files from workspaces, archived artifacts, etc.) it serves. +This page discusses how to customize this and make HTML reports and similar content both functional and safe to view. link:build-authorization[Access Control for Builds]:: -Learn how to restrict what individual builds can do in Jenkins once they're running. -*This needs to be configured according to the needs of your environment.* +Learn how to restrict what individual builds can do in Jenkins once they are running. link:environment-variables[Handling Environment Variables]:: Improperly written build scripts may be tricked into behaving differently than intended due to special environment variable names or values being injected as build parameters. -This section discusses how to protect your builds. -*This needs to be configured according to the needs of your environment.* +This page discusses how to configure environment variables to protect your builds. link:services[Exposed Services and Ports]:: Jenkins is a complex application that may expose services on the network. diff --git a/content/doc/book/security/managing-security.adoc b/content/doc/book/security/managing-security.adoc index d40391c94365..d2a06665bf4c 100644 --- a/content/doc/book/security/managing-security.adoc +++ b/content/doc/book/security/managing-security.adoc @@ -46,15 +46,17 @@ TODO: Justify this with the actual UI page so it includes all fields in a reason //// link:/doc/book/security/access-control[Jenkins Access Control]:: -During installation, Jenkins creates the "admin" user who has full permissions to do everything. +During installation, Jenkins creates the "admin" user who has full permissions to do everything and does not allow anonymous access.. Use the *Security Realm* and *Authorization* blocks on this page -to define the scheme used to add and manage additional users. +to safely add and manage additional users and grant them appropriate permissions. +Note that, if the setup wizard is disabled on first launch, access may not be configured securely by default. link:/doc/book/security/tcp-port[TCP Port for Inbound Agents]:: Inbound agents (such as Windows agents) require a TCP port. By default, this port is disabled. If your builds use inbound agents, you must configure this port. If your builds do not use inbound agents, you should leave this port disabled. +Note also that it may be able to implement this functionality using SSH or the WebSocket Transport. The **Global Security Settings** screen also includes fields to configure or enable @@ -67,21 +69,25 @@ but still leave it enabled. In many cases, plugins and practices are available to reduce the security vulnerability of these features. -link:/doc/book/security/markup-formatter/[Markup Formatters]:: +* link:/doc/book/security/markup-formatter/[Markup Formatters]:: Controls how HTML formatting in descriptions is handled. -Some of these characters can be used maliciously, -so the default is _Plain text_ -but plugins are available that allow some of the formatting to be rendered. +The default markup formatter renders text as entered (i.e. escaping HTML metacharacters). +Some of these characters can be used maliciously, so the default is _Plain text_ but plugins are available that allow some of the formatting to be rendered. -link:/doc/book/security/csrf-protection[CSRF Protection]:: +* link:/doc/book/security/csrf-protection[CSRF Protection]:: CSRF is an exploit that enables an unauthorized third party to perform requests against a web application by impersonating another, authenticated user. In a Jenkins environment, a CSRF attack could allow a malicious actor to delete projects, alter builds, or modify the system configuration of the Jenkins instance. - - -link:/doc/book/security/agent-controller-access[Agent → Controller Access Control]:: -Prevents an agent from sending malicious commands to the controller. +Jenkins protects from cross-site request forgery (CSRF) by default. +This page explains how to work around any problems this may cause. +// TODO Confirm that skipping the setup wizard in 2.222 no longer disables CSRF protection + +* The Agent → Controller Access Control filter +prevents an agent from sending malicious commands to the controller: +This filter is discussed on the +link:http://localhost:4242/doc/book/security/controller-isolation/[Distributed Builds] page. +It can not be disabled from the UI although the filter's rules can be tweaked when necessary. From 4b4ced3b3dd5bc0e535dcfd72c134f59102d724b Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 25 Jan 2022 20:55:03 -0800 Subject: [PATCH 58/59] Move Agent -> Controller Security into controller-isolation.adoc --- content/doc/book/security/_chapter.yml | 1 - .../security/agent-controller-access.adoc | 40 ------------------- .../book/security/controller-isolation.adoc | 30 +++++++++++++- content/doc/book/security/index.adoc | 2 +- .../doc/book/security/managing-security.adoc | 4 +- 5 files changed, 31 insertions(+), 46 deletions(-) delete mode 100644 content/doc/book/security/agent-controller-access.adoc diff --git a/content/doc/book/security/_chapter.yml b/content/doc/book/security/_chapter.yml index 368ead572d5b..353a7d6c2dad 100644 --- a/content/doc/book/security/_chapter.yml +++ b/content/doc/book/security/_chapter.yml @@ -15,7 +15,6 @@ sections: - csrf-protection - user-content - build-authorization - - agent-controller-access - environment-variables # Further references diff --git a/content/doc/book/security/agent-controller-access.adoc b/content/doc/book/security/agent-controller-access.adoc deleted file mode 100644 index 932a30287e98..000000000000 --- a/content/doc/book/security/agent-controller-access.adoc +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Agent → Controller Security -layout: section ---- -ifdef::backend-html5[] -:notitle: -:description: -:author: -:email: jenkinsci-docs@googlegroups.com -:sectanchors: -:toc: -ifdef::env-github[:imagesdir: ../resources] -ifndef::env-github[:imagesdir: ../../resources] -:hide-uri-scheme: -endif::[] - -The Jenkins controller and agents can be thought of as a distributed process that executes across multiple discrete processes and machines. -Not building on the built-in controller node is an essential practice to protect the controller from bugs and less sophisticated attackers. -However, an agent can stil ask the controller process for information such as the contents of files, and can even request that the controller run certain commands. -This means that an agent process taken over by a malicious user could still obtain data or execute commands on the Jenkins controller. -To prevent this, Jenkins implements the **Agent → Controller Access Control** filter that prevents agent processes from sending malicious commands to the Jenkins controller. - -This filter may prevent your builds from executing legitimate operations. - -* If builds are failing because of the agent-to-controller access control, you should first ensure that you have upgraded to the latest version of all plugins, since older versions of plugins may not work correctly with this feature. - -* You can also tweak the filter's rules by adding `allow/deny` rules to specify the commands that you need and the type of access that is allowed for the agent. -See link:/doc/book/security/controller-isolation/agent-to-controller/[Customizing Agent -> Controller Security] for more information. - -[NOTE] -==== -// TODO Add mention of first LTS once it's known -In releases prior to Jenkins 2.326 (see link:jep-235[Agent → Controller Security Changes in 2.326]), this protection could be -disabled in the web UI by un-checking the box on the _Manage Jenkins » Configure Global Security_ page, although this was strongly discouraged. - -image::security/configure-global-security-agent-controller-toggle.png["Configure Global Security - Enable Agent => Controller Access Control", role=center] - -See link:/doc/book/security/controller-isolation/agent-to-controller/[the documentation] for details. -==== - diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 85db4336bf3c..33d60a5386a4 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -95,9 +95,35 @@ Unless the number of executors is 0, it is possible for a build to run on the co The link:http://localhost:4242/doc/book/security/agent-controller-access/[Agent → Controller Access Control system] provides additional protections for the controller. -=== Other Tips and Tricks - Another way to prevent builds from running on the controller is to use a plugin such as the plugin:job-restrictions[Job Restrictions Plugin] to limit which jobs can be run on certain nodes (like the built-in controller node), independent of what your less trusted users may use as label expression in their job configurations. +== Agent → Controller Security + +The Jenkins controller and agents can be thought of as a distributed process that executes across multiple discrete processes and machines. +Not building on the built-in controller node is an essential practice to protect the controller from bugs and less sophisticated attackers. +However, an agent can stil ask the controller process for information such as the contents of files, and can even request that the controller run certain commands. +This means that an agent process taken over by a malicious user could still obtain data or execute commands on the Jenkins controller. +To prevent this, Jenkins implements the **Agent → Controller Access Control** filter that prevents agent processes from sending malicious commands to the Jenkins controller. + +This filter may prevent your builds from executing legitimate operations. + +* If builds are failing because of the agent-to-controller access control, you should first ensure that you have upgraded to the latest version of all plugins, since older versions of plugins may not work correctly with this feature. + +* You can also tweak the filter's rules by adding `allow/deny` rules to specify the commands that you need and the type of access that is allowed for the agent. +See link:/doc/book/security/controller-isolation/agent-to-controller/[Customizing Agent -> Controller Security] for more information. + +[NOTE] +==== +// TODO Add mention of first LTS once it's known +In releases prior to Jenkins 2.326 (see link:jep-235[Agent → Controller Security Changes in 2.326]), this protection could be +disabled in the web UI by un-checking the box on the _Manage Jenkins » Configure Global Security_ page, although this was strongly discouraged. + +image::security/configure-global-security-agent-controller-toggle.png["Configure Global Security - Enable Agent => Controller Access Control", role=center] + +See link:/doc/book/security/controller-isolation/agent-to-controller/[the documentation] for details. +==== + +== Other Tips and Tricks + If you do not have any other computers on which to run agents, you can run an agent process as a different operating system user on the same system to achieve a similar isolation effect. In this case, be sure that the agent process has neither read nor write file system access to the Jenkins home directory, and that the agent process cannot use `sudo` or other practices to elevate its own permissions. diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index d3ff298ba0e6..a92aa71a3c3b 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -38,7 +38,7 @@ Gives an overview of the internal steps Jenkins takes to execute a job so you ca link:controller-isolation[Distributed Builds]:: Builds should not be executed on the built-in node, but that is just the beginning. -This section discusses what other steps can be taken to protect the controller from being impacted by running builds and the protections Jenkins itself provides.. +This section discusses what other steps can be taken to protect the controller from being impacted by running builds and the protections Jenkins itself provides. link:managing-security[Configure Global Security]:: Much of the basic security configuration is implemented on the _Manage Jenkins >> Configure Global Security_ page. diff --git a/content/doc/book/security/managing-security.adoc b/content/doc/book/security/managing-security.adoc index d2a06665bf4c..0dd3b9234c2f 100644 --- a/content/doc/book/security/managing-security.adoc +++ b/content/doc/book/security/managing-security.adoc @@ -87,7 +87,7 @@ This page explains how to work around any problems this may cause. * The Agent → Controller Access Control filter prevents an agent from sending malicious commands to the controller: -This filter is discussed on the -link:http://localhost:4242/doc/book/security/controller-isolation/[Distributed Builds] page. +See +link:/doc/book/security/controller-isolation/#agent-controller-security[Agent → Controller Security] for more information. It can not be disabled from the UI although the filter's rules can be tweaked when necessary. From e92c6f76d14b4b2882207ebfcadcdec67b9a24b3 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 26 Jan 2022 03:37:23 -0800 Subject: [PATCH 59/59] fix xref --- content/doc/book/security/controller-isolation.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 33d60a5386a4..74f019a8a4bd 100644 --- a/content/doc/book/security/controller-isolation.adoc +++ b/content/doc/book/security/controller-isolation.adoc @@ -93,7 +93,7 @@ NOTE: A job that performs administrative tasks such as backup may run on the con Jenkins should normally be configured to have 0 executors on the controller, and then be temporarily reconfigured to have 1 executor long enough to run the backup or other administrative task. Unless the number of executors is 0, it is possible for a build to run on the controller. -The link:http://localhost:4242/doc/book/security/agent-controller-access/[Agent → Controller Access Control system] provides additional protections for the controller. +The link:/doc/book/security/agent-controller-access/[Agent → Controller Access Control system] provides additional protections for the controller. Another way to prevent builds from running on the controller is to use a plugin such as the plugin:job-restrictions[Job Restrictions Plugin] to limit which jobs can be run on certain nodes (like the built-in controller node), independent of what your less trusted users may use as label expression in their job configurations.