Draft for review: script security #4693
Conversation
probot-autolabeler
bot
added
the
documentation
StackScribe
changed the title
There was a problem hiding this comment.
A good start, thanks a lot for taking this on! ❤️
One thing to keep in mind with this chapter is that we have some advice for admins (basically all of the current content), and some other advice applies to script authors specifically.
It's kind of new to have user docs in the security chapter, unsure whether that's a separate page or should be combined here.
| 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] |
There was a problem hiding this comment.
I think we're fairly explicit in that Pipelines are not Groovy because of the missing support for some language features.
| * 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. |
There was a problem hiding this comment.
Almost never matters I think?
- https://plugins.jenkins.io/command-launcher/ uses
SystemCommandLanguage. - https://plugins.jenkins.io/email-ext/ uses
JellyLanguage
That seems to be it?
There was a problem hiding this comment.
Are you saying lines 52-54 should be deleted?
| 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 Pipelin) has unfettered access to Jenkins inernal objects. |
There was a problem hiding this comment.
Normal users cannot do it; only admins. So the real advice is probably to teach users to deal with the restrictions of the sandbox, preferring Jenkins's REST API over internal (Java) APIs; minimize whole-script approvals, and instead use https://plugins.jenkins.io/workflow-cps-global-lib/ that are versioned and tested.
There was a problem hiding this comment.
https://plugins.jenkins.io/workflow-cps-global-lib/ seems to be deprecated. Is there a new version?
| * 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] |
There was a problem hiding this comment.
Maybe it's better to structure this page more explicitly along the following lines to guide readers along a top-level view of the concepts involved?
- Scripting capabilities are very powerful, but are potentially dangerous if mishandled.
- The unrestricted Groovy-based Script Console is a powerful diagnostic tool and can only be used by admins. It has full access to all Jenkins internals and no restrictions.
- Many plugins offer scripting capabilities (this list) to users without Overall/Administer permission, and they integrate with Script Security plugin to do this more safely.
- Script Security plugin has a sandbox for Groovy scripts and Pipelines, and whole-script approval for all languages it supports.
- The sandbox allows regular users to implement scripts safely, restricting access to potentially unsafe code based on an allowlist (default + admin customizable, but that is very complicated)
- Whole-script approval lets users ask admins to approve entire scripts. This is generally discouraged.
There was a problem hiding this comment.
Thanks for this! As you may have guessed, I did not understand this well but this clarifies things a lot! I will rewrite.
There was a problem hiding this comment.
I would be inclined to leave the detailed technical documentation to the plugin, and limit discussion here to simple advice as @daniel-beck already began to suggest: leave the sandbox enabled; do not ever go to the script approval screen unless you absolutely know what you are doing (and if you are reading about this for the first time on jenkins.io, you do not know what you are doing); if you are very confident that you have discovered a new signature that is genuinely useful and harmless, file a PR to add it to the default whitelist and let a developer decide whether you are right or not (in the meantime step back and try to accomplish whatever you think you needed without in-process scripting).
| In most cases, you should use the | ||
| link:http://localhost:4242/doc/book/managing/script-approval/#approve-assuming-permissions-check[Approve assuming permissions check] option rather than the simple Approve option. |
There was a problem hiding this comment.
Just no.
| In most cases, you should use the | |
| link:http://localhost:4242/doc/book/managing/script-approval/#approve-assuming-permissions-check[Approve assuming permissions check] option rather than the simple Approve option. |
Anyway this (very dubious) feature applies to the sandbox, not whole-script approval, so it is not even in the right bullet point.
| * 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. |
There was a problem hiding this comment.
Just duplicates the first bullet point?
| * 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. |
Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com>
Co-authored-by: Jesse Glick <jglick@cloudbees.com>
Comment from dbeck and jglick Co-authored-by: Jesse Glick <jglick@cloudbees.com>
Co-authored-by: Jesse Glick <jglick@cloudbees.com>
Co-authored-by: Jesse Glick <jglick@cloudbees.com>
Co-authored-by: Jesse Glick <jglick@cloudbees.com>
Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com>
Co-authored-by: Jesse Glick <jglick@cloudbees.com>
Co-authored-by: Hervé Le Meur <91831478+lemeurherve@users.noreply.github.com>
Co-authored-by: Wadeck Follonier <Wadeck@users.noreply.github.com>
| @@ -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` | |||
|
|
|||
| @@ -186,6 +187,7 @@ Now execute the restored Jenkins instance: | |||
|
|
|||
| [source,bash] | |||
| ---- | |||
|
|
|||
| 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. |
There was a problem hiding this comment.
| 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. |
No this is not true at all and in fact that option should rarely if ever be used.
Anyway this option pertains to sandbox signatures, unrelated to whole-script approval which this bullet point is about.
| * 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. |
There was a problem hiding this comment.
This is just part of the first bullet point?
|
Question posed to gitter on 15 Feb 2022, should be answered somewhere in conjunction with this: hello i'm trying to figure out how the script approval thingy works, we've got a file which contains both approvedScriptHashes and approvedSignatures |
Like a
yes. If not, then it will just be run (no hash check). No admin should ever approve a script which delegates to some other unspecified script. That would be like signing a blank check and taping it to your front door. |
github-actions
bot
added
the
unresolved-merge-conflict
|
Please take a moment and address the merge conflicts of your pull request. Thanks! |
github-actions
bot
removed
the
unresolved-merge-conflict
|
Please take a moment and address the merge conflicts of your pull request. Thanks! |
github-actions
bot
added
the
unresolved-merge-conflict
github-actions
bot
removed
the
unresolved-merge-conflict
This is intended as a small document that just summarizes "best practices" about script security with links to other documents for details.
@daniel-beck @Wadeck @MarkEWaite This is my first stab at this. The odds of errors, omissions, or wrong style are pretty high so feel free to critique harshly.
Also, not sure how this happened but the system-administration/backing-up.adoc file has been included here. That was in #4668 which has been merged. I'll figure it out but, until I do, just ignore that part of this PR.