A ptrace-based syscall filtering sandbox
========================================

This is a configurable ptrace jail that supports sandboxing multiple threads,
filtering access to subtrees of the filesystem, suspending processes, and
pretending that HTTP links are files. This seemmingly absurd set of features
is ideal for sandboxing a programming language interpreter process for an
interactive evaluation bot on IRC or the like.

In general, you'll want an environment analogous to a chroot (except we don't
do chroots), with all the executables and shared libraries inside, and,
possibly a writeable directory in there as well. The sandbox doesn't enforce
any file size limits so it would be appropriate to place the writeable
directory on a loop mountpoint, or assign a filesystem quota, or use a
filesystem-specific solution that accomplishes the same.

To run a process inside the sandbox, run:

    sandbox <config.conf> <ident> [program [args...]]

The <ident> is an identifier that is used to distinguish suspended processes,
and to allow identifier-specific configuration.

To kill a suspended process by its identifier, run:

    sandbox <config.conf> kill <ident>

The configuration file syntax is as follows: each line is a keyword followed
by optional space-separated arguments whose meaning depends on the keyword.
A line beginning with # followed by a space is a comment.

A line "ident <name>" starts a block of configuration specific to the
identifier <ident>, which spans until the line "end". Other keywords include:


program <path>
    Specify a default executable path in case sandbox is called without
    specifying the executable.

arg <word>
    Append an argument to the default commandline. Note that the first such
    keyword actually sets argv[0].

closefds
    Close all file descriptors other than 0, 1, 2.

setenv <var> <value>
    Set an environment variable for the sandboxed process.

clearenv
    Clear all environment variables at the start.

unsetenv <var>
    Remove a single environment variable.

see <path>
    Specify a subtree of the filesystem which the sandboxed process is allowed
    to see. This includes opening for reading, stat'ing, readlink'ing,
    readdir'ing, execve'ing, and so on.

    Note that this doesn't magically lift restrictions imposed by the kernel:
    the sandboxed process still won't be able to see files/directories hidden
    by permission bits affecting the process's UID/GID.

write <path>
    Specify a subtree of the filesystem which the sandboxed process is allowed
    to write to. This includes opening for writing, mkdir'ing, rename'ing, and
    so on.

maxthreads <number>
    Specify the maximum number of threads or processes in a sandbox.

chdir <path>
    Change directory for the sandboxed process to the specified one.

rlimit <lim> <value>
    Set a rlimit on the sandboxed process. For more information consult
    getrlimit(3). Example: "rlimit NOFILE 32". You might wish to limit the
    amount of virtual memory available to the process (AS) with this.

timelimit <limit>
    Specify a time limit in seconds (wall clock time) after which the sandboxed
    process will be forcibly and abruptly terminated.

wakeup
    Allow the process to issue a special syscall that will tell the sandbox
    that the process is done interpreting the current command, and is waiting
    for the next. The sandbox will then fork into the background, and then
    a later invocation with the same identifier will talk to the existing
    process instead of creating a new one.

    In a REPL, you'll want to place the syscall at the end of the Loop, after
    the Read, Eval, Print steps. You also want to make sure that an invocation
    of the sandbox receives exactly as much input as the Read step expects,
    otherwise it might time out waiting for input, or have extra input queued
    up.

    With this flag enabled, an EOF on the sandbox's stdin will not cause the
    sandboxed process to receive an EOF, in assurance that the sandboxed
    process will suspend after consuming the input.

sockdir <path>
    Specify a directory for UNIX sockets which are used to talk to suspended
    processes.

http <url>
    Pretend that any file whose name begins with <url> actually exists. When
    the sandboxed process tries to open such a file, it will be downloaded and
    fed into the process.

downloadpat <pattern>
    Specify location and name of temporary files used for downloads. This will
    be fed to mkstemp(3) and should conform to that function's expectations.