Package org.graalvm.polyglot

Enum Class SandboxPolicy

java.lang.Object
java.lang.Enum<SandboxPolicy>
org.graalvm.polyglot.SandboxPolicy
All Implemented Interfaces:
Serializable, Comparable<SandboxPolicy>, 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:

  • 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.
  • 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.
  • 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.
  • 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 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 TRUSTED. Changes to the policy are announced in the SDK release changelog.

For further information on Polyglot Sandboxing, please refer to the security guide.

Since:
23.0
See Also:

  • Enum Constant Details

    • 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:

      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 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 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 ISOLATED constraints, the UNTRUSTED sandbox policy adds the following requirements:

      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 Details

    • values

      public static SandboxPolicy[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static SandboxPolicy valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class 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