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