org.graalvm.polyglot

Enum SandboxPolicy

java.lang.Object

java.lang.Enum<SandboxPolicy>

org.graalvm.polyglot.SandboxPolicy

All Implemented Interfaces:

Serializable, Comparable<SandboxPolicy>, java.lang.constant.Constable

public enum SandboxPolicy
extends Enum<SandboxPolicy>

The sandbox policy presets and validates configurations of a context or engine to be suitable as a code sandbox. The policy is set by passing it to the engine or context builder method.

There are four policies to choose from that become strictly more strict:

• SandboxPolicy.TRUSTED policy intended for fully trusted applications. In this mode, access to any resource of the host might be accessible to the guest application. This is the default mode, there are no restrictions to the context or engine configuration.
• SandboxPolicy.CONSTRAINED policy intended for trusted, but potentially buggy applications. In this mode, any access to host resources is required to be as restrictive as possible. In this mode, the guest and host application share a heap and execute on the same underlying virtual machine.
• SandboxPolicy.ISOLATED policy intended for trusted applications, but which might have security vulnerabilities and optionally that can be mitigated using this policy. For example, a script that processes untrusted input. Security vulnerabilities would allow an attacker to compromise the guest application by providing malicious input. In this mode, guest and host application execute on separate virtual machine instances.
• SandboxPolicy.UNTRUSTED policy intended for fully untrusted applications. This assumes that a potentially malicious actor is supplying the guest code itself that is being run. A strong adversarial scenario is the execution of client-side Javascript in the browser that is supplied by an untrusted website. In this mode, the sandbox employs additional hardening mechanisms at the compiler and runtime level to mitigate e.g. JIT spraying or speculative execution attacks.

It is unsupported to run untrusted code with any other policy than SandboxPolicy.UNTRUSTED.

Compatibility Notice: The behavior of sandbox policies is subject to incompatible changes for new GraalVM major releases. New presets and validations may be added in new GraalVM releases that may let configurations valid in older versions fail for newer versions. Therefore, adopting a new GraalVM version with a set sandbox policy might require changes for the embedder. This applies to all policies other than SandboxPolicy.TRUSTED. Changes to the policy are announced in the SDK release changelog.

Since:

23.0

See Also:

Context.Builder.sandbox(SandboxPolicy), Engine.Builder.sandbox(SandboxPolicy)

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Enum Constant Summary

Enum Constants

Enum Constant and Description
CONSTRAINED Policy intended for trusted, but potentially buggy applications.
ISOLATED Policy intended for trusted applications, but which might have security vulnerabilities and optionally that can be mitigated using this policy.
TRUSTED Policy intended for fully trusted applications.
UNTRUSTED Policy intended for untrusted applications.

Method Summary

Modifier and Type	Method and Description
boolean	isStricterOrEqual(SandboxPolicy other) Tests whether this SandboxPolicy is stricter or equal to other.
boolean	isStricterThan(SandboxPolicy other) Tests whether this SandboxPolicy is stricter than other.
static SandboxPolicy	valueOf(String name) Returns the enum constant of this type with the specified name.
static SandboxPolicy[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

TRUSTED

public static final SandboxPolicy TRUSTED

Policy intended for fully trusted applications. In this mode, access to any resource of the host might be accessible to the guest application. This is the default mode, there are no restrictions to the context or engine configuration.

Since:

23.0

CONSTRAINED

public static final SandboxPolicy CONSTRAINED

Policy intended for trusted, but potentially buggy applications. In this mode, any access to host resources is required to be as restrictive as possible. In this mode, the guest and host application share a heap and execute on the same underlying virtual machine.

The CONSTRAINED sandbox policy enforces the following context restriction:

• The list of permitted languages must be explicitly set.
• If in is not specified, the InputStream.nullInputStream() is used. Otherwise, it must be redirected elsewhere than to System.in.
• Standard out and Context.Builder.err(OutputStream) err} streams must be redirected.
• The all access must not be enabled.
• The native access must not be enabled.
• The Context.Builder.allowHostClassLoading(boolean) host class loading} must not be enabled.
• The external process execution must not be enabled.
• The environment access must be EnvironmentAccess.NONE.
• The host System.exit must not be used.
• The access to the host file system must be disabled. IO can be disabled or it can use a custom file system.
• If a custom filesystem is used, it must not be the default filesystem or a filesytem wrapping the default file system.
• Only languages with a sandbox policy of at least CONSTRAINED can be used.
• Only instruments with a sandbox policy of at least CONSTRAINED can be used.
• Only a subset of options that are safe with the sandbox policy can be used.
• If HostAccess is not specified, the HostAccess.CONSTRAINED is used.
Otherwise, the specified HostAccess must not allow public access, access inheritance, all class implementations, all interface implementations and mutable target type mappings.
• The execution listeners must not be attached.
• The message transport must not be set.

Constrained Context building example:

 ByteArrayOutputStream output = new ByteArrayOutputStream();
 ByteArrayOutputStream errorOutput = new ByteArrayOutputStream();
 try (Context context = Context.newBuilder("js") //
                 .sandbox(SandboxPolicy.CONSTRAINED) //
                 .out(output) //
                 .err(errorOutput) //
                 .build()) {
     context.eval(source);
 }
 

Since:

23.0

ISOLATED

public static final SandboxPolicy ISOLATED

Policy intended for trusted applications, but which might have security vulnerabilities and optionally that can be mitigated using this policy. For example, a script that processes untrusted input. Security vulnerabilities may allow an attacker to compromise the guest application by providing malicious input. In this mode, guest and host application execute on separate virtual machine instances.

In addition to the SandboxPolicy.CONSTRAINED restrictions, the ISOLATED sandbox policy adds the following constraints:

• The engine.SpawnIsolate option is preset to true if it has not been explicitly set.
• The engine.MaxIsolateMemory option must be set.
• The sandbox.MaxCPUTime limits option must be set. Use sandbox.TraceLimits to estimate an application's optimal sandbox parameters.
• If HostAccess is not specified, the HostAccess.ISOLATED is used.
Otherwise, the specified HostAccess must meet all the constraints of the SandboxPolicy.CONSTRAINED sandbox policy and must in addition use scoped references.

Isolated Context building example:

 ByteArrayOutputStream output = new ByteArrayOutputStream();
 ByteArrayOutputStream errorOutput = new ByteArrayOutputStream();
 try (Context context = Context.newBuilder("js") //
                 .sandbox(SandboxPolicy.ISOLATED)  //
                 .out(output)  //
                 .err(errorOutput)  //
                 .option("engine.MaxIsolateMemory", "1GB")  //
                 .option("sandbox.MaxCPUTime", "10s") //
                 .build()) {
     context.eval(source);
 }
 

Since:

23.0

UNTRUSTED

public static final SandboxPolicy UNTRUSTED

Policy intended for untrusted applications. This assumes that a malicious actor is supplying the guest code itself that is being run. A strong adversarial scenario is the execution of client-side Javascript in the browser that is supplied by an untrusted website. In this mode, the sandbox employs additional hardening mechanisms at the compiler and runtime level to mitigate e.g. speculative execution attacks.

In addition to the SandboxPolicy.ISOLATED constraints, the UNTRUSTED sandbox policy adds the following requirements:

• If HostAccess is not specified, the HostAccess.UNTRUSTED is used. Otherwise, the specified HostAccess must meet all the constraints of the SandboxPolicy.ISOLATED sandbox policy.
• The engine.UntrustedCodeMitigation option is preset to software if it has not been explicitly set.
• The sandbox.MaxCPUTime, sandbox.MaxHeapMemory, sandbox.MaxASTDepth, sandbox.MaxStackFrames, sandbox.MaxThreads, sandbox.MaxOutputStreamSize, sandbox.MaxErrorStreamSize limits options must be set. Use sandbox.TraceLimits to estimate an application's optimal sandbox parameters.

Untrusted Context building example:

 ByteArrayOutputStream output = new ByteArrayOutputStream();
 ByteArrayOutputStream errorOutput = new ByteArrayOutputStream();
 try (Context context = Context.newBuilder("js") //
                 .sandbox(SandboxPolicy.UNTRUSTED) //
                 .out(output) //
                 .err(errorOutput) //
                 .option("engine.MaxIsolateMemory", "1GB") //
                 .option("sandbox.MaxHeapMemory", "800MB") //
                 .option("sandbox.MaxCPUTime", "10s") //
                 .option("sandbox.MaxASTDepth", "100") //
                 .option("sandbox.MaxStackFrames", "10") //
                 .option("sandbox.MaxThreads", "1") //
                 .option("sandbox.MaxOutputStreamSize", "1MB") //
                 .option("sandbox.MaxErrorStreamSize", "1MB") //
                 .build()) {
     context.eval(source);
 }
 

Since:

23.0

Method Detail

values

public static SandboxPolicy[] values()

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static SandboxPolicy valueOf(String name)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

isStricterThan

public boolean isStricterThan(SandboxPolicy other)

Tests whether this SandboxPolicy is stricter than other.

Since:

23.0

isStricterOrEqual

public boolean isStricterOrEqual(SandboxPolicy other)

Tests whether this SandboxPolicy is stricter or equal to other.

Since:

23.0