INTRODUCTION The sandbox libraries (libsandbox & pysandbox) provide API's in C/C++ and Python for executing and profiling simple (single process) programs in a restricted environment, or sandbox. These API's can help developers to build automated profiling tools and watchdogs that capture and block the runtime behaviours of binary executable programs according to configurable / programmable policies. The sandbox libraries are distributed under the terms of the New BSD license, please refer to the plain text file named COPYING in individual packages. Project Homepage: http://openjudge.net/~liuyu/Project/LibSandbox Author: LIU Yu, <pineapple.liu@gmail.com> FEATURES 1. capture system calls with arguments from *sandboxed* binary programs in runtime, and block malicious actions through user-defined policy modules; 2. specify quota limit of resources allocated to the *sandboxed* program, including cpu and wallclock time, memory, and disk output; 3. minimize privileges of the *sandboxed* program, and isolate its execution from critical parts of the operating system; INSTALLATION Note, there is no need to install 32bit packages on x86_64 systems. The 64bit libsandbox and pysandbox can handle both 32bit and 64bit binary programs. binary packages (CentOS/RedHat) $ yum install --nogpgcheck libsandbox-<version>.<platform>.rpm $ yum install --nogpgcheck pysandbox-<version>.<platform>.rpm binary packages (Ubuntu) $ dpkg -i libsandbox_<version>_<platform>.deb $ dpkg -i pysandbox_<version>_<platform>.deb source packages $ tar -xzf libsandbox-<version>.tar.gz $ cd libsandbox-<version> $ ./configure $ sudo make install $ tar -xzvf pysandbox-<version>.tar.gz $ cd pysandbox-<version> $ python setup.py build $ sudo python setup.py install GETTING STARTED The simplest way to get started with the sandbox libraries is to invoke the Pythonic wrapper (aka. pysandbox) through the interactive Python interpreter. $ python >>> from sandbox import * >>> s = Sandbox(['/foo/bar.exe', 'arg1', 'arg2']) >>> s.run() ... >>> s.probe() ... For a more elaborate example, refer to the sample Python script sample2.py. It demonstrates essential functionalities of pysandbox including I/O redirection, resource quota limitation, and white-list system call interception. $ python sample2.py SPECIAL NOTICES 1. libsandbox is designed for, and has been tested on, Linux 2.6 (CentOS 6.2 -6.4), 3.0 (Ubuntu 11.10), and 3.2 (Ubuntu 12.04 LTS) systems on i686 and x86_64 architectures (x86_64 supported since v0.3.x). The behaviours of libsandbox on other platforms are undefined, even if -- though unlikely -- they can pass configuration and (or) compilation; 2. As of v0.3.5, libsandbox only supports single process ELF programs. If the user-provided policy module bypasses system calls that spawn new processes (i.e. returning S_ACTION_CONT upon seeing SYS_fork, SYS_vfork, SYS_clone) the subsequent behaviours of libsandbox are undefined; 3. On x86_64 systems, both 32bit and 64bit programs MUST be *sandboxed* by 64bit libsandbox. In particular, NEVER run any program (not even native 32bit programs) with 32bit libsandbox on 64bit systems. Otherwise, there is suspected risk that a malicious 32bit program can bypass some system call restrictions through mapping in 64bit system call table; 4. As of v0.3.5, libsandbox internally uses ptrace() to intercept and probe system calls invoked by the *sandboxed* program. If the *sandboxed* program itself invokes ptrace(), and that the user-provided policy module bypasses relevant events (i.e. returning S_ACTION_CONT upon seeing SYS_ptrace), the subsequent behaviours of libsandbox are undefined; 5. libsandbox interprets some signals sent to the *sandboxed* program as out- of-quota (wallclock, cpu, memory, disk) events (for v0.2.x the affiliated signals are SIGXCPU, SIGXFZ, SIGPROF, SIGALRM, SIGVTALRM, and SIGUSR1; for v0.3.x the only affiliated signal is SIGXFSZ). If the *sandboxed* program depends on these signals to perform internal functionalities, the user- provided policy module of libsandbox may cause the *sandboxed* program to terminate upon seeing relevant events. Moreover, if user-provided policies bypass system call events that block such signals (i.e. returning S_ACTION _CONT without checking parameters of SYS_sigsetmask, SYS_pthread_sigmask, etc.), libsandbox could fail to detect relevant out-of-quota events; 6. By default, the disk output quota only applies to eligible file systems. Write operations to i) standard output streams (i.e. stdout / stderr), ii) null devices (i.e. /dev/null), or iii) pipelined to another process do NOT count against the disk output quota. This default behaviour, however, could be overridden by user-specified policy modules; 7. Since v0.3.5, libsandbox dedicates a manager thread to handle termination signals including SIGTERM, SIGINT, and SIGQUIT. When the manager thread receives any of these signals, it sends the same signal to the *sandboxed* program. But the supervisor process, or thread, running libsandbox may continue to execute if i) the *sandboxed* program is still running after receiving the signal, and ii) the user-specified policy module explicitly requires libsandbox to continue; 8. If the supervisor process, or thread, running libsandbox (i.e. which is the parent process of the *sandboxed* program) terminates upon receiving termination signals other than SIGTERM, SIGINT, and SIGQUIT, or if custom signal handlers are registered such that they prevent the manager thread of libsandbox from receiving the three termination signals, then there is suspected risk that the *sandboxed* program may escape the control of libsandbox. In such cases, some of the restrictions placed by libsandbox, including quota limit and policy-based behaviour auditing, may become invalid. However, OS-level security mechanisms, including chroot() jail and setuid() privileges, are still in effect; 9. libsandbox (v0.3.x) includes some optional features that can be enabled during configuration. Please note that --enable-tsc and --enable-rtsched are highly experimental, and are not recommended for production systems; 10. On some linux-2.6-x86_64 systems, to correctly inspect the system call mode of some 32bit programs, it could be mandatory to build libsandbox (0.3.x) with --enable-chkvsc option (since 0.3.3-rc4). The binary packages for x86_64 systems enabled this option by default; 11. On some Linux systems, the default installation directory of libsandbox (aka. /usr/local/lib) is not a trusted directory for the runtime linker (aka. ld.so). It could be mandatory to build libsandbox (0.3.x) with --prefix and (or) --libdir options to override the default settings; The binary packages are built with --prefix=/usr by default; CONTACT Project Homepage: http://openjudge.net/~liuyu/Project/LibSandbox Project Page at SourceForge.net: http://sourceforge.net/projects/libsandbox/ Project Page at Python Package Index: http://pypi.python.org/pypi/sandbox Project Code Repository at GitHub: http://github.com/openjudge/sandbox Project Mail List at Google Groups: http://groups.google.com/group/open-judge Author: LIU Yu, <pineapple.liu@gmail.com>
churehill/sandbox
The sandbox libraries (libsandbox & pysandbox) are an open-source suite of software components for C/C++ and Python developers to create automated profiling tools and watchdog programs. The API's are designed for executing and instrumenting simple (single process) tasks, featuring policy-based behavioral auditing, resource quota, and statistics collecting.
C