Plash: tools for practical least privilege
pola-run: A command line tool for launching sandboxed programs
-f[awls]... pathname |
-t[awls]... pathname pathname |
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
-a option adds strings to the argument list,
in order. The
-t options add files and
directories to the file namespace. These can be combined:
-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.
-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.)
pola-run can be used to invoke executable objects, in which case the callee can have access to objects that the caller doesn't have access to.
NB. The implementation is incomplete. Some things mentioned here aren't implemented yet.
For arguments that take one parameter, there are two forms to choose
". The first form may be more
convenient to generate in a C program. The latter may be more
readable in hand-written shell scripts.
This gives the filename of the executable to be invoked. If it
doesn't contain a slash, it will be looked up in
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
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.
Add pathname to the argument list. Equivalent to
adding the argument "
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.
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.
Grant permission to create symbolic links. (Only
w is used.)
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.
Grant permission to connect to Unix domain sockets (as
w option does), but without granting write
access to file and directory objects.
-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
Note that "
-foptions pathname" is not
exactly equivalent to "
-t will not introduce symlinks at the
directory components of dest-pathname, and it will fail if there
are any symlinks in these locations.
Add string to the argument list.
These options set the current working directory (cwd) for the process.
--copy-cwd will use the calling process's cwd. This is the
--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.
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
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.
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
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.
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.
gcc -c foo.c -o foo.o
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
pola-run sets the following environment variables:
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
XAUTHORITY: pola-run looks at this when the --x11 option is