diff --git a/content/doc/book/security/_chapter.yml b/content/doc/book/security/_chapter.yml index f7a36d799c28..353a7d6c2dad 100644 --- a/content/doc/book/security/_chapter.yml +++ b/content/doc/book/security/_chapter.yml @@ -2,19 +2,20 @@ sections: # index - implied overview -- access-control - -# Legacy sections -- securing-jenkins -- managing-security +# General information + - concepts + - how-jobs-execute + - controller-isolation + - managing-security # Individual how-to pages -- controller-isolation -- csrf-protection -- user-content -- build-authorization -- environment-variables -- markup-formatter + - access-control + - tcp-port + - markup-formatter + - csrf-protection + - user-content + - build-authorization + - environment-variables # Further references -- services + - services diff --git a/content/doc/book/security/access-control.adoc b/content/doc/book/security/access-control.adoc index 70c56aebfeaf..aa088585fc2d 100644 --- a/content/doc/book/security/access-control.adoc +++ b/content/doc/book/security/access-control.adoc @@ -5,60 +5,206 @@ layout: section :toc: :toclevels: 4 -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 (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. -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). +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). + +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] +that may not be installed on your instance. ==== -== Common Configuration Mistakes +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. -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. -_Anyone can do anything_:: +[CAUTION] +==== +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. +==== + +--- + +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 + +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 +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. -_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. +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. + +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. -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_. +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. + +//// +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] -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. +[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. +==== -//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]. +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 +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" +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." == 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. @@ -81,6 +227,29 @@ As an example, plugin:matrix-auth[Matrix Authorization Strategy] provides two di 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/concepts.adoc b/content/doc/book/security/concepts.adoc new file mode 100644 index 000000000000..583699a0c945 --- /dev/null +++ b/content/doc/book/security/concepts.adoc @@ -0,0 +1,35 @@ +--- +title: Security Concepts +layout: section +--- + +Security concepts 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. +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. +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 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. +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. + diff --git a/content/doc/book/security/controller-isolation.adoc b/content/doc/book/security/controller-isolation.adoc index 5937b4936311..a1fcb56dc130 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 Builds layout: section --- ifdef::backend-html5[] @@ -9,67 +9,126 @@ 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: +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. -* Jenkins users with Job/Configure permission -* Build script authors (`pom.xml`, `Makefile`, etc.) -* Code authors (for example test code executed during a build) +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. -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. +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. -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. - -[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. +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. +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 +By extension, you also should not run agents on the same Docker host as the controller. -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. +== Distributed Components -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. +A Jenkins distributed builds instance includes the following components. +For more details about these components, see link:/doc/book/managing/nodes/[Managing Nodes]. -// TODO Fix this once https://github.com/jenkinsci/jenkins/pull/5425 is merged and released: +Jenkins controller:: -To prevent builds from running on the built-in node directly, navigate to _Manage Jenkins » Manage Nodes and Clouds_. +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. + +To prevent builds from running drectly on the built-in node, navigate to _Manage Jenkins » Manage Nodes and Clouds_. Select _Built-In Node_ in the list, then select _Configure_ in the menu. Set the number of executors to 0 and save. -Make sure to also set up clouds or build agents to run builds on, otherwise builds won't be able to start. +Configure clouds or build agents where builds can execute. -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. +Nodes:: -[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. -==== +Nodes are the "machines" on which build agents run. +The Jenkins controller itself runs on a special _built-in node_. + +Agents:: + +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:: + +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: +* Create nodes and agents where the builds can run. +* Prevent builds from running on the controller. -//== Infrastructure -// TODO Don't run agents on the same Docker host as the controller etc. +This section also includes other tips and tricks you can use. -== Agent → Controller Access Control +=== Create Nodes and Agents for Builds -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. +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. -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. +=== Prevent Builds from Running on the 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]). -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. +You must also prevent builds from running on the built-in controller node. +To do this: -IMPORTANT: It is strongly recommended that you not disable the Agent → Controller Access Control system. +. 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. + +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. + +== 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] -As an alternative to disabling Agent → Controller Access Control, in Jenkins 2.325 and earlier, administrators can selectively allow greater access. 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/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. + diff --git a/content/doc/book/security/index.adoc b/content/doc/book/security/index.adoc index e131351f350b..a92aa71a3c3b 100644 --- a/content/doc/book/security/index.adoc +++ b/content/doc/book/security/index.adoc @@ -9,55 +9,54 @@ 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. +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. -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. +Your Jenkins environment is a fully-distributed build system. +Each network connection is a potential point of entry. -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 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. + +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. // 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 what to do if a security feature blocks legitimate tasks required in your environment: -== Basic Setup +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:controller-isolation[Controller Isolation]:: -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:/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:access-control[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: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. +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 pages that explain each field in detail. -== Build Behavior +link:user-content[Rendering User Content]:: +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. +This chapter provides information about these services. -== User Interface -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._ diff --git a/content/doc/book/security/managing-security.adoc b/content/doc/book/security/managing-security.adoc index bedeea793ca3..0dd3b9234c2f 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[] @@ -23,202 +24,70 @@ https://github.com/jenkinsci/jenkins/blob/master/core/src/main/resources/jenkins //// -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. - - -== Enabling Security +explicitly disables certain protections. -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. - -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. +//// +Do we want screen shots or not? 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 -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." - -=== Markup Formatter - -See link:/doc/book/security/markup-formatter/[Markup Formatter]. - - -== CSRF Protection - -See link:/doc/book/security/csrf-protection[CSRF Protection]. +//// +TODO: Justify this with the actual UI page so it includes all fields in a reasonable order. +//// -== Agent/Master Access Control +link:/doc/book/security/access-control[Jenkins Access Control]:: +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 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 +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. +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]:: +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. +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: +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. -See link:/doc/book/security/controller-isolation[Isolating the Controller from Builds]. diff --git a/content/doc/book/security/securing-jenkins.adoc b/content/doc/book/security/securing-jenkins.adoc deleted file mode 100644 index 61fb84a33737..000000000000 --- a/content/doc/book/security/securing-jenkins.adoc +++ /dev/null @@ -1,46 +0,0 @@ ---- -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::[] - -= 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. - - -* 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. diff --git a/content/doc/book/security/tcp-port.adoc b/content/doc/book/security/tcp-port.adoc new file mode 100644 index 000000000000..a6a189da3767 --- /dev/null +++ b/content/doc/book/security/tcp-port.adoc @@ -0,0 +1,35 @@ +--- +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. + + +