org.pkl.thirdparty.graalvm.polyglot.SandboxPolicy Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of pkl-config-java-all Show documentation
Shaded fat Jar for pkl-config-java, a Java config library based on the Pkl config language.
There is a newer version: 0.27.1
/*
 * Copyright (c) 2023, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * The Universal Permissive License (UPL), Version 1.0
 *
 * Subject to the condition set forth below, permission is hereby granted to any
 * person obtaining a copy of this software, associated documentation and/or
 * data (collectively the "Software"), free of charge and under any and all
 * copyright rights in the Software, and any and all patent rights owned or
 * freely licensable by each licensor hereunder covering either (i) the
 * unmodified Software as contributed to or provided by such licensor, or (ii)
 * the Larger Works (as defined below), to deal in both
 *
 * (a) the Software, and
 *
 * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
 * one is included with the Software each a "Larger Work" to which the Software
 * is contributed by such licensors),
 *
 * without restriction, including without limitation the rights to copy, create
 * derivative works of, display, perform, and distribute the Software and make,
 * use, sell, offer for sale, import, export, have made, and have sold the
 * Software and the Larger Work(s), and to sublicense the foregoing rights on
 * either these or other terms.
 *
 * This license is subject to the following condition:
 *
 * The above copyright notice and either this complete permission notice or at a
 * minimum a reference to the UPL must be included in all copies or substantial
 * portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
package org.pkl.thirdparty.graalvm.polyglot;

import org.pkl.thirdparty.graalvm.polyglot.io.FileSystem;
import org.pkl.thirdparty.graalvm.polyglot.io.IOAccess;
import org.pkl.thirdparty.graalvm.polyglot.io.MessageTransport;

import java.io.InputStream;
import java.io.OutputStream;

/**
 * The sandbox policy presets and validates configurations of a {@link Context context} or
 * {@link Engine engine} to be suitable as a code sandbox. The policy is set by passing it to the
 * {@link Engine.Builder#sandbox(SandboxPolicy) engine} or
 * {@link Context.Builder#sandbox(SandboxPolicy) context} builder method.
 * 
 *
 * There are four policies to choose from that become strictly more strict:
 * 

 * {@link #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.
 * 
{@link #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.
 * 
{@link #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.
 * 
{@link #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 {@link #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 {@link #TRUSTED}. Changes to the policy are announced in
 * the SDK release
 * changelog.
 * 

 *
 * For further information on Polyglot Sandboxing, please refer to the
 * security guide.
 *
 * @see Context.Builder#sandbox(SandboxPolicy)
 * @see Engine.Builder#sandbox(SandboxPolicy)
 *
 * @since 23.0
 */
public enum SandboxPolicy {

    /**
     * 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
     */
    TRUSTED,

    /**
     * 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 {@code CONSTRAINED} sandbox policy enforces the following context restriction:
     * 

     * The list of {@link Context#newBuilder(String...) permitted languages} must be explicitly
     * set.
     * If {@link Context.Builder#in(InputStream) in} is not specified, the
     * {@link InputStream#nullInputStream()} is used. Otherwise, it must be redirected elsewhere
     * than to {@link System#in}.
     * 
Standard {@link Context.Builder#out(OutputStream) out} and
     * {@link Context.Builder#err(OutputStream)} err} streams must be redirected.
     * The {@link Context.Builder#allowAllAccess(boolean) all access} must not be enabled.
     * The {@link Context.Builder#allowNativeAccess(boolean) native access} must not be
     * enabled.
     * The {@link Context.Builder#allowHostClassLoading(boolean)} host class loading} must not
     * be enabled.
     * The {@link Context.Builder#allowCreateProcess(boolean) external process execution} must
     * not be enabled.
     * The {@link Context.Builder#allowEnvironmentAccess(EnvironmentAccess) environment access}
     * must be {@link EnvironmentAccess#NONE}.
     * The {@link Context.Builder#useSystemExit(boolean) host System.exit} must not be
     * used.
     * The {@link Context.Builder#allowIO(IOAccess) access to the host file system} must be
     * disabled. IO can be {@link IOAccess#NONE disabled} or it can use a
     * {@link org.pkl.thirdparty.graalvm.polyglot.io.IOAccess.Builder#fileSystem(FileSystem) custom file
     * system}.
     * If a custom filesystem is used, it must not be the
     * {@link FileSystem#newDefaultFileSystem() default filesystem} or a filesytem wrapping the
     * default file system.
     * Only languages with a sandbox policy of at least {@code CONSTRAINED} can be used.
     * Only instruments with a sandbox policy of at least {@code CONSTRAINED} can be used.
     * Only a subset of options that are safe with the sandbox policy can be used.
     * If {@link HostAccess} is not specified, the {@link HostAccess#CONSTRAINED} is used.
     * Otherwise, the specified {@link HostAccess} must not allow
     * {@link HostAccess.Builder#allowPublicAccess(boolean) public access},
     * {@link HostAccess.Builder#allowAccessInheritance(boolean) access inheritance},
     * {@link HostAccess.Builder#allowAllClassImplementations(boolean) all class implementations},
     * {@link HostAccess.Builder#allowAllImplementations(boolean) all interface implementations} and
     * {@link HostAccess.Builder#allowMutableTargetMappings(HostAccess.MutableTargetMapping...)
     * mutable target type mappings}.
     * The {@link org.pkl.thirdparty.graalvm.polyglot.management.ExecutionListener.Builder#attach(Engine)
     * execution listeners} must not be attached.
     * The {@link Engine.Builder#serverTransport(MessageTransport) 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
     */
    CONSTRAINED,

    /**
     * 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 {@link #CONSTRAINED} restrictions, the {@code ISOLATED} sandbox policy
     * adds the following constraints:
     * 

     * The {@code engine.SpawnIsolate} option is preset to true if it has not been
     * explicitly set.
     * The {@code engine.MaxIsolateMemory} option must be set.
     * The {@code sandbox.MaxCPUTime} limits option must be set. Use {@code sandbox.TraceLimits}
     * to estimate an application's optimal sandbox parameters.
     * If {@link HostAccess} is not specified, the {@link HostAccess#ISOLATED} is used.
     * Otherwise, the specified {@link HostAccess} must meet all the constraints of the
     * {@link #CONSTRAINED} sandbox policy and must in addition use
     * {@link HostAccess.Builder#methodScoping(boolean) 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
     */
    ISOLATED,

    /**
     * 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 {@link #ISOLATED} constraints, the {@code UNTRUSTED} sandbox policy adds
     * the following requirements:
     * 

     * If {@link HostAccess} is not specified, the {@link HostAccess#UNTRUSTED} is used.
     * Otherwise, the specified {@link HostAccess} must meet all the constraints of the
     * {@link #ISOLATED} sandbox policy.
     * The {@code engine.UntrustedCodeMitigation} option is preset to {@code software} if it has
     * not been explicitly set.
     * The {@code sandbox.MaxCPUTime}, {@code sandbox.MaxHeapMemory},
     * {@code sandbox.MaxASTDepth}, {@code sandbox.MaxStackFrames}, {@code sandbox.MaxThreads},
     * {@code sandbox.MaxOutputStreamSize}, {@code sandbox.MaxErrorStreamSize} limits options must
     * be set. Use {@code 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
     */
    UNTRUSTED;

    /**
     * Tests whether this {@link SandboxPolicy} is stricter than {@code other}.
     *
     * @since 23.0
     */
    public boolean isStricterThan(SandboxPolicy other) {
        return this.ordinal() > other.ordinal();
    }

    /**
     * Tests whether this {@link SandboxPolicy} is stricter or equal to {@code other}.
     *
     * @since 23.0
     */
    public boolean isStricterOrEqual(SandboxPolicy other) {
        return this.ordinal() >= other.ordinal();
    }
}