Package delight.nashornsandbox

Interface NashornSandbox

All Known Implementing Classes:
NashornSandboxImpl
public interface NashornSandbox
The Nashorn sandbox interface.

Created on 2015-08-06

Version:
$Id$

  • Method Details

    • allow

      void allow(Class<?> clazz)
      Add a new class to the list of allowed classes.

    • disallow

      void disallow(Class<?> clazz)
      Remove a class from the list of allowed classes.

    • isAllowed

      boolean isAllowed(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(String variableName, Object object)
      Will add a global variable available to all scripts executed with this sandbox.
      Parameters:
      variableName - the name of the variable
      object - the value, can be null

    • 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:
      • ThreadMXBean.getThreadAllocatedBytes(long)

    • setWriter

      void setWriter(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(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:

    • getExecutor

      ExecutorService getExecutor()
      Gets the current executor service.
      Returns:
      current executor service

    • eval

      Object eval(String js) throws ScriptCPUAbuseException, ScriptException
      Evaluates the JavaScript string.
      Parameters:
      js - the JavaScript script to be evaluated
      Throws:
      ScriptCPUAbuseException - when execution time exceeded (when greater than 0 is set
      ScriptException - when script syntax error occurs
      See Also:

    • eval

      Object eval(String js, Bindings bindings) throws ScriptCPUAbuseException, ScriptException
      Evaluates the JavaScript string.
      Parameters:
      js - the JavaScript script to be evaluated
      bindings - the Bindings to use for evaluation
      Throws:
      ScriptCPUAbuseException - when execution time exceeded (when greater than 0 is set
      ScriptException - when script syntax error occurs
      See Also:

    • eval

      Object eval(String js, ScriptContext scriptContext) throws ScriptCPUAbuseException, ScriptException
      Evaluates the JavaScript string for a given script context
      Parameters:
      js - the JavaScript script to be evaluated
      scriptContext - the ScriptContext exposing sets of attributes in different scopes.
      Throws:
      ScriptCPUAbuseException - when execution time exceeded (when greater than 0 is set
      ScriptException - 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 evaluated
      scriptContext - 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 set
      ScriptException - when script syntax error occurs
      See Also:

    • get

      Object get(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 use Thread.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 engine

      This can be typically used to override ECMAScript "global" properties

      Returns:

    • getSandboxedInvocable

      Invocable getSandboxedInvocable()
      Returns an Invocable 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 of eval(String) and its overloads.
      Parameters:
      cache - the new cache to use

    • compile

      CompiledScript compile(String js) throws ScriptException
      Compile the JavaScript string
      Parameters:
      js - the JavaScript script to be compiled
      Returns:
      a CompiledScript object
      Throws:
      ScriptException

    • eval

      Object eval(CompiledScript compiledScript) throws ScriptCPUAbuseException, ScriptException
      Run a pre-compiled JavaScript
      Throws:
      ScriptCPUAbuseException
      ScriptException

    • eval

      Object eval(CompiledScript compiledScript, Bindings bindings) throws ScriptCPUAbuseException, ScriptException
      Throws:
      ScriptCPUAbuseException
      ScriptException

    • eval

      Object eval(CompiledScript compiledScript, ScriptContext scriptContext) throws ScriptCPUAbuseException, ScriptException
      Throws:
      ScriptCPUAbuseException
      ScriptException

    • eval

      Object eval(CompiledScript compiledScript, ScriptContext scriptContext, Bindings bindings) throws ScriptCPUAbuseException, ScriptException
      Throws:
      ScriptCPUAbuseException
      ScriptException