1		SECure COMPuting with filters
2		=============================
3
4Introduction
5------------
6
7A large number of system calls are exposed to every userland process
8with many of them going unused for the entire lifetime of the process.
9As system calls change and mature, bugs are found and eradicated.  A
10certain subset of userland applications benefit by having a reduced set
11of available system calls.  The resulting set reduces the total kernel
12surface exposed to the application.  System call filtering is meant for
13use with those applications.
14
15Seccomp filtering provides a means for a process to specify a filter for
16incoming system calls.  The filter is expressed as a Berkeley Packet
17Filter (BPF) program, as with socket filters, except that the data
18operated on is related to the system call being made: system call
19number and the system call arguments.  This allows for expressive
20filtering of system calls using a filter program language with a long
21history of being exposed to userland and a straightforward data set.
22
23Additionally, BPF makes it impossible for users of seccomp to fall prey
24to time-of-check-time-of-use (TOCTOU) attacks that are common in system
25call interposition frameworks.  BPF programs may not dereference
26pointers which constrains all filters to solely evaluating the system
27call arguments directly.
28
29What it isn't
30-------------
31
32System call filtering isn't a sandbox.  It provides a clearly defined
33mechanism for minimizing the exposed kernel surface.  It is meant to be
34a tool for sandbox developers to use.  Beyond that, policy for logical
35behavior and information flow should be managed with a combination of
36other system hardening techniques and, potentially, an LSM of your
37choosing.  Expressive, dynamic filters provide further options down this
38path (avoiding pathological sizes or selecting which of the multiplexed
39system calls in socketcall() is allowed, for instance) which could be
40construed, incorrectly, as a more complete sandboxing solution.
41
42Usage
43-----
44
45An additional seccomp mode is added and is enabled using the same
46prctl(2) call as the strict seccomp.  If the architecture has
47CONFIG_HAVE_ARCH_SECCOMP_FILTER, then filters may be added as below:
48
49PR_SET_SECCOMP:
50	Now takes an additional argument which specifies a new filter
51	using a BPF program.
52	The BPF program will be executed over struct seccomp_data
53	reflecting the system call number, arguments, and other
54	metadata.  The BPF program must then return one of the
55	acceptable values to inform the kernel which action should be
56	taken.
57
58	Usage:
59		prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, prog);
60
61	The 'prog' argument is a pointer to a struct sock_fprog which
62	will contain the filter program.  If the program is invalid, the
63	call will return -1 and set errno to EINVAL.
64
65	If fork/clone and execve are allowed by @prog, any child
66	processes will be constrained to the same filters and system
67	call ABI as the parent.
68
69	Prior to use, the task must call prctl(PR_SET_NO_NEW_PRIVS, 1) or
70	run with CAP_SYS_ADMIN privileges in its namespace.  If these are not
71	true, -EACCES will be returned.  This requirement ensures that filter
72	programs cannot be applied to child processes with greater privileges
73	than the task that installed them.
74
75	Additionally, if prctl(2) is allowed by the attached filter,
76	additional filters may be layered on which will increase evaluation
77	time, but allow for further decreasing the attack surface during
78	execution of a process.
79
80The above call returns 0 on success and non-zero on error.
81
82Return values
83-------------
84A seccomp filter may return any of the following values. If multiple
85filters exist, the return value for the evaluation of a given system
86call will always use the highest precedent value. (For example,
87SECCOMP_RET_KILL will always take precedence.)
88
89In precedence order, they are:
90
91SECCOMP_RET_KILL:
92	Results in the task exiting immediately without executing the
93	system call.  The exit status of the task (status & 0x7f) will
94	be SIGSYS, not SIGKILL.
95
96SECCOMP_RET_TRAP:
97	Results in the kernel sending a SIGSYS signal to the triggering
98	task without executing the system call.  siginfo->si_call_addr
99	will show the address of the system call instruction, and
100	siginfo->si_syscall and siginfo->si_arch will indicate which
101	syscall was attempted.  The program counter will be as though
102	the syscall happened (i.e. it will not point to the syscall
103	instruction).  The return value register will contain an arch-
104	dependent value -- if resuming execution, set it to something
105	sensible.  (The architecture dependency is because replacing
106	it with -ENOSYS could overwrite some useful information.)
107
108	The SECCOMP_RET_DATA portion of the return value will be passed
109	as si_errno.
110
111	SIGSYS triggered by seccomp will have a si_code of SYS_SECCOMP.
112
113SECCOMP_RET_ERRNO:
114	Results in the lower 16-bits of the return value being passed
115	to userland as the errno without executing the system call.
116
117SECCOMP_RET_TRACE:
118	When returned, this value will cause the kernel to attempt to
119	notify a ptrace()-based tracer prior to executing the system
120	call.  If there is no tracer present, -ENOSYS is returned to
121	userland and the system call is not executed.
122
123	A tracer will be notified if it requests PTRACE_O_TRACESECCOMP
124	using ptrace(PTRACE_SETOPTIONS).  The tracer will be notified
125	of a PTRACE_EVENT_SECCOMP and the SECCOMP_RET_DATA portion of
126	the BPF program return value will be available to the tracer
127	via PTRACE_GETEVENTMSG.
128
129	The tracer can skip the system call by changing the syscall number
130	to -1.  Alternatively, the tracer can change the system call
131	requested by changing the system call to a valid syscall number.  If
132	the tracer asks to skip the system call, then the system call will
133	appear to return the value that the tracer puts in the return value
134	register.
135
136	The seccomp check will not be run again after the tracer is
137	notified.  (This means that seccomp-based sandboxes MUST NOT
138	allow use of ptrace, even of other sandboxed processes, without
139	extreme care; ptracers can use this mechanism to escape.)
140
141SECCOMP_RET_ALLOW:
142	Results in the system call being executed.
143
144If multiple filters exist, the return value for the evaluation of a
145given system call will always use the highest precedent value.
146
147Precedence is only determined using the SECCOMP_RET_ACTION mask.  When
148multiple filters return values of the same precedence, only the
149SECCOMP_RET_DATA from the most recently installed filter will be
150returned.
151
152Pitfalls
153--------
154
155The biggest pitfall to avoid during use is filtering on system call
156number without checking the architecture value.  Why?  On any
157architecture that supports multiple system call invocation conventions,
158the system call numbers may vary based on the specific invocation.  If
159the numbers in the different calling conventions overlap, then checks in
160the filters may be abused.  Always check the arch value!
161
162Example
163-------
164
165The samples/seccomp/ directory contains both an x86-specific example
166and a more generic example of a higher level macro interface for BPF
167program generation.
168
169
170
171Adding architecture support
172-----------------------
173
174See arch/Kconfig for the authoritative requirements.  In general, if an
175architecture supports both ptrace_event and seccomp, it will be able to
176support seccomp filter with minor fixup: SIGSYS support and seccomp return
177value checking.  Then it must just add CONFIG_HAVE_ARCH_SECCOMP_FILTER
178to its arch-specific Kconfig.
179
180
181
182Caveats
183-------
184
185The vDSO can cause some system calls to run entirely in userspace,
186leading to surprises when you run programs on different machines that
187fall back to real syscalls.  To minimize these surprises on x86, make
188sure you test with
189/sys/devices/system/clocksource/clocksource0/current_clocksource set to
190something like acpi_pm.
191
192On x86-64, vsyscall emulation is enabled by default.  (vsyscalls are
193legacy variants on vDSO calls.)  Currently, emulated vsyscalls will honor seccomp, with a few oddities:
194
195- A return value of SECCOMP_RET_TRAP will set a si_call_addr pointing to
196  the vsyscall entry for the given call and not the address after the
197  'syscall' instruction.  Any code which wants to restart the call
198  should be aware that (a) a ret instruction has been emulated and (b)
199  trying to resume the syscall will again trigger the standard vsyscall
200  emulation security checks, making resuming the syscall mostly
201  pointless.
202
203- A return value of SECCOMP_RET_TRACE will signal the tracer as usual,
204  but the syscall may not be changed to another system call using the
205  orig_rax register. It may only be changed to -1 order to skip the
206  currently emulated call. Any other change MAY terminate the process.
207  The rip value seen by the tracer will be the syscall entry address;
208  this is different from normal behavior.  The tracer MUST NOT modify
209  rip or rsp.  (Do not rely on other changes terminating the process.
210  They might work.  For example, on some kernels, choosing a syscall
211  that only exists in future kernels will be correctly emulated (by
212  returning -ENOSYS).
213
214To detect this quirky behavior, check for addr & ~0x0C00 ==
2150xFFFFFFFFFF600000.  (For SECCOMP_RET_TRACE, use rip.  For
216SECCOMP_RET_TRAP, use siginfo->si_call_addr.)  Do not check any other
217condition: future kernels may improve vsyscall emulation and current
218kernels in vsyscall=native mode will behave differently, but the
219instructions at 0xF...F600{0,4,8,C}00 will not be system calls in these
220cases.
221
222Note that modern systems are unlikely to use vsyscalls at all -- they
223are a legacy feature and they are considerably slower than standard
224syscalls.  New code will use the vDSO, and vDSO-issued system calls
225are indistinguishable from normal system calls.
226