2017-05-13 05:51:37 -06:00
|
|
|
===========================================
|
|
|
|
Seccomp BPF (SECure COMPuting with filters)
|
|
|
|
===========================================
|
2012-04-12 15:48:04 -06:00
|
|
|
|
|
|
|
Introduction
|
2017-05-13 05:51:37 -06:00
|
|
|
============
|
2012-04-12 15:48:04 -06:00
|
|
|
|
|
|
|
A large number of system calls are exposed to every userland process
|
|
|
|
with many of them going unused for the entire lifetime of the process.
|
|
|
|
As system calls change and mature, bugs are found and eradicated. A
|
|
|
|
certain subset of userland applications benefit by having a reduced set
|
|
|
|
of available system calls. The resulting set reduces the total kernel
|
|
|
|
surface exposed to the application. System call filtering is meant for
|
|
|
|
use with those applications.
|
|
|
|
|
|
|
|
Seccomp filtering provides a means for a process to specify a filter for
|
|
|
|
incoming system calls. The filter is expressed as a Berkeley Packet
|
|
|
|
Filter (BPF) program, as with socket filters, except that the data
|
|
|
|
operated on is related to the system call being made: system call
|
|
|
|
number and the system call arguments. This allows for expressive
|
|
|
|
filtering of system calls using a filter program language with a long
|
|
|
|
history of being exposed to userland and a straightforward data set.
|
|
|
|
|
|
|
|
Additionally, BPF makes it impossible for users of seccomp to fall prey
|
|
|
|
to time-of-check-time-of-use (TOCTOU) attacks that are common in system
|
|
|
|
call interposition frameworks. BPF programs may not dereference
|
|
|
|
pointers which constrains all filters to solely evaluating the system
|
|
|
|
call arguments directly.
|
|
|
|
|
|
|
|
What it isn't
|
2017-05-13 05:51:37 -06:00
|
|
|
=============
|
2012-04-12 15:48:04 -06:00
|
|
|
|
|
|
|
System call filtering isn't a sandbox. It provides a clearly defined
|
|
|
|
mechanism for minimizing the exposed kernel surface. It is meant to be
|
|
|
|
a tool for sandbox developers to use. Beyond that, policy for logical
|
|
|
|
behavior and information flow should be managed with a combination of
|
|
|
|
other system hardening techniques and, potentially, an LSM of your
|
|
|
|
choosing. Expressive, dynamic filters provide further options down this
|
|
|
|
path (avoiding pathological sizes or selecting which of the multiplexed
|
|
|
|
system calls in socketcall() is allowed, for instance) which could be
|
|
|
|
construed, incorrectly, as a more complete sandboxing solution.
|
|
|
|
|
|
|
|
Usage
|
2017-05-13 05:51:37 -06:00
|
|
|
=====
|
2012-04-12 15:48:04 -06:00
|
|
|
|
|
|
|
An additional seccomp mode is added and is enabled using the same
|
|
|
|
prctl(2) call as the strict seccomp. If the architecture has
|
2017-05-13 05:51:37 -06:00
|
|
|
``CONFIG_HAVE_ARCH_SECCOMP_FILTER``, then filters may be added as below:
|
2012-04-12 15:48:04 -06:00
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
``PR_SET_SECCOMP``:
|
2012-04-12 15:48:04 -06:00
|
|
|
Now takes an additional argument which specifies a new filter
|
|
|
|
using a BPF program.
|
|
|
|
The BPF program will be executed over struct seccomp_data
|
|
|
|
reflecting the system call number, arguments, and other
|
|
|
|
metadata. The BPF program must then return one of the
|
|
|
|
acceptable values to inform the kernel which action should be
|
|
|
|
taken.
|
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
Usage::
|
|
|
|
|
2012-04-12 15:48:04 -06:00
|
|
|
prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, prog);
|
|
|
|
|
|
|
|
The 'prog' argument is a pointer to a struct sock_fprog which
|
|
|
|
will contain the filter program. If the program is invalid, the
|
2017-05-13 05:51:37 -06:00
|
|
|
call will return -1 and set errno to ``EINVAL``.
|
2012-04-12 15:48:04 -06:00
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
If ``fork``/``clone`` and ``execve`` are allowed by @prog, any child
|
2012-04-12 15:48:04 -06:00
|
|
|
processes will be constrained to the same filters and system
|
|
|
|
call ABI as the parent.
|
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
Prior to use, the task must call ``prctl(PR_SET_NO_NEW_PRIVS, 1)`` or
|
|
|
|
run with ``CAP_SYS_ADMIN`` privileges in its namespace. If these are not
|
|
|
|
true, ``-EACCES`` will be returned. This requirement ensures that filter
|
2012-04-12 15:48:04 -06:00
|
|
|
programs cannot be applied to child processes with greater privileges
|
|
|
|
than the task that installed them.
|
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
Additionally, if ``prctl(2)`` is allowed by the attached filter,
|
2012-04-12 15:48:04 -06:00
|
|
|
additional filters may be layered on which will increase evaluation
|
|
|
|
time, but allow for further decreasing the attack surface during
|
|
|
|
execution of a process.
|
|
|
|
|
|
|
|
The above call returns 0 on success and non-zero on error.
|
|
|
|
|
|
|
|
Return values
|
2017-05-13 05:51:37 -06:00
|
|
|
=============
|
|
|
|
|
2012-04-12 15:48:04 -06:00
|
|
|
A seccomp filter may return any of the following values. If multiple
|
|
|
|
filters exist, the return value for the evaluation of a given system
|
|
|
|
call will always use the highest precedent value. (For example,
|
seccomp: Implement SECCOMP_RET_KILL_PROCESS action
Right now, SECCOMP_RET_KILL_THREAD (neé SECCOMP_RET_KILL) kills the
current thread. There have been a few requests for this to kill the entire
process (the thread group). This cannot be just changed (discovered when
adding coredump support since coredumping kills the entire process)
because there are userspace programs depending on the thread-kill
behavior.
Instead, implement SECCOMP_RET_KILL_PROCESS, which is 0x80000000, and can
be processed as "-1" by the kernel, below the existing RET_KILL that is
ABI-set to "0". For userspace, SECCOMP_RET_ACTION_FULL is added to expand
the mask to the signed bit. Old userspace using the SECCOMP_RET_ACTION
mask will see SECCOMP_RET_KILL_PROCESS as 0 still, but this would only
be visible when examining the siginfo in a core dump from a RET_KILL_*,
where it will think it was thread-killed instead of process-killed.
Attempts to introduce this behavior via other ways (filter flags,
seccomp struct flags, masked RET_DATA bits) all come with weird
side-effects and baggage. This change preserves the central behavioral
expectations of the seccomp filter engine without putting too great
a burden on changes needed in userspace to use the new action.
The new action is discoverable by userspace through either the new
actions_avail sysctl or through the SECCOMP_GET_ACTION_AVAIL seccomp
operation. If used without checking for availability, old kernels
will treat RET_KILL_PROCESS as RET_KILL_THREAD (since the old mask
will produce RET_KILL_THREAD).
Cc: Paul Moore <paul@paul-moore.com>
Cc: Fabricio Voznika <fvoznika@google.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
2017-08-11 14:12:11 -06:00
|
|
|
``SECCOMP_RET_KILL_PROCESS`` will always take precedence.)
|
2012-04-12 15:48:04 -06:00
|
|
|
|
|
|
|
In precedence order, they are:
|
|
|
|
|
seccomp: Implement SECCOMP_RET_KILL_PROCESS action
Right now, SECCOMP_RET_KILL_THREAD (neé SECCOMP_RET_KILL) kills the
current thread. There have been a few requests for this to kill the entire
process (the thread group). This cannot be just changed (discovered when
adding coredump support since coredumping kills the entire process)
because there are userspace programs depending on the thread-kill
behavior.
Instead, implement SECCOMP_RET_KILL_PROCESS, which is 0x80000000, and can
be processed as "-1" by the kernel, below the existing RET_KILL that is
ABI-set to "0". For userspace, SECCOMP_RET_ACTION_FULL is added to expand
the mask to the signed bit. Old userspace using the SECCOMP_RET_ACTION
mask will see SECCOMP_RET_KILL_PROCESS as 0 still, but this would only
be visible when examining the siginfo in a core dump from a RET_KILL_*,
where it will think it was thread-killed instead of process-killed.
Attempts to introduce this behavior via other ways (filter flags,
seccomp struct flags, masked RET_DATA bits) all come with weird
side-effects and baggage. This change preserves the central behavioral
expectations of the seccomp filter engine without putting too great
a burden on changes needed in userspace to use the new action.
The new action is discoverable by userspace through either the new
actions_avail sysctl or through the SECCOMP_GET_ACTION_AVAIL seccomp
operation. If used without checking for availability, old kernels
will treat RET_KILL_PROCESS as RET_KILL_THREAD (since the old mask
will produce RET_KILL_THREAD).
Cc: Paul Moore <paul@paul-moore.com>
Cc: Fabricio Voznika <fvoznika@google.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
2017-08-11 14:12:11 -06:00
|
|
|
``SECCOMP_RET_KILL_PROCESS``:
|
|
|
|
Results in the entire process exiting immediately without executing
|
|
|
|
the system call. The exit status of the task (``status & 0x7f``)
|
|
|
|
will be ``SIGSYS``, not ``SIGKILL``.
|
|
|
|
|
2017-08-11 13:53:18 -06:00
|
|
|
``SECCOMP_RET_KILL_THREAD``:
|
2012-04-12 15:48:04 -06:00
|
|
|
Results in the task exiting immediately without executing the
|
2017-05-13 05:51:37 -06:00
|
|
|
system call. The exit status of the task (``status & 0x7f``) will
|
|
|
|
be ``SIGSYS``, not ``SIGKILL``.
|
2012-04-12 15:48:04 -06:00
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
``SECCOMP_RET_TRAP``:
|
|
|
|
Results in the kernel sending a ``SIGSYS`` signal to the triggering
|
|
|
|
task without executing the system call. ``siginfo->si_call_addr``
|
2012-10-01 12:40:45 -06:00
|
|
|
will show the address of the system call instruction, and
|
2017-05-13 05:51:37 -06:00
|
|
|
``siginfo->si_syscall`` and ``siginfo->si_arch`` will indicate which
|
2012-10-01 12:40:45 -06:00
|
|
|
syscall was attempted. The program counter will be as though
|
|
|
|
the syscall happened (i.e. it will not point to the syscall
|
|
|
|
instruction). The return value register will contain an arch-
|
|
|
|
dependent value -- if resuming execution, set it to something
|
|
|
|
sensible. (The architecture dependency is because replacing
|
2017-05-13 05:51:37 -06:00
|
|
|
it with ``-ENOSYS`` could overwrite some useful information.)
|
2012-04-12 15:48:04 -06:00
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
The ``SECCOMP_RET_DATA`` portion of the return value will be passed
|
|
|
|
as ``si_errno``.
|
2012-04-12 15:48:04 -06:00
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
``SIGSYS`` triggered by seccomp will have a si_code of ``SYS_SECCOMP``.
|
2012-04-12 15:48:04 -06:00
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
``SECCOMP_RET_ERRNO``:
|
2012-04-12 15:48:04 -06:00
|
|
|
Results in the lower 16-bits of the return value being passed
|
|
|
|
to userland as the errno without executing the system call.
|
|
|
|
|
seccomp: add a return code to trap to userspace
This patch introduces a means for syscalls matched in seccomp to notify
some other task that a particular filter has been triggered.
The motivation for this is primarily for use with containers. For example,
if a container does an init_module(), we obviously don't want to load this
untrusted code, which may be compiled for the wrong version of the kernel
anyway. Instead, we could parse the module image, figure out which module
the container is trying to load and load it on the host.
As another example, containers cannot mount() in general since various
filesystems assume a trusted image. However, if an orchestrator knows that
e.g. a particular block device has not been exposed to a container for
writing, it want to allow the container to mount that block device (that
is, handle the mount for it).
This patch adds functionality that is already possible via at least two
other means that I know about, both of which involve ptrace(): first, one
could ptrace attach, and then iterate through syscalls via PTRACE_SYSCALL.
Unfortunately this is slow, so a faster version would be to install a
filter that does SECCOMP_RET_TRACE, which triggers a PTRACE_EVENT_SECCOMP.
Since ptrace allows only one tracer, if the container runtime is that
tracer, users inside the container (or outside) trying to debug it will not
be able to use ptrace, which is annoying. It also means that older
distributions based on Upstart cannot boot inside containers using ptrace,
since upstart itself uses ptrace to monitor services while starting.
The actual implementation of this is fairly small, although getting the
synchronization right was/is slightly complex.
Finally, it's worth noting that the classic seccomp TOCTOU of reading
memory data from the task still applies here, but can be avoided with
careful design of the userspace handler: if the userspace handler reads all
of the task memory that is necessary before applying its security policy,
the tracee's subsequent memory edits will not be read by the tracer.
Signed-off-by: Tycho Andersen <tycho@tycho.ws>
CC: Kees Cook <keescook@chromium.org>
CC: Andy Lutomirski <luto@amacapital.net>
CC: Oleg Nesterov <oleg@redhat.com>
CC: Eric W. Biederman <ebiederm@xmission.com>
CC: "Serge E. Hallyn" <serge@hallyn.com>
Acked-by: Serge Hallyn <serge@hallyn.com>
CC: Christian Brauner <christian@brauner.io>
CC: Tyler Hicks <tyhicks@canonical.com>
CC: Akihiro Suda <suda.akihiro@lab.ntt.co.jp>
Signed-off-by: Kees Cook <keescook@chromium.org>
2018-12-09 11:24:13 -07:00
|
|
|
``SECCOMP_RET_USER_NOTIF``:
|
2019-03-04 13:31:52 -07:00
|
|
|
Results in a ``struct seccomp_notif`` message sent on the userspace
|
|
|
|
notification fd, if it is attached, or ``-ENOSYS`` if it is not. See
|
|
|
|
below on discussion of how to handle user notifications.
|
seccomp: add a return code to trap to userspace
This patch introduces a means for syscalls matched in seccomp to notify
some other task that a particular filter has been triggered.
The motivation for this is primarily for use with containers. For example,
if a container does an init_module(), we obviously don't want to load this
untrusted code, which may be compiled for the wrong version of the kernel
anyway. Instead, we could parse the module image, figure out which module
the container is trying to load and load it on the host.
As another example, containers cannot mount() in general since various
filesystems assume a trusted image. However, if an orchestrator knows that
e.g. a particular block device has not been exposed to a container for
writing, it want to allow the container to mount that block device (that
is, handle the mount for it).
This patch adds functionality that is already possible via at least two
other means that I know about, both of which involve ptrace(): first, one
could ptrace attach, and then iterate through syscalls via PTRACE_SYSCALL.
Unfortunately this is slow, so a faster version would be to install a
filter that does SECCOMP_RET_TRACE, which triggers a PTRACE_EVENT_SECCOMP.
Since ptrace allows only one tracer, if the container runtime is that
tracer, users inside the container (or outside) trying to debug it will not
be able to use ptrace, which is annoying. It also means that older
distributions based on Upstart cannot boot inside containers using ptrace,
since upstart itself uses ptrace to monitor services while starting.
The actual implementation of this is fairly small, although getting the
synchronization right was/is slightly complex.
Finally, it's worth noting that the classic seccomp TOCTOU of reading
memory data from the task still applies here, but can be avoided with
careful design of the userspace handler: if the userspace handler reads all
of the task memory that is necessary before applying its security policy,
the tracee's subsequent memory edits will not be read by the tracer.
Signed-off-by: Tycho Andersen <tycho@tycho.ws>
CC: Kees Cook <keescook@chromium.org>
CC: Andy Lutomirski <luto@amacapital.net>
CC: Oleg Nesterov <oleg@redhat.com>
CC: Eric W. Biederman <ebiederm@xmission.com>
CC: "Serge E. Hallyn" <serge@hallyn.com>
Acked-by: Serge Hallyn <serge@hallyn.com>
CC: Christian Brauner <christian@brauner.io>
CC: Tyler Hicks <tyhicks@canonical.com>
CC: Akihiro Suda <suda.akihiro@lab.ntt.co.jp>
Signed-off-by: Kees Cook <keescook@chromium.org>
2018-12-09 11:24:13 -07:00
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
``SECCOMP_RET_TRACE``:
|
2012-04-12 15:48:04 -06:00
|
|
|
When returned, this value will cause the kernel to attempt to
|
2017-05-13 05:51:37 -06:00
|
|
|
notify a ``ptrace()``-based tracer prior to executing the system
|
|
|
|
call. If there is no tracer present, ``-ENOSYS`` is returned to
|
2012-04-12 15:48:04 -06:00
|
|
|
userland and the system call is not executed.
|
|
|
|
|
2019-03-04 13:31:51 -07:00
|
|
|
A tracer will be notified if it requests ``PTRACE_O_TRACESECCOMP``
|
2017-05-13 05:51:37 -06:00
|
|
|
using ``ptrace(PTRACE_SETOPTIONS)``. The tracer will be notified
|
|
|
|
of a ``PTRACE_EVENT_SECCOMP`` and the ``SECCOMP_RET_DATA`` portion of
|
2012-04-12 15:48:04 -06:00
|
|
|
the BPF program return value will be available to the tracer
|
2017-05-13 05:51:37 -06:00
|
|
|
via ``PTRACE_GETEVENTMSG``.
|
2012-04-12 15:48:04 -06:00
|
|
|
|
2012-10-01 12:40:45 -06:00
|
|
|
The tracer can skip the system call by changing the syscall number
|
|
|
|
to -1. Alternatively, the tracer can change the system call
|
|
|
|
requested by changing the system call to a valid syscall number. If
|
|
|
|
the tracer asks to skip the system call, then the system call will
|
|
|
|
appear to return the value that the tracer puts in the return value
|
|
|
|
register.
|
|
|
|
|
|
|
|
The seccomp check will not be run again after the tracer is
|
|
|
|
notified. (This means that seccomp-based sandboxes MUST NOT
|
|
|
|
allow use of ptrace, even of other sandboxed processes, without
|
|
|
|
extreme care; ptracers can use this mechanism to escape.)
|
|
|
|
|
seccomp: Action to log before allowing
Add a new action, SECCOMP_RET_LOG, that logs a syscall before allowing
the syscall. At the implementation level, this action is identical to
the existing SECCOMP_RET_ALLOW action. However, it can be very useful when
initially developing a seccomp filter for an application. The developer
can set the default action to be SECCOMP_RET_LOG, maybe mark any
obviously needed syscalls with SECCOMP_RET_ALLOW, and then put the
application through its paces. A list of syscalls that triggered the
default action (SECCOMP_RET_LOG) can be easily gleaned from the logs and
that list can be used to build the syscall whitelist. Finally, the
developer can change the default action to the desired value.
This provides a more friendly experience than seeing the application get
killed, then updating the filter and rebuilding the app, seeing the
application get killed due to a different syscall, then updating the
filter and rebuilding the app, etc.
The functionality is similar to what's supported by the various LSMs.
SELinux has permissive mode, AppArmor has complain mode, SMACK has
bring-up mode, etc.
SECCOMP_RET_LOG is given a lower value than SECCOMP_RET_ALLOW as allow
while logging is slightly more restrictive than quietly allowing.
Unfortunately, the tests added for SECCOMP_RET_LOG are not capable of
inspecting the audit log to verify that the syscall was logged.
With this patch, the logic for deciding if an action will be logged is:
if action == RET_ALLOW:
do not log
else if action == RET_KILL && RET_KILL in actions_logged:
log
else if action == RET_LOG && RET_LOG in actions_logged:
log
else if filter-requests-logging && action in actions_logged:
log
else if audit_enabled && process-is-being-audited:
log
else:
do not log
Signed-off-by: Tyler Hicks <tyhicks@canonical.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
2017-08-10 22:33:57 -06:00
|
|
|
``SECCOMP_RET_LOG``:
|
|
|
|
Results in the system call being executed after it is logged. This
|
|
|
|
should be used by application developers to learn which syscalls their
|
|
|
|
application needs without having to iterate through multiple test and
|
|
|
|
development cycles to build the list.
|
|
|
|
|
|
|
|
This action will only be logged if "log" is present in the
|
|
|
|
actions_logged sysctl string.
|
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
``SECCOMP_RET_ALLOW``:
|
2012-04-12 15:48:04 -06:00
|
|
|
Results in the system call being executed.
|
|
|
|
|
|
|
|
If multiple filters exist, the return value for the evaluation of a
|
|
|
|
given system call will always use the highest precedent value.
|
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
Precedence is only determined using the ``SECCOMP_RET_ACTION`` mask. When
|
2012-04-12 15:48:04 -06:00
|
|
|
multiple filters return values of the same precedence, only the
|
2017-05-13 05:51:37 -06:00
|
|
|
``SECCOMP_RET_DATA`` from the most recently installed filter will be
|
2012-04-12 15:48:04 -06:00
|
|
|
returned.
|
|
|
|
|
|
|
|
Pitfalls
|
2017-05-13 05:51:37 -06:00
|
|
|
========
|
2012-04-12 15:48:04 -06:00
|
|
|
|
|
|
|
The biggest pitfall to avoid during use is filtering on system call
|
|
|
|
number without checking the architecture value. Why? On any
|
|
|
|
architecture that supports multiple system call invocation conventions,
|
|
|
|
the system call numbers may vary based on the specific invocation. If
|
|
|
|
the numbers in the different calling conventions overlap, then checks in
|
|
|
|
the filters may be abused. Always check the arch value!
|
|
|
|
|
|
|
|
Example
|
2017-05-13 05:51:37 -06:00
|
|
|
=======
|
2012-04-12 15:48:04 -06:00
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
The ``samples/seccomp/`` directory contains both an x86-specific example
|
2012-04-12 15:48:04 -06:00
|
|
|
and a more generic example of a higher level macro interface for BPF
|
|
|
|
program generation.
|
|
|
|
|
seccomp: add a return code to trap to userspace
This patch introduces a means for syscalls matched in seccomp to notify
some other task that a particular filter has been triggered.
The motivation for this is primarily for use with containers. For example,
if a container does an init_module(), we obviously don't want to load this
untrusted code, which may be compiled for the wrong version of the kernel
anyway. Instead, we could parse the module image, figure out which module
the container is trying to load and load it on the host.
As another example, containers cannot mount() in general since various
filesystems assume a trusted image. However, if an orchestrator knows that
e.g. a particular block device has not been exposed to a container for
writing, it want to allow the container to mount that block device (that
is, handle the mount for it).
This patch adds functionality that is already possible via at least two
other means that I know about, both of which involve ptrace(): first, one
could ptrace attach, and then iterate through syscalls via PTRACE_SYSCALL.
Unfortunately this is slow, so a faster version would be to install a
filter that does SECCOMP_RET_TRACE, which triggers a PTRACE_EVENT_SECCOMP.
Since ptrace allows only one tracer, if the container runtime is that
tracer, users inside the container (or outside) trying to debug it will not
be able to use ptrace, which is annoying. It also means that older
distributions based on Upstart cannot boot inside containers using ptrace,
since upstart itself uses ptrace to monitor services while starting.
The actual implementation of this is fairly small, although getting the
synchronization right was/is slightly complex.
Finally, it's worth noting that the classic seccomp TOCTOU of reading
memory data from the task still applies here, but can be avoided with
careful design of the userspace handler: if the userspace handler reads all
of the task memory that is necessary before applying its security policy,
the tracee's subsequent memory edits will not be read by the tracer.
Signed-off-by: Tycho Andersen <tycho@tycho.ws>
CC: Kees Cook <keescook@chromium.org>
CC: Andy Lutomirski <luto@amacapital.net>
CC: Oleg Nesterov <oleg@redhat.com>
CC: Eric W. Biederman <ebiederm@xmission.com>
CC: "Serge E. Hallyn" <serge@hallyn.com>
Acked-by: Serge Hallyn <serge@hallyn.com>
CC: Christian Brauner <christian@brauner.io>
CC: Tyler Hicks <tyhicks@canonical.com>
CC: Akihiro Suda <suda.akihiro@lab.ntt.co.jp>
Signed-off-by: Kees Cook <keescook@chromium.org>
2018-12-09 11:24:13 -07:00
|
|
|
Userspace Notification
|
|
|
|
======================
|
|
|
|
|
|
|
|
The ``SECCOMP_RET_USER_NOTIF`` return code lets seccomp filters pass a
|
|
|
|
particular syscall to userspace to be handled. This may be useful for
|
|
|
|
applications like container managers, which wish to intercept particular
|
|
|
|
syscalls (``mount()``, ``finit_module()``, etc.) and change their behavior.
|
|
|
|
|
|
|
|
To acquire a notification FD, use the ``SECCOMP_FILTER_FLAG_NEW_LISTENER``
|
|
|
|
argument to the ``seccomp()`` syscall:
|
|
|
|
|
|
|
|
.. code-block:: c
|
|
|
|
|
|
|
|
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 be
|
|
|
|
passed around via ``SCM_RIGHTS`` or similar. Note that filter fds correspond to
|
|
|
|
a 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 and
|
|
|
|
writes to/from a filter fd are also synchronized, so a filter fd can safely
|
|
|
|
have many readers.
|
|
|
|
|
|
|
|
The interface for a seccomp notification fd consists of two structures:
|
|
|
|
|
|
|
|
.. code-block:: c
|
|
|
|
|
|
|
|
struct seccomp_notif_sizes {
|
|
|
|
__u16 seccomp_notif;
|
|
|
|
__u16 seccomp_notif_resp;
|
|
|
|
__u16 seccomp_data;
|
|
|
|
};
|
|
|
|
|
|
|
|
struct seccomp_notif {
|
|
|
|
__u64 id;
|
|
|
|
__u32 pid;
|
|
|
|
__u32 flags;
|
|
|
|
struct seccomp_data data;
|
|
|
|
};
|
|
|
|
|
|
|
|
struct seccomp_notif_resp {
|
|
|
|
__u64 id;
|
|
|
|
__s64 val;
|
|
|
|
__s32 error;
|
|
|
|
__u32 flags;
|
|
|
|
};
|
|
|
|
|
|
|
|
The ``struct seccomp_notif_sizes`` structure can be used to determine the size
|
|
|
|
of the various structures used in seccomp notifications. The size of ``struct
|
|
|
|
seccomp_data`` may change in the future, so code should use:
|
|
|
|
|
|
|
|
.. code-block:: c
|
|
|
|
|
|
|
|
struct seccomp_notif_sizes sizes;
|
|
|
|
seccomp(SECCOMP_GET_NOTIF_SIZES, 0, &sizes);
|
|
|
|
|
|
|
|
to determine the size of the various structures to allocate. See
|
|
|
|
samples/seccomp/user-trap.c for an example.
|
|
|
|
|
|
|
|
Users can read via ``ioctl(SECCOMP_IOCTL_NOTIF_RECV)`` (or ``poll()``) on a
|
|
|
|
seccomp notification fd to receive a ``struct seccomp_notif``, which contains
|
|
|
|
five members: the input length of the structure, a unique-per-filter ``id``,
|
|
|
|
the ``pid`` of the task which triggered this request (which may be 0 if the
|
|
|
|
task is in a pid ns not visible from the listener's pid namespace), a ``flags``
|
|
|
|
member which for now only has ``SECCOMP_NOTIF_FLAG_SIGNALED``, representing
|
|
|
|
whether or not the notification is a result of a non-fatal signal, and the
|
|
|
|
``data`` passed to seccomp. Userspace can then make a decision based on this
|
|
|
|
information about what to do, and ``ioctl(SECCOMP_IOCTL_NOTIF_SEND)`` a
|
|
|
|
response, indicating what should be returned to userspace. The ``id`` member of
|
|
|
|
``struct seccomp_notif_resp`` should be the same ``id`` as in ``struct
|
|
|
|
seccomp_notif``.
|
|
|
|
|
|
|
|
It is worth noting that ``struct seccomp_data`` contains the values of register
|
|
|
|
arguments to the syscall, but does not contain pointers to memory. The task's
|
|
|
|
memory is accessible to suitably privileged traces via ``ptrace()`` or
|
|
|
|
``/proc/pid/mem``. However, care should be taken to avoid the TOCTOU mentioned
|
|
|
|
above in this document: all arguments being read from the tracee's memory
|
|
|
|
should be read into the tracer's memory before any policy decisions are made.
|
|
|
|
This allows for an atomic decision on syscall arguments.
|
|
|
|
|
2017-08-10 22:33:52 -06:00
|
|
|
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 the
|
|
|
|
``SECCOMP_RET_*`` macros above) in string form. The ordering, from
|
|
|
|
left-to-right, is the least permissive return value to the most
|
|
|
|
permissive return value.
|
2012-04-12 15:48:04 -06:00
|
|
|
|
2017-08-10 22:33:52 -06:00
|
|
|
The list represents the set of seccomp return values supported
|
|
|
|
by the kernel. A userspace program may use this list to
|
|
|
|
determine if the actions found in the ``seccomp.h``, when the
|
|
|
|
program was built, differs from the set of actions actually
|
|
|
|
supported in the current running kernel.
|
2012-04-12 15:48:04 -06:00
|
|
|
|
2017-08-10 22:33:54 -06:00
|
|
|
``actions_logged``:
|
|
|
|
A read-write ordered list of seccomp return values (refer to the
|
|
|
|
``SECCOMP_RET_*`` macros above) that are allowed to be logged. Writes
|
|
|
|
to the file do not need to be in ordered form but reads from the file
|
|
|
|
will be ordered in the same way as the actions_avail sysctl.
|
|
|
|
|
|
|
|
The ``allow`` string is not accepted in the ``actions_logged`` sysctl
|
|
|
|
as it is not possible to log ``SECCOMP_RET_ALLOW`` actions. Attempting
|
|
|
|
to write ``allow`` to the sysctl will result in an EINVAL being
|
|
|
|
returned.
|
|
|
|
|
2012-04-12 15:48:04 -06:00
|
|
|
Adding architecture support
|
2017-05-13 05:51:37 -06:00
|
|
|
===========================
|
2012-04-12 15:48:04 -06:00
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
See ``arch/Kconfig`` for the authoritative requirements. In general, if an
|
2012-04-12 15:48:04 -06:00
|
|
|
architecture supports both ptrace_event and seccomp, it will be able to
|
2017-05-13 05:51:37 -06:00
|
|
|
support seccomp filter with minor fixup: ``SIGSYS`` support and seccomp return
|
|
|
|
value checking. Then it must just add ``CONFIG_HAVE_ARCH_SECCOMP_FILTER``
|
2012-04-12 15:48:04 -06:00
|
|
|
to its arch-specific Kconfig.
|
2012-10-01 12:40:45 -06:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Caveats
|
2017-05-13 05:51:37 -06:00
|
|
|
=======
|
2012-10-01 12:40:45 -06:00
|
|
|
|
|
|
|
The vDSO can cause some system calls to run entirely in userspace,
|
|
|
|
leading to surprises when you run programs on different machines that
|
|
|
|
fall back to real syscalls. To minimize these surprises on x86, make
|
|
|
|
sure you test with
|
2017-05-13 05:51:37 -06:00
|
|
|
``/sys/devices/system/clocksource/clocksource0/current_clocksource`` set to
|
|
|
|
something like ``acpi_pm``.
|
2012-10-01 12:40:45 -06:00
|
|
|
|
|
|
|
On x86-64, vsyscall emulation is enabled by default. (vsyscalls are
|
2017-05-13 05:51:37 -06:00
|
|
|
legacy variants on vDSO calls.) Currently, emulated vsyscalls will
|
|
|
|
honor seccomp, with a few oddities:
|
2012-10-01 12:40:45 -06:00
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
- A return value of ``SECCOMP_RET_TRAP`` will set a ``si_call_addr`` pointing to
|
2012-10-01 12:40:45 -06:00
|
|
|
the vsyscall entry for the given call and not the address after the
|
|
|
|
'syscall' instruction. Any code which wants to restart the call
|
|
|
|
should be aware that (a) a ret instruction has been emulated and (b)
|
|
|
|
trying to resume the syscall will again trigger the standard vsyscall
|
|
|
|
emulation security checks, making resuming the syscall mostly
|
|
|
|
pointless.
|
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
- A return value of ``SECCOMP_RET_TRACE`` will signal the tracer as usual,
|
2012-10-01 12:40:45 -06:00
|
|
|
but the syscall may not be changed to another system call using the
|
|
|
|
orig_rax register. It may only be changed to -1 order to skip the
|
|
|
|
currently 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 modify
|
|
|
|
rip or rsp. (Do not rely on other changes terminating the process.
|
|
|
|
They might work. For example, on some kernels, choosing a syscall
|
|
|
|
that only exists in future kernels will be correctly emulated (by
|
2017-05-13 05:51:37 -06:00
|
|
|
returning ``-ENOSYS``).
|
2012-10-01 12:40:45 -06:00
|
|
|
|
2017-05-13 05:51:37 -06:00
|
|
|
To detect this quirky behavior, check for ``addr & ~0x0C00 ==
|
|
|
|
0xFFFFFFFFFF600000``. (For ``SECCOMP_RET_TRACE``, use rip. For
|
|
|
|
``SECCOMP_RET_TRAP``, use ``siginfo->si_call_addr``.) Do not check any other
|
2012-10-01 12:40:45 -06:00
|
|
|
condition: future kernels may improve vsyscall emulation and current
|
|
|
|
kernels in vsyscall=native mode will behave differently, but the
|
2017-05-13 05:51:37 -06:00
|
|
|
instructions at ``0xF...F600{0,4,8,C}00`` will not be system calls in these
|
2012-10-01 12:40:45 -06:00
|
|
|
cases.
|
|
|
|
|
|
|
|
Note that modern systems are unlikely to use vsyscalls at all -- they
|
|
|
|
are a legacy feature and they are considerably slower than standard
|
|
|
|
syscalls. New code will use the vDSO, and vDSO-issued system calls
|
|
|
|
are indistinguishable from normal system calls.
|