2Seccomp BPF (SECure COMPuting with filters)
   8A large number of system calls are exposed to every userland process
   9with many of them going unused for the entire lifetime of the process.
  10As system calls change and mature, bugs are found and eradicated.  A
  11certain subset of userland applications benefit by having a reduced set
  12of available system calls.  The resulting set reduces the total kernel
  13surface exposed to the application.  System call filtering is meant for
  14use with those applications.
  16Seccomp filtering provides a means for a process to specify a filter for
  17incoming system calls.  The filter is expressed as a Berkeley Packet
  18Filter (BPF) program, as with socket filters, except that the data
  19operated on is related to the system call being made: system call
  20number and the system call arguments.  This allows for expressive
  21filtering of system calls using a filter program language with a long
  22history of being exposed to userland and a straightforward data set.
  24Additionally, BPF makes it impossible for users of seccomp to fall prey
  25to time-of-check-time-of-use (TOCTOU) attacks that are common in system
  26call interposition frameworks.  BPF programs may not dereference
  27pointers which constrains all filters to solely evaluating the system
  28call arguments directly.
  30What it isn't
  33System call filtering isn't a sandbox.  It provides a clearly defined
  34mechanism for minimizing the exposed kernel surface.  It is meant to be
  35a tool for sandbox developers to use.  Beyond that, policy for logical
  36behavior and information flow should be managed with a combination of
  37other system hardening techniques and, potentially, an LSM of your
  38choosing.  Expressive, dynamic filters provide further options down this
  39path (avoiding pathological sizes or selecting which of the multiplexed
  40system calls in socketcall() is allowed, for instance) which could be
  41construed, incorrectly, as a more complete sandboxing solution.
  46An additional seccomp mode is added and is enabled using the same
  47prctl(2) call as the strict seccomp.  If the architecture has
  48``CONFIG_HAVE_ARCH_SECCOMP_FILTER``, then filters may be added as below:
  51        Now takes an additional argument which specifies a new filter
  52        using a BPF program.
  53        The BPF program will be executed over struct seccomp_data
  54        reflecting the system call number, arguments, and other
  55        metadata.  The BPF program must then return one of the
  56        acceptable values to inform the kernel which action should be
  57        taken.
  59        Usage::
  61                prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, prog);
  63        The 'prog' argument is a pointer to a struct sock_fprog which
  64        will contain the filter program.  If the program is invalid, the
  65        call will return -1 and set errno to ``EINVAL``.
  67        If ``fork``/``clone`` and ``execve`` are allowed by @prog, any child
  68        processes will be constrained to the same filters and system
  69        call ABI as the parent.
  71        Prior to use, the task must call ``prctl(PR_SET_NO_NEW_PRIVS, 1)`` or
  72        run with ``CAP_SYS_ADMIN`` privileges in its namespace.  If these are not
  73        true, ``-EACCES`` will be returned.  This requirement ensures that filter
  74        programs cannot be applied to child processes with greater privileges
  75        than the task that installed them.
  77        Additionally, if ``prctl(2)`` is allowed by the attached filter,
  78        additional filters may be layered on which will increase evaluation
  79        time, but allow for further decreasing the attack surface during
  80        execution of a process.
  82The above call returns 0 on success and non-zero on error.
  84Return values
  87A seccomp filter may return any of the following values. If multiple
  88filters exist, the return value for the evaluation of a given system
  89call will always use the highest precedent value. (For example,
  90``SECCOMP_RET_KILL_PROCESS`` will always take precedence.)
  92In precedence order, they are:
  95        Results in the entire process exiting immediately without executing
  96        the system call.  The exit status of the task (``status & 0x7f``)
  97        will be ``SIGSYS``, not ``SIGKILL``.
 100        Results in the task exiting immediately without executing the
 101        system call.  The exit status of the task (``status & 0x7f``) will
 102        be ``SIGSYS``, not ``SIGKILL``.
 105        Results in the kernel sending a ``SIGSYS`` signal to the triggering
 106        task without executing the system call. ``siginfo->si_call_addr``
 107        will show the address of the system call instruction, and
 108        ``siginfo->si_syscall`` and ``siginfo->si_arch`` will indicate which
 109        syscall was attempted.  The program counter will be as though
 110        the syscall happened (i.e. it will not point to the syscall
 111        instruction).  The return value register will contain an arch-
 112        dependent value -- if resuming execution, set it to something
 113        sensible.  (The architecture dependency is because replacing
 114        it with ``-ENOSYS`` could overwrite some useful information.)
 116        The ``SECCOMP_RET_DATA`` portion of the return value will be passed
 117        as ``si_errno``.
 119        ``SIGSYS`` triggered by seccomp will have a si_code of ``SYS_SECCOMP``.
 122        Results in the lower 16-bits of the return value being passed
 123        to userland as the errno without executing the system call.
 126        Results in a ``struct seccomp_notif`` message sent on the userspace
 127        notification fd, if it is attached, or ``-ENOSYS`` if it is not. See
 128        below on discussion of how to handle user notifications.
 131        When returned, this value will cause the kernel to attempt to
 132        notify a ``ptrace()``-based tracer prior to executing the system
 133        call.  If there is no tracer present, ``-ENOSYS`` is returned to
 134        userland and the system call is not executed.
 136        A tracer will be notified if it requests ``PTRACE_O_TRACESECCOMP``
 137        using ``ptrace(PTRACE_SETOPTIONS)``.  The tracer will be notified
 138        of a ``PTRACE_EVENT_SECCOMP`` and the ``SECCOMP_RET_DATA`` portion of
 139        the BPF program return value will be available to the tracer
 140        via ``PTRACE_GETEVENTMSG``.
 142        The tracer can skip the system call by changing the syscall number
 143        to -1.  Alternatively, the tracer can change the system call
 144        requested by changing the system call to a valid syscall number.  If
 145        the tracer asks to skip the system call, then the system call will
 146        appear to return the value that the tracer puts in the return value
 147        register.
 149        The seccomp check will not be run again after the tracer is
 150        notified.  (This means that seccomp-based sandboxes MUST NOT
 151        allow use of ptrace, even of other sandboxed processes, without
 152        extreme care; ptracers can use this mechanism to escape.)
 155        Results in the system call being executed after it is logged. This
 156        should be used by application developers to learn which syscalls their
 157        application needs without having to iterate through multiple test and
 158        development cycles to build the list.
 160        This action will only be logged if "log" is present in the
 161        actions_logged sysctl string.
 164        Results in the system call being executed.
 166If multiple filters exist, the return value for the evaluation of a
 167given system call will always use the highest precedent value.
 169Precedence is only determined using the ``SECCOMP_RET_ACTION`` mask.  When
 170multiple filters return values of the same precedence, only the
 171``SECCOMP_RET_DATA`` from the most recently installed filter will be
 177The biggest pitfall to avoid during use is filtering on system call
 178number without checking the architecture value.  Why?  On any
 179architecture that supports multiple system call invocation conventions,
 180the system call numbers may vary based on the specific invocation.  If
 181the numbers in the different calling conventions overlap, then checks in
 182the filters may be abused.  Always check the arch value!
 187The ``samples/seccomp/`` directory contains both an x86-specific example
 188and a more generic example of a higher level macro interface for BPF
 189program generation.
 191Userspace Notification
 194The ``SECCOMP_RET_USER_NOTIF`` return code lets seccomp filters pass a
 195particular syscall to userspace to be handled. This may be useful for
 196applications like container managers, which wish to intercept particular
 197syscalls (``mount()``, ``finit_module()``, etc.) and change their behavior.
 199To acquire a notification FD, use the ``SECCOMP_FILTER_FLAG_NEW_LISTENER``
 200argument to the ``seccomp()`` syscall:
 202.. code-block:: c
 206which (on success) will return a listener fd for the filter, which can then be
 207passed around via ``SCM_RIGHTS`` or similar. Note that filter fds correspond to
 208a 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 and
 210writes to/from a filter fd are also synchronized, so a filter fd can safely
 211have many readers.
 213The interface for a seccomp notification fd consists of two structures:
 215.. code-block:: c
 217    struct seccomp_notif_sizes {
 218        __u16 seccomp_notif;
 219        __u16 seccomp_notif_resp;
 220        __u16 seccomp_data;
 221    };
 223    struct seccomp_notif {
 224        __u64 id;
 225        __u32 pid;
 226        __u32 flags;
 227        struct seccomp_data data;
 228    };
 230    struct seccomp_notif_resp {
 231        __u64 id;
 232        __s64 val;
 233        __s32 error;
 234        __u32 flags;
 235    };
 237The ``struct seccomp_notif_sizes`` structure can be used to determine the size
 238of the various structures used in seccomp notifications. The size of ``struct
 239seccomp_data`` may change in the future, so code should use:
 241.. code-block:: c
 243    struct seccomp_notif_sizes sizes;
 244    seccomp(SECCOMP_GET_NOTIF_SIZES, 0, &sizes);
 246to determine the size of the various structures to allocate. See
 247samples/seccomp/user-trap.c for an example.
 249Users can read via ``ioctl(SECCOMP_IOCTL_NOTIF_RECV)``  (or ``poll()``) on a
 250seccomp notification fd to receive a ``struct seccomp_notif``, which contains
 251five 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 the
 253task is in a pid ns not visible from the listener's pid namespace). The
 254notification also contains the ``data`` passed to seccomp, and a filters flag.
 255The structure should be zeroed out prior to calling the ioctl.
 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 be
 259returned to userspace. The ``id`` member of ``struct seccomp_notif_resp`` should
 260be the same ``id`` as in ``struct seccomp_notif``.
 262Userspace can also add file descriptors to the notifying process via
 263``ioctl(SECCOMP_IOCTL_NOTIF_ADDFD)``. The ``id`` member of
 264``struct seccomp_notif_addfd`` should be the same ``id`` as in
 265``struct seccomp_notif``. The ``newfd_flags`` flag may be used to set flags
 266like O_CLOEXEC on the file descriptor in the notifying process. If the supervisor
 267wants to inject the file descriptor with a specific number, the
 268``SECCOMP_ADDFD_FLAG_SETFD`` flag can be used, and set the ``newfd`` member to
 269the specific number to use. If that file descriptor is already open in the
 270notifying process it will be replaced. The supervisor can also add an FD, and
 271respond atomically by using the ``SECCOMP_ADDFD_FLAG_SEND`` flag and the return
 272value will be the injected file descriptor number.
 274It is worth noting that ``struct seccomp_data`` contains the values of register
 275arguments to the syscall, but does not contain pointers to memory. The task's
 276memory is accessible to suitably privileged traces via ``ptrace()`` or
 277``/proc/pid/mem``. However, care should be taken to avoid the TOCTOU mentioned
 278above in this document: all arguments being read from the tracee's memory
 279should be read into the tracer's memory before any policy decisions are made.
 280This allows for an atomic decision on syscall arguments.
 285Seccomp's sysctl files can be found in the ``/proc/sys/kernel/seccomp/``
 286directory. Here's a description of each file in that directory:
 289        A read-only ordered list of seccomp return values (refer to the
 290        ``SECCOMP_RET_*`` macros above) in string form. The ordering, from
 291        left-to-right, is the least permissive return value to the most
 292        permissive return value.
 294        The list represents the set of seccomp return values supported
 295        by the kernel. A userspace program may use this list to
 296        determine if the actions found in the ``seccomp.h``, when the
 297        program was built, differs from the set of actions actually
 298        supported in the current running kernel.
 301        A read-write ordered list of seccomp return values (refer to the
 302        ``SECCOMP_RET_*`` macros above) that are allowed to be logged. Writes
 303        to the file do not need to be in ordered form but reads from the file
 304        will be ordered in the same way as the actions_avail sysctl.
 306        The ``allow`` string is not accepted in the ``actions_logged`` sysctl
 307        as it is not possible to log ``SECCOMP_RET_ALLOW`` actions. Attempting
 308        to write ``allow`` to the sysctl will result in an EINVAL being
 309        returned.
 311Adding architecture support
 314See ``arch/Kconfig`` for the authoritative requirements.  In general, if an
 315architecture supports both ptrace_event and seccomp, it will be able to
 316support seccomp filter with minor fixup: ``SIGSYS`` support and seccomp return
 317value checking.  Then it must just add ``CONFIG_HAVE_ARCH_SECCOMP_FILTER``
 318to its arch-specific Kconfig.
 325The vDSO can cause some system calls to run entirely in userspace,
 326leading to surprises when you run programs on different machines that
 327fall back to real syscalls.  To minimize these surprises on x86, make
 328sure you test with
 329``/sys/devices/system/clocksource/clocksource0/current_clocksource`` set to
 330something like ``acpi_pm``.
 332On x86-64, vsyscall emulation is enabled by default.  (vsyscalls are
 333legacy variants on vDSO calls.)  Currently, emulated vsyscalls will
 334honor seccomp, with a few oddities:
 336- A return value of ``SECCOMP_RET_TRAP`` will set a ``si_call_addr`` pointing to
 337  the vsyscall entry for the given call and not the address after the
 338  'syscall' instruction.  Any code which wants to restart the call
 339  should be aware that (a) a ret instruction has been emulated and (b)
 340  trying to resume the syscall will again trigger the standard vsyscall
 341  emulation security checks, making resuming the syscall mostly
 342  pointless.
 344- A return value of ``SECCOMP_RET_TRACE`` will signal the tracer as usual,
 345  but the syscall may not be changed to another system call using the
 346  orig_rax register. It may only be changed to -1 order to skip the
 347  currently emulated call. Any other change MAY terminate the process.
 348  The rip value seen by the tracer will be the syscall entry address;
 349  this is different from normal behavior.  The tracer MUST NOT modify
 350  rip or rsp.  (Do not rely on other changes terminating the process.
 351  They might work.  For example, on some kernels, choosing a syscall
 352  that only exists in future kernels will be correctly emulated (by
 353  returning ``-ENOSYS``).
 355To detect this quirky behavior, check for ``addr & ~0x0C00 ==
 3560xFFFFFFFFFF600000``.  (For ``SECCOMP_RET_TRACE``, use rip.  For
 357``SECCOMP_RET_TRAP``, use ``siginfo->si_call_addr``.)  Do not check any other
 358condition: future kernels may improve vsyscall emulation and current
 359kernels in vsyscall=native mode will behave differently, but the
 360instructions at ``0xF...F600{0,4,8,C}00`` will not be system calls in these
 363Note that modern systems are unlikely to use vsyscalls at all -- they
 364are a legacy feature and they are considerably slower than standard
 365syscalls.  New code will use the vDSO, and vDSO-issued system calls
 366are indistinguishable from normal system calls.