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. The kernel will 99 rollback the register state to just before the system call 100 entry such that a signal handler in the task will be able to 101 inspect the ucontext_t->uc_mcontext registers and emulate 102 system call success or failure upon return from the signal 103 handler. 104 105 The SECCOMP_RET_DATA portion of the return value will be passed 106 as si_errno. 107 108 SIGSYS triggered by seccomp will have a si_code of SYS_SECCOMP. 109 110SECCOMP_RET_ERRNO: 111 Results in the lower 16-bits of the return value being passed 112 to userland as the errno without executing the system call. 113 114SECCOMP_RET_TRACE: 115 When returned, this value will cause the kernel to attempt to 116 notify a ptrace()-based tracer prior to executing the system 117 call. If there is no tracer present, -ENOSYS is returned to 118 userland and the system call is not executed. 119 120 A tracer will be notified if it requests PTRACE_O_TRACESECCOMP 121 using ptrace(PTRACE_SETOPTIONS). The tracer will be notified 122 of a PTRACE_EVENT_SECCOMP and the SECCOMP_RET_DATA portion of 123 the BPF program return value will be available to the tracer 124 via PTRACE_GETEVENTMSG. 125 126SECCOMP_RET_ALLOW: 127 Results in the system call being executed. 128 129If multiple filters exist, the return value for the evaluation of a 130given system call will always use the highest precedent value. 131 132Precedence is only determined using the SECCOMP_RET_ACTION mask. When 133multiple filters return values of the same precedence, only the 134SECCOMP_RET_DATA from the most recently installed filter will be 135returned. 136 137Pitfalls 138-------- 139 140The biggest pitfall to avoid during use is filtering on system call 141number without checking the architecture value. Why? On any 142architecture that supports multiple system call invocation conventions, 143the system call numbers may vary based on the specific invocation. If 144the numbers in the different calling conventions overlap, then checks in 145the filters may be abused. Always check the arch value! 146 147Example 148------- 149 150The samples/seccomp/ directory contains both an x86-specific example 151and a more generic example of a higher level macro interface for BPF 152program generation. 153 154 155 156Adding architecture support 157----------------------- 158 159See arch/Kconfig for the authoritative requirements. In general, if an 160architecture supports both ptrace_event and seccomp, it will be able to 161support seccomp filter with minor fixup: SIGSYS support and seccomp return 162value checking. Then it must just add CONFIG_HAVE_ARCH_SECCOMP_FILTER 163to its arch-specific Kconfig. 164