377 lines · plain
1===========================================2Seccomp BPF (SECure COMPuting with filters)3===========================================4 5Introduction6============7 8A large number of system calls are exposed to every userland process9with many of them going unused for the entire lifetime of the process.10As system calls change and mature, bugs are found and eradicated. A11certain subset of userland applications benefit by having a reduced set12of available system calls. The resulting set reduces the total kernel13surface exposed to the application. System call filtering is meant for14use with those applications.15 16Seccomp filtering provides a means for a process to specify a filter for17incoming system calls. The filter is expressed as a Berkeley Packet18Filter (BPF) program, as with socket filters, except that the data19operated on is related to the system call being made: system call20number and the system call arguments. This allows for expressive21filtering of system calls using a filter program language with a long22history of being exposed to userland and a straightforward data set.23 24Additionally, BPF makes it impossible for users of seccomp to fall prey25to time-of-check-time-of-use (TOCTOU) attacks that are common in system26call interposition frameworks. BPF programs may not dereference27pointers which constrains all filters to solely evaluating the system28call arguments directly.29 30What it isn't31=============32 33System call filtering isn't a sandbox. It provides a clearly defined34mechanism for minimizing the exposed kernel surface. It is meant to be35a tool for sandbox developers to use. Beyond that, policy for logical36behavior and information flow should be managed with a combination of37other system hardening techniques and, potentially, an LSM of your38choosing. Expressive, dynamic filters provide further options down this39path (avoiding pathological sizes or selecting which of the multiplexed40system calls in socketcall() is allowed, for instance) which could be41construed, incorrectly, as a more complete sandboxing solution.42 43Usage44=====45 46An additional seccomp mode is added and is enabled using the same47prctl(2) call as the strict seccomp. If the architecture has48``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 filter52 using a BPF program.53 The BPF program will be executed over struct seccomp_data54 reflecting the system call number, arguments, and other55 metadata. The BPF program must then return one of the56 acceptable values to inform the kernel which action should be57 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 which64 will contain the filter program. If the program is invalid, the65 call will return -1 and set errno to ``EINVAL``.66 67 If ``fork``/``clone`` and ``execve`` are allowed by @prog, any child68 processes will be constrained to the same filters and system69 call ABI as the parent.70 71 Prior to use, the task must call ``prctl(PR_SET_NO_NEW_PRIVS, 1)`` or72 run with ``CAP_SYS_ADMIN`` privileges in its namespace. If these are not73 true, ``-EACCES`` will be returned. This requirement ensures that filter74 programs cannot be applied to child processes with greater privileges75 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 evaluation79 time, but allow for further decreasing the attack surface during80 execution of a process.81 82The above call returns 0 on success and non-zero on error.83 84Return values85=============86 87A seccomp filter may return any of the following values. If multiple88filters exist, the return value for the evaluation of a given system89call 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 executing96 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 the101 system call. The exit status of the task (``status & 0x7f``) will102 be ``SIGSYS``, not ``SIGKILL``.103 104``SECCOMP_RET_TRAP``:105 Results in the kernel sending a ``SIGSYS`` signal to the triggering106 task without executing the system call. ``siginfo->si_call_addr``107 will show the address of the system call instruction, and108 ``siginfo->si_syscall`` and ``siginfo->si_arch`` will indicate which109 syscall was attempted. The program counter will be as though110 the syscall happened (i.e. it will not point to the syscall111 instruction). The return value register will contain an arch-112 dependent value -- if resuming execution, set it to something113 sensible. (The architecture dependency is because replacing114 it with ``-ENOSYS`` could overwrite some useful information.)115 116 The ``SECCOMP_RET_DATA`` portion of the return value will be passed117 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 passed123 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 userspace127 notification fd, if it is attached, or ``-ENOSYS`` if it is not. See128 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 to132 notify a ``ptrace()``-based tracer prior to executing the system133 call. If there is no tracer present, ``-ENOSYS`` is returned to134 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 notified138 of a ``PTRACE_EVENT_SECCOMP`` and the ``SECCOMP_RET_DATA`` portion of139 the BPF program return value will be available to the tracer140 via ``PTRACE_GETEVENTMSG``.141 142 The tracer can skip the system call by changing the syscall number143 to -1. Alternatively, the tracer can change the system call144 requested by changing the system call to a valid syscall number. If145 the tracer asks to skip the system call, then the system call will146 appear to return the value that the tracer puts in the return value147 register.148 149 The seccomp check will not be run again after the tracer is150 notified. (This means that seccomp-based sandboxes MUST NOT151 allow use of ptrace, even of other sandboxed processes, without152 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. This156 should be used by application developers to learn which syscalls their157 application needs without having to iterate through multiple test and158 development cycles to build the list.159 160 This action will only be logged if "log" is present in the161 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 a167given system call will always use the highest precedent value.168 169Precedence is only determined using the ``SECCOMP_RET_ACTION`` mask. When170multiple filters return values of the same precedence, only the171``SECCOMP_RET_DATA`` from the most recently installed filter will be172returned.173 174Pitfalls175========176 177The biggest pitfall to avoid during use is filtering on system call178number without checking the architecture value. Why? On any179architecture that supports multiple system call invocation conventions,180the system call numbers may vary based on the specific invocation. If181the numbers in the different calling conventions overlap, then checks in182the filters may be abused. Always check the arch value!183 184Example185=======186 187The ``samples/seccomp/`` directory contains both an x86-specific example188and a more generic example of a higher level macro interface for BPF189program generation.190 191Userspace Notification192======================193 194The ``SECCOMP_RET_USER_NOTIF`` return code lets seccomp filters pass a195particular syscall to userspace to be handled. This may be useful for196applications like container managers, which wish to intercept particular197syscalls (``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:: c203 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 be207passed around via ``SCM_RIGHTS`` or similar. Note that filter fds correspond to208a 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 and210writes to/from a filter fd are also synchronized, so a filter fd can safely211have many readers.212 213The interface for a seccomp notification fd consists of two structures:214 215.. code-block:: c216 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 size238of the various structures used in seccomp notifications. The size of ``struct239seccomp_data`` may change in the future, so code should use:240 241.. code-block:: c242 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. See247samples/seccomp/user-trap.c for an example.248 249Users can read via ``ioctl(SECCOMP_IOCTL_NOTIF_RECV)`` (or ``poll()``) on a250seccomp notification fd to receive a ``struct seccomp_notif``, which contains251five 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 the253task is in a pid ns not visible from the listener's pid namespace). The254notification 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 be259returned to userspace. The ``id`` member of ``struct seccomp_notif_resp`` should260be the same ``id`` as in ``struct seccomp_notif``.261 262Userspace can also add file descriptors to the notifying process via263``ioctl(SECCOMP_IOCTL_NOTIF_ADDFD)``. The ``id`` member of264``struct seccomp_notif_addfd`` should be the same ``id`` as in265``struct seccomp_notif``. The ``newfd_flags`` flag may be used to set flags266like O_CLOEXEC on the file descriptor in the notifying process. If the supervisor267wants to inject the file descriptor with a specific number, the268``SECCOMP_ADDFD_FLAG_SETFD`` flag can be used, and set the ``newfd`` member to269the specific number to use. If that file descriptor is already open in the270notifying process it will be replaced. The supervisor can also add an FD, and271respond atomically by using the ``SECCOMP_ADDFD_FLAG_SEND`` flag and the return272value will be the injected file descriptor number.273 274The notifying process can be preempted, resulting in the notification being275aborted. This can be problematic when trying to take actions on behalf of the276notifying process that are long-running and typically retryable (mounting a277filesystem). Alternatively, at filter installation time, the278``SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV`` flag can be set. This flag makes it279such that when a user notification is received by the supervisor, the notifying280process will ignore non-fatal signals until the response is sent. Signals that281are sent prior to the notification being received by userspace are handled282normally.283 284It is worth noting that ``struct seccomp_data`` contains the values of register285arguments to the syscall, but does not contain pointers to memory. The task's286memory is accessible to suitably privileged traces via ``ptrace()`` or287``/proc/pid/mem``. However, care should be taken to avoid the TOCTOU mentioned288above in this document: all arguments being read from the tracee's memory289should be read into the tracer's memory before any policy decisions are made.290This allows for an atomic decision on syscall arguments.291 292Sysctls293=======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 the300 ``SECCOMP_RET_*`` macros above) in string form. The ordering, from301 left-to-right, is the least permissive return value to the most302 permissive return value.303 304 The list represents the set of seccomp return values supported305 by the kernel. A userspace program may use this list to306 determine if the actions found in the ``seccomp.h``, when the307 program was built, differs from the set of actions actually308 supported in the current running kernel.309 310``actions_logged``:311 A read-write ordered list of seccomp return values (refer to the312 ``SECCOMP_RET_*`` macros above) that are allowed to be logged. Writes313 to the file do not need to be in ordered form but reads from the file314 will be ordered in the same way as the actions_avail sysctl.315 316 The ``allow`` string is not accepted in the ``actions_logged`` sysctl317 as it is not possible to log ``SECCOMP_RET_ALLOW`` actions. Attempting318 to write ``allow`` to the sysctl will result in an EINVAL being319 returned.320 321Adding architecture support322===========================323 324See ``arch/Kconfig`` for the authoritative requirements. In general, if an325architecture supports both ptrace_event and seccomp, it will be able to326support seccomp filter with minor fixup: ``SIGSYS`` support and seccomp return327value checking. Then it must just add ``CONFIG_HAVE_ARCH_SECCOMP_FILTER``328to its arch-specific Kconfig.329 330 331 332Caveats333=======334 335The vDSO can cause some system calls to run entirely in userspace,336leading to surprises when you run programs on different machines that337fall back to real syscalls. To minimize these surprises on x86, make338sure you test with339``/sys/devices/system/clocksource/clocksource0/current_clocksource`` set to340something like ``acpi_pm``.341 342On x86-64, vsyscall emulation is enabled by default. (vsyscalls are343legacy variants on vDSO calls.) Currently, emulated vsyscalls will344honor seccomp, with a few oddities:345 346- A return value of ``SECCOMP_RET_TRAP`` will set a ``si_call_addr`` pointing to347 the vsyscall entry for the given call and not the address after the348 'syscall' instruction. Any code which wants to restart the call349 should be aware that (a) a ret instruction has been emulated and (b)350 trying to resume the syscall will again trigger the standard vsyscall351 emulation security checks, making resuming the syscall mostly352 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 the356 orig_rax register. It may only be changed to -1 order to skip the357 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 modify360 rip or rsp. (Do not rely on other changes terminating the process.361 They might work. For example, on some kernels, choosing a syscall362 that only exists in future kernels will be correctly emulated (by363 returning ``-ENOSYS``).364 365To detect this quirky behavior, check for ``addr & ~0x0C00 ==3660xFFFFFFFFFF600000``. (For ``SECCOMP_RET_TRACE``, use rip. For367``SECCOMP_RET_TRAP``, use ``siginfo->si_call_addr``.) Do not check any other368condition: future kernels may improve vsyscall emulation and current369kernels in vsyscall=native mode will behave differently, but the370instructions at ``0xF...F600{0,4,8,C}00`` will not be system calls in these371cases.372 373Note that modern systems are unlikely to use vsyscalls at all -- they374are a legacy feature and they are considerably slower than standard375syscalls. New code will use the vDSO, and vDSO-issued system calls376are indistinguishable from normal system calls.377