README

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>