From a45cd5434335323d144a46e3568600892a9bddfe Mon Sep 17 00:00:00 2001 From: Zbynek Konecny Date: Sun, 2 Oct 2022 09:04:55 +0200 Subject: [PATCH 1/4] Add more permission descriptions --- .../security/access-control/permissions.adoc | 118 +++++++++++++++++- 1 file changed, 116 insertions(+), 2 deletions(-) diff --git a/content/doc/book/security/access-control/permissions.adoc b/content/doc/book/security/access-control/permissions.adoc index 061a3fe22ecc..e0a022fe9881 100644 --- a/content/doc/book/security/access-control/permissions.adoc +++ b/content/doc/book/security/access-control/permissions.adoc @@ -5,8 +5,6 @@ layout: documentation :toc: :toclevels: 3 -// TODO add some more permissions - The following sections describe the access granted to users with (or without) the specified permissions. == Default Permissions @@ -107,6 +105,95 @@ Anything they cannot accomplish through the existing UI they can do through the An instance on which an untrusted user gained _Overall/Administer_ permission should be considered fully compromised and should be replaced. All secrets (credentials, etc.) stored on that instance should be rotated or revoked and all artifacts created from that point on should be verified. + +=== Agent permissions === + +==== Agent/Build ==== + +This permission allows users to run jobs as them on agents. + +==== Agent/Configure + +This permission allows users to configure agents. + +==== Agent/Connect + +This permission allows users to connect agents or mark agents as online.

This permission is implied by Agent/Disconnect. + +==== Agent/Create + +This permission allows users to create agents. + +==== Agent/Delete + +This permission allows users to delete existing agents. + +==== Agent/Disconnect + +This permission allows users to disconnect agents or mark agents as temporarily offline. + +=== Job permissions + +==== Job/Build + +This permission grants the ability to start a new build. + +==== Job/Cancel + +This permission grants the ability to cancel a scheduled, or abort a running, build. + +==== Job/Configure + +Change the configuration of a job. + +==== Job/Create + +Create a new job. + +==== Job/Delete + +Delete a job. + +==== Job/Discover + +This permission grants discover access to jobs. Lower than read permissions, it allows you to redirect anonymous users to the login page when they try to access a job url. Without it they would get a 404 error and wouldn't be able to discover project names.

This permission is implied by Job/Read. + +==== Job/Move + +Required to move a job from one folder (or Jenkins root) to another. + +==== Job/Read + +See a job. (You may deny this permission but allow Discover to force an anonymous user to log in to see the job.) + +==== Job/Workspace + +This permission grants the ability to retrieve the contents of a workspace Jenkins checked out for performing builds. If you don’t want a user to access files in the workspace (e.g. source code checked out from SCM or intermediate build results) through the workspace browser, you can revoke this permission. + +=== Run permissions + +==== Run/Delete + +This permission allows users to manually delete specific builds from the build history. + +==== Run/Update + +This permission allows users to update description and other properties of a build, for example to leave notes about the cause of a build failure. + +=== View permissions + +==== View/Configure +This permission allows users to change the configuration of views. + +==== View/Create +This permission allows users to create new views. + +==== View/Delete +This permission allows users to delete existing views. + +==== View/Read +This permission allows users to see views (implied by generic read access). + == Optional Permissions These permissions are not enabled by default. @@ -141,6 +228,33 @@ Learn more in jep:223[]. NOTE: This permission was added in Jenkins 2.222. Some features, especially those provided by plugins, may not yet support this permission. +=== Credentials permissons + +Following permissions are only enabled if the plugin:credentials[Credentials Plugin] is installed + +==== Credentials/Create +The create permission is necessary to add credentials to a credentials provider. + +==== Credentials/Delete +The delete permission is necessary to remove credentials stored in a credentials provider. + +==== Credentials/ManageDomains +The manage domains permission is necessary to add/remove/configure the credential domains of a credentials provider (where the credentials provider supports multiple credential domains). + +==== Credentials/Update + +The update permission is necessary to modify credentials in a credentials provider. + +==== Credentials/View + +The view permission is necessary to view the credentials stored in a credentials provider. + +=== Pipleline-related permissions + +==== Run/Replay + +Ability to perform a new Pipeline build with an edited script. This permission is implied by Job/Configure. +This permission is enabled by plugin:workflow-cps[Pipeline: Groovy]. == Obsolete Permissions From db8cfb696419a158efa0dd9d3fe612bac9c9214d Mon Sep 17 00:00:00 2001 From: Zbynek Konecny Date: Sun, 2 Oct 2022 18:07:32 +0200 Subject: [PATCH 2/4] AsciiDoc syntax fixes Co-authored-by: Mark Waite --- .../security/access-control/permissions.adoc | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/content/doc/book/security/access-control/permissions.adoc b/content/doc/book/security/access-control/permissions.adoc index e0a022fe9881..0b230869806d 100644 --- a/content/doc/book/security/access-control/permissions.adoc +++ b/content/doc/book/security/access-control/permissions.adoc @@ -106,9 +106,9 @@ An instance on which an untrusted user gained _Overall/Administer_ permission sh All secrets (credentials, etc.) stored on that instance should be rotated or revoked and all artifacts created from that point on should be verified. -=== Agent permissions === +=== Agent permissions -==== Agent/Build ==== +==== Agent/Build This permission allows users to run jobs as them on agents. @@ -118,7 +118,9 @@ This permission allows users to configure agents. ==== Agent/Connect -This permission allows users to connect agents or mark agents as online.

This permission is implied by Agent/Disconnect. +This permission allows users to connect agents or mark agents as online. + +This permission is implied by Agent/Disconnect. ==== Agent/Create @@ -156,7 +158,10 @@ Delete a job. ==== Job/Discover -This permission grants discover access to jobs. Lower than read permissions, it allows you to redirect anonymous users to the login page when they try to access a job url. Without it they would get a 404 error and wouldn't be able to discover project names.

This permission is implied by Job/Read. +This permission grants discover access to jobs. Lower than read permissions, it allows you to redirect anonymous users to the login page when they try to access a job url. +Without it they would get a 404 error and wouldn't be able to discover project names. + +This permission is implied by Job/Read. ==== Job/Move @@ -168,7 +173,8 @@ See a job. (You may deny this permission but allow Discover to force an anonymou ==== Job/Workspace -This permission grants the ability to retrieve the contents of a workspace Jenkins checked out for performing builds. If you don’t want a user to access files in the workspace (e.g. source code checked out from SCM or intermediate build results) through the workspace browser, you can revoke this permission. +This permission grants the ability to retrieve the contents of a workspace Jenkins checked out for performing builds. +If you don’t want a user to access files in the workspace (e.g. source code checked out from SCM or intermediate build results) through the workspace browser, you can revoke this permission. === Run permissions From 54b78ccd988c58ec7580d4f0040338f964497223 Mon Sep 17 00:00:00 2001 From: Zbynek Konecny Date: Fri, 7 Oct 2022 02:04:41 +0200 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com> --- content/doc/book/security/access-control/permissions.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/doc/book/security/access-control/permissions.adoc b/content/doc/book/security/access-control/permissions.adoc index 0b230869806d..54884b0ede14 100644 --- a/content/doc/book/security/access-control/permissions.adoc +++ b/content/doc/book/security/access-control/permissions.adoc @@ -106,7 +106,7 @@ An instance on which an untrusted user gained _Overall/Administer_ permission sh All secrets (credentials, etc.) stored on that instance should be rotated or revoked and all artifacts created from that point on should be verified. -=== Agent permissions +=== _Agent_ Permissions ==== Agent/Build @@ -134,7 +134,7 @@ This permission allows users to delete existing agents. This permission allows users to disconnect agents or mark agents as temporarily offline. -=== Job permissions +=== _Job_ Permissions ==== Job/Build From 8cc0b86ff895da1597554215df714d430ecf36f6 Mon Sep 17 00:00:00 2001 From: Zbynek Konecny Date: Wed, 19 Oct 2022 23:10:50 +0200 Subject: [PATCH 4/4] Permission page: review feedback --- .../security/access-control/permissions.adoc | 135 ++++++++---------- 1 file changed, 62 insertions(+), 73 deletions(-) diff --git a/content/doc/book/security/access-control/permissions.adoc b/content/doc/book/security/access-control/permissions.adoc index 54884b0ede14..5f6c674edd31 100644 --- a/content/doc/book/security/access-control/permissions.adoc +++ b/content/doc/book/security/access-control/permissions.adoc @@ -108,98 +108,115 @@ All secrets (credentials, etc.) stored on that instance should be rotated or rev === _Agent_ Permissions -==== Agent/Build - +Agent/Build:: This permission allows users to run jobs as them on agents. +In default setup where all builds run under SYSTEM user this permission is not relevant, +but if link:/doc/book/security/build-authorization/[build authorization] is active this permission defines which users may run jobs on agents. -==== Agent/Configure - +Agent/Configure:: This permission allows users to configure agents. +Users with this permission can make all jobs run on a computer where they have root access, +gaining access to all information used by the build (content of files, environment variables including credentials). -==== Agent/Connect - +Agent/Connect:: This permission allows users to connect agents or mark agents as online. ++ +This permission is implied by _Agent/Disconnect_. -This permission is implied by Agent/Disconnect. - -==== Agent/Create - -This permission allows users to create agents. - -==== Agent/Delete +Agent/Create:: +This permission allows users to create agents. Security implications are the same as for _Agent/Configure_. +Agent/Delete:: This permission allows users to delete existing agents. -==== Agent/Disconnect - +Agent/Disconnect:: This permission allows users to disconnect agents or mark agents as temporarily offline. === _Job_ Permissions -==== Job/Build +Though these permissions use the word "Job" in their name, +they refer to any items you can create using the _New Item_ menu option (freestyle jobs, folders, pipelines, ...) +Job/Build:: This permission grants the ability to start a new build. -==== Job/Cancel - +Job/Cancel:: This permission grants the ability to cancel a scheduled, or abort a running, build. -==== Job/Configure - +Job/Configure:: Change the configuration of a job. -==== Job/Create - +Job/Create:: Create a new job. -==== Job/Delete - +Job/Delete:: Delete a job. -==== Job/Discover - -This permission grants discover access to jobs. Lower than read permissions, it allows you to redirect anonymous users to the login page when they try to access a job url. +Job/Discover:: +This permission grants discover access to jobs. +Lower than read permissions, it allows you to redirect anonymous users to the login page when they try to access a job url. Without it they would get a 404 error and wouldn't be able to discover project names. ++ +This permission is only useful if anonymous users have _Overall/Read_ permission, but not _Job/Read_. +It is implied by _Job/Read_. -This permission is implied by Job/Read. - -==== Job/Move - +Job/Move:: Required to move a job from one folder (or Jenkins root) to another. -==== Job/Read - +Job/Read:: See a job. (You may deny this permission but allow Discover to force an anonymous user to log in to see the job.) -==== Job/Workspace - +Job/Workspace:: This permission grants the ability to retrieve the contents of a workspace Jenkins checked out for performing builds. If you don’t want a user to access files in the workspace (e.g. source code checked out from SCM or intermediate build results) through the workspace browser, you can revoke this permission. -=== Run permissions - -==== Run/Delete +=== _Run_ Permissions +Run/Delete:: This permission allows users to manually delete specific builds from the build history. -==== Run/Update - +Run/Update:: This permission allows users to update description and other properties of a build, for example to leave notes about the cause of a build failure. -=== View permissions +=== _View_ Permissions -==== View/Configure +View/Configure:: This permission allows users to change the configuration of views. -==== View/Create +View/Create:: This permission allows users to create new views. -==== View/Delete +View/Delete:: This permission allows users to delete existing views. -==== View/Read +View/Read:: This permission allows users to see views (implied by generic read access). +=== _Credentials_ Permissions + +Following permissions are only enabled if the plugin:credentials[Credentials Plugin] is installed + +Credentials/Create:: +The create permission is necessary to add credentials to a credentials provider. + +Credentials/Delete:: +The delete permission is necessary to remove credentials stored in a credentials provider. + +Credentials/ManageDomains:: +The manage domains permission is necessary to add/remove/configure the credential domains of a credentials provider (where the credentials provider supports multiple credential domains). + +Credentials/Update:: +The update permission is necessary to modify credentials in a credentials provider. + +Credentials/View:: +The view permission is necessary to view the credentials stored in a credentials provider. + +=== Pipeline-related Permissions + +Run/Replay:: +Ability to perform a new Pipeline build with an edited script. This permission is implied by Job/Configure. +This permission is enabled by plugin:workflow-cps[Pipeline: Groovy]. + == Optional Permissions These permissions are not enabled by default. @@ -234,34 +251,6 @@ Learn more in jep:223[]. NOTE: This permission was added in Jenkins 2.222. Some features, especially those provided by plugins, may not yet support this permission. -=== Credentials permissons - -Following permissions are only enabled if the plugin:credentials[Credentials Plugin] is installed - -==== Credentials/Create -The create permission is necessary to add credentials to a credentials provider. - -==== Credentials/Delete -The delete permission is necessary to remove credentials stored in a credentials provider. - -==== Credentials/ManageDomains -The manage domains permission is necessary to add/remove/configure the credential domains of a credentials provider (where the credentials provider supports multiple credential domains). - -==== Credentials/Update - -The update permission is necessary to modify credentials in a credentials provider. - -==== Credentials/View - -The view permission is necessary to view the credentials stored in a credentials provider. - -=== Pipleline-related permissions - -==== Run/Replay - -Ability to perform a new Pipeline build with an edited script. This permission is implied by Job/Configure. -This permission is enabled by plugin:workflow-cps[Pipeline: Groovy]. - == Obsolete Permissions The following three permissions are obsolete since Jenkins 2.222: