pola-run: Launch a program in a sandbox

Contents

pola-run: Launch a program in a sandbox

Synopsis

pola-run
  --prog filename
  [  -f[awls]... pathname
   | -t[awls]... pathname pathname
   | -a string
   | --cwd dir
   | --no-cwd
   | --copy-cwd
  ]...
  [-B] [--x11] [--net]
  [--powerbox [--pet-name name]]

Description

pola-run runs programs under the Plash environment. It starts a process with a subset of the caller process's authority. The caller can grant the callee read-only or read-write access to specific files and directories, which can be mapped at any point in the callee's filesystem namespace.

pola-run provides a programmatic interface. It is intended to be used from Bash shell scripts and other programs. Since it works via the command line, it can be used from virtually any language, in contrast to a C API. pola-run is different from the Plash shell, which does not provide a programmatic interface: Plash shell commands are intended to be written by hand, not generated automatically.

pola-run constructs two things to pass to the callee program: a list of argument strings (as received by main()), and a file namespace. The -a option adds strings to the argument list, in order. The -f and -t options add files and directories to the file namespace. These can be combined: -fa and -ta add an object to the file namespace and a corresponding filename to the argument list.

Unlike the Plash shell, pola-run grants access to no files by default. The -B option will grant access to a fairly safe but large installation endowment, which includes /usr, /bin and /lib. (Currently this is different to the shell's default installation endowment, which includes /etc as well.)

Options

For arguments that take one parameter, there are two forms to choose from: "--arg param" and "--arg=param". The first form may be more convenient to generate in a C program. The latter may be more readable in hand-written shell scripts.

--prog

--prog filename
--prog=filename

This gives the filename of the executable to be invoked. If it doesn't contain a slash, it will be looked up in PATH.

The filename is resolved in the callee's namespace, not the caller's namespace.

Note that if the executable is a "#!" script, access to the interpreter specified in the "#!" line will not be implicitly granted.

-f

-f[awls]...[,option]... pathname
-f[awls]...[,option]...=pathname

Grant access to a file or directory (given by pathname), and optionally add pathname to the argument list. This takes the following single-letter options. The multi-character options must be separated by commas.

a: Add pathname to the argument list. Equivalent to adding the argument "-a pathname".
w: Grant read/write access to the slot specified by pathname. By default, without this option, read-only access is granted to the file or directory specified by pathname.
l: Follow symbolic links (the "l" is for "foLLow"). If symbolic links are encountered when pola-run resolves pathname, these links will be followed. When the symlink occurs at the last element in a pathname, this will cause pola-run to grant access to both the symlink object and the destination object (or the slots containing them, when the w option is used). If pathname resolves to a directory, this option does not affect the treatment of symlinks inside the directory.
s: Grant permission to create symbolic links. (Only relevant if w is used.)
objrw: Grant read/write access to the file or directory object, but not the slot, specified by pathname. This is useful for granting access to writable devices such as /dev/null.
socket: Grant permission to connect to Unix domain sockets (as the w option does), but without granting write access to file and directory objects.

-t

-t[awls]...[,option]... dest-pathname source-pathname

Grant access to a file or directory (source-pathname), but attach it to a different pathname in the file namespace(dest-pathname). Optionally add dest-pathname to the argument list. This takes the same options as -f.

Note that "-foptions pathname" is not exactly equivalent to "-toptions pathname pathname". -t will not introduce symlinks at the directory components of dest-pathname, and it will fail if there are any symlinks in these locations.

-a

-a string
-a=string

Add string to the argument list.

Setting the current directory

--cwd dir
--cwd=dir
--no-cwd
--copy-cwd

These options set the current working directory (cwd) for the process.

--copy-cwd will use the calling process's cwd. This is the default.

--no-cwd unsets the cwd, so that using a pathname relative to the cwd will give an error.

--cwd sets the cwd to a directory given by a pathname.

In any case, if the directory's pathname does not exist in the namespace created for the process, the cwd will be left unset.

These options also affect how the pathnames in other arguments are interpreted. You can use multiple cwd arguments. An argument pathname is resolved relative to the most recent one. The final cwd argument also sets the process's cwd.

-B

Grant access to a default installation endowment. This is equivalent to the options:

-fl /usr
-fl /bin
-fl /lib
-fl,objrw /dev/null
-fl,objrw /dev/tty

--x11

Grant access to the X11 Window System. This is currently equivalent to the options:

-fl,socket /tmp/.X11-unix/
-fl ~/.Xauthority

In the future, --x11 may work using an X11 proxy.

--net

This grants access to some files that are important for accessing the Internet. When Plash gains the ability to deny a process access to the network, this option will gain the function of passing network access on to the callee.

Currently, this is equivalent to:

-fl /etc/resolv.conf
-fl /etc/hosts
-fl /etc/services

--powerbox

Grants the callee program an object "powerbox_req_filename" which can be used to open a file powerbox. A file powerbox is a file chooser dialog box which can grant the callee program access to files. The powerbox will dynamically attach files or directories into the callee program's file namespace.

Currently, it only makes sense to use this when the caller runs with the user's namespace, since the file chooser will display directory contents for the caller's namespace. In the future, the --powerbox option will be able to pass on the caller's powerbox request object rather than always creating a new one.

--pet-name name

This provides a name to use in the title bar of powerbox windows, so that the user can identify which application is making the request.

Examples

In Bash:

gcc -c foo.c -o foo.o

In pola-shell:

gcc -c foo.c => -o foo.o + .

This would become:

pola-run -B --prog=gcc  -a=-c  -fa=foo.c  -a=-o  -faw=foo.o  -f=.

Run Bash with the same filesystem namespace as the caller. This is useful for testing Plash:

pola-run -fw=/ --prog /bin/bash

Environment variables

pola-run sets the following environment variables:

LD_LIBRARY_PATH
PLASH_CAPS
PLASH_COMM_FD
PLASH_FAKE_UID
PLASH_FAKE_EUID
PLASH_FAKE_GID
PLASH_FAKE_EGID

LD_PRELOAD: pola-run must treat this specially to ensure that it is preserved across the invocation of run-as-anonymous (the fact that this is a setuid executable usually causes LD_PRELOAD to be unset).

XAUTHORITY: pola-run looks at this when the --x11 option is used.