Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Isolate - utility for isolating Unix processes, minimizing their priv…
…ileges
  • Loading branch information
auser committed Jan 5, 2010
0 parents commit 5776cf0
Show file tree
Hide file tree
Showing 10 changed files with 1,906 additions and 0 deletions.
339 changes: 339 additions & 0 deletions COPYING.txt

Large diffs are not rendered by default.

34 changes: 34 additions & 0 deletions Makefile
@@ -0,0 +1,34 @@
CFLAGS += -Wall -Wextra -Os
LDFLAGS += -lelf

SOURCES = isolate.cpp configuration.sh privilege.h privilege.cpp help.h

default: isolate

configuration.h:
sh configuration.sh > configuration.h

isolate: $(SOURCES) configuration.h
c++ $(CFLAGS) $(LDFLAGS) -o isolate isolate.cpp privilege.cpp
chmod u+s isolate

clean: cleandoc
-rm *.o isolate err configuration.h

doc: isolate.tex isolate.bib
pdflatex isolate.tex > err 2>&1
bibtex isolate >> err 2>&1
pdflatex isolate.tex >> err 2>&1
pdflatex isolate.tex >> err 2>&1
evince isolate.pdf &

cleandoc:
-rm err *.log *.aux *.out *.pdf *.bbl *.blg *.brf *.ilf *.ind *.ilg

all: cleandoc clean isolate doc

install: isolate
install -S -o 0 -g 0 -m a=rx,u+s -s isolate /usr/local/bin/isolate
install -S -o 0 -g 0 -m 0644 isolate.1 /usr/local/man/man1/isolate.1
gzip -9 /usr/local/man/man1/isolate.1

4 changes: 4 additions & 0 deletions configuration.h
@@ -0,0 +1,4 @@

Unfortunately, isolate has not yet been ported to Darwin.
Please email Chris Palmer <chris@isecpartners.com> to help!

64 changes: 64 additions & 0 deletions configuration.sh
@@ -0,0 +1,64 @@
#!/bin/sh

# $Id: configuration.sh 10 2009-03-10 04:47:06Z snackypants $

upper()
{
echo "$1" | tr a-z A-Z
}


## MAIN

uname=$(uname)

if [ "FreeBSD" = $uname ]
then
echo "
const string LD_ELF_SO_PATH = \"/libexec/ld-elf.so.1\";
const string MDMFS = \"/sbin/mdmfs\";
"
elif [ "Linux" = $uname ]
then
echo "
const string DEV_RANDOM = \"/dev/urandom\";
const string LD_ELF_SO_PATH = \"/lib/ld-linux.so.2\";
"
else
echo "
Unfortunately, isolate has not yet been ported to $uname.
Please email Chris Palmer <chris@isecpartners.com> to help!
"
exit 1
fi

has_glibc=$(echo "#include <stdio.h>" | g++ -E -dM - | grep __GLIBC__ | wc -l)
if [ "$:{has_glibc}" != ":0" -a "Linux" = $uname ]
then
echo "/* GNU libc present */"
echo "
#define has_glibc 1
const string NSS_COMPAT=\"/lib/libnss_compat.so.2\";
const string NSS_DNS=\"/lib/libnss_dns.so.2\";
const string NSS_FILES=\"/lib/libnss_files.so.2\";
const string LIBRESOLV = \"/lib/libresolv.so.2\";
const string NSSWITCH_CONF = \"/etc/nsswitch.conf\";
"
fi

echo "
const static bool DEBUG = true;
const string CONFINEMENT_ROOT = \"/var/isolation\";
const mode_t CONFINEMENT_ROOT_MODE = 040755;
const string DEFAULT_PATH = \"/bin:/usr/bin:/usr/local/bin\";
const string RESOLV_CONF = \"/etc/resolv.conf\";
const string TERMCAP = \"/usr/share/misc/termcap.db\";
const rlim_t DEFAULT_MEMORY_LIMIT = 0x2000000;
"

for p in chown cp mount rm rmdir umount xauth
do
echo "const string $(upper $p) = \"$(which $p)\";"
done

10 changes: 10 additions & 0 deletions help.h
@@ -0,0 +1,10 @@
/**
* $Id: help.h 12 2010-01-05 11:19:02Z ioerror $
*/

const string HELP_MESSAGE =
"Usage: isolate [-hTvMS] [-D path] [-a bytes] [-c bytes] [-d bytes] [-f files]\n"
" [-m bytes] [-n bytes] [-p processes] [-r bytes] [-s bytes]\n"
" [-t seconds] [-z bytes] program [program-arguments...]\n"
;

172 changes: 172 additions & 0 deletions isolate.1
@@ -0,0 +1,172 @@
.\" $ Id: $
.Dd February 1, 2009
.Dt ISOLATE 1
.Os
.Sh NAME
.Nm isolate
.Nd isolate untrustworthy processes
.Sh SYNOPSIS
.Nm
.Op Fl hTvS
.Op Fl M Ar megabytes
.Op Fl D Ar path
.Op Fl a Ar bytes
.Op Fl c Ar bytes
.Op Fl d Ar bytes
.Op Fl f Ar files
.Op Fl m Ar bytes
.Op Fl n Ar bytes
.Op Fl p Ar processes
.Op Fl r Ar bytes
.Op Fl s Ar bytes
.Op Fl t Ar seconds
.Op Fl z Ar bytes
.Ar program
.Op Ar program arguments...
.Sh DESCRIPTION
.Nm
isolates
.Ar program
(the
.Em isolatee Ns )
by running it with a randomly selected unprivileged UID
(the
.Em isolator Ns ),
with constrained resource limits, and chrooted. The purpose of
.Nm
is to protect your machine and your data from untrustworthy isolatees and
their untrustworthy input.
.Pp
.Nm
automatically discovers the library dependencies of
.Ar program
and copies them into the chroot environment. On FreeBSD,
.Nm
uses devfs to provide the isolatee with device nodes.
.Pp
If the isolatee links against libX11.so,
.Nm
generates an
.Em untrusted
X11 authentication token for the isolatee, to protect
.Em trusted
windows from the isolatee. For example, isolatees will not be able to log
keystrokes intended for trusted windows, and will not be able to take
screenshots of trusted windows.
.Pp
Basic options:
.Bl -tag -width indent
.It Fl D Ar path
The path to a directory or file to be copied into the isolation environment,
in case the isolatee needs additional support files.
.It Fl h
Print the help message.
.It Fl M Ar megabytes
Make the isolation environment a memory filesystem (see mdmfs(8)) instead of
a normal on-disk directory. Incompatible with -S. The argument to -M is the
size in MB of the filesystem. This option greatly improves isolate's startup
and shutdown times.
.It Fl S
Save the isolation environment after the program exits. (By default the
environment is destroyed.) Ownership of the environment will be given to the
invoker. Incompatible with -M.
.It Fl v
Print verbose messages.
.El
.Pp
Resource limit options:
.Pp
.Bl -tag -width indent
.It Fl a Ar bytes
The maximum amount of virtual memory the process is allowed to map.
(RLIMIT_AS)
.It Fl c Ar bytes
The largest size of core file the process can create. (RLIMIT_CORE)
.It Fl d Ar bytes
The maximum size of the process' data segment. (RLIMIT_DATA)
.It Fl f Ar files
The maximum number of files to allow the process to open. (RLIMIT_NOFILE)
.It Fl m Ar bytes
The maximum amount of memory a process may lock into memory. (RLIMIT_MEMLOCK)
.It Fl n Ar bytes
The maximum amount of network socket buffer memory for the isolator.
(RLIMIT_SBSIZE) Not available on Linux.
.It Fl p Ar processes
The maximum number of simultaneous processes for this user ID. (RLIMIT_NPROC)
.It Fl r Ar bytes
The maximum size of the process' resident set size. (RLIMIT_RSS)
.It Fl s Ar bytes
The maximum size of the process' stack. (RLIMIT_STACK)
.It Fl t Ar seconds
The maximum amount of CPU time the process will be allotted. (RLIMIT_CPU)
.It Fl T Ar trusted
Flip this bird if you'd like to set a trusted X11 cookie.
.It Fl z Ar bytes
The largest file the process can create. (RLIMIT_FSIZE)
.El
.Pp
Numeric values for arguments can be given in decimal, hexadecimal, or octal
notation. For more information on the exact meaning of each limit, see the
setrlimit(2) manual page. The default values will usually be safe yet allow
the program to run normally; you should only need to supply a non-default
value in special cases. Use -v to show the values of the limits.
.Pp
Note that the effective default value is the default value given or the
invoking user's current limit, whichever is lower.
.Sh SECURITY
.Nm
must be setuid root in order to operate correctly. All due caution has been
taken in its implementation, but there may still be bugs. Please report any
problems to the author.
.Pp
Note that
.Nm
does not necessarily protect the isolatee from its environment; its goal is
to protect the environment from the isolatee.
.Sh EXAMPLES
To isolate the shell, you will need to provide some useful programs and their
libraries, and you will need to allow the isolatee to open some files and
fork some processes:
.Pp
.Dl isolate -D /bin -D /lib -p 3 -f 10 sh
.Pp
However, note that many Linux distributions put tons of stuff in /bin and/or
/lib, so this example might not be practical for you.
.Pp
Many programs need extra virtual memory, and may fail silently or weirdly if
they don't get it. To pass a file to the isolatee as an argument, you will
need to tell
.Nm
to copy it into the isolation environment:
.Pp
.Dl isolate -a 0x4000000 -D foo.txt vim foo.txt
.Pp
You can also isolate multiple programs in a pipeline. In this example,
multiple isolatees, separately isolated, can communicate via standard in and
standard out:
.Pp
.Dl cat input.png | isolate pngtopnm | isolate pnmtojpeg > output.jpg
.Pp
.Sh SEE ALSO
.Xr setrlimit(2) ,
.Xr chroot(2) ,
.Xr setresuid(2) ,
.Xr xauth(1) ,
.Xr mdmfs(8) ,
.Xr devfs(5) ,
.Xr devfs(8) ,
.Xr devfs.conf(5) ,
.Xr devfs.rules(5)
.Sh COMPATIBILITY
.Nm
was written on FreeBSD and later ported to Linux. The Linux port is not yet
feature complete (missing memory filesystem and device filesystem support).
These are bugs and will be fixed. The two platforms support some different
resource limits, and the Linux-specific limits are not yet supported.
.Sh HISTORY
.Nm
was written by Chris Palmer <chris@isecpartners.com> for FreeBSD and Linux.
Sebastian Ng helped on an earlier version.
.Sh BUGS AND MISSING FEATURES
Numerous. Please report problems to the author!

0 comments on commit 5776cf0

Please sign in to comment.