Draft for review: script security

[StackScribe]

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.

[daniel-beck]

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.

[daniel-beck]

I think we're fairly explicit in that Pipelines are not Groovy because of the missing support for some language features.

[daniel-beck]

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?

[jglick]

Yup, very uncommon.

[StackScribe]

Are you saying lines 52-54 should be deleted?

[daniel-beck]

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.

[StackScribe]

https://plugins.jenkins.io/workflow-cps-global-lib/ seems to be deprecated. Is there a new version?

[MarkEWaite]

https://plugins.jenkins.io/pipeline-groovy-lib/ is the replacement

[daniel-beck]

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?

1. Scripting capabilities are very powerful, but are potentially dangerous if mishandled.
2. 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.
3. 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.
4. Script Security plugin has a sandbox for Groovy scripts and Pipelines, and whole-script approval for all languages it supports.
5. 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)
6. Whole-script approval lets users ask admins to approve entire scripts. This is generally discouraged.

[StackScribe]

Thanks for this! As you may have guessed, I did not understand this well but this clarifies things a lot! I will rewrite.

[jglick]

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).

[jglick]

Just no.

Suggested change

	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.

[jglick]

Yup, very uncommon.

[jglick]

Just duplicates the first bullet point?

Suggested change

	* 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.

[jglick]

?

[jglick]

?

[jglick]

Suggested change

	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.

[jglick]

This is just part of the first bullet point?

[StackScribe]

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
approvedScriptHashes I assume are whole .groovy scripts (well, looking at the code it's a bit more complicated than that, there's "language:" prepended to it before hashing)
approvedSignatures looks like methods which are explicitely allowed
question is, if Jenkins calls an "unknown" .groovy script from a pipeline and its hash is not in approvedScriptHashes, will it run line by line as long as all methods are explicitly allowed?

[jglick]

if Jenkins calls an "unknown" .groovy script from a pipeline

Like a load step? From a sandboxed pipeline? If so then

will it run line by line as long as all methods are explicitly allowed?

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.