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 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 string
      javax.script.Bindings createBindings()
      Create new bindings used to replace the state of the current script engine
      void 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 context
      java.lang.Object eval​(java.lang.String js, javax.script.ScriptContext scriptContext, javax.script.Bindings bindings)
      Evaluates the JavaScript string for a given script context
      java.lang.Object eval​(javax.script.CompiledScript compiledScript)
      Run a pre-compiled JavaScript
      java.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 an Invocable 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 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:
        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 set
        javax.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 evaluated
        bindings - the Bindings to use for evaluation
        Throws:
        ScriptCPUAbuseException - when execution time exceeded (when greater than 0 is set
        javax.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 evaluated
        scriptContext - the ScriptContext exposing sets of attributes in different scopes.
        Throws:
        ScriptCPUAbuseException - when execution time exceeded (when greater than 0 is set
        javax.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 evaluated
        bindings - the Bindings to use for evaluation
        scriptContext - the ScriptContext exposing sets of attributes in different scopes.
        Throws:
        ScriptCPUAbuseException - when execution time exceeded (when greater than 0 is set
        javax.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 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

        javax.script.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

        javax.script.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

        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,
                      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