Draft for review: script security

content/doc/book/security/_chapter.yml

@@ -18,3 +18,4 @@ sections:
 
 # Further references
 - services
+- scripting

content/doc/book/security/scripted.adoc

@@ -0,0 +1,70 @@
+---
+title: Security for Scripts
+layout: section
+---
+ifdef::backend-html5[]
+:toc:
+ifdef::env-github[:imagesdir: ../resources]
+ifndef::env-github[:imagesdir: ../../resources]
+:hide-uri-scheme:
+endif::[]
+
+Apache Groovy scripts can be executed on the Jenkins controller and agents through various mechanisms including:
+
+* link:/doc/book/managing/script-console/[Script Console]
+* link:https://plugins.jenkins.io/groovy/[Groovy plugin] 
+when using the "Execute system Groovy script" step
+* link:https://plugins.jenkins.io/email-ext/[Extended Email plugin]
+* link:https://plugins.jenkins.io/groovy/[Job DSL plugin]
+* link:https://www.jenkins.io/doc/book/pipeline/[Pipelines]
+
+Scripts are powerful and useful tools but they must be managed carefully
+to ensure that they are not used to compromise your installation:
+
+* Limit the people to whom the *Overall/Administer* permission is granted.
+This allows people to use the
+link:/doc/book/managing/script-console/[Script Console].
+This authorization allows one to type in and execute an Apache Groovy script
+in a largely unrestricted environment
+so it should only be available to highly trusted, sophisticated users.
+
+
+Two facilities are provided that allow users with lesser permissions
+(such as *Job/Configure* or *Job/Build*) to run scripts that may be associated with plugins or their applications:
+
+* Jenkins maintains a list of "approved" scripts that cannot do any damage.
+If a user attempts to run a script that is not approved,
+the script is blocked until an administrator reviews the script and approves it
+using the _Manage Jenkins » In-process Script Approval_ screen.
+See the link:/doc/book/managing/script-approval/[In-process Script Approval] documentation for more information.
+In most cases, you should use the
+link:/doc/book/managing/script-approval/#approve-assuming-permissions-check[Approve assuming permissions check] option rather than the simple Approve option.
+
+* Groovy scripts can be run in the
+link:/doc/book/managing/script-approval/#groovy-sandbox[Groovy Sandbox] without approval.
+Each method call, object construction, and field access is checked against a list of allowed operations.
+If the script attempts to call any operations that are not allowed,
+it is killed and the unallowed operation is added to an approval queue.
+An administrator can approve that operation and then the script can be rerun.
+
+* Scripts written in languages other than Groovy can be run by an administrator
+or must be approved by an administrator;
+the sandbox is only for Groovy scripts.
+
+* Users can disable the Groovy sandbox.
+The entire script must be approved by the administrator unless it is in the list of administrator-managed list of approved scripts.
+``
+`
+
+////
+This is an alternative to the preceding bullet item.
+I am guessing that the documenttion reflects the current reality.
+
+* You should never disable the sandbox. If you disable the sandbox, a Scripted Pipeline (or a `script` step in a Declarative Pipeline) has unfettered access to Jenkins internal objects.
+For a light-hearted explanation about how dangerous this can be, see
+link:https://brokenco.de/2017/08/03/donut-disable-groovy-sandbox.html[Do not disable Groovy Sandbox].
+////
+
+See link:https://plugins.jenkins.io/script-security/[Script Security plugin]
+for more information.
+

content/doc/book/system-administration/backing-up.adoc

@@ -64,6 +64,7 @@ Use link:https://man7.org/linux/man-pages/man8/cron.8.html[cron]
 to schedule when the backup script runs.
 
 The shell script should create a directory such as `/mnt/backup`
+
 to which the backup will be written;
 be sure that you have write permissions to that directory.
 Consider creating `/mnt/backup` as a separate filesystem with its own mount point.
@@ -186,6 +187,7 @@ Now execute the restored Jenkins instance:
 
 [source,bash]
 ----
+
 java -jar jenkins.war ---httpPort=9999
 ----