io.apigee.trireme.core

Class Sandbox

java.lang.Object

io.apigee.trireme.core.Sandbox

public class Sandbox
extends Object

The Sandbox defines the execution environment for all scripts. It may be used when embedding Noderunner so that there's a way to restrict the execution environment and plug in to various key services. To use a sandbox, implement this interface and pass it to NodeEnvironment.setSandbox().

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Sandbox.ClassLoaderSupplier A Supplier that returns an instance of a ClassLoader to be used for loading Java classes into the currently-running script.

Constructor Summary

Constructors

Constructor and Description
Sandbox() Create a new sandbox that will not affect anything in any way.
Sandbox(Sandbox parent) Create a new sandbox that will copy the parameters from a parent.

Method Summary

Methods

Modifier and Type	Method and Description
ExecutorService	getAsyncThreadPool()
Sandbox.ClassLoaderSupplier	getClassLoaderSupplier() Returns the ClassLoaderSupplier if set, null otherwise.
org.mozilla.javascript.ClassShutter	getExtraClassShutter()
String	getFilesystemRoot()
List<Map.Entry<String,String>>	getMounts()
NetworkPolicy	getNetworkPolicy()
OutputStream	getStderr()
InputStream	getStdin()
OutputStream	getStdout()
SubprocessPolicy	getSubprocessPolicy()
String	getWorkingDirectory()
boolean	isAllowJarLoading()
boolean	isHideOSDetails()
void	mount(String prefix, String target) Mount a location on the local filesystem at a virtual path.
Sandbox	setAllowJarLoading(boolean allowed) Allow the use of the "trireme-support" module's "loadJars" method to load JAR files into the currently-running script.
Sandbox	setAsyncThreadPool(ExecutorService exec) Set the Executor where any jobs can be run that require a separate thread pool.
Sandbox	setClassLoaderSupplier(Sandbox.ClassLoaderSupplier classLoaderSupplier) Allows specifying the Supplier that will return an instance of a ClassLoader that will be used by the "trireme-support" module's "loadJars" method to load JAR files into the currently-running script.
Sandbox	setExtraClassShutter(org.mozilla.javascript.ClassShutter extraClassShutter) Attach an extra ClassShutter that can allow Trireme embedders the ability to expose extra Java classes to JavaScript code.
Sandbox	setFilesystemRoot(String root) Provide a "chroot"-like facility so that all filenames used by the "fs" module (not all files used internally by NodeRunner) must be treated as if the "root" is in a different location.
Sandbox	setHideOSDetails(boolean obscure) If set to true, hide the internal details returned by the "OS" package.
Sandbox	setNetworkPolicy(NetworkPolicy policy) Attach an object that will be called every time the process tries to open an outgoing network connection or listen for incoming connections.
Sandbox	setStderr(OutputStream s) Set the stream that scripts should use for standard error output.
Sandbox	setStdin(InputStream s) Set the stream that scripts should use for standard input.
Sandbox	setStdout(OutputStream s) Set the stream that scripts should use for standard output.
Sandbox	setSubprocessPolicy(SubprocessPolicy policy) Attach an object that will be called every time the process tries to invoke a sub process, including "node" itself.
Sandbox	setWorkingDirectory(String wd) Set the working directory of this script.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Sandbox

public Sandbox()

Create a new sandbox that will not affect anything in any way.

Sandbox

public Sandbox(Sandbox parent)

Create a new sandbox that will copy the parameters from a parent. This allows a hierarchy of sandboxes.

Method Detail

setFilesystemRoot

public Sandbox setFilesystemRoot(String root)

Provide a "chroot"-like facility so that all filenames used by the "fs" module (not all files used internally by NodeRunner) must be treated as if the "root" is in a different location. Any files "above" the root will be treated as "not found." This will also affect module loading of all but the root module, so that "require" statements must only refer to files under the root directory. Once this is set, then all filesystem calls must be specified relative to this root.

getFilesystemRoot

public String getFilesystemRoot()

mount

public void mount(String prefix,
         String target)

Mount a location on the local filesystem at a virtual path. This works in a similar way to "mount" in an OS in that everything in the directory tree under the path is directed to the mounted location. In other words, if "/foo/bar" is mounted as "/usr/lib/bar," then "/usr/lib/bar/baz" will be translated to "/foo/bar/baz".

Parameters:

prefix - where to mount, such as "/opt". This must be an absolute path.

target - what to mount there, which may be a relative or absolute path.

getMounts

public List<Map.Entry<String,String>> getMounts()

setWorkingDirectory

public Sandbox setWorkingDirectory(String wd)

Set the working directory of this script. This is the directory for relative paths and for "process.cwd()". This directory is relative to the filesystem root set in "setFilesystemRoot". By default if "setFilesystemRoot" was called then the directory defaults to that, and otherwise to the user's working directory.

getWorkingDirectory

public String getWorkingDirectory()

setStdout

public Sandbox setStdout(OutputStream s)

Set the stream that scripts should use for standard output. By default, System.out will be used. If this method is used to set the stream to non-null, then the corresponding stream will be used instead.

getStdout

public OutputStream getStdout()

setStderr

public Sandbox setStderr(OutputStream s)

Set the stream that scripts should use for standard error output. By default, System.err will be used. If this method is used to set the stream to non-null, then the corresponding stream will be used instead.

getStderr

public OutputStream getStderr()

setStdin

public Sandbox setStdin(InputStream s)

Set the stream that scripts should use for standard input. By default, System.in will be used. If this method is used to set the stream to non-null, then the corresponding stream will be used instead.

getStdin

public InputStream getStdin()

setAsyncThreadPool

public Sandbox setAsyncThreadPool(ExecutorService exec)

Set the Executor where any jobs can be run that require a separate thread pool. At the moment, this includes DNS lookups and asynchronous filesystem calls. If this is unset or set to null then a new thread pool will be created.

getAsyncThreadPool

public ExecutorService getAsyncThreadPool()

setNetworkPolicy

public Sandbox setNetworkPolicy(NetworkPolicy policy)

Attach an object that will be called every time the process tries to open an outgoing network connection or listen for incoming connections. This may be used to protect access to and from certain hosts on an internal network. Note that this object is not consulted if an HttpAdapter has been registered -- in that case the HttpAdapter itself is responsible for restricting access.

getNetworkPolicy

public NetworkPolicy getNetworkPolicy()

setSubprocessPolicy

public Sandbox setSubprocessPolicy(SubprocessPolicy policy)

Attach an object that will be called every time the process tries to invoke a sub process, including "node" itself. If it returns false, then the process will not be launched.

getSubprocessPolicy

public SubprocessPolicy getSubprocessPolicy()

setHideOSDetails

public Sandbox setHideOSDetails(boolean obscure)

If set to true, hide the internal details returned by the "OS" package. Default is false. If set to true:

• os.cpus returns an array of a single "cpu" rather than the actual number.
• os.networkinterfaces returns only the loopback interface.
• os.type, platform, arch, and release all return constants rather than the real information.

isHideOSDetails

public boolean isHideOSDetails()

setExtraClassShutter

public Sandbox setExtraClassShutter(org.mozilla.javascript.ClassShutter extraClassShutter)

Attach an extra ClassShutter that can allow Trireme embedders the ability to expose extra Java classes to JavaScript code. WARNING: This must be used with care as passing Java objects disallowed by the default Trireme ClassShutter can result in unknown consequences.

getExtraClassShutter

public org.mozilla.javascript.ClassShutter getExtraClassShutter()

setAllowJarLoading

public Sandbox setAllowJarLoading(boolean allowed)

Allow the use of the "trireme-support" module's "loadJars" method to load JAR files into the currently-running script. This is enabled by default -- this option allows an environment to disable this feature.

isAllowJarLoading

public boolean isAllowJarLoading()

setClassLoaderSupplier

public Sandbox setClassLoaderSupplier(Sandbox.ClassLoaderSupplier classLoaderSupplier)

Allows specifying the Supplier that will return an instance of a ClassLoader that will be used by the "trireme-support" module's "loadJars" method to load JAR files into the currently-running script.

getClassLoaderSupplier

public Sandbox.ClassLoaderSupplier getClassLoaderSupplier()

Returns the ClassLoaderSupplier if set, null otherwise.