Changes in seccomp_filter.rst

c1966bd1 - Documentation: userspace-api: correct spelling

Sun, 29 Jan 2023 23:10:53 +0000

Documentation: userspace-api: correct spellingCorrect spelling problems for Documentation/userspace-api/ as reportedby codespell.Signed-off-by: Randy Dunlap Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.orgCc: Sean Young Cc: Mauro Carvalho Chehab Cc: linux-media@vger.kernel.orgLink: https://lore.kernel.org/r/20230129231053.20863-10-rdunlap@infradead.orgSigned-off-by: Jonathan Corbet List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

c2aa2dfe - seccomp: Add wait_killable semantic to seccomp user notifier

Tue, 03 May 2022 08:09:56 +0000

seccomp: Add wait_killable semantic to seccomp user notifierThis introduces a per-filter flag (SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV)that makes it so that when notifications are received by the supervisor thenotifying process will transition to wait killable semantics. Although waitkillable isn't a set of semantics formally exposed to userspace, theconcept is searchable. If the notifying process is signaled prior to thenotification being received by the userspace agent, it will be handled asnormal.One quirk about how this is handled is that the notifying processonly switches to TASK_KILLABLE if it receives a wakeup from eitheran addfd or a signal. This is to avoid an unnecessary wakeup ofthe notifying task.The reasons behind switching into wait_killable only after userspacereceives the notification are:* Avoiding unncessary work - Often, workloads will perform work that they may abort (request racing comes to mind). This allows for syscalls to be aborted safely prior to the notification being received by the supervisor. In this, the supervisor doesn't end up doing work that the workload does not want to complete anyways.* Avoiding side effects - We don't want the syscall to be interruptible once the supervisor starts doing work because it may not be trivial to reverse the operation. For example, unmounting a file system may take a long time, and it's hard to rollback, or treat that as reentrant.* Avoid breaking runtimes - Various runtimes do not GC when they are during a syscall (or while running native code that subsequently calls a syscall). If many notifications are blocked, and not picked up by the supervisor, this can get the application into a bad state.Signed-off-by: Sargun Dhillon Signed-off-by: Kees Cook Link: https://lore.kernel.org/r/20220503080958.20220-2-sargun@sargun.me List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

19d67694 - Documentation: seccomp: Fix typo in user notification

Fri, 02 Jul 2021 15:19:27 +0000

Documentation: seccomp: Fix typo in user notificationThe close on exec flag is O_CLOEXEC, not O_EXEC. This patch just fixesthe typo.Suggested-by: Christian Brauner Signed-off-by: Rodrigo Campos Acked-by: Christian Brauner Signed-off-by: Kees Cook Fixes: 0ae71c7720e3 ("seccomp: Support atomic "addfd + send reply"")Link: https://lore.kernel.org/r/20210702151927.263402-1-rodrigo@kinvolk.io List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

0ae71c77 - seccomp: Support atomic "addfd + send reply"

Mon, 17 May 2021 19:39:07 +0000

seccomp: Support atomic "addfd + send reply"Alban Crequy reported a race condition userspace faces when we want toadd some fds and make the syscall return them[1] using seccomp notify.The problem is that currently two different ioctl() calls are needed bythe process handling the syscalls (agent) for another userspace process(target): SECCOMP_IOCTL_NOTIF_ADDFD to allocate the fd andSECCOMP_IOCTL_NOTIF_SEND to return that value. Therefore, it is possiblefor the agent to do the first ioctl to add a file descriptor but thetarget is interrupted (EINTR) before the agent does the second ioctl()call.This patch adds a flag to the ADDFD ioctl() so it adds the fd andreturns that value atomically to the target program, as suggested byKees Cook[2]. This is done by simply allowingseccomp_do_user_notification() to add the fd and return it in this case.Therefore, in this case the target wakes up from the wait inseccomp_do_user_notification() either to interrupt the syscall or to addthe fd and return it.This "allocate an fd and return" functionality is useful for syscallsthat return a file descriptor only, like connect(2). Other syscalls thatreturn a file descriptor but not as return value (or return more thanone fd), like socketpair(), pipe(), recvmsg with SCM_RIGHTs, will notwork with this flag.This effectively combines SECCOMP_IOCTL_NOTIF_ADDFD andSECCOMP_IOCTL_NOTIF_SEND into an atomic opteration. The notification'sreturn value, nor error can be set by the user. Upon successful invocationof the SECCOMP_IOCTL_NOTIF_ADDFD ioctl with the SECCOMP_ADDFD_FLAG_SENDflag, the notifying process's errno will be 0, and the return value willbe the file descriptor number that was installed.[1]: https://lore.kernel.org/lkml/CADZs7q4sw71iNHmV8EOOXhUKJMORPzF7thraxZYddTZsxta-KQ@mail.gmail.com/[2]: https://lore.kernel.org/lkml/202012011322.26DCBC64F2@keescook/Signed-off-by: Rodrigo Campos Signed-off-by: Sargun Dhillon Acked-by: Tycho Andersen Acked-by: Christian Brauner Signed-off-by: Kees Cook Link: https://lore.kernel.org/r/20210517193908.3113-4-sargun@sargun.me List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

aac90292 - Documentation: seccomp: Fix user notification documentation

Mon, 17 May 2021 19:39:05 +0000

Documentation: seccomp: Fix user notification documentationThe documentation had some previously incorrect information about howuserspace notifications (and responses) were handled due to a changefrom a previously proposed patchset.Signed-off-by: Sargun Dhillon Acked-by: Tycho Andersen Acked-by: Christian Brauner Signed-off-by: Kees Cook Fixes: 6a21cc50f0c7 ("seccomp: add a return code to trap to userspace")Cc: stable@vger.kernel.orgLink: https://lore.kernel.org/r/20210517193908.3113-2-sargun@sargun.me List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

2f1ff589 - Documentation: seccomp: unify list indentation

Mon, 04 Mar 2019 20:31:52 +0000

Documentation: seccomp: unify list indentationUse tabs to indent SECCOMP_RET_USER_NOTIF definition, for consistencywith other items in this list.Signed-off-by: Jakub Wilk Acked-by: Kees Cook Signed-off-by: Jonathan Corbet List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

6491126e - Documentation: seccomp: fix reST markup

Mon, 04 Mar 2019 20:31:51 +0000

Documentation: seccomp: fix reST markupSigned-off-by: Jakub Wilk Acked-by: Kees Cook Signed-off-by: Jonathan Corbet List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

6a21cc50 - seccomp: add a return code to trap to userspace

Sun, 09 Dec 2018 18:24:13 +0000

seccomp: add a return code to trap to userspaceThis patch introduces a means for syscalls matched in seccomp to notifysome 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 thisuntrusted code, which may be compiled for the wrong version of the kernelanyway. Instead, we could parse the module image, figure out which modulethe container is trying to load and load it on the host.As another example, containers cannot mount() in general since variousfilesystems assume a trusted image. However, if an orchestrator knows thate.g. a particular block device has not been exposed to a container forwriting, it want to allow the container to mount that block device (thatis, handle the mount for it).This patch adds functionality that is already possible via at least twoother means that I know about, both of which involve ptrace(): first, onecould ptrace attach, and then iterate through syscalls via PTRACE_SYSCALL.Unfortunately this is slow, so a faster version would be to install afilter that does SECCOMP_RET_TRACE, which triggers a PTRACE_EVENT_SECCOMP.Since ptrace allows only one tracer, if the container runtime is thattracer, users inside the container (or outside) trying to debug it will notbe able to use ptrace, which is annoying. It also means that olderdistributions 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 thesynchronization right was/is slightly complex.Finally, it's worth noting that the classic seccomp TOCTOU of readingmemory data from the task still applies here, but can be avoided withcareful design of the userspace handler: if the userspace handler reads allof 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 CC: Kees Cook CC: Andy Lutomirski CC: Oleg Nesterov CC: Eric W. Biederman CC: "Serge E. Hallyn" Acked-by: Serge Hallyn CC: Christian Brauner CC: Tyler Hicks CC: Akihiro Suda Signed-off-by: Kees Cook List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

326bee02 - seccomp: Don't special case audited processes when logging

Fri, 04 May 2018 01:08:15 +0000

seccomp: Don't special case audited processes when loggingSeccomp logging for "handled" actions such as RET_TRAP, RET_TRACE, orRET_ERRNO can be very noisy for processes that are being audited. Thispatch modifies the seccomp logging behavior to treat processes that arebeing inspected via the audit subsystem the same as processes thataren't under inspection. Handled actions will no longer be logged justbecause the process is being inspected. Since v4.14, applications havethe ability to request logging of handled actions by using theSECCOMP_FILTER_FLAG_LOG flag when loading seccomp filters.With this patch, the logic for deciding if an action will be logged is: if action == RET_ALLOW: do not log else if action not in actions_logged: do not log else if action == RET_KILL: log else if action == RET_LOG: log else if filter-requests-logging: log else: do not logReported-by: Steve Grubb Signed-off-by: Tyler Hicks Acked-by: Kees Cook Signed-off-by: Paul Moore List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

0466bdb9 - seccomp: Implement SECCOMP_RET_KILL_PROCESS action

Fri, 11 Aug 2017 20:12:11 +0000

seccomp: Implement SECCOMP_RET_KILL_PROCESS actionRight now, SECCOMP_RET_KILL_THREAD (neé SECCOMP_RET_KILL) kills thecurrent thread. There have been a few requests for this to kill the entireprocess (the thread group). This cannot be just changed (discovered whenadding coredump support since coredumping kills the entire process)because there are userspace programs depending on the thread-killbehavior.Instead, implement SECCOMP_RET_KILL_PROCESS, which is 0x80000000, and canbe processed as "-1" by the kernel, below the existing RET_KILL that isABI-set to "0". For userspace, SECCOMP_RET_ACTION_FULL is added to expandthe mask to the signed bit. Old userspace using the SECCOMP_RET_ACTIONmask will see SECCOMP_RET_KILL_PROCESS as 0 still, but this would onlybe 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 weirdside-effects and baggage. This change preserves the central behavioralexpectations of the seccomp filter engine without putting too greata burden on changes needed in userspace to use the new action.The new action is discoverable by userspace through either the newactions_avail sysctl or through the SECCOMP_GET_ACTION_AVAIL seccompoperation. If used without checking for availability, old kernelswill treat RET_KILL_PROCESS as RET_KILL_THREAD (since the old maskwill produce RET_KILL_THREAD).Cc: Paul Moore Cc: Fabricio Voznika Signed-off-by: Kees Cook List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

fd76875c - seccomp: Rename SECCOMP_RET_KILL to SECCOMP_RET_KILL_THREAD

Fri, 11 Aug 2017 19:53:18 +0000

seccomp: Rename SECCOMP_RET_KILL to SECCOMP_RET_KILL_THREADIn preparation for adding SECCOMP_RET_KILL_PROCESS, rename SECCOMP_RET_KILLto the more accurate SECCOMP_RET_KILL_THREAD.The existing selftest values are intentionally left as SECCOMP_RET_KILLjust to be sure we're exercising the alias.Signed-off-by: Kees Cook List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

59f5cf44 - seccomp: Action to log before allowing

Fri, 11 Aug 2017 04:33:57 +0000

seccomp: Action to log before allowingAdd a new action, SECCOMP_RET_LOG, that logs a syscall before allowingthe syscall. At the implementation level, this action is identical tothe existing SECCOMP_RET_ALLOW action. However, it can be very useful wheninitially developing a seccomp filter for an application. The developercan set the default action to be SECCOMP_RET_LOG, maybe mark anyobviously needed syscalls with SECCOMP_RET_ALLOW, and then put theapplication through its paces. A list of syscalls that triggered thedefault action (SECCOMP_RET_LOG) can be easily gleaned from the logs andthat list can be used to build the syscall whitelist. Finally, thedeveloper can change the default action to the desired value.This provides a more friendly experience than seeing the application getkilled, then updating the filter and rebuilding the app, seeing theapplication get killed due to a different syscall, then updating thefilter 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 hasbring-up mode, etc.SECCOMP_RET_LOG is given a lower value than SECCOMP_RET_ALLOW as allowwhile logging is slightly more restrictive than quietly allowing.Unfortunately, the tests added for SECCOMP_RET_LOG are not capable ofinspecting 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 logelse if action == RET_KILL && RET_KILL in actions_logged: logelse if action == RET_LOG && RET_LOG in actions_logged: logelse if filter-requests-logging && action in actions_logged: logelse if audit_enabled && process-is-being-audited: logelse: do not logSigned-off-by: Tyler Hicks Signed-off-by: Kees Cook List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

0ddec0fc - seccomp: Sysctl to configure actions that are allowed to be logged

Fri, 11 Aug 2017 04:33:54 +0000

seccomp: Sysctl to configure actions that are allowed to be loggedAdminstrators can write to this sysctl to set the seccomp actions thatare allowed to be logged. Any actions not found in this sysctl will notbe logged.For example, all SECCOMP_RET_KILL, SECCOMP_RET_TRAP, andSECCOMP_RET_ERRNO actions would be loggable if "kill trap errno" werewritten to the sysctl. SECCOMP_RET_TRACE actions would not be loggedsince its string representation ("trace") wasn't present in the sysctlvalue.The path to the sysctl is: /proc/sys/kernel/seccomp/actions_loggedThe actions_avail sysctl can be read to discover the valid action namesthat can be written to the actions_logged sysctl with the exception of"allow". SECCOMP_RET_ALLOW actions cannot be configured for logging.The default setting for the sysctl is to allow all actions to be loggedexcept SECCOMP_RET_ALLOW. While only SECCOMP_RET_KILL actions arecurrently logged, an upcoming patch will allow applications to requestadditional actions to be logged.There's one important exception to this sysctl. If a task isspecifically being audited, meaning that an audit context has beenallocated for the task, seccomp will log all actions other thanSECCOMP_RET_ALLOW despite the value of actions_logged. This exceptionpreserves the existing auditing behavior of tasks with an allocatedaudit context.With this patch, the logic for deciding if an action will be logged is:if action == RET_ALLOW: do not logelse if action == RET_KILL && RET_KILL in actions_logged: logelse if audit_enabled && task-is-being-audited: logelse: do not logSigned-off-by: Tyler Hicks Signed-off-by: Kees Cook List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

8e5f1ad1 - seccomp: Sysctl to display available actions

Fri, 11 Aug 2017 04:33:52 +0000

seccomp: Sysctl to display available actionsThis patch creates a read-only sysctl containing an ordered list ofseccomp actions that the kernel supports. The ordering, from left toright, is the lowest action value (kill) to the highest action value(allow). Currently, a read of the sysctl file would return "kill traperrno trace allow". The contents of this sysctl file can be useful foruserspace code as well as the system administrator.The path to the sysctl is: /proc/sys/kernel/seccomp/actions_availlibseccomp and other userspace code can easily determine which actionsthe current kernel supports. The set of actions supported by the currentkernel may be different than the set of action macros found in kernelheaders that were installed where the userspace code was built.In addition, this sysctl will allow system administrators to know whichactions are supported by the kernel and make it easier to configureexactly what seccomp logs through the audit subsystem. Support for thislevel of logging configuration will come in a future patch.Signed-off-by: Tyler Hicks Signed-off-by: Kees Cook List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst

c061f33f - doc: ReSTify seccomp_filter.txt

Sat, 13 May 2017 11:51:37 +0000

doc: ReSTify seccomp_filter.txtThis updates seccomp_filter.txt for ReST markup, and moves it under theuser-space API index, since it describes how application author can useseccomp.Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet List of files: /linux-6.15/Documentation/userspace-api/seccomp_filter.rst