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.
-
Constructor Summary
Constructors Constructor Description GroovySandbox()
Creates a sandbox with default settings.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 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.static Object
run(groovy.lang.Script script, Whitelist whitelist)
Deprecated.static void
runInSandbox(Runnable r, Whitelist whitelist)
Deprecated.useenter()
static <V> V
runInSandbox(Callable<V> c, Whitelist whitelist)
Deprecated.useenter()
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.
-
-
-
Field Detail
-
LOGGER
public static final Logger LOGGER
-
-
Method Detail
-
withWhitelist
public GroovySandbox withWhitelist(@CheckForNull Whitelist whitelist)
Specify a whitelist. By defaultWhitelist.all()
is used.- Returns:
this
-
withApprovalContext
public GroovySandbox withApprovalContext(@CheckForNull ApprovalContext context)
Specify an approval context. By defaultApprovalContext.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; seecreateSecureCompilerConfiguration()
and similar methodsscriptText
- 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 thisCompilerConfiguration
, you also have to usecreateSecureClassLoader(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 bycreateSecureCompilerConfiguration()
.
-
createSecureClassLoader
@NonNull public static ClassLoader createSecureClassLoader(ClassLoader base)
Prepares a classloader for Groovy shell for sandboxing. SeecreateSecureCompilerConfiguration()
for the discussion.
-
runInSandbox
@Deprecated public static void runInSandbox(@NonNull Runnable r, @NonNull Whitelist whitelist) throws RejectedAccessException
Deprecated.useenter()
Runs a block in the sandbox. You must have usedcreateSecureCompilerConfiguration()
to prepare the Groovy shell. Userun(groovy.lang.Script, org.jenkinsci.plugins.scriptsecurity.sandbox.Whitelist)
instead whenever possible.- Parameters:
r
- a block of code during whose execution all calls are interceptedwhitelist
- the whitelist to use, such asWhitelist.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.useenter()
Runs a function in the sandbox. You must have usedcreateSecureCompilerConfiguration()
to prepare the Groovy shell. Userun(groovy.lang.Script, org.jenkinsci.plugins.scriptsecurity.sandbox.Whitelist)
instead whenever possible.- Parameters:
c
- a block of code during whose execution all calls are interceptedwhitelist
- the whitelist to use, such asWhitelist.all()
- Returns:
- the return value of the block
- Throws:
RejectedAccessException
- in case an attempted call was not whitelistedException
- 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.- Throws:
RejectedAccessException
-
run
@Deprecated public static Object run(@NonNull groovy.lang.GroovyShell shell, @NonNull String script, @NonNull Whitelist whitelist) throws RejectedAccessException
Deprecated.Runs a script in the sandbox. You must have usedcreateSecureCompilerConfiguration()
to prepare the Groovy shell.- Parameters:
shell
- a shell ready forGroovyShell.parse(String)
script
- a scriptwhitelist
- the whitelist to use, such asWhitelist.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 checkclassLoader
- TheGroovyClassLoader
to use during compilation.- Returns:
- The
FormValidation
for the compilation check.
-
-