forked from openjudge/sandbox
/
README
144 lines (121 loc) · 7.48 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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>