Nashorn Sandbox

A sandbox for executing JavaScript in Java apps using the Nashorn engine.

Also see Graal JS Sandbox and Rhino Sandbox.

Part of the Java Delight Suite.

Note: Use version 0.3.x if you are using a Java version older than Java 20.

Usage

The sandbox by default blocks access to all Java classes.

Classes, which should be used in JavaScript, must be explicitly allowed.

NashornSandbox sandbox = NashornSandboxes.create();
     
sandbox.allow(File.class);
     
sandbox.eval("var File = Java.type('java.io.File'); File;")

Or you can inject your Java object as a JS global variable

NashornSandbox sandbox = NashornSandboxes.create();

sandbox.inject("fromJava", new Object());

sandbox.eval("fromJava.getClass();");

The sandbox also allows limiting the CPU time and memory usage of scripts. This allows terminating scripts which contain infinite loops and other problematic code.

NashornSandbox sandbox = NashornSandboxes.create();
     
sandbox.setMaxCPUTime(100);
sandbox.setMaxMemory(50*1024);
sandbox.setMaxPreparedStatements(30); // because preparing scripts for execution is expensive
sandbox.setExecutor(Executors.newSingleThreadExecutor());
     
sandbox.eval("var o={}, i=0; while (true) {o[i++]='abc';};");

This code will raise a ScriptCPUAbuseException.

The sandbox beautifies the JavaScript code for this and injects additional statements into the submitted code. It is thus possible that the original line numbers from the submitted JS code are not preserved. To debug the code, which is generated by the sandbox, activate its debug mode as follows using a log4j.properties file (see log4j.properties):

log4j.logger.delight.nashornsandbox.NashornSandbox=DEBUG

This will output the generated JS on the console as follows:

--- Running JS ---
var \__it = Java.type('delight.nashornsandbox.internal.InterruptTest');var \__if=function(){\__it.test();};
while(true) {__if();
  i = i+1;
}
--- JS END ---

The sandbox also allows precompiling frequently used scripts. Using a precompiled script can substantially increase execution times.

NashornSandbox sandbox = NashornSandboxes.create();
CompiledScript script = sandbox.compile("1 + 1");
int result1 = (int) sandbox.eval(script);
int result2 = (int) sandbox.eval(script);

Maven

Just add the following dependency to your projects.

<dependency>
    <groupId>org.javadelight</groupId>
    <artifactId>delight-nashorn-sandbox</artifactId>
    <version>[insert latest version]</version>
</dependency>

Note that up to version v.0.1.31 the library would only work with Java versions lower than 13. To make the library work with Java version 13 and above, please use a library version 0.2.0+. The compatibility with v0.2.0 with lower versions of Java is still experimental. If you encounter issues, specifically in Java 1.8 please use a 0.1.x version (and please report any issues).

This artifact is available on Maven Central.

If you are looking for a JAR with all dependencies, you can also download it from here.

Contributors

Eduardo Velasques: API extensions to block/allow Rhino system functions; Capability to block/allow variables after Sandbox has been created.

Marcin Gołębski: Major refactoring and performance improvements. Among other things improved the performance for JS evaluation and better handling of monitoring for threads for possible CPU abuse (#23).

Marco Ellwanger: Initial support for GraalJS engine by implementing sandbox implementation backed by GraalJS.

Olivier Bourgain: Detection for JDK version and ability to use standalone Nashorn for JDK versions in which it is not included.

busterace: Perform code injection using AST rather than regex (#157)

Version History

• 0.5.0: Code injection performed via AST rather than RegEx for improved performance and accuracy (PR #157). Option allowNoBraces no longer supported, since not required.
• 0.4.5: Increasing limits for iterations for RegEx resolutions. Resolves Issue #151
• 0.4.4: Adds additional check for completed execution. Resolves Issue #153
• 0.4.3: Ensure compatibility with Java Platform Module System (JPMS) (PR #154 by nea89o)
• 0.4.2: Ensure compatibility with Java 17
• 0.4.0: Upgrade to Java 20
• 0.3.2: Updating JSBeautifier dependency (PR #143 by davejbur)
• 0.3.1: Protect against RegEx attacks in sanitising script input by PR #139
• 0.3.0: Creating a wrapper for Script Context to be passed to eval to avoid accidental exposure. Resolves Issue #134
• 0.2.5: Support for pre-compiled scripts (PR #119 by geoffreyharding]
• 0.2.4: Increased resiliency for killing threads under high load (PR #118 by tellmewhattodo)
• 0.2.0: Dynamically detects what version of the JDK the library is run with, and will either use the included Nashorn version or use Nashorn dependency (Issue #109, PR #101).
• 0.1.32: Defaulted allowNoBraces to true since the check easily leads to false positives (Issue #102 and Issue #104)
• 0.1.28: Upgraded JS Beautify version to 1.9.0 to address failing security checks (Issue #93)
• 0.1.27: Fix bug that Nashorn Sandbox does not guarantee that scripts will be stopped if they consume too much memory or CPU time (PR #96 by jerome-baudoux)
• 0.1.25: Graal JS sandbox capabilities have been moved to delight-graaljs-sandbox repository.
• 0.1.23: Initial support for Graal JS (PR #87 by mellster2012)
• 0.1.22: Fixing issue with injection of if statement in certain situations (PR #82 by foxep2001); Support for JVMs that do not support ThreadMXBean (PR #84 by amoravec)
• 0.1.21: Fixing executor thread not set after ms - intermittent issue # 75 by pradeepKaatnam
• 0.1.20: Implementing protection for security issue # 73 as suggested by amlweems
• 0.1.19: Performance improvement for beautification PR #71 by turbanoff
• 0.1.18: Fixing issue #66 with PR #69 by everestbt
• 0.1.17: Improved way bindings are handled (see PR #68 by everestbt); Fixing issue #66
• 0.1.16: Removing tools.jar dependency (see issue # 62)
• 0.1.15: Allowing to inject custom cache for secure JS (see PR #59); Preventing the use of --no-java engine parameter (see issue #57)
• 0.1.14: Fixed bug that ThreadMonitor waits for too long sometimes (see PR #56 by cmorris)
• 0.1.13: Added support for providing Bindings for evaluating scrips (see PR #44 by Frontrider); Improving way access to global functions such as exit is blocked; Allowing for|while|do when they are given in quoted strings in JavaScript (see issue #47).
• 0.1.12: Adding capability for calling Invocable:invoke (see PR #42 from escitalopram); Fixing typos in method signatures (see PR #41 by Sina)
• 0.1.11: Added support for custom parameters in creating Nashorn Script engine (see issue #40).
• 0.1.10: Added createBindings to the API to allow overriding global properties (see PR #39 by Srinivasa Chintalapati)
• 0.1.9: Fixed bug #36
• 0.1.8: Fixed that do, while and for in comments might cause BracesExceptions (see bug #34)
• 0.1.7: Used webjar dependency for BeautifyJS and slf4j as logging dependency (PR #35 by thjaeckle); Updated license (see bug #32)
• 0.1.6: Fixing bug that monitor checking for CPU abuses would hang when it encountered monitor.wait(0) (see issue 30)
• 0.1.5: Fixing bug #28 with PR 29 by srinivasarajuch - added support for evaluation JS with specific ScriptContext
• 0.1.4: Fixing bug #27
• 0.1.3: Improving regex for interrupt injections (PR 26), cleaning up code for obtaining JSBeautifier instance (PR 25)
• 0.1.2: Improving way JsBeautifier instance is obtained (PR 24)
• 0.1.1: Making all fields in NashornSandboxImpl protected rather than private (see issue #19)
• 0.1.0: Major rework and performance improvements implemented by Marcin Gołębski (PR 23)

Further Documentation

• JavaDocs
• All Maven Reports