Interface NashornSandbox
- All Known Implementing Classes:
NashornSandboxImpl
Created on 2015-08-06
- Version:
- $Id$
-
Method Summary
Modifier and TypeMethodDescriptionvoid
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.Compile the JavaScript stringCreate new bindings used to replace the state of the current script enginevoid
Remove a class from the list of allowed classes.void
Remove all classes from the list of allowed classes.Evaluates the JavaScript string.Evaluates the JavaScript string.eval
(String js, ScriptContext scriptContext) Evaluates the JavaScript string for a given script contexteval
(String js, ScriptContext scriptContext, Bindings bindings) Evaluates the JavaScript string for a given script contexteval
(CompiledScript compiledScript) Run a pre-compiled JavaScripteval
(CompiledScript compiledScript, Bindings bindings) eval
(CompiledScript compiledScript, ScriptContext scriptContext) eval
(CompiledScript compiledScript, ScriptContext scriptContext, Bindings bindings) Obtains the value of the specified JavaScript variable.Gets the current executor service.Returns anInvocable
instance, so that method invocations are also sandboxed.void
Will add a global variable available to all scripts executed with this sandbox.boolean
Check if a class is in the list of allowed classes.void
setExecutor
(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
Sets the writer, when want to have output from writer function called in JS script
-
Method Details
-
allow
Add a new class to the list of allowed classes. -
disallow
Remove a class from the list of allowed classes. -
isAllowed
Check if a class is in the list of allowed classes. -
disallowAllClasses
void disallowAllClasses()Remove all classes from the list of allowed classes. -
inject
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:
-
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:
-
setWriter
Sets the writer, when want to have output from writer function called in JS script- Parameters:
writer
- the writer, eg.StringWriter
-
setExecutor
Specifies the executor service which is used to run scripts when a CPU time limit is specified.- Parameters:
executor
- the executor service- See Also:
-
getExecutor
ExecutorService getExecutor()Gets the current executor service.- Returns:
- current executor service
-
eval
Evaluates the JavaScript string.- Parameters:
js
- the JavaScript script to be evaluated- Throws:
ScriptCPUAbuseException
- when execution time exceeded (when greater than 0 is setScriptException
- when script syntax error occurs- See Also:
-
eval
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 setScriptException
- when script syntax error occurs- See Also:
-
eval
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 setScriptException
- when script syntax error occurs- See Also:
-
eval
Object eval(String js, ScriptContext scriptContext, Bindings bindings) throws ScriptCPUAbuseException, 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.bindings
- the Bindings to use for evaluation- Throws:
ScriptCPUAbuseException
- when execution time exceeded (when greater than 0 is setScriptException
- when script syntax error occurs- See Also:
-
get
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
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
Invocable getSandboxedInvocable()Returns anInvocable
instance, so that method invocations are also sandboxed.- Returns:
-
setScriptCache
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
Compile the JavaScript string- Parameters:
js
- the JavaScript script to be compiled- Returns:
- a CompiledScript object
- Throws:
ScriptException
-
eval
Run a pre-compiled JavaScript -
eval
Object eval(CompiledScript compiledScript, Bindings bindings) throws ScriptCPUAbuseException, ScriptException -
eval
Object eval(CompiledScript compiledScript, ScriptContext scriptContext) throws ScriptCPUAbuseException, ScriptException -
eval
Object eval(CompiledScript compiledScript, ScriptContext scriptContext, Bindings bindings) throws ScriptCPUAbuseException, ScriptException
-