Package com.tnsai.quality.sandbox

Class ProcessSandbox

java.lang.Object

com.tnsai.quality.sandbox.ProcessSandbox

All Implemented Interfaces:

Sandbox, AutoCloseable

public final class ProcessSandbox
extends Object
implements Sandbox

Portable Sandbox backend using JVM ProcessBuilder (TNS-296). The fallback that runs everywhere — slower than container/microVM/WASM backends but available on every host.

Provides

• Process boundary — child code does not share in-process JVM heap references. This backend does not provide OS-level process isolation against same-user attach, tracing, or host-kernel capabilities.
• Per-instance temporary working directory.
• Env scrubbing — only SandboxSpec.env() entries are visible to sandboxed processes; the host's environment is not inherited.
• Timeout enforcement — Process.waitFor(long, TimeUnit) with the spec's ResourceLimits.timeout(); over-budget processes are killed and SandboxResult.timedOut() is set.
• Host-heap output cap — combined stdout+stderr cannot exceed ResourceLimits.maxOutputBytes(); overflow kills the child and sets SandboxResult.outputTruncated().
• Wall-clock accounting — ResourceUsage.wallClockMs.

Cannot provide (use a stronger backend)

• Filesystem isolation or mounts. The temporary working directory is only passed to ProcessBuilder.directory(java.io.File); it is not a chroot, namespace, or path interceptor. Child processes can still read and write host paths permitted to the JVM user. Use ContainerSandbox or a stronger backend when filesystem confinement or FsMount mappings are required. This backend rejects every non-empty SandboxSpec.fsMounts() request rather than silently changing an absolute sandbox path into a relative copy.
• Network policy enforcement. NetPolicy.DenyAll and NetPolicy.AllowList are recorded but not enforced by this backend; a JVM child process inherits the host network stack. The factory logs a warning at creation time. For real network isolation use ContainerSandbox or FirecrackerSandbox.
• CPU / memory caps. The JVM has no portable way to limit a child process's resources; backends backed by cgroups or container runtimes do this properly.

Since:

0.10.0 (TNS-296)

Method Summary

Modifier and Type	Method	Description
SandboxResult	execute(Command command)	Run command to completion (or until the sandbox kills it for exceeding ResourceLimits.timeout).
SandboxSpec	spec()	The SandboxSpec this instance was created from.
void	stop()	Graceful shutdown.
void	terminate()	Forcibly kill the sandbox and release its resources.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.tnsai.quality.sandbox.Sandbox

close

Method Details

spec

public SandboxSpec spec()

Description copied from interface: Sandbox

The SandboxSpec this instance was created from. Useful for downstream tooling (audit, observability) that needs to record the configured policy alongside the result.

Specified by:

spec in interface Sandbox

execute

public SandboxResult execute(Command command)

Description copied from interface: Sandbox

Run command to completion (or until the sandbox kills it for exceeding ResourceLimits.timeout). Always returns a SandboxResult; failures inside the sandbox are reflected in SandboxResult.exitCode and SandboxResult.stderr, not thrown.

Throws if the sandbox itself has been terminated, or if the backend layer cannot dispatch the command (image missing, runtime crash). Those are infrastructure failures, distinct from "the user's command exited non-zero".

Specified by:

execute in interface Sandbox

stop

public void stop()

Description copied from interface: Sandbox

Graceful shutdown. Backends SHOULD send SIGTERM (or the platform equivalent), wait a short grace period, then promote to Sandbox.terminate() if the process is still running.

Specified by:

stop in interface Sandbox

terminate

public void terminate()

Description copied from interface: Sandbox

Forcibly kill the sandbox and release its resources. Idempotent — calling on an already-terminated sandbox is a no-op. Safe in finally blocks.

Specified by:

terminate in interface Sandbox