sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget0/translations/zh_CN/userspace-api/seccomp_filtermodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/zh_TW/userspace-api/seccomp_filtermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/it_IT/userspace-api/seccomp_filtermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/ja_JP/userspace-api/seccomp_filtermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/ko_KR/userspace-api/seccomp_filtermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/pt_BR/userspace-api/seccomp_filtermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/sp_SP/userspace-api/seccomp_filtermodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(h+Seccomp BPF (SECure COMPuting with filters)h]h+Seccomp BPF (SECure COMPuting with filters)}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhJ/var/lib/git/docbuild/linux/Documentation/userspace-api/seccomp_filter.rsthKubh)}(hhh](h)}(h Introductionh]h Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXA 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.h]hXA 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.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXSeccomp 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.h]hXSeccomp 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.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hX/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.h]hX/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.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h What it isn'th]hWhat it isn’t}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXtSystem 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.h]hXvSystem 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.}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK!hjhhubeh}(h] what-it-isn-tah ]h"] what it isn'tah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hUsageh]hUsage}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj7hhhhhK,ubh)}(hAn additional seccomp mode is added and is enabled using the same prctl(2) call as the strict seccomp. If the architecture has ``CONFIG_HAVE_ARCH_SECCOMP_FILTER``, then filters may be added as below:h](hAn additional seccomp mode is added and is enabled using the same prctl(2) call as the strict seccomp. If the architecture has }(hjHhhhNhNubhliteral)}(h#``CONFIG_HAVE_ARCH_SECCOMP_FILTER``h]hCONFIG_HAVE_ARCH_SECCOMP_FILTER}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjHubh%, then filters may be added as below:}(hjHhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK.hj7hhubhdefinition_list)}(hhh]hdefinition_list_item)}(hX``PR_SET_SECCOMP``: 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. Usage:: 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 call will return -1 and set errno to ``EINVAL``. If ``fork``/``clone`` and ``execve`` are allowed by @prog, any child processes will be constrained to the same filters and system call ABI as the parent. 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 programs cannot be applied to child processes with greater privileges than the task that installed them. Additionally, if ``prctl(2)`` is allowed by the attached filter, additional filters may be layered on which will increase evaluation time, but allow for further decreasing the attack surface during execution of a process. h](hterm)}(h``PR_SET_SECCOMP``:h](jQ)}(h``PR_SET_SECCOMP``h]hPR_SET_SECCOMP}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjwubh:}(hjwhhhNhNubeh}(h]h ]h"]h$]h&]uh1juhhhKPhjqubh definition)}(hhh](h)}(hX@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.h]hX@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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK3hjubh)}(hUsage::h]hUsage:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK;hjubh literal_block)}(h1prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, prog);h]h1prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, prog);}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jhhhK=hjubh)}(hThe 'prog' argument is a pointer to a struct sock_fprog which will contain the filter program. If the program is invalid, the call will return -1 and set errno to ``EINVAL``.h](hThe ‘prog’ argument is a pointer to a struct sock_fprog which will contain the filter program. If the program is invalid, the call will return -1 and set errno to }(hjhhhNhNubjQ)}(h ``EINVAL``h]hEINVAL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK?hjubh)}(hIf ``fork``/``clone`` and ``execve`` are allowed by @prog, any child processes will be constrained to the same filters and system call ABI as the parent.h](hIf }(hjhhhNhNubjQ)}(h``fork``h]hfork}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh/}(hjhhhNhNubjQ)}(h ``clone``h]hclone}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh and }(hjhhhNhNubjQ)}(h ``execve``h]hexecve}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubhu are allowed by @prog, any child processes will be constrained to the same filters and system call ABI as the parent.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKChjubh)}(hXBPrior 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 programs cannot be applied to child processes with greater privileges than the task that installed them.h](h!Prior to use, the task must call }(hj*hhhNhNubjQ)}(h!``prctl(PR_SET_NO_NEW_PRIVS, 1)``h]hprctl(PR_SET_NO_NEW_PRIVS, 1)}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj*ubh or run with }(hj*hhhNhNubjQ)}(h``CAP_SYS_ADMIN``h]h CAP_SYS_ADMIN}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj*ubh6 privileges in its namespace. If these are not true, }(hj*hhhNhNubjQ)}(h ``-EACCES``h]h-EACCES}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj*ubh will be returned. This requirement ensures that filter programs cannot be applied to child processes with greater privileges than the task that installed them.}(hj*hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKGhjubh)}(hAdditionally, if ``prctl(2)`` is allowed by the attached filter, additional filters may be layered on which will increase evaluation time, but allow for further decreasing the attack surface during execution of a process.h](hAdditionally, if }(hjnhhhNhNubjQ)}(h ``prctl(2)``h]hprctl(2)}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjnubh is allowed by the attached filter, additional filters may be layered on which will increase evaluation time, but allow for further decreasing the attack surface during execution of a process.}(hjnhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKMhjubeh}(h]h ]h"]h$]h&]uh1jhjqubeh}(h]h ]h"]h$]h&]uh1johhhKPhjlubah}(h]h ]h"]h$]h&]uh1jjhj7hhhhhNubh)}(h:The above call returns 0 on success and non-zero on error.h]h:The above call returns 0 on success and non-zero on error.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKRhj7hhubeh}(h]usageah ]h"]usageah$]h&]uh1hhhhhhhhK,ubh)}(hhh](h)}(h Return valuesh]h Return values}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKUubh)}(hXA 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_RET_KILL_PROCESS`` will always take precedence.)h](hA 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, }(hjhhhNhNubjQ)}(h``SECCOMP_RET_KILL_PROCESS``h]hSECCOMP_RET_KILL_PROCESS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh will always take precedence.)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKWhjhhubh)}(hIn precedence order, they are:h]hIn precedence order, they are:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK\hjhhubjk)}(hhh](jp)}(h``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``. h](jv)}(h``SECCOMP_RET_KILL_PROCESS``:h](jQ)}(h``SECCOMP_RET_KILL_PROCESS``h]hSECCOMP_RET_KILL_PROCESS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1juhhhKahjubj)}(hhh]h)}(hResults in the entire process exiting immediately without executing the system call. The exit status of the task (``status & 0x7f``) will be ``SIGSYS``, not ``SIGKILL``.h](hsResults in the entire process exiting immediately without executing the system call. The exit status of the task (}(hjhhhNhNubjQ)}(h``status & 0x7f``h]h status & 0x7f}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh ) will be }(hjhhhNhNubjQ)}(h ``SIGSYS``h]hSIGSYS}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh, not }(hjhhhNhNubjQ)}(h ``SIGKILL``h]hSIGKILL}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK_hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1johhhKahjubjp)}(h``SECCOMP_RET_KILL_THREAD``: Results in the task exiting immediately without executing the system call. The exit status of the task (``status & 0x7f``) will be ``SIGSYS``, not ``SIGKILL``. h](jv)}(h``SECCOMP_RET_KILL_THREAD``:h](jQ)}(h``SECCOMP_RET_KILL_THREAD``h]hSECCOMP_RET_KILL_THREAD}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjoubh:}(hjohhhNhNubeh}(h]h ]h"]h$]h&]uh1juhhhKfhjkubj)}(hhh]h)}(hResults in the task exiting immediately without executing the system call. The exit status of the task (``status & 0x7f``) will be ``SIGSYS``, not ``SIGKILL``.h](hiResults in the task exiting immediately without executing the system call. The exit status of the task (}(hjhhhNhNubjQ)}(h``status & 0x7f``h]h status & 0x7f}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh ) will be }(hjhhhNhNubjQ)}(h ``SIGSYS``h]hSIGSYS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh, not }(hjhhhNhNubjQ)}(h ``SIGKILL``h]hSIGKILL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKdhjubah}(h]h ]h"]h$]h&]uh1jhjkubeh}(h]h ]h"]h$]h&]uh1johhhKfhjhhubjp)}(hX,``SECCOMP_RET_TRAP``: Results in the kernel sending a ``SIGSYS`` signal to the triggering task without executing the system call. ``siginfo->si_call_addr`` will show the address of the system call instruction, and ``siginfo->si_syscall`` and ``siginfo->si_arch`` will indicate which 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 it with ``-ENOSYS`` could overwrite some useful information.) The ``SECCOMP_RET_DATA`` portion of the return value will be passed as ``si_errno``. ``SIGSYS`` triggered by seccomp will have a si_code of ``SYS_SECCOMP``. h](jv)}(h``SECCOMP_RET_TRAP``:h](jQ)}(h``SECCOMP_RET_TRAP``h]hSECCOMP_RET_TRAP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1juhhhKwhjubj)}(hhh](h)}(hXvResults in the kernel sending a ``SIGSYS`` signal to the triggering task without executing the system call. ``siginfo->si_call_addr`` will show the address of the system call instruction, and ``siginfo->si_syscall`` and ``siginfo->si_arch`` will indicate which 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 it with ``-ENOSYS`` could overwrite some useful information.)h](h Results in the kernel sending a }(hjhhhNhNubjQ)}(h ``SIGSYS``h]hSIGSYS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubhB signal to the triggering task without executing the system call. }(hjhhhNhNubjQ)}(h``siginfo->si_call_addr``h]hsiginfo->si_call_addr}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh; will show the address of the system call instruction, and }(hjhhhNhNubjQ)}(h``siginfo->si_syscall``h]hsiginfo->si_syscall}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh and }(hjhhhNhNubjQ)}(h``siginfo->si_arch``h]hsiginfo->si_arch}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubhXQ will indicate which 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 it with }(hjhhhNhNubjQ)}(h ``-ENOSYS``h]h-ENOSYS}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh* could overwrite some useful information.)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKihjubh)}(hTThe ``SECCOMP_RET_DATA`` portion of the return value will be passed as ``si_errno``.h](hThe }(hjihhhNhNubjQ)}(h``SECCOMP_RET_DATA``h]hSECCOMP_RET_DATA}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjiubh/ portion of the return value will be passed as }(hjihhhNhNubjQ)}(h ``si_errno``h]hsi_errno}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjiubh.}(hjihhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKthjubh)}(hG``SIGSYS`` triggered by seccomp will have a si_code of ``SYS_SECCOMP``.h](jQ)}(h ``SIGSYS``h]hSIGSYS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh- triggered by seccomp will have a si_code of }(hjhhhNhNubjQ)}(h``SYS_SECCOMP``h]h SYS_SECCOMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKwhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1johhhKwhjhhubjp)}(h``SECCOMP_RET_ERRNO``: Results in the lower 16-bits of the return value being passed to userland as the errno without executing the system call. h](jv)}(h``SECCOMP_RET_ERRNO``:h](jQ)}(h``SECCOMP_RET_ERRNO``h]hSECCOMP_RET_ERRNO}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1juhhhK{hjubj)}(hhh]h)}(hyResults in the lower 16-bits of the return value being passed to userland as the errno without executing the system call.h]hyResults in the lower 16-bits of the return value being passed to userland as the errno without executing the system call.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKzhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1johhhK{hjhhubjp)}(h``SECCOMP_RET_USER_NOTIF``: 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. h](jv)}(h``SECCOMP_RET_USER_NOTIF``:h](jQ)}(h``SECCOMP_RET_USER_NOTIF``h]hSECCOMP_RET_USER_NOTIF}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1juhhhKhjubj)}(hhh]h)}(hResults 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.h](h Results in a }(hj5hhhNhNubjQ)}(h``struct seccomp_notif``h]hstruct seccomp_notif}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj5ubhF message sent on the userspace notification fd, if it is attached, or }(hj5hhhNhNubjQ)}(h ``-ENOSYS``h]h-ENOSYS}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj5ubhK if it is not. See below on discussion of how to handle user notifications.}(hj5hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK~hj2ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1johhhKhjhhubjp)}(hXu``SECCOMP_RET_TRACE``: When returned, this value will cause the kernel to attempt to notify a ``ptrace()``-based tracer prior to executing the system call. If there is no tracer present, ``-ENOSYS`` is returned to userland and the system call is not executed. A tracer will be notified if it requests ``PTRACE_O_TRACESECCOMP`` using ``ptrace(PTRACE_SETOPTIONS)``. The tracer will be notified of a ``PTRACE_EVENT_SECCOMP`` and the ``SECCOMP_RET_DATA`` portion of the BPF program return value will be available to the tracer via ``PTRACE_GETEVENTMSG``. 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.) h](jv)}(h``SECCOMP_RET_TRACE``:h](jQ)}(h``SECCOMP_RET_TRACE``h]hSECCOMP_RET_TRACE}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjwubh:}(hjwhhhNhNubeh}(h]h ]h"]h$]h&]uh1juhhhKhjsubj)}(hhh](h)}(hWhen returned, this value will cause the kernel to attempt to notify a ``ptrace()``-based tracer prior to executing the system call. If there is no tracer present, ``-ENOSYS`` is returned to userland and the system call is not executed.h](hGWhen returned, this value will cause the kernel to attempt to notify a }(hjhhhNhNubjQ)}(h ``ptrace()``h]hptrace()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubhR-based tracer prior to executing the system call. If there is no tracer present, }(hjhhhNhNubjQ)}(h ``-ENOSYS``h]h-ENOSYS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh= is returned to userland and the system call is not executed.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hX#A tracer will be notified if it requests ``PTRACE_O_TRACESECCOMP`` using ``ptrace(PTRACE_SETOPTIONS)``. The tracer will be notified of a ``PTRACE_EVENT_SECCOMP`` and the ``SECCOMP_RET_DATA`` portion of the BPF program return value will be available to the tracer via ``PTRACE_GETEVENTMSG``.h](h)A tracer will be notified if it requests }(hjhhhNhNubjQ)}(h``PTRACE_O_TRACESECCOMP``h]hPTRACE_O_TRACESECCOMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh using }(hjhhhNhNubjQ)}(h``ptrace(PTRACE_SETOPTIONS)``h]hptrace(PTRACE_SETOPTIONS)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh$. The tracer will be notified of a }(hjhhhNhNubjQ)}(h``PTRACE_EVENT_SECCOMP``h]hPTRACE_EVENT_SECCOMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh and the }(hjhhhNhNubjQ)}(h``SECCOMP_RET_DATA``h]hSECCOMP_RET_DATA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubhM portion of the BPF program return value will be available to the tracer via }(hjhhhNhNubjQ)}(h``PTRACE_GETEVENTMSG``h]hPTRACE_GETEVENTMSG}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hXUThe 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.h]hXUThe 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.}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hThe 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.)h]hThe 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.)}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjsubeh}(h]h ]h"]h$]h&]uh1johhhKhjhhubjp)}(hXe``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. h](jv)}(h``SECCOMP_RET_LOG``:h](jQ)}(h``SECCOMP_RET_LOG``h]hSECCOMP_RET_LOG}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj\ubh:}(hj\hhhNhNubeh}(h]h ]h"]h$]h&]uh1juhhhKhjXubj)}(hhh](h)}(hResults 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.h]hResults 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.}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjxubh)}(hXThis action will only be logged if "log" is present in the actions_logged sysctl string.h]h\This action will only be logged if “log” is present in the actions_logged sysctl string.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjxubeh}(h]h ]h"]h$]h&]uh1jhjXubeh}(h]h ]h"]h$]h&]uh1johhhKhjhhubjp)}(hB``SECCOMP_RET_ALLOW``: Results in the system call being executed. h](jv)}(h``SECCOMP_RET_ALLOW``:h](jQ)}(h``SECCOMP_RET_ALLOW``h]hSECCOMP_RET_ALLOW}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1juhhhKhjubj)}(hhh]h)}(h*Results in the system call being executed.h]h*Results in the system call being executed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1johhhKhjhhubeh}(h]h ]h"]h$]h&]uh1jjhjhhhhhNubh)}(hIf multiple filters exist, the return value for the evaluation of a given system call will always use the highest precedent value.h]hIf multiple filters exist, the return value for the evaluation of a given system call will always use the highest precedent value.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hPrecedence is only determined using the ``SECCOMP_RET_ACTION`` mask. When multiple filters return values of the same precedence, only the ``SECCOMP_RET_DATA`` from the most recently installed filter will be returned.h](h(Precedence is only determined using the }(hjhhhNhNubjQ)}(h``SECCOMP_RET_ACTION``h]hSECCOMP_RET_ACTION}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubhM mask. When multiple filters return values of the same precedence, only the }(hjhhhNhNubjQ)}(h``SECCOMP_RET_DATA``h]hSECCOMP_RET_DATA}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh: from the most recently installed filter will be returned.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] return-valuesah ]h"] return valuesah$]h&]uh1hhhhhhhhKUubh)}(hhh](h)}(hPitfallsh]hPitfalls}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj.hhhhhKubh)}(hXThe 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!h]hXThe 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!}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj.hhubeh}(h]pitfallsah ]h"]pitfallsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hExampleh]hExample}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjUhhhhhKubh)}(hThe ``samples/seccomp/`` directory contains both an x86-specific example and a more generic example of a higher level macro interface for BPF program generation.h](hThe }(hjfhhhNhNubjQ)}(h``samples/seccomp/``h]hsamples/seccomp/}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjfubh directory contains both an x86-specific example and a more generic example of a higher level macro interface for BPF program generation.}(hjfhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjUhhubeh}(h]exampleah ]h"]exampleah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hUserspace Notificationh]hUserspace Notification}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hX!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.h](hThe }(hjhhhNhNubjQ)}(h``SECCOMP_RET_USER_NOTIF``h]hSECCOMP_RET_USER_NOTIF}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh 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 (}(hjhhhNhNubjQ)}(h ``mount()``h]hmount()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh, }(hjhhhNhNubjQ)}(h``finit_module()``h]hfinit_module()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh", etc.) and change their behavior.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hqTo acquire a notification FD, use the ``SECCOMP_FILTER_FLAG_NEW_LISTENER`` argument to the ``seccomp()`` syscall:h](h&To acquire a notification FD, use the }(hjhhhNhNubjQ)}(h$``SECCOMP_FILTER_FLAG_NEW_LISTENER``h]h SECCOMP_FILTER_FLAG_NEW_LISTENER}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh argument to the }(hjhhhNhNubjQ)}(h ``seccomp()``h]h seccomp()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh syscall:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hOfd = seccomp(SECCOMP_SET_MODE_FILTER, SECCOMP_FILTER_FLAG_NEW_LISTENER, &prog);h]hOfd = seccomp(SECCOMP_SET_MODE_FILTER, SECCOMP_FILTER_FLAG_NEW_LISTENER, &prog);}hjsbah}(h]h ]h"]h$]h&]jjforcelanguagechighlight_args}uh1jhhhKhjhhubh)}(hXwhich (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.h](hawhich (on success) will return a listener fd for the filter, which can then be passed around via }(hj(hhhNhNubjQ)}(h``SCM_RIGHTS``h]h SCM_RIGHTS}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj(ubhX% 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.}(hj(hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hGThe interface for a seccomp notification fd consists of two structures:h]hGThe interface for a seccomp notification fd consists of two structures:}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hX4struct 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; };h]hX4struct 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; };}hjVsbah}(h]h ]h"]h$]h&]jjj#j$j%j&}uh1jhhhKhjhhubh)}(hThe ``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:h](hThe }(hjehhhNhNubjQ)}(h``struct seccomp_notif_sizes``h]hstruct seccomp_notif_sizes}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjeubhr structure can be used to determine the size of the various structures used in seccomp notifications. The size of }(hjehhhNhNubjQ)}(h``struct seccomp_data``h]hstruct seccomp_data}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjeubh. may change in the future, so code should use:}(hjehhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hNstruct seccomp_notif_sizes sizes; seccomp(SECCOMP_GET_NOTIF_SIZES, 0, &sizes);h]hNstruct seccomp_notif_sizes sizes; seccomp(SECCOMP_GET_NOTIF_SIZES, 0, &sizes);}hjsbah}(h]h ]h"]h$]h&]jjj#j$j%j&}uh1jhhhKhjhhubh)}(hlto determine the size of the various structures to allocate. See samples/seccomp/user-trap.c for an example.h]hlto determine the size of the various structures to allocate. See samples/seccomp/user-trap.c for an example.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX 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). The notification also contains the ``data`` passed to seccomp, and a filters flag. The structure should be zeroed out prior to calling the ioctl.h](hUsers can read via }(hjhhhNhNubjQ)}(h#``ioctl(SECCOMP_IOCTL_NOTIF_RECV)``h]hioctl(SECCOMP_IOCTL_NOTIF_RECV)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh (or }(hjhhhNhNubjQ)}(h ``poll()``h]hpoll()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh,) on a seccomp notification fd to receive a }(hjhhhNhNubjQ)}(h``struct seccomp_notif``h]hstruct seccomp_notif}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubhV, which contains five members: the input length of the structure, a unique-per-filter }(hjhhhNhNubjQ)}(h``id``h]hid}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh, the }(hjhhhNhNubjQ)}(h``pid``h]hpid}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubh 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). The notification also contains the }(hjhhhNhNubjQ)}(h``data``h]hdata}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjubhf passed to seccomp, and a filters flag. The structure should be zeroed out prior to calling the ioctl.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX 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``.h](hSUserspace can then make a decision based on this information about what to do, and }(hj. hhhNhNubjQ)}(h#``ioctl(SECCOMP_IOCTL_NOTIF_SEND)``h]hioctl(SECCOMP_IOCTL_NOTIF_SEND)}(hj6 hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj. ubhB a response, indicating what should be returned to userspace. The }(hj. hhhNhNubjQ)}(h``id``h]hid}(hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj. ubh member of }(hj. hhhNhNubjQ)}(h``struct seccomp_notif_resp``h]hstruct seccomp_notif_resp}(hjZ hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj. ubh should be the same }(hj. hhhNhNubjQ)}(h``id``h]hid}(hjl hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj. ubh as in }(hj. hhhNhNubjQ)}(h``struct seccomp_notif``h]hstruct seccomp_notif}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj. ubh.}(hj. hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXUserspace can also add file descriptors to the notifying process via ``ioctl(SECCOMP_IOCTL_NOTIF_ADDFD)``. The ``id`` member of ``struct seccomp_notif_addfd`` should be the same ``id`` as in ``struct seccomp_notif``. The ``newfd_flags`` flag may be used to set flags like O_CLOEXEC on the file descriptor in the notifying process. If the supervisor wants to inject the file descriptor with a specific number, the ``SECCOMP_ADDFD_FLAG_SETFD`` flag can be used, and set the ``newfd`` member to the specific number to use. If that file descriptor is already open in the notifying process it will be replaced. The supervisor can also add an FD, and respond atomically by using the ``SECCOMP_ADDFD_FLAG_SEND`` flag and the return value will be the injected file descriptor number.h](hEUserspace can also add file descriptors to the notifying process via }(hj hhhNhNubjQ)}(h$``ioctl(SECCOMP_IOCTL_NOTIF_ADDFD)``h]h ioctl(SECCOMP_IOCTL_NOTIF_ADDFD)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh. The }(hj hhhNhNubjQ)}(h``id``h]hid}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh member of }(hj hhhNhNubjQ)}(h``struct seccomp_notif_addfd``h]hstruct seccomp_notif_addfd}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh should be the same }(hj hhhNhNubjQ)}(h``id``h]hid}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh as in }(hj hhhNhNubjQ)}(h``struct seccomp_notif``h]hstruct seccomp_notif}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh. The }hj sbjQ)}(h``newfd_flags``h]h newfd_flags}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh flag may be used to set flags like O_CLOEXEC on the file descriptor in the notifying process. If the supervisor wants to inject the file descriptor with a specific number, the }(hj hhhNhNubjQ)}(h``SECCOMP_ADDFD_FLAG_SETFD``h]hSECCOMP_ADDFD_FLAG_SETFD}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh flag can be used, and set the }(hj hhhNhNubjQ)}(h ``newfd``h]hnewfd}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh member to the specific number to use. If that file descriptor is already open in the notifying process it will be replaced. The supervisor can also add an FD, and respond atomically by using the }(hj hhhNhNubjQ)}(h``SECCOMP_ADDFD_FLAG_SEND``h]hSECCOMP_ADDFD_FLAG_SEND}(hj. hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubhG flag and the return value will be the injected file descriptor number.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXeThe notifying process can be preempted, resulting in the notification being aborted. This can be problematic when trying to take actions on behalf of the notifying process that are long-running and typically retryable (mounting a filesystem). Alternatively, at filter installation time, the ``SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV`` flag can be set. This flag makes it such that when a user notification is received by the supervisor, the notifying process will ignore non-fatal signals until the response is sent. Signals that are sent prior to the notification being received by userspace are handled normally.h](hX#The notifying process can be preempted, resulting in the notification being aborted. This can be problematic when trying to take actions on behalf of the notifying process that are long-running and typically retryable (mounting a filesystem). Alternatively, at filter installation time, the }(hjF hhhNhNubjQ)}(h*``SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV``h]h&SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV}(hjN hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjF ubhX flag can be set. This flag makes it such that when a user notification is received by the supervisor, the notifying process will ignore non-fatal signals until the response is sent. Signals that are sent prior to the notification being received by userspace are handled normally.}(hjF hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXIt 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.h](hIt is worth noting that }(hjf hhhNhNubjQ)}(h``struct seccomp_data``h]hstruct seccomp_data}(hjn hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjf ubh 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 }(hjf hhhNhNubjQ)}(h ``ptrace()``h]hptrace()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjf ubh or }(hjf hhhNhNubjQ)}(h``/proc/pid/mem``h]h /proc/pid/mem}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjf ubhX. 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.}(hjf hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]userspace-notificationah ]h"]userspace notificationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hSysctlsh]hSysctls}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM%ubh)}(hSeccomp's sysctl files can be found in the ``/proc/sys/kernel/seccomp/`` directory. Here's a description of each file in that directory:h](h-Seccomp’s sysctl files can be found in the }(hj hhhNhNubjQ)}(h``/proc/sys/kernel/seccomp/``h]h/proc/sys/kernel/seccomp/}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubhB directory. Here’s a description of each file in that directory:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM'hj hhubjk)}(hhh](jp)}(hX ``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. 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. h](jv)}(h``actions_avail``:h](jQ)}(h``actions_avail``h]h actions_avail}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1juhhhM4hj ubj)}(hhh](h)}(hA 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.h](h@A read-only ordered list of seccomp return values (refer to the }(hj hhhNhNubjQ)}(h``SECCOMP_RET_*``h]h SECCOMP_RET_*}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh macros above) in string form. The ordering, from left-to-right, is the least permissive return value to the most permissive return value.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM+hj ubh)}(hXThe 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.h](hThe 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 }(hj) hhhNhNubjQ)}(h ``seccomp.h``h]h seccomp.h}(hj1 hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj) ubho, when the program was built, differs from the set of actions actually supported in the current running kernel.}(hj) hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM0hj ubeh}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1johhhM4hj ubjp)}(hX``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. h](jv)}(h``actions_logged``:h](jQ)}(h``actions_logged``h]hactions_logged}(hj] hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjY ubh:}(hjY hhhNhNubeh}(h]h ]h"]h$]h&]uh1juhhhM?hjU ubj)}(hhh](h)}(hX 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.h](hAA read-write ordered list of seccomp return values (refer to the }(hjx hhhNhNubjQ)}(h``SECCOMP_RET_*``h]h SECCOMP_RET_*}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjx ubh 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.}(hjx hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM7hju ubh)}(hThe ``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.h](hThe }(hj hhhNhNubjQ)}(h ``allow``h]hallow}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh string is not accepted in the }(hj hhhNhNubjQ)}(h``actions_logged``h]hactions_logged}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh% sysctl as it is not possible to log }(hj hhhNhNubjQ)}(h``SECCOMP_RET_ALLOW``h]hSECCOMP_RET_ALLOW}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh actions. Attempting to write }(hj hhhNhNubjQ)}(h ``allow``h]hallow}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh7 to the sysctl will result in an EINVAL being returned.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM<hju ubeh}(h]h ]h"]h$]h&]uh1jhjU ubeh}(h]h ]h"]h$]h&]uh1johhhM?hj hhubeh}(h]h ]h"]h$]h&]uh1jjhj hhhhhNubeh}(h]sysctlsah ]h"]sysctlsah$]h&]uh1hhhhhhhhM%ubh)}(hhh](h)}(hAdding architecture supporth]hAdding architecture support}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMBubh)}(hXKSee ``arch/Kconfig`` for the authoritative requirements. In general, if an architecture supports both ptrace_event and seccomp, it will be able to support seccomp filter with minor fixup: ``SIGSYS`` support and seccomp return value checking. Then it must just add ``CONFIG_HAVE_ARCH_SECCOMP_FILTER`` to its arch-specific Kconfig.h](hSee }(hj hhhNhNubjQ)}(h``arch/Kconfig``h]h arch/Kconfig}(hj! hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh for the authoritative requirements. In general, if an architecture supports both ptrace_event and seccomp, it will be able to support seccomp filter with minor fixup: }(hj hhhNhNubjQ)}(h ``SIGSYS``h]hSIGSYS}(hj3 hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubhC support and seccomp return value checking. Then it must just add }(hj hhhNhNubjQ)}(h#``CONFIG_HAVE_ARCH_SECCOMP_FILTER``h]hCONFIG_HAVE_ARCH_SECCOMP_FILTER}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh to its arch-specific Kconfig.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMDhj hhubeh}(h]adding-architecture-supportah ]h"]adding architecture supportah$]h&]uh1hhhhhhhhMBubh)}(hhh](h)}(hCaveatsh]hCaveats}(hjh hhhNhNubah}(h]h ]h"]h$]h&]uh1hhje hhhhhMMubh)}(hXIThe 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 ``/sys/devices/system/clocksource/clocksource0/current_clocksource`` set to something like ``acpi_pm``.h](hThe 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 }(hjv hhhNhNubjQ)}(hD``/sys/devices/system/clocksource/clocksource0/current_clocksource``h]h@/sys/devices/system/clocksource/clocksource0/current_clocksource}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjv ubh set to something like }(hjv hhhNhNubjQ)}(h ``acpi_pm``h]hacpi_pm}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhjv ubh.}(hjv hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMOhje hhubh)}(hOn x86-64, vsyscall emulation is enabled by default. (vsyscalls are legacy variants on vDSO calls.) Currently, emulated vsyscalls will honor seccomp, with a few oddities:h]hOn x86-64, vsyscall emulation is enabled by default. (vsyscalls are legacy variants on vDSO calls.) Currently, emulated vsyscalls will honor seccomp, with a few oddities:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMVhje hhubh bullet_list)}(hhh](h list_item)}(hXA return value of ``SECCOMP_RET_TRAP`` will set a ``si_call_addr`` pointing to 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. h]h)}(hXA return value of ``SECCOMP_RET_TRAP`` will set a ``si_call_addr`` pointing to 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.h](hA return value of }(hj hhhNhNubjQ)}(h``SECCOMP_RET_TRAP``h]hSECCOMP_RET_TRAP}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh will set a }(hj hhhNhNubjQ)}(h``si_call_addr``h]h si_call_addr}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubhXi pointing to 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.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMZhj ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubj )}(hX}A return value of ``SECCOMP_RET_TRACE`` will signal the tracer as usual, 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 returning ``-ENOSYS``). h]h)}(hX|A return value of ``SECCOMP_RET_TRACE`` will signal the tracer as usual, 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 returning ``-ENOSYS``).h](hA return value of }(hj hhhNhNubjQ)}(h``SECCOMP_RET_TRACE``h]hSECCOMP_RET_TRACE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubhXH will signal the tracer as usual, 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 returning }(hj hhhNhNubjQ)}(h ``-ENOSYS``h]h-ENOSYS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj ubh).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMbhj ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1j hhhMZhje hhubh)}(hXTo 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 condition: future kernels may improve vsyscall emulation and current kernels in vsyscall=native mode will behave differently, but the instructions at ``0xF...F600{0,4,8,C}00`` will not be system calls in these cases.h](h*To detect this quirky behavior, check for }(hj= hhhNhNubjQ)}(h(``addr & ~0x0C00 == 0xFFFFFFFFFF600000``h]h$addr & ~0x0C00 == 0xFFFFFFFFFF600000}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj= ubh. (For }(hj= hhhNhNubjQ)}(h``SECCOMP_RET_TRACE``h]hSECCOMP_RET_TRACE}(hjW hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj= ubh, use rip. For }(hj= hhhNhNubjQ)}(h``SECCOMP_RET_TRAP``h]hSECCOMP_RET_TRAP}(hji hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj= ubh, use }(hj= hhhNhNubjQ)}(h``siginfo->si_call_addr``h]hsiginfo->si_call_addr}(hj{ hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj= ubh.) Do not check any other condition: future kernels may improve vsyscall emulation and current kernels in vsyscall=native mode will behave differently, but the instructions at }(hj= hhhNhNubjQ)}(h``0xF...F600{0,4,8,C}00``h]h0xF...F600{0,4,8,C}00}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jPhj= ubh) will not be system calls in these cases.}(hj= hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMmhje hhubh)}(hNote 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.h]hNote 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. }(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMuhje hhubeh}(h]caveatsah ]h"]caveatsah$]h&]uh1hhhhhhhhMMubeh}(h])seccomp-bpf-secure-computing-with-filtersah ]h"]+seccomp bpf (secure computing with filters)ah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehʌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j j j j j4j1jjj+j(jRjOjjj j j j jb j_ j j u nametypes}(j j j4jj+jRjj j jb j uh}(j hj hj1jjj7j(jjOj.jjUj jj j j_ j j je u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.