linux/Documentation/prctl/seccomp_filter.txt
<<
>>
Prefs
   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
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.