committed 0.3.5-1 (rc8) source

README

@@ -23,98 +23,82 @@ FEATURES
      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)
+  Note, there is no need to install 32bit package(s) on x86_64 systems. The 
+  64bit libsandbox can handle both 32bit and 64bit binary programs.
+
+  binary package (CentOS/RedHat)
 
   $ yum install --nogpgcheck libsandbox-<version>.<platform>.rpm
-  $ yum install --nogpgcheck pysandbox-<version>.<platform>.rpm
 
-  binary packages (Ubuntu)
+  binary package (Ubuntu)
 
   $ dpkg -i libsandbox_<version>_<platform>.deb
-  $ dpkg -i pysandbox_<version>_<platform>.deb
 
-  source packages
+  source package
 
   $ 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,
-     Ubuntu 11.4) and linux-3.0 (Ubuntu 11.10) 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, it can pass 
-     configuration and (or) compilation;
-  2. As of v0.3.3, libsandbox only supports single process ELF programs. If the
+     Ubuntu 11.4) and linux-3.0 (Ubuntu 11.10, Ubuntu 12.10) 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 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 should be *sandboxed* by  
+  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.3, libsandbox internally uses ptrace() to intercept and probe 
+  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) 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 (i.e. Java VM uses 
-     SIGPROF and optionally SIGUSR1 and SIGUSR2), 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 relevant 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. When the process, or thread, running libsandbox v0.3.x (i.e. which is the
-     parent process of the *sandboxed* program) receives any one of SIGTERM, 
-     SIGINT, and SIGQUIT signals, it sends the same signal to the *sandboxed* 
-     program. But the former 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;
-  7. When the process, or thread, running libsandbox v0.3.x receives unexpected 
-     signals (i.e. not any of SIGALRM, SIGPROF, SIGTERM, SIGINT, or SIGQUIT) that
-     are blockable (i.e. other than SIGKILL and SIGSTOP), it terminates the 
-     *sandboxed* program with SIGKILL. And since this is not the fault of the 
-     *sandboxed* program, the result will be set to S_RESULT_IE;
-  8. libsandbox (v0.3.x) includes some optional features that can be enabled
+     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 persistent storage. 
+     Write operations to i) standard output buffer (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 go beyond 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;
-  9. On some linux-2.6-x86_64 systems, to correctly inspect the system call mode
+ 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;

libsandbox/CHANGES

@@ -1,3 +1,9 @@
+[2012/10/08] LIU Yu, <pineapple.liu@gmail.com>
+  * in platform.h fixed x86_64 syscall abi (4th argument)
+
+[2012/10/05] LIU Yu, <pineapple.liu@gmail.com>
+  * in Makefile.in reordered linker arguments to resolve a gcc linking error
+
 [2012/08/31] LIU Yu, <pineapple.liu@gmail.com>
   * revoked the use of real-time signals, RT_SIGTERM (SIGRTMIN + 1) -> SIGEXIT
     (SIGUSR1), RT_SIGSTAT (SIGRTMIN + 2) -> SIGSTAT (SIGUSR2), RT_SIGPROF ->

libsandbox/Makefile.in

@@ -74,7 +74,7 @@ lib$(LIBRARY).so : lib$(LIBRARY).so.$(VERSION)
 	$(LN) lib$(LIBRARY).so.$(VERSION) lib$(LIBRARY).so
 
 lib$(LIBRARY).so.$(VERSION) : $($(LIBRARY)_obj)
-	$(CC) $(CFLAGS) $(LDFLAGS) $(LIBS) -o $(@) $($(LIBRARY)_obj)
+	$(CC) $(CFLAGS) $(LDFLAGS) -o $(@) $($(LIBRARY)_obj) $(LIBS)
 
 lib$(LIBRARY).a: $($(LIBRARY)_obj)
 	$(AR) $(@) $($(LIBRARY)_obj)

libsandbox/src/platform.h

@@ -255,7 +255,7 @@ int proc_syscall_mode(proc_t * const);
 /* SYSCALL_ARG3 */
 #define SYSCALL_ARG4(pproc) \
     RVAL_IF(THE_SCMODE(pproc) == SCMODE_LINUX64) \
-        ((pproc)->regs.rcx) \
+        ((pproc)->regs.r10) \
     RVAL_ELSE \
         MAKE_WORD((pproc)->regs.rsi, 0) \
     RVAL_FI \

pysandbox/setup.py

@@ -65,7 +65,7 @@
     core_ccflags = check_output(pkgconfig + ['--cflags', ]).decode().split()
     core_ldflags = check_output(pkgconfig + ['--libs', ]).decode().split()
 except:
-    core_ccflags = []
+    core_ccflags = ['-pthread', ]
     core_ldflags = ['-lsandbox', '-lrt']
 
 _sandbox = Extension('_sandbox',

sample2.py

@@ -101,7 +101,7 @@ def probe(self):
     def __call__(self, e, a):
         # handle SYSCALL/SYSRET events with local rules
         if e.type in (S_EVENT_SYSCALL, S_EVENT_SYSRET):
-            if machine is 'x86_64' and e.ext0 is not 0:
+            if machine == 'x86_64' and e.ext0 != 0:
                 return self._KILL_RF(e, a)
             return self.sc_table[e.data](e, a)
         # bypass other events to base class