projects/linux·blob master · refs

376 lines · 16.2 KiB

1===========================================
2Seccomp BPF (SECure COMPuting with filters)
3===========================================
4
5Introduction
6============
7
8A large number of system calls are exposed to every userland process
9with many of them going unused for the entire lifetime of the process.
10As system calls change and mature, bugs are found and eradicated. A
11certain subset of userland applications benefit by having a reduced set
12of available system calls. The resulting set reduces the total kernel
13surface exposed to the application. System call filtering is meant for
14use with those applications.
15
16Seccomp filtering provides a means for a process to specify a filter for
17incoming system calls. The filter is expressed as a Berkeley Packet
18Filter (BPF) program, as with socket filters, except that the data
19operated on is related to the system call being made: system call
20number and the system call arguments. This allows for expressive
21filtering of system calls using a filter program language with a long
22history of being exposed to userland and a straightforward data set.
23
24Additionally, BPF makes it impossible for users of seccomp to fall prey
25to time-of-check-time-of-use (TOCTOU) attacks that are common in system
26call interposition frameworks. BPF programs may not dereference
27pointers which constrains all filters to solely evaluating the system
28call arguments directly.
29
30What it isn't
31=============
32
33System call filtering isn't a sandbox. It provides a clearly defined
34mechanism for minimizing the exposed kernel surface. It is meant to be
35a tool for sandbox developers to use. Beyond that, policy for logical
36behavior and information flow should be managed with a combination of
37other system hardening techniques and, potentially, an LSM of your
38choosing. Expressive, dynamic filters provide further options down this
39path (avoiding pathological sizes or selecting which of the multiplexed
40system calls in socketcall() is allowed, for instance) which could be
41construed, incorrectly, as a more complete sandboxing solution.
42
43Usage
44=====
45
46An additional seccomp mode is added and is enabled using the same
47prctl(2) call as the strict seccomp. If the architecture has
48``CONFIG_HAVE_ARCH_SECCOMP_FILTER``, then filters may be added as below:
49
50``PR_SET_SECCOMP``:
51 Now takes an additional argument which specifies a new filter
52 using a BPF program.
53 The BPF program will be executed over struct seccomp_data
54 reflecting the system call number, arguments, and other
55 metadata. The BPF program must then return one of the
56 acceptable values to inform the kernel which action should be
57 taken.
58
59 Usage::
60
61 prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, prog);
62
63 The 'prog' argument is a pointer to a struct sock_fprog which
64 will contain the filter program. If the program is invalid, the
65 call will return -1 and set errno to ``EINVAL``.
66
67 If ``fork``/``clone`` and ``execve`` are allowed by @prog, any child
68 processes will be constrained to the same filters and system
69 call ABI as the parent.
70
71 Prior to use, the task must call ``prctl(PR_SET_NO_NEW_PRIVS, 1)`` or
72 run with ``CAP_SYS_ADMIN`` privileges in its namespace. If these are not
73 true, ``-EACCES`` will be returned. This requirement ensures that filter
74 programs cannot be applied to child processes with greater privileges
75 than the task that installed them.
76
77 Additionally, if ``prctl(2)`` is allowed by the attached filter,
78 additional filters may be layered on which will increase evaluation
79 time, but allow for further decreasing the attack surface during
80 execution of a process.
81
82The above call returns 0 on success and non-zero on error.
83
84Return values
85=============
86
87A seccomp filter may return any of the following values. If multiple
88filters exist, the return value for the evaluation of a given system
89call will always use the highest precedent value. (For example,
90``SECCOMP_RET_KILL_PROCESS`` will always take precedence.)
91
92In precedence order, they are:
93
94``SECCOMP_RET_KILL_PROCESS``:
95 Results in the entire process exiting immediately without executing
96 the system call. The exit status of the task (``status & 0x7f``)
97 will be ``SIGSYS``, not ``SIGKILL``.
98
99``SECCOMP_RET_KILL_THREAD``:
100 Results in the task exiting immediately without executing the
101 system call. The exit status of the task (``status & 0x7f``) will
102 be ``SIGSYS``, not ``SIGKILL``.
103
104``SECCOMP_RET_TRAP``:
105 Results in the kernel sending a ``SIGSYS`` signal to the triggering
106 task without executing the system call. ``siginfo->si_call_addr``
107 will show the address of the system call instruction, and
108 ``siginfo->si_syscall`` and ``siginfo->si_arch`` will indicate which
109 syscall was attempted. The program counter will be as though
110 the syscall happened (i.e. it will not point to the syscall
111 instruction). The return value register will contain an arch-
112 dependent value -- if resuming execution, set it to something
113 sensible. (The architecture dependency is because replacing
114 it with ``-ENOSYS`` could overwrite some useful information.)
115
116 The ``SECCOMP_RET_DATA`` portion of the return value will be passed
117 as ``si_errno``.
118
119 ``SIGSYS`` triggered by seccomp will have a si_code of ``SYS_SECCOMP``.
120
121``SECCOMP_RET_ERRNO``:
122 Results in the lower 16-bits of the return value being passed
123 to userland as the errno without executing the system call.
124
125``SECCOMP_RET_USER_NOTIF``:
126 Results in a ``struct seccomp_notif`` message sent on the userspace
127 notification fd, if it is attached, or ``-ENOSYS`` if it is not. See
128 below on discussion of how to handle user notifications.
129
130``SECCOMP_RET_TRACE``:
131 When returned, this value will cause the kernel to attempt to
132 notify a ``ptrace()``-based tracer prior to executing the system
133 call. If there is no tracer present, ``-ENOSYS`` is returned to
134 userland and the system call is not executed.
135
136 A tracer will be notified if it requests ``PTRACE_O_TRACESECCOMP``
137 using ``ptrace(PTRACE_SETOPTIONS)``. The tracer will be notified
138 of a ``PTRACE_EVENT_SECCOMP`` and the ``SECCOMP_RET_DATA`` portion of
139 the BPF program return value will be available to the tracer
140 via ``PTRACE_GETEVENTMSG``.
141
142 The tracer can skip the system call by changing the syscall number
143 to -1. Alternatively, the tracer can change the system call
144 requested by changing the system call to a valid syscall number. If
145 the tracer asks to skip the system call, then the system call will
146 appear to return the value that the tracer puts in the return value
147 register.
148
149 The seccomp check will not be run again after the tracer is
150 notified. (This means that seccomp-based sandboxes MUST NOT
151 allow use of ptrace, even of other sandboxed processes, without
152 extreme care; ptracers can use this mechanism to escape.)
153
154``SECCOMP_RET_LOG``:
155 Results in the system call being executed after it is logged. This
156 should be used by application developers to learn which syscalls their
157 application needs without having to iterate through multiple test and
158 development cycles to build the list.
159
160 This action will only be logged if "log" is present in the
161 actions_logged sysctl string.
162
163``SECCOMP_RET_ALLOW``:
164 Results in the system call being executed.
165
166If multiple filters exist, the return value for the evaluation of a
167given system call will always use the highest precedent value.
168
169Precedence is only determined using the ``SECCOMP_RET_ACTION`` mask. When
170multiple filters return values of the same precedence, only the
171``SECCOMP_RET_DATA`` from the most recently installed filter will be
172returned.
173
174Pitfalls
175========
176
177The biggest pitfall to avoid during use is filtering on system call
178number without checking the architecture value. Why? On any
179architecture that supports multiple system call invocation conventions,
180the system call numbers may vary based on the specific invocation. If
181the numbers in the different calling conventions overlap, then checks in
182the filters may be abused. Always check the arch value!
183
184Example
185=======
186
187The ``samples/seccomp/`` directory contains both an x86-specific example
188and a more generic example of a higher level macro interface for BPF
189program generation.
190
191Userspace Notification
192======================
193
194The ``SECCOMP_RET_USER_NOTIF`` return code lets seccomp filters pass a
195particular syscall to userspace to be handled. This may be useful for
196applications like container managers, which wish to intercept particular
197syscalls (``mount()``, ``finit_module()``, etc.) and change their behavior.
198
199To acquire a notification FD, use the ``SECCOMP_FILTER_FLAG_NEW_LISTENER``
200argument to the ``seccomp()`` syscall:
201
202.. code-block:: c
203
204 fd = seccomp(SECCOMP_SET_MODE_FILTER, SECCOMP_FILTER_FLAG_NEW_LISTENER, &prog);
205
206which (on success) will return a listener fd for the filter, which can then be
207passed around via ``SCM_RIGHTS`` or similar. Note that filter fds correspond to
208a particular filter, and not a particular task. So if this task then forks,
209notifications from both tasks will appear on the same filter fd. Reads and
210writes to/from a filter fd are also synchronized, so a filter fd can safely
211have many readers.
212
213The interface for a seccomp notification fd consists of two structures:
214
215.. code-block:: c
216
217 struct seccomp_notif_sizes {
218 __u16 seccomp_notif;
219 __u16 seccomp_notif_resp;
220 __u16 seccomp_data;
221 };
222
223 struct seccomp_notif {
224 __u64 id;
225 __u32 pid;
226 __u32 flags;
227 struct seccomp_data data;
228 };
229
230 struct seccomp_notif_resp {
231 __u64 id;
232 __s64 val;
233 __s32 error;
234 __u32 flags;
235 };
236
237The ``struct seccomp_notif_sizes`` structure can be used to determine the size
238of the various structures used in seccomp notifications. The size of ``struct
239seccomp_data`` may change in the future, so code should use:
240
241.. code-block:: c
242
243 struct seccomp_notif_sizes sizes;
244 seccomp(SECCOMP_GET_NOTIF_SIZES, 0, &sizes);
245
246to determine the size of the various structures to allocate. See
247samples/seccomp/user-trap.c for an example.
248
249Users can read via ``ioctl(SECCOMP_IOCTL_NOTIF_RECV)`` (or ``poll()``) on a
250seccomp notification fd to receive a ``struct seccomp_notif``, which contains
251five members: the input length of the structure, a unique-per-filter ``id``,
252the ``pid`` of the task which triggered this request (which may be 0 if the
253task is in a pid ns not visible from the listener's pid namespace). The
254notification also contains the ``data`` passed to seccomp, and a filters flag.
255The structure should be zeroed out prior to calling the ioctl.
256
257Userspace can then make a decision based on this information about what to do,
258and ``ioctl(SECCOMP_IOCTL_NOTIF_SEND)`` a response, indicating what should be
259returned to userspace. The ``id`` member of ``struct seccomp_notif_resp`` should
260be the same ``id`` as in ``struct seccomp_notif``.
261
262Userspace can also add file descriptors to the notifying process via
263``ioctl(SECCOMP_IOCTL_NOTIF_ADDFD)``. The ``id`` member of
264``struct seccomp_notif_addfd`` should be the same ``id`` as in
265``struct seccomp_notif``. The ``newfd_flags`` flag may be used to set flags
266like O_CLOEXEC on the file descriptor in the notifying process. If the supervisor
267wants to inject the file descriptor with a specific number, the
268``SECCOMP_ADDFD_FLAG_SETFD`` flag can be used, and set the ``newfd`` member to
269the specific number to use. If that file descriptor is already open in the
270notifying process it will be replaced. The supervisor can also add an FD, and
271respond atomically by using the ``SECCOMP_ADDFD_FLAG_SEND`` flag and the return
272value will be the injected file descriptor number.
273
274The notifying process can be preempted, resulting in the notification being
275aborted. This can be problematic when trying to take actions on behalf of the
276notifying process that are long-running and typically retryable (mounting a
277filesystem). Alternatively, at filter installation time, the
278``SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV`` flag can be set. This flag makes it
279such that when a user notification is received by the supervisor, the notifying
280process will ignore non-fatal signals until the response is sent. Signals that
281are sent prior to the notification being received by userspace are handled
282normally.
283
284It is worth noting that ``struct seccomp_data`` contains the values of register
285arguments to the syscall, but does not contain pointers to memory. The task's
286memory is accessible to suitably privileged traces via ``ptrace()`` or
287``/proc/pid/mem``. However, care should be taken to avoid the TOCTOU mentioned
288above in this document: all arguments being read from the tracee's memory
289should be read into the tracer's memory before any policy decisions are made.
290This allows for an atomic decision on syscall arguments.
291
292Sysctls
293=======
294
295Seccomp's sysctl files can be found in the ``/proc/sys/kernel/seccomp/``
296directory. Here's a description of each file in that directory:
297
298``actions_avail``:
299 A read-only ordered list of seccomp return values (refer to the
300 ``SECCOMP_RET_*`` macros above) in string form. The ordering, from
301 left-to-right, is the least permissive return value to the most
302 permissive return value.
303
304 The list represents the set of seccomp return values supported
305 by the kernel. A userspace program may use this list to
306 determine if the actions found in the ``seccomp.h``, when the
307 program was built, differs from the set of actions actually
308 supported in the current running kernel.
309
310``actions_logged``:
311 A read-write ordered list of seccomp return values (refer to the
312 ``SECCOMP_RET_*`` macros above) that are allowed to be logged. Writes
313 to the file do not need to be in ordered form but reads from the file
314 will be ordered in the same way as the actions_avail sysctl.
315
316 The ``allow`` string is not accepted in the ``actions_logged`` sysctl
317 as it is not possible to log ``SECCOMP_RET_ALLOW`` actions. Attempting
318 to write ``allow`` to the sysctl will result in an EINVAL being
319 returned.
320
321Adding architecture support
322===========================
323
324See ``arch/Kconfig`` for the authoritative requirements. In general, if an
325architecture supports both ptrace_event and seccomp, it will be able to
326support seccomp filter with minor fixup: ``SIGSYS`` support and seccomp return
327value checking. Then it must just add ``CONFIG_HAVE_ARCH_SECCOMP_FILTER``
328to its arch-specific Kconfig.
329
330
331
332Caveats
333=======
334
335The vDSO can cause some system calls to run entirely in userspace,
336leading to surprises when you run programs on different machines that
337fall back to real syscalls. To minimize these surprises on x86, make
338sure you test with
339``/sys/devices/system/clocksource/clocksource0/current_clocksource`` set to
340something like ``acpi_pm``.
341
342On x86-64, vsyscall emulation is enabled by default. (vsyscalls are
343legacy variants on vDSO calls.) Currently, emulated vsyscalls will
344honor seccomp, with a few oddities:
345
346- A return value of ``SECCOMP_RET_TRAP`` will set a ``si_call_addr`` pointing to
347 the vsyscall entry for the given call and not the address after the
348 'syscall' instruction. Any code which wants to restart the call
349 should be aware that (a) a ret instruction has been emulated and (b)
350 trying to resume the syscall will again trigger the standard vsyscall
351 emulation security checks, making resuming the syscall mostly
352 pointless.
353
354- A return value of ``SECCOMP_RET_TRACE`` will signal the tracer as usual,
355 but the syscall may not be changed to another system call using the
356 orig_rax register. It may only be changed to -1 order to skip the
357 currently emulated call. Any other change MAY terminate the process.
358 The rip value seen by the tracer will be the syscall entry address;
359 this is different from normal behavior. The tracer MUST NOT modify
360 rip or rsp. (Do not rely on other changes terminating the process.
361 They might work. For example, on some kernels, choosing a syscall
362 that only exists in future kernels will be correctly emulated (by
363 returning ``-ENOSYS``).
364
365To detect this quirky behavior, check for ``addr & ~0x0C00 ==
3660xFFFFFFFFFF600000``. (For ``SECCOMP_RET_TRACE``, use rip. For
367``SECCOMP_RET_TRAP``, use ``siginfo->si_call_addr``.) Do not check any other
368condition: future kernels may improve vsyscall emulation and current
369kernels in vsyscall=native mode will behave differently, but the
370instructions at ``0xF...F600{0,4,8,C}00`` will not be system calls in these
371cases.
372
373Note that modern systems are unlikely to use vsyscalls at all -- they
374are a legacy feature and they are considerably slower than standard
375syscalls. New code will use the vDSO, and vDSO-issued system calls
376are indistinguishable from normal system calls.