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 262It is worth noting that ``struct seccomp_data`` contains the values of register 263arguments to the syscall, but does not contain pointers to memory. The task's 264memory is accessible to suitably privileged traces via ``ptrace()`` or 265``/proc/pid/mem``. However, care should be taken to avoid the TOCTOU mentioned 266above in this document: all arguments being read from the tracee's memory 267should be read into the tracer's memory before any policy decisions are made. 268This allows for an atomic decision on syscall arguments. 269 270Sysctls 271======= 272 273Seccomp's sysctl files can be found in the ``/proc/sys/kernel/seccomp/`` 274directory. Here's a description of each file in that directory: 275 276``actions_avail``: 277 A read-only ordered list of seccomp return values (refer to the 278 ``SECCOMP_RET_*`` macros above) in string form. The ordering, from 279 left-to-right, is the least permissive return value to the most 280 permissive return value. 281 282 The list represents the set of seccomp return values supported 283 by the kernel. A userspace program may use this list to 284 determine if the actions found in the ``seccomp.h``, when the 285 program was built, differs from the set of actions actually 286 supported in the current running kernel. 287 288``actions_logged``: 289 A read-write ordered list of seccomp return values (refer to the 290 ``SECCOMP_RET_*`` macros above) that are allowed to be logged. Writes 291 to the file do not need to be in ordered form but reads from the file 292 will be ordered in the same way as the actions_avail sysctl. 293 294 The ``allow`` string is not accepted in the ``actions_logged`` sysctl 295 as it is not possible to log ``SECCOMP_RET_ALLOW`` actions. Attempting 296 to write ``allow`` to the sysctl will result in an EINVAL being 297 returned. 298 299Adding architecture support 300=========================== 301 302See ``arch/Kconfig`` for the authoritative requirements. In general, if an 303architecture supports both ptrace_event and seccomp, it will be able to 304support seccomp filter with minor fixup: ``SIGSYS`` support and seccomp return 305value checking. Then it must just add ``CONFIG_HAVE_ARCH_SECCOMP_FILTER`` 306to its arch-specific Kconfig. 307 308 309 310Caveats 311======= 312 313The vDSO can cause some system calls to run entirely in userspace, 314leading to surprises when you run programs on different machines that 315fall back to real syscalls. To minimize these surprises on x86, make 316sure you test with 317``/sys/devices/system/clocksource/clocksource0/current_clocksource`` set to 318something like ``acpi_pm``. 319 320On x86-64, vsyscall emulation is enabled by default. (vsyscalls are 321legacy variants on vDSO calls.) Currently, emulated vsyscalls will 322honor seccomp, with a few oddities: 323 324- A return value of ``SECCOMP_RET_TRAP`` will set a ``si_call_addr`` pointing to 325 the vsyscall entry for the given call and not the address after the 326 'syscall' instruction. Any code which wants to restart the call 327 should be aware that (a) a ret instruction has been emulated and (b) 328 trying to resume the syscall will again trigger the standard vsyscall 329 emulation security checks, making resuming the syscall mostly 330 pointless. 331 332- A return value of ``SECCOMP_RET_TRACE`` will signal the tracer as usual, 333 but the syscall may not be changed to another system call using the 334 orig_rax register. It may only be changed to -1 order to skip the 335 currently emulated call. Any other change MAY terminate the process. 336 The rip value seen by the tracer will be the syscall entry address; 337 this is different from normal behavior. The tracer MUST NOT modify 338 rip or rsp. (Do not rely on other changes terminating the process. 339 They might work. For example, on some kernels, choosing a syscall 340 that only exists in future kernels will be correctly emulated (by 341 returning ``-ENOSYS``). 342 343To detect this quirky behavior, check for ``addr & ~0x0C00 == 3440xFFFFFFFFFF600000``. (For ``SECCOMP_RET_TRACE``, use rip. For 345``SECCOMP_RET_TRAP``, use ``siginfo->si_call_addr``.) Do not check any other 346condition: future kernels may improve vsyscall emulation and current 347kernels in vsyscall=native mode will behave differently, but the 348instructions at ``0xF...F600{0,4,8,C}00`` will not be system calls in these 349cases. 350 351Note that modern systems are unlikely to use vsyscalls at all -- they 352are a legacy feature and they are considerably slower than standard 353syscalls. New code will use the vDSO, and vDSO-issued system calls 354are indistinguishable from normal system calls. 355