[4564] Restructure Security section

content/doc/book/security/index.adoc

@@ -9,15 +9,113 @@ 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.
+
+== 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
 

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
@@ -36,19 +55,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