Interface NashornSandbox
-
- All Known Implementing Classes:
NashornSandboxImpl
public interface NashornSandbox
The Nashorn sandbox interface.Created on 2015-08-06
- Version:
- $Id$
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
allow(java.lang.Class<?> clazz)
Add a new class to the list of allowed classes.void
allowExitFunctions(boolean v)
Allow Nashorn quit and exit functions.void
allowGlobalsObjects(boolean v)
Allow Nashorn globals object $ARG, $ENV, $EXEC, $OPTIONS, $OUT, $ERR and $EXIT.void
allowLoadFunctions(boolean v)
Allow Nashorn load and loadWithNewGlobal functions.void
allowNoBraces(boolean v)
Force, to check if all blocks are enclosed with curly braces "{}".void
allowPrintFunctions(boolean v)
Allow Nashorn print and echo functions.void
allowReadFunctions(boolean v)
Allow Nashorn readLine and readFully functions.javax.script.CompiledScript
compile(java.lang.String js)
Compile the JavaScript stringjavax.script.Bindings
createBindings()
Create new bindings used to replace the state of the current script enginevoid
disallow(java.lang.Class<?> clazz)
Remove a class from the list of allowed classes.void
disallowAllClasses()
Remove all classes from the list of allowed classes.java.lang.Object
eval(java.lang.String js)
Evaluates the JavaScript string.java.lang.Object
eval(java.lang.String js, javax.script.Bindings bindings)
Evaluates the JavaScript string.java.lang.Object
eval(java.lang.String js, javax.script.ScriptContext scriptContext)
Evaluates the JavaScript string for a given script contextjava.lang.Object
eval(java.lang.String js, javax.script.ScriptContext scriptContext, javax.script.Bindings bindings)
Evaluates the JavaScript string for a given script contextjava.lang.Object
eval(javax.script.CompiledScript compiledScript)
Run a pre-compiled JavaScriptjava.lang.Object
eval(javax.script.CompiledScript compiledScript, javax.script.Bindings bindings)
java.lang.Object
eval(javax.script.CompiledScript compiledScript, javax.script.ScriptContext scriptContext)
java.lang.Object
eval(javax.script.CompiledScript compiledScript, javax.script.ScriptContext scriptContext, javax.script.Bindings bindings)
java.lang.Object
get(java.lang.String variableName)
Obtains the value of the specified JavaScript variable.java.util.concurrent.ExecutorService
getExecutor()
Gets the current executor service.javax.script.Invocable
getSandboxedInvocable()
Returns anInvocable
instance, so that method invocations are also sandboxed.void
inject(java.lang.String variableName, java.lang.Object object)
Will add a global variable available to all scripts executed with this sandbox.boolean
isAllowed(java.lang.Class<?> clazz)
Check if a class is in the list of allowed classes.void
setExecutor(java.util.concurrent.ExecutorService executor)
Specifies the executor service which is used to run scripts when a CPU time limit is specified.void
setMaxCPUTime(long limit)
Sets the maximum CPU time in milliseconds allowed for script execution.void
setMaxMemory(long limit)
Sets the maximum memory in Bytes which JS executor thread can allocate.void
setMaxPreparedStatements(int max)
The size of prepared statements LRU cache.void
setScriptCache(SecuredJsCache cache)
Overwrites the cache for pre-processed javascript.void
setWriter(java.io.Writer writer)
Sets the writer, when want to have output from writer function called in JS script
-
-
-
Method Detail
-
allow
void allow(java.lang.Class<?> clazz)
Add a new class to the list of allowed classes.
-
disallow
void disallow(java.lang.Class<?> clazz)
Remove a class from the list of allowed classes.
-
isAllowed
boolean isAllowed(java.lang.Class<?> clazz)
Check if a class is in the list of allowed classes.
-
disallowAllClasses
void disallowAllClasses()
Remove all classes from the list of allowed classes.
-
inject
void inject(java.lang.String variableName, java.lang.Object object)
Will add a global variable available to all scripts executed with this sandbox.- Parameters:
variableName
- the name of the variableobject
- the value, can benull
-
setMaxCPUTime
void setMaxCPUTime(long limit)
Sets the maximum CPU time in milliseconds allowed for script execution.Note,
ExecutorService
should be also set when time is set greater than 0.- Parameters:
limit
- time limit in milliseconds- See Also:
setExecutor(ExecutorService)
-
setMaxMemory
void setMaxMemory(long limit)
Sets the maximum memory in Bytes which JS executor thread can allocate.
Note, thread memory usage is only approximation.
Note,
ExecutorService
should be also set when memory limit is set greater than 0. Nashorn takes some memory at start, be generous and give at least 1MB. If bindings are used, Nashorn allocates additional memory for the bindings which might be a multiple of the memory theoretically required by the data types used. For details, see issue 86.Current implementation of this limit works only on Sun/Oracle JVM.
- Parameters:
limit
- limit in bytes- See Also:
ThreadMXBean.getThreadAllocatedBytes(long)
-
setWriter
void setWriter(java.io.Writer writer)
Sets the writer, when want to have output from writer function called in JS script- Parameters:
writer
- the writer, eg.StringWriter
-
setExecutor
void setExecutor(java.util.concurrent.ExecutorService executor)
Specifies the executor service which is used to run scripts when a CPU time limit is specified.- Parameters:
executor
- the executor service- See Also:
setMaxCPUTime(long)
-
getExecutor
java.util.concurrent.ExecutorService getExecutor()
Gets the current executor service.- Returns:
- current executor service
-
eval
java.lang.Object eval(java.lang.String js) throws ScriptCPUAbuseException, javax.script.ScriptException
Evaluates the JavaScript string.- Parameters:
js
- the JavaScript script to be evaluated- Throws:
ScriptCPUAbuseException
- when execution time exceeded (when greater than 0 is setjavax.script.ScriptException
- when script syntax error occurs- See Also:
setMaxCPUTime(long)
-
eval
java.lang.Object eval(java.lang.String js, javax.script.Bindings bindings) throws ScriptCPUAbuseException, javax.script.ScriptException
Evaluates the JavaScript string.- Parameters:
js
- the JavaScript script to be evaluatedbindings
- the Bindings to use for evaluation- Throws:
ScriptCPUAbuseException
- when execution time exceeded (when greater than 0 is setjavax.script.ScriptException
- when script syntax error occurs- See Also:
setMaxCPUTime(long)
-
eval
java.lang.Object eval(java.lang.String js, javax.script.ScriptContext scriptContext) throws ScriptCPUAbuseException, javax.script.ScriptException
Evaluates the JavaScript string for a given script context- Parameters:
js
- the JavaScript script to be evaluatedscriptContext
- the ScriptContext exposing sets of attributes in different scopes.- Throws:
ScriptCPUAbuseException
- when execution time exceeded (when greater than 0 is setjavax.script.ScriptException
- when script syntax error occurs- See Also:
setMaxCPUTime(long)
-
eval
java.lang.Object eval(java.lang.String js, javax.script.ScriptContext scriptContext, javax.script.Bindings bindings) throws ScriptCPUAbuseException, javax.script.ScriptException
Evaluates the JavaScript string for a given script context- Parameters:
js
- the JavaScript script to be evaluatedbindings
- the Bindings to use for evaluationscriptContext
- the ScriptContext exposing sets of attributes in different scopes.- Throws:
ScriptCPUAbuseException
- when execution time exceeded (when greater than 0 is setjavax.script.ScriptException
- when script syntax error occurs- See Also:
setMaxCPUTime(long)
-
get
java.lang.Object get(java.lang.String variableName)
Obtains the value of the specified JavaScript variable.
-
allowPrintFunctions
void allowPrintFunctions(boolean v)
Allow Nashorn print and echo functions.Only before first
eval(String)
call cause effect.
-
allowReadFunctions
void allowReadFunctions(boolean v)
Allow Nashorn readLine and readFully functions.Only before first
eval(String)
call cause effect.
-
allowLoadFunctions
void allowLoadFunctions(boolean v)
Allow Nashorn load and loadWithNewGlobal functions.Only before first
eval(String)
call cause effect.
-
allowExitFunctions
void allowExitFunctions(boolean v)
Allow Nashorn quit and exit functions.Only before first
eval(String)
call cause effect.
-
allowGlobalsObjects
void allowGlobalsObjects(boolean v)
Allow Nashorn globals object $ARG, $ENV, $EXEC, $OPTIONS, $OUT, $ERR and $EXIT.Only before first
eval(String)
call cause effect.
-
allowNoBraces
void allowNoBraces(boolean v)
Force, to check if all blocks are enclosed with curly braces "{}".Warning This option is useful to identify potential abuse but is also prone to identify false positives. Please use with caution. Alternatively you can use
setMaxCPUTime
to prevent abusive script execution.Explanation: all loops (for, do-while, while, and if-else, and functions should use braces, because poison_pill() function will be inserted after each open brace "{", to ensure interruption checking. Otherwise simple code like:
while(true) while(true) { // do nothing }
or even:while(true)
cause unbreakable loop, which force this sandbox to useThread.stop()
which make JVM unstable.Properly written code (even in bad intention) like:
while(true) { while(true) { // do nothing }}
will be changed into:while(true) {poison_pill(); while(true) {poison_pill(); // do nothing } }
which finish nicely when interrupted.For legacy code, this check can be turned off, but with no guarantee, the JS thread will gracefully finish when interrupted.
- Parameters:
v
-true
when sandbox should check if all required braces are placed into JS code,false
when no check should be performed
-
setMaxPreparedStatements
void setMaxPreparedStatements(int max)
The size of prepared statements LRU cache. Default 0 (disabled).Each statements when
setMaxCPUTime(long)
is set is prepared to quit itself when time exceeded. To execute only once this procedure per statement set this value.When
setMaxCPUTime(long)
is set 0, this value is ignored.- Parameters:
max
- the maximum number of statements in the LRU cache
-
createBindings
javax.script.Bindings createBindings()
Create new bindings used to replace the state of the current script engineThis can be typically used to override ECMAScript "global" properties
- Returns:
-
getSandboxedInvocable
javax.script.Invocable getSandboxedInvocable()
Returns anInvocable
instance, so that method invocations are also sandboxed.- Returns:
-
setScriptCache
void setScriptCache(SecuredJsCache cache)
Overwrites the cache for pre-processed javascript. Must be called before the first invocation ofeval(String)
and its overloads.- Parameters:
cache
- the new cache to use
-
compile
javax.script.CompiledScript compile(java.lang.String js) throws javax.script.ScriptException
Compile the JavaScript string- Parameters:
js
- the JavaScript script to be compiled- Returns:
- a CompiledScript object
- Throws:
javax.script.ScriptException
-
eval
java.lang.Object eval(javax.script.CompiledScript compiledScript) throws ScriptCPUAbuseException, javax.script.ScriptException
Run a pre-compiled JavaScript- Throws:
ScriptCPUAbuseException
javax.script.ScriptException
-
eval
java.lang.Object eval(javax.script.CompiledScript compiledScript, javax.script.Bindings bindings) throws ScriptCPUAbuseException, javax.script.ScriptException
- Throws:
ScriptCPUAbuseException
javax.script.ScriptException
-
eval
java.lang.Object eval(javax.script.CompiledScript compiledScript, javax.script.ScriptContext scriptContext) throws ScriptCPUAbuseException, javax.script.ScriptException
- Throws:
ScriptCPUAbuseException
javax.script.ScriptException
-
eval
java.lang.Object eval(javax.script.CompiledScript compiledScript, javax.script.ScriptContext scriptContext, javax.script.Bindings bindings) throws ScriptCPUAbuseException, javax.script.ScriptException
- Throws:
ScriptCPUAbuseException
javax.script.ScriptException
-
-