Based on kernel version 4.10.8. Page generated on 2017-04-01 14:44 EST.
1 SECure COMPuting with filters 2 ============================= 3 4 Introduction 5 ------------ 6 7 A large number of system calls are exposed to every userland process 8 with many of them going unused for the entire lifetime of the process. 9 As system calls change and mature, bugs are found and eradicated. A 10 certain subset of userland applications benefit by having a reduced set 11 of available system calls. The resulting set reduces the total kernel 12 surface exposed to the application. System call filtering is meant for 13 use with those applications. 14 15 Seccomp filtering provides a means for a process to specify a filter for 16 incoming system calls. The filter is expressed as a Berkeley Packet 17 Filter (BPF) program, as with socket filters, except that the data 18 operated on is related to the system call being made: system call 19 number and the system call arguments. This allows for expressive 20 filtering of system calls using a filter program language with a long 21 history of being exposed to userland and a straightforward data set. 22 23 Additionally, BPF makes it impossible for users of seccomp to fall prey 24 to time-of-check-time-of-use (TOCTOU) attacks that are common in system 25 call interposition frameworks. BPF programs may not dereference 26 pointers which constrains all filters to solely evaluating the system 27 call arguments directly. 28 29 What it isn't 30 ------------- 31 32 System call filtering isn't a sandbox. It provides a clearly defined 33 mechanism for minimizing the exposed kernel surface. It is meant to be 34 a tool for sandbox developers to use. Beyond that, policy for logical 35 behavior and information flow should be managed with a combination of 36 other system hardening techniques and, potentially, an LSM of your 37 choosing. Expressive, dynamic filters provide further options down this 38 path (avoiding pathological sizes or selecting which of the multiplexed 39 system calls in socketcall() is allowed, for instance) which could be 40 construed, incorrectly, as a more complete sandboxing solution. 41 42 Usage 43 ----- 44 45 An additional seccomp mode is added and is enabled using the same 46 prctl(2) call as the strict seccomp. If the architecture has 47 CONFIG_HAVE_ARCH_SECCOMP_FILTER, then filters may be added as below: 48 49 PR_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 80 The above call returns 0 on success and non-zero on error. 81 82 Return values 83 ------------- 84 A seccomp filter may return any of the following values. If multiple 85 filters exist, the return value for the evaluation of a given system 86 call will always use the highest precedent value. (For example, 87 SECCOMP_RET_KILL will always take precedence.) 88 89 In precedence order, they are: 90 91 SECCOMP_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 96 SECCOMP_RET_TRAP: 97 Results in the kernel sending a SIGSYS signal to the triggering 98 task without executing the system call. siginfo->si_call_addr 99 will show the address of the system call instruction, and 100 siginfo->si_syscall and siginfo->si_arch will indicate which 101 syscall was attempted. The program counter will be as though 102 the syscall happened (i.e. it will not point to the syscall 103 instruction). The return value register will contain an arch- 104 dependent value -- if resuming execution, set it to something 105 sensible. (The architecture dependency is because replacing 106 it with -ENOSYS could overwrite some useful information.) 107 108 The SECCOMP_RET_DATA portion of the return value will be passed 109 as si_errno. 110 111 SIGSYS triggered by seccomp will have a si_code of SYS_SECCOMP. 112 113 SECCOMP_RET_ERRNO: 114 Results in the lower 16-bits of the return value being passed 115 to userland as the errno without executing the system call. 116 117 SECCOMP_RET_TRACE: 118 When returned, this value will cause the kernel to attempt to 119 notify a ptrace()-based tracer prior to executing the system 120 call. If there is no tracer present, -ENOSYS is returned to 121 userland and the system call is not executed. 122 123 A tracer will be notified if it requests PTRACE_O_TRACESECCOMP 124 using ptrace(PTRACE_SETOPTIONS). The tracer will be notified 125 of a PTRACE_EVENT_SECCOMP and the SECCOMP_RET_DATA portion of 126 the BPF program return value will be available to the tracer 127 via PTRACE_GETEVENTMSG. 128 129 The tracer can skip the system call by changing the syscall number 130 to -1. Alternatively, the tracer can change the system call 131 requested by changing the system call to a valid syscall number. If 132 the tracer asks to skip the system call, then the system call will 133 appear to return the value that the tracer puts in the return value 134 register. 135 136 The seccomp check will not be run again after the tracer is 137 notified. (This means that seccomp-based sandboxes MUST NOT 138 allow use of ptrace, even of other sandboxed processes, without 139 extreme care; ptracers can use this mechanism to escape.) 140 141 SECCOMP_RET_ALLOW: 142 Results in the system call being executed. 143 144 If multiple filters exist, the return value for the evaluation of a 145 given system call will always use the highest precedent value. 146 147 Precedence is only determined using the SECCOMP_RET_ACTION mask. When 148 multiple filters return values of the same precedence, only the 149 SECCOMP_RET_DATA from the most recently installed filter will be 150 returned. 151 152 Pitfalls 153 -------- 154 155 The biggest pitfall to avoid during use is filtering on system call 156 number without checking the architecture value. Why? On any 157 architecture that supports multiple system call invocation conventions, 158 the system call numbers may vary based on the specific invocation. If 159 the numbers in the different calling conventions overlap, then checks in 160 the filters may be abused. Always check the arch value! 161 162 Example 163 ------- 164 165 The samples/seccomp/ directory contains both an x86-specific example 166 and a more generic example of a higher level macro interface for BPF 167 program generation. 168 169 170 171 Adding architecture support 172 ----------------------- 173 174 See arch/Kconfig for the authoritative requirements. In general, if an 175 architecture supports both ptrace_event and seccomp, it will be able to 176 support seccomp filter with minor fixup: SIGSYS support and seccomp return 177 value checking. Then it must just add CONFIG_HAVE_ARCH_SECCOMP_FILTER 178 to its arch-specific Kconfig. 179 180 181 182 Caveats 183 ------- 184 185 The vDSO can cause some system calls to run entirely in userspace, 186 leading to surprises when you run programs on different machines that 187 fall back to real syscalls. To minimize these surprises on x86, make 188 sure you test with 189 /sys/devices/system/clocksource/clocksource0/current_clocksource set to 190 something like acpi_pm. 191 192 On x86-64, vsyscall emulation is enabled by default. (vsyscalls are 193 legacy variants on vDSO calls.) Currently, emulated vsyscalls will honor seccomp, with a few oddities: 194 195 - A return value of SECCOMP_RET_TRAP will set a si_call_addr pointing to 196 the vsyscall entry for the given call and not the address after the 197 'syscall' instruction. Any code which wants to restart the call 198 should be aware that (a) a ret instruction has been emulated and (b) 199 trying to resume the syscall will again trigger the standard vsyscall 200 emulation security checks, making resuming the syscall mostly 201 pointless. 202 203 - A return value of SECCOMP_RET_TRACE will signal the tracer as usual, 204 but the syscall may not be changed to another system call using the 205 orig_rax register. It may only be changed to -1 order to skip the 206 currently emulated call. Any other change MAY terminate the process. 207 The rip value seen by the tracer will be the syscall entry address; 208 this is different from normal behavior. The tracer MUST NOT modify 209 rip or rsp. (Do not rely on other changes terminating the process. 210 They might work. For example, on some kernels, choosing a syscall 211 that only exists in future kernels will be correctly emulated (by 212 returning -ENOSYS). 213 214 To detect this quirky behavior, check for addr & ~0x0C00 == 215 0xFFFFFFFFFF600000. (For SECCOMP_RET_TRACE, use rip. For 216 SECCOMP_RET_TRAP, use siginfo->si_call_addr.) Do not check any other 217 condition: future kernels may improve vsyscall emulation and current 218 kernels in vsyscall=native mode will behave differently, but the 219 instructions at 0xF...F600{0,4,8,C}00 will not be system calls in these 220 cases. 221 222 Note that modern systems are unlikely to use vsyscalls at all -- they 223 are a legacy feature and they are considerably slower than standard 224 syscalls. New code will use the vDSO, and vDSO-issued system calls 225 are indistinguishable from normal system calls.