Introduction¶

A large number of system calls are exposed to every userland processwith many of them going unused for the entire lifetime of the process.As system calls change and mature, bugs are found and eradicated. Acertain subset of userland applications benefit by having a reduced setof available system calls. The resulting set reduces the total kernelsurface exposed to the application. System call filtering is meant foruse with those applications.

Seccomp filtering provides a means for a process to specify a filter forincoming system calls. The filter is expressed as a Berkeley PacketFilter (BPF) program, as with socket filters, except that the dataoperated on is related to the system call being made: system callnumber and the system call arguments. This allows for expressivefiltering of system calls using a filter program language with a longhistory of being exposed to userland and a straightforward data set.

Additionally, BPF makes it impossible for users of seccomp to fall preyto time-of-check-time-of-use (TOCTOU) attacks that are common in systemcall interposition frameworks. BPF programs may not dereferencepointers which constrains all filters to solely evaluating the systemcall arguments directly.

What it isn’t¶

System call filtering isn’t a sandbox. It provides a clearly definedmechanism for minimizing the exposed kernel surface. It is meant to bea tool for sandbox developers to use. Beyond that, policy for logicalbehavior and information flow should be managed with a combination ofother system hardening techniques and, potentially, an LSM of yourchoosing. Expressive, dynamic filters provide further options down thispath (avoiding pathological sizes or selecting which of the multiplexedsystem calls in socketcall() is allowed, for instance) which could beconstrued, incorrectly, as a more complete sandboxing solution.

Usage¶

An additional seccomp mode is added and is enabled using the sameprctl(2) call as the strict seccomp. If the architecture hasCONFIG_HAVE_ARCH_SECCOMP_FILTER, then filters may be added as below:

PR_SET_SECCOMP:

Now takes an additional argument which specifies a new filterusing a BPF program.The BPF program will be executed over struct seccomp_datareflecting the system call number, arguments, and othermetadata. The BPF program must then return one of theacceptable values to inform the kernel which action should betaken.

Usage:

prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, prog);

The ‘prog’ argument is a pointer to a struct sock_fprog whichwill contain the filter program. If the program is invalid, thecall will return -1 and set errno toEINVAL.

Iffork/clone andexecve are allowed by @prog, any childprocesses will be constrained to the same filters and systemcall ABI as the parent.

Prior to use, the task must callprctl(PR_SET_NO_NEW_PRIVS,1) orrun withCAP_SYS_ADMIN privileges in its namespace. If these are nottrue,-EACCES will be returned. This requirement ensures that filterprograms cannot be applied to child processes with greater privilegesthan the task that installed them.

Additionally, ifprctl(2) is allowed by the attached filter,additional filters may be layered on which will increase evaluationtime, but allow for further decreasing the attack surface duringexecution of a process.

The above call returns 0 on success and non-zero on error.

Return values¶

A seccomp filter may return any of the following values. If multiplefilters exist, the return value for the evaluation of a given systemcall will always use the highest precedent value. (For example,SECCOMP_RET_KILL_PROCESS will always take precedence.)

In precedence order, they are:

SECCOMP_RET_KILL_PROCESS:

Results in the entire process exiting immediately without executingthe system call. The exit status of the task (status&0x7f)will beSIGSYS, notSIGKILL.

SECCOMP_RET_KILL_THREAD:

Results in the task exiting immediately without executing thesystem call. The exit status of the task (status&0x7f) willbeSIGSYS, notSIGKILL.

SECCOMP_RET_TRAP:

Results in the kernel sending aSIGSYS signal to the triggeringtask without executing the system call.siginfo->si_call_addrwill show the address of the system call instruction, andsiginfo->si_syscall andsiginfo->si_arch will indicate whichsyscall was attempted. The program counter will be as thoughthe syscall happened (i.e. it will not point to the syscallinstruction). The return value register will contain an arch-dependent value – if resuming execution, set it to somethingsensible. (The architecture dependency is because replacingit with-ENOSYS could overwrite some useful information.)

TheSECCOMP_RET_DATA portion of the return value will be passedassi_errno.

SIGSYS triggered by seccomp will have a si_code ofSYS_SECCOMP.

SECCOMP_RET_ERRNO:

Results in the lower 16-bits of the return value being passedto userland as the errno without executing the system call.

SECCOMP_RET_USER_NOTIF:

Results in astructseccomp_notif message sent on the userspacenotification fd, if it is attached, or-ENOSYS if it is not. Seebelow on discussion of how to handle user notifications.

SECCOMP_RET_TRACE:

When returned, this value will cause the kernel to attempt tonotify aptrace()-based tracer prior to executing the systemcall. If there is no tracer present,-ENOSYS is returned touserland and the system call is not executed.

A tracer will be notified if it requestsPTRACE_O_TRACESECCOMPusingptrace(PTRACE_SETOPTIONS). The tracer will be notifiedof aPTRACE_EVENT_SECCOMP and theSECCOMP_RET_DATA portion ofthe BPF program return value will be available to the tracerviaPTRACE_GETEVENTMSG.

The tracer can skip the system call by changing the syscall numberto -1. Alternatively, the tracer can change the system callrequested by changing the system call to a valid syscall number. Ifthe tracer asks to skip the system call, then the system call willappear to return the value that the tracer puts in the return valueregister.

The seccomp check will not be run again after the tracer isnotified. (This means that seccomp-based sandboxes MUST NOTallow use of ptrace, even of other sandboxed processes, withoutextreme care; ptracers can use this mechanism to escape.)

SECCOMP_RET_LOG:

Results in the system call being executed after it is logged. Thisshould be used by application developers to learn which syscalls theirapplication needs without having to iterate through multiple test anddevelopment cycles to build the list.

This action will only be logged if “log” is present in theactions_logged sysctl string.

SECCOMP_RET_ALLOW:

Results in the system call being executed.

If multiple filters exist, the return value for the evaluation of agiven system call will always use the highest precedent value.

Precedence is only determined using theSECCOMP_RET_ACTION mask. Whenmultiple filters return values of the same precedence, only theSECCOMP_RET_DATA from the most recently installed filter will bereturned.

Pitfalls¶

The biggest pitfall to avoid during use is filtering on system callnumber without checking the architecture value. Why? On anyarchitecture that supports multiple system call invocation conventions,the system call numbers may vary based on the specific invocation. Ifthe numbers in the different calling conventions overlap, then checks inthe filters may be abused. Always check the arch value!

Example¶

Thesamples/seccomp/ directory contains both an x86-specific exampleand a more generic example of a higher level macro interface for BPFprogram generation.

Userspace Notification¶

TheSECCOMP_RET_USER_NOTIF return code lets seccomp filters pass aparticular syscall to userspace to be handled. This may be useful forapplications like container managers, which wish to intercept particularsyscalls (mount(),finit_module(), etc.) and change their behavior.

To acquire a notification FD, use theSECCOMP_FILTER_FLAG_NEW_LISTENERargument to theseccomp() syscall:

fd=seccomp(SECCOMP_SET_MODE_FILTER,SECCOMP_FILTER_FLAG_NEW_LISTENER,&prog);

which (on success) will return a listener fd for the filter, which can then bepassed around viaSCM_RIGHTS or similar. Note that filter fds correspond toa particular filter, and not a particular task. So if this task then forks,notifications from both tasks will appear on the same filter fd. Reads andwrites to/from a filter fd are also synchronized, so a filter fd can safelyhave many readers.

The interface for a seccomp notification fd consists of two structures:

structseccomp_notif_sizes{__u16seccomp_notif;__u16seccomp_notif_resp;__u16seccomp_data;};structseccomp_notif{__u64id;__u32pid;__u32flags;structseccomp_datadata;};structseccomp_notif_resp{__u64id;__s64val;__s32error;__u32flags;};

Thestructseccomp_notif_sizes structure can be used to determine the sizeof the various structures used in seccomp notifications. The size ofstructseccomp_data may change in the future, so code should use:

structseccomp_notif_sizessizes;seccomp(SECCOMP_GET_NOTIF_SIZES,0,&sizes);

to determine the size of the various structures to allocate. Seesamples/seccomp/user-trap.c for an example.

Users can read viaioctl(SECCOMP_IOCTL_NOTIF_RECV) (orpoll()) on aseccomp notification fd to receive astructseccomp_notif, which containsfive members: the input length of the structure, a unique-per-filterid,thepid of the task which triggered this request (which may be 0 if thetask is in a pid ns not visible from the listener’s pid namespace), aflagsmember which for now only hasSECCOMP_NOTIF_FLAG_SIGNALED, representingwhether or not the notification is a result of a non-fatal signal, and thedata passed to seccomp. Userspace can then make a decision based on thisinformation about what to do, andioctl(SECCOMP_IOCTL_NOTIF_SEND) aresponse, indicating what should be returned to userspace. Theid member ofstructseccomp_notif_resp should be the sameid as instructseccomp_notif.

It is worth noting thatstructseccomp_data contains the values of registerarguments to the syscall, but does not contain pointers to memory. The task’smemory is accessible to suitably privileged traces viaptrace() or/proc/pid/mem. However, care should be taken to avoid the TOCTOU mentionedabove in this document: all arguments being read from the tracee’s memoryshould be read into the tracer’s memory before any policy decisions are made.This allows for an atomic decision on syscall arguments.

Sysctls¶

Seccomp’s sysctl files can be found in the/proc/sys/kernel/seccomp/directory. Here’s a description of each file in that directory:

actions_avail:

A read-only ordered list of seccomp return values (refer to theSECCOMP_RET_* macros above) in string form. The ordering, fromleft-to-right, is the least permissive return value to the mostpermissive return value.

The list represents the set of seccomp return values supportedby the kernel. A userspace program may use this list todetermine if the actions found in theseccomp.h, when theprogram was built, differs from the set of actions actuallysupported in the current running kernel.

actions_logged:

A read-write ordered list of seccomp return values (refer to theSECCOMP_RET_* macros above) that are allowed to be logged. Writesto the file do not need to be in ordered form but reads from the filewill be ordered in the same way as the actions_avail sysctl.

Theallow string is not accepted in theactions_logged sysctlas it is not possible to logSECCOMP_RET_ALLOW actions. Attemptingto writeallow to the sysctl will result in an EINVAL beingreturned.

Adding architecture support¶

Seearch/Kconfig for the authoritative requirements. In general, if anarchitecture supports both ptrace_event and seccomp, it will be able tosupport seccomp filter with minor fixup:SIGSYS support and seccomp returnvalue checking. Then it must just addCONFIG_HAVE_ARCH_SECCOMP_FILTERto its arch-specific Kconfig.

Caveats¶

The vDSO can cause some system calls to run entirely in userspace,leading to surprises when you run programs on different machines thatfall back to real syscalls. To minimize these surprises on x86, makesure you test with/sys/devices/system/clocksource/clocksource0/current_clocksource set tosomething likeacpi_pm.

On x86-64, vsyscall emulation is enabled by default. (vsyscalls arelegacy variants on vDSO calls.) Currently, emulated vsyscalls willhonor seccomp, with a few oddities:

• A return value ofSECCOMP_RET_TRAP will set asi_call_addr pointing tothe vsyscall entry for the given call and not the address after the‘syscall’ instruction. Any code which wants to restart the callshould be aware that (a) a ret instruction has been emulated and (b)trying to resume the syscall will again trigger the standard vsyscallemulation security checks, making resuming the syscall mostlypointless.
• A return value ofSECCOMP_RET_TRACE will signal the tracer as usual,but the syscall may not be changed to another system call using theorig_rax register. It may only be changed to -1 order to skip thecurrently emulated call. Any other change MAY terminate the process.The rip value seen by the tracer will be the syscall entry address;this is different from normal behavior. The tracer MUST NOT modifyrip or rsp. (Do not rely on other changes terminating the process.They might work. For example, on some kernels, choosing a syscallthat only exists in future kernels will be correctly emulated (byreturning-ENOSYS).

To detect this quirky behavior, check foraddr&~0x0C00==0xFFFFFFFFFF600000. (ForSECCOMP_RET_TRACE, use rip. ForSECCOMP_RET_TRAP, usesiginfo->si_call_addr.) Do not check any othercondition: future kernels may improve vsyscall emulation and currentkernels in vsyscall=native mode will behave differently, but theinstructions at0xF...F600{0,4,8,C}00 will not be system calls in thesecases.

Note that modern systems are unlikely to use vsyscalls at all – theyare a legacy feature and they are considerably slower than standardsyscalls. New code will use the vDSO, and vDSO-issued system callsare indistinguishable from normal system calls.