Package org.jenkinsci.plugins.scriptsecurity.sandbox.groovy

Class GroovySandbox

java.lang.Object

org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.GroovySandbox

public final class GroovySandbox
extends Object

Allows Groovy scripts (including Groovy Templates) to be run inside a sandbox.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	GroovySandbox.Scope	Handle for exiting the dynamic scope of the Groovy sandbox.

Field Summary

Fields

Modifier and Type	Field	Description
static Logger	LOGGER

Constructor Summary

Constructors

Constructor	Description
GroovySandbox()	Creates a sandbox with default settings.

Method Summary

Modifier and Type	Method	Description
static FormValidation	checkScriptForCompilationErrors(String script, groovy.lang.GroovyClassLoader classLoader)	Checks a script for compilation errors in a sandboxed environment, without going all the way to actual class creation or initialization.
static org.codehaus.groovy.control.CompilerConfiguration	createBaseCompilerConfiguration()	Prepares a compiler configuration that rejects certain AST transformations.
static ClassLoader	createSecureClassLoader(ClassLoader base)	Prepares a classloader for Groovy shell for sandboxing.
static org.codehaus.groovy.control.CompilerConfiguration	createSecureCompilerConfiguration()	Prepares a compiler configuration the sandbox.
GroovySandbox.Scope	enter()	Starts a dynamic scope within which calls will be sandboxed.
static Object	run(groovy.lang.GroovyShell shell, String script, Whitelist whitelist)	Deprecated. use runScript(groovy.lang.GroovyShell, java.lang.String)
static Object	run(groovy.lang.Script script, Whitelist whitelist)	Deprecated. insecure; use run(GroovyShell, String, Whitelist) or runScript(groovy.lang.GroovyShell, java.lang.String)
static void	runInSandbox(Runnable r, Whitelist whitelist)	Deprecated. use enter()
static <V> V	runInSandbox(Callable<V> c, Whitelist whitelist)	Deprecated. use enter()
Object	runScript(groovy.lang.GroovyShell shell, String scriptText)	Compiles and runs a script within the sandbox.
GroovySandbox	withApprovalContext(ApprovalContext context)	Specify an approval context.
GroovySandbox	withTaskListener(TaskListener listener)	Specify a place to print messages.
GroovySandbox	withWhitelist(Whitelist whitelist)	Specify a whitelist.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOGGER

public static final Logger LOGGER

Constructor Detail

GroovySandbox

public GroovySandbox()

Creates a sandbox with default settings.

Method Detail

withWhitelist

public GroovySandbox withWhitelist(@CheckForNull
                                   Whitelist whitelist)

Specify a whitelist. By default Whitelist.all() is used.

Returns:

this

withApprovalContext

public GroovySandbox withApprovalContext(@CheckForNull
                                         ApprovalContext context)

Specify an approval context. By default ApprovalContext.create() is used.

Returns:

this

withTaskListener

public GroovySandbox withTaskListener(@CheckForNull
                                      TaskListener listener)

Specify a place to print messages. By default nothing is printed.

Returns:

this

enter

public GroovySandbox.Scope enter()

Starts a dynamic scope within which calls will be sandboxed.

Returns:

a scope object, useful for putting this into a try-with-resources block

runScript

public Object runScript(@NonNull
                        groovy.lang.GroovyShell shell,
                        @NonNull
                        String scriptText)

Compiles and runs a script within the sandbox.

Parameters:

shell - the shell to be used; see createSecureCompilerConfiguration() and similar methods

scriptText - the script to run

Returns:

the return value of the script

createSecureCompilerConfiguration

@NonNull
public static org.codehaus.groovy.control.CompilerConfiguration createSecureCompilerConfiguration()

Prepares a compiler configuration the sandbox.

CAUTION: When creating GroovyShell with this CompilerConfiguration, you also have to use createSecureClassLoader(ClassLoader) to wrap a classloader of your choice into sandbox-aware one.

Otherwise the classloader that you provide to GroovyShell might have its own copy of groovy-sandbox, which lets the code escape the sandbox.

Returns:

a compiler configuration set up to use the sandbox

createBaseCompilerConfiguration

@NonNull
public static org.codehaus.groovy.control.CompilerConfiguration createBaseCompilerConfiguration()

Prepares a compiler configuration that rejects certain AST transformations. Used by createSecureCompilerConfiguration().

createSecureClassLoader

@NonNull
public static ClassLoader createSecureClassLoader(ClassLoader base)

Prepares a classloader for Groovy shell for sandboxing. See createSecureCompilerConfiguration() for the discussion.

runInSandbox

@Deprecated
public static void runInSandbox(@NonNull
                                Runnable r,
                                @NonNull
                                Whitelist whitelist)
                         throws RejectedAccessException

Deprecated.

use enter()

Runs a block in the sandbox. You must have used createSecureCompilerConfiguration() to prepare the Groovy shell. Use run(groovy.lang.Script, org.jenkinsci.plugins.scriptsecurity.sandbox.Whitelist) instead whenever possible.

Parameters:

r - a block of code during whose execution all calls are intercepted

whitelist - the whitelist to use, such as Whitelist.all()

Throws:

RejectedAccessException - in case an attempted call was not whitelisted

runInSandbox

@Deprecated
public static <V> V runInSandbox(@NonNull
                                 Callable<V> c,
                                 @NonNull
                                 Whitelist whitelist)
                          throws Exception

Deprecated.

use enter()

Runs a function in the sandbox. You must have used createSecureCompilerConfiguration() to prepare the Groovy shell. Use run(groovy.lang.Script, org.jenkinsci.plugins.scriptsecurity.sandbox.Whitelist) instead whenever possible.

Parameters:

c - a block of code during whose execution all calls are intercepted

whitelist - the whitelist to use, such as Whitelist.all()

Returns:

the return value of the block

Throws:

RejectedAccessException - in case an attempted call was not whitelisted

Exception - in case the block threw some other exception

run

@Deprecated
public static Object run(@NonNull
                         groovy.lang.Script script,
                         @NonNull
                         Whitelist whitelist)
                  throws RejectedAccessException

Deprecated.

insecure; use run(GroovyShell, String, Whitelist) or runScript(groovy.lang.GroovyShell, java.lang.String)

Throws:

RejectedAccessException

run

@Deprecated
public static Object run(@NonNull
                         groovy.lang.GroovyShell shell,
                         @NonNull
                         String script,
                         @NonNull
                         Whitelist whitelist)
                  throws RejectedAccessException

Deprecated.

use runScript(groovy.lang.GroovyShell, java.lang.String)

Runs a script in the sandbox. You must have used createSecureCompilerConfiguration() to prepare the Groovy shell.

Parameters:

shell - a shell ready for GroovyShell.parse(String)

script - a script

whitelist - the whitelist to use, such as Whitelist.all()

Returns:

the value produced by the script, if any

Throws:

RejectedAccessException - in case an attempted call was not whitelisted

checkScriptForCompilationErrors

@NonNull
public static FormValidation checkScriptForCompilationErrors(String script,
                                                             groovy.lang.GroovyClassLoader classLoader)

Checks a script for compilation errors in a sandboxed environment, without going all the way to actual class creation or initialization.

Parameters:

script - The script to check

classLoader - The GroovyClassLoader to use during compilation.

Returns:

The FormValidation for the compilation check.