Debian Codegraph @

upstream/debian-unstable/man2/seccomp.2

raw
1 .\" Copyright 2008-2017 Michael Kerrisk <[email protected]>
2 .\" Copyright 2012, Will Drewry <[email protected]>
3 .\" Copyright 2017, Tyler Hicks <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH seccomp 2 2026-02-10 "Linux man-pages 6.18"
9 .SH NAME
10 seccomp \- operate on Secure Computing state of the process
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .BR "#include <linux/seccomp.h>" " /* Definition of " SECCOMP_* " constants */"
17 .BR "#include <linux/filter.h>" " /* Definition of " "struct sock_fprog" " */"
18 .BR "#include <linux/audit.h>" " /* Definition of " AUDIT_* " constants */"
19 .BR "#include <linux/signal.h>" " /* Definition of " SIG* " constants */"
20 .BR "#include <sys/ptrace.h>" " /* Definition of " PTRACE_* " constants */"
21 .\" Kees Cook noted: Anything that uses SECCOMP_RET_TRACE returns will
22 .\" need <sys/ptrace.h>
23 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
24 .B #include <unistd.h>
25 .P
26 .BI "int syscall(SYS_seccomp, unsigned int " operation ", unsigned int " flags ,
27 .BI " void *" args );
28 .fi
29 .P
30 .IR Note :
31 glibc provides no wrapper for
32 .BR seccomp (),
33 necessitating the use of
34 .BR syscall (2).
35 .SH DESCRIPTION
36 The
37 .BR seccomp ()
38 system call operates on the Secure Computing (seccomp) state of the
39 calling process.
40 .P
41 Currently, Linux supports the following
42 .I operation
43 values:
44 .TP
45 .B SECCOMP_SET_MODE_STRICT
46 The only system calls that the calling thread is permitted to make are
47 .BR read (2),
48 .BR write (2),
49 .BR _exit (2)
50 (but not
51 .BR exit_group (2)),
52 and
53 .BR sigreturn (2).
54 Other system calls result in the termination of the calling thread,
55 or termination of the entire process with the
56 .B SIGKILL
57 signal when there is only one thread.
58 Strict secure computing mode is useful for number-crunching
59 applications that may need to execute untrusted byte code, perhaps
60 obtained by reading from a pipe or socket.
61 .IP
62 Note that although the calling thread can no longer call
63 .BR sigprocmask (2),
64 it can use
65 .BR sigreturn (2)
66 to block all signals apart from
67 .B SIGKILL
68 and
69 .BR SIGSTOP .
70 This means that
71 .BR alarm (2)
72 (for example) is not sufficient for restricting the process's execution time.
73 Instead, to reliably terminate the process,
74 .B SIGKILL
75 must be used.
76 This can be done by using
77 .BR timer_create (2)
78 with
79 .B SIGEV_SIGNAL
80 and
81 .I sigev_signo
82 set to
83 .BR SIGKILL ,
84 or by using
85 .BR setrlimit (2)
86 to set the hard limit for
87 .BR RLIMIT_CPU .
88 .IP
89 This operation is available only if the kernel is configured with
90 .B CONFIG_SECCOMP
91 enabled.
92 .IP
93 The value of
94 .I flags
95 must be 0, and
96 .I args
97 must be NULL.
98 .IP
99 This operation is functionally identical to the call:
100 .IP
101 .in +4n
102 .EX
103 prctl(PR_SET_SECCOMP, SECCOMP_MODE_STRICT);
104 .EE
105 .in
106 .TP
107 .B SECCOMP_SET_MODE_FILTER
108 The system calls allowed are defined by a pointer to a Berkeley Packet
109 Filter (BPF) passed via
110 .IR args .
111 This argument is a pointer to a
112 .IR "struct\~sock_fprog" ;
113 it can be designed to filter arbitrary system calls and system call
114 arguments.
115 If the filter is invalid,
116 .BR seccomp ()
117 fails, returning
118 .B EINVAL
119 in
120 .IR errno .
121 .IP
122 If
123 .BR fork (2)
124 or
125 .BR clone (2)
126 is allowed by the filter, any child processes will be constrained to
127 the same system call filters as the parent.
128 If
129 .BR execve (2)
130 is allowed,
131 the existing filters will be preserved across a call to
132 .BR execve (2).
133 .IP
134 In order to use the
135 .B SECCOMP_SET_MODE_FILTER
136 operation, either the calling thread must have the
137 .B CAP_SYS_ADMIN
138 capability in its user namespace, or the thread must already have the
139 .I no_new_privs
140 bit set.
141 If that bit was not already set by an ancestor of this thread,
142 the thread must make the following call:
143 .IP
144 .in +4n
145 .EX
146 prctl(PR_SET_NO_NEW_PRIVS, 1);
147 .EE
148 .in
149 .IP
150 Otherwise, the
151 .B SECCOMP_SET_MODE_FILTER
152 operation fails and returns
153 .B EACCES
154 in
155 .IR errno .
156 This requirement ensures that an unprivileged process cannot apply
157 a malicious filter and then invoke a set-user-ID or
158 other privileged program using
159 .BR execve (2),
160 thus potentially compromising that program.
161 (Such a malicious filter might, for example, cause an attempt to use
162 .BR setuid (2)
163 to set the caller's user IDs to nonzero values to instead
164 return 0 without actually making the system call.
165 Thus, the program might be tricked into retaining superuser privileges
166 in circumstances where it is possible to influence it to do
167 dangerous things because it did not actually drop privileges.)
168 .IP
169 If
170 .BR prctl (2)
171 or
172 .BR seccomp ()
173 is allowed by the attached filter, further filters may be added.
174 This will increase evaluation time, but allows for further reduction of
175 the attack surface during execution of a thread.
176 .IP
177 The
178 .B SECCOMP_SET_MODE_FILTER
179 operation is available only if the kernel is configured with
180 .B CONFIG_SECCOMP_FILTER
181 enabled.
182 .IP
183 When
184 .I flags
185 is 0, this operation is functionally identical to the call:
186 .IP
187 .in +4n
188 .EX
189 prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, args);
190 .EE
191 .in
192 .IP
193 The recognized
194 .I flags
195 are:
196 .RS
197 .TP
198 .BR SECCOMP_FILTER_FLAG_LOG " (since Linux 4.14)"
199 .\" commit e66a39977985b1e69e17c4042cb290768eca9b02
200 All filter return actions except
201 .B SECCOMP_RET_ALLOW
202 should be logged.
203 An administrator may override this filter flag by preventing specific
204 actions from being logged via the
205 .I /proc/sys/kernel/seccomp/actions_logged
206 file.
207 .TP
208 .BR SECCOMP_FILTER_FLAG_NEW_LISTENER " (since Linux 5.0)"
209 .\" commit 6a21cc50f0c7f87dae5259f6cfefe024412313f6
210 After successfully installing the filter program,
211 return a new user-space notification file descriptor.
212 (The close-on-exec flag is set for the file descriptor.)
213 When the filter returns
214 .B SECCOMP_RET_USER_NOTIF
215 a notification will be sent to this file descriptor.
216 .IP
217 At most one seccomp filter using the
218 .B SECCOMP_FILTER_FLAG_NEW_LISTENER
219 flag can be installed for a thread.
220 .IP
221 See
222 .BR seccomp_unotify (2)
223 for further details.
224 .TP
225 .BR SECCOMP_FILTER_FLAG_SPEC_ALLOW " (since Linux 4.17)"
226 .\" commit 00a02d0c502a06d15e07b857f8ff921e3e402675
227 Disable Speculative Store Bypass mitigation.
228 .TP
229 .B SECCOMP_FILTER_FLAG_TSYNC
230 When adding a new filter, synchronize all other threads of the calling
231 process to the same seccomp filter tree.
232 A "filter tree" is the ordered list of filters attached to a thread.
233 (Attaching identical filters in separate
234 .BR seccomp ()
235 calls results in different filters from this perspective.)
236 .IP
237 If any thread cannot synchronize to the same filter tree,
238 the call will not attach the new seccomp filter,
239 and will fail, returning the first thread ID found that cannot synchronize.
240 Synchronization will fail if another thread in the same process is in
241 .B SECCOMP_MODE_STRICT
242 or if it has attached new seccomp filters to itself,
243 diverging from the calling thread's filter tree.
244 .RE
245 .TP
246 .BR SECCOMP_GET_ACTION_AVAIL " (since Linux 4.14)"
247 .\" commit d612b1fd8010d0d67b5287fe146b8b55bcbb8655
248 Test to see if an action is supported by the kernel.
249 This operation is helpful to confirm that the kernel knows
250 of a more recently added filter return action
251 since the kernel treats all unknown actions as
252 .BR SECCOMP_RET_KILL_PROCESS .
253 .IP
254 The value of
255 .I flags
256 must be 0, and
257 .I args
258 must be a pointer to an unsigned 32-bit filter return action.
259 .TP
260 .BR SECCOMP_GET_NOTIF_SIZES " (since Linux 5.0)"
261 .\" commit 6a21cc50f0c7f87dae5259f6cfefe024412313f6
262 Get the sizes of the seccomp user-space notification structures.
263 Since these structures may evolve and grow over time,
264 this command can be used to determine how
265 much memory to allocate for sending and receiving notifications.
266 .IP
267 The value of
268 .I flags
269 must be 0, and
270 .I args
271 must be a pointer to a
272 .IR "struct seccomp_notif_sizes" ,
273 which has the following form:
274 .IP
275 .EX
276 struct seccomp_notif_sizes
277 __u16 seccomp_notif; /* Size of notification structure */
278 __u16 seccomp_notif_resp; /* Size of response structure */
279 __u16 seccomp_data; /* Size of \[aq]struct seccomp_data\[aq] */
280 };
281 .EE
282 .IP
283 See
284 .BR seccomp_unotify (2)
285 for further details.
286 .\"
287 .SS Filters
288 When adding filters via
289 .BR SECCOMP_SET_MODE_FILTER ,
290 .I args
291 points to a filter program:
292 .P
293 .in +4n
294 .EX
295 struct sock_fprog {
296 unsigned short len; /* Number of BPF instructions */
297 struct sock_filter *filter; /* Pointer to array of
298 BPF instructions */
299 };
300 .EE
301 .in
302 .P
303 Each program must contain one or more BPF instructions:
304 .P
305 .in +4n
306 .EX
307 struct sock_filter { /* Filter block */
308 __u16 code; /* Actual filter code */
309 __u8 jt; /* Jump true */
310 __u8 jf; /* Jump false */
311 __u32 k; /* Generic multiuse field */
312 };
313 .EE
314 .in
315 .P
316 When executing the instructions, the BPF program operates on the
317 system call information made available (i.e., use the
318 .B BPF_ABS
319 addressing mode) as a (read-only)
320 .\" Quoting Kees Cook:
321 .\" If BPF even allows changing the data, it's not copied back to
322 .\" the syscall when it runs. Anything wanting to do things like
323 .\" that would need to use ptrace to catch the call and directly
324 .\" modify the registers before continuing with the call.
325 buffer of the following form:
326 .P
327 .in +4n
328 .EX
329 struct seccomp_data {
330 int nr; /* System call number */
331 __u32 arch; /* AUDIT_ARCH_* value
332 (see <linux/audit.h>) */
333 __u64 instruction_pointer; /* CPU instruction pointer */
334 __u64 args[6]; /* Up to 6 system call arguments */
335 };
336 .EE
337 .in
338 .P
339 Because numbering of system calls varies between architectures and
340 some architectures (e.g., x86-64) allow user-space code to use
341 the calling conventions of multiple architectures
342 (and the convention being used may vary over the life of a process that uses
343 .BR execve (2)
344 to execute binaries that employ the different conventions),
345 it is usually necessary to verify the value of the
346 .I arch
347 field.
348 .P
349 It is strongly recommended to use an allow-list approach whenever
350 possible because such an approach is more robust and simple.
351 A deny-list will have to be updated whenever a potentially
352 dangerous system call is added (or a dangerous flag or option if those
353 are deny-listed), and it is often possible to alter the
354 representation of a value without altering its meaning, leading to
355 a deny-list bypass.
356 See also
357 .I Caveats
358 below.
359 .P
360 The
361 .I arch
362 field is not unique for all calling conventions.
363 The x86-64 ABI and the x32 ABI both use
364 .B AUDIT_ARCH_X86_64
365 as
366 .IR arch ,
367 and they run on the same processors.
368 Instead, the mask
369 .B __X32_SYSCALL_BIT
370 is used on the system call number to tell the two ABIs apart.
371 .\" As noted by Dave Drysdale in a note at the end of
372 .\" https://lwn.net/Articles/604515/
373 .\" One additional detail to point out for the x32 ABI case:
374 .\" the syscall number gets a high bit set (__X32_SYSCALL_BIT),
375 .\" to mark it as an x32 call.
376 .\"
377 .\" If x32 support is included in the kernel, then __SYSCALL_MASK
378 .\" will have a value that is not all-ones, and this will trigger
379 .\" an extra instruction in system_call to mask off the extra bit,
380 .\" so that the syscall table indexing still works.
381 .P
382 This means that a policy must either deny all syscalls with
383 .B __X32_SYSCALL_BIT
384 or it must recognize syscalls with and without
385 .B __X32_SYSCALL_BIT
386 set.
387 A list of system calls to be denied based on
388 .I nr
389 that does not also contain
390 .I nr
391 values with
392 .B __X32_SYSCALL_BIT
393 set can be bypassed by a malicious program that sets
394 .BR __X32_SYSCALL_BIT .
395 .P
396 Additionally, kernels prior to Linux 5.4 incorrectly permitted
397 .I nr
398 in the ranges 512-547 as well as the corresponding non-x32 syscalls ORed
399 with
400 .BR __X32_SYSCALL_BIT .
401 For example,
402 .I nr
403 == 521 and
404 .I nr
405 == (101 |
406 .BR __X32_SYSCALL_BIT )
407 would result in invocations of
408 .BR ptrace (2)
409 with potentially confused x32-vs-x86_64 semantics in the kernel.
410 Policies intended to work on kernels before Linux 5.4 must ensure that they
411 deny or otherwise correctly handle these system calls.
412 On Linux 5.4 and newer,
413 .\" commit 6365b842aae4490ebfafadfc6bb27a6d3cc54757
414 such system calls will fail with the error
415 .BR ENOSYS ,
416 without doing anything.
417 .P
418 The
419 .I instruction_pointer
420 field provides the address of the machine-language instruction that
421 performed the system call.
422 This might be useful in conjunction with the use of
423 .IR /proc/ pid /maps
424 to perform checks based on which region (mapping) of the program
425 made the system call.
426 (Probably, it is wise to lock down the
427 .BR mmap (2)
428 and
429 .BR mprotect (2)
430 system calls to prevent the program from subverting such checks.)
431 .P
432 When checking values from
433 .IR args ,
434 keep in mind that arguments are often
435 silently truncated before being processed, but after the seccomp check.
436 For example, this happens if the i386 ABI is used on an
437 x86-64 kernel: although the kernel will normally not look beyond
438 the 32 lowest bits of the arguments, the values of the full
439 64-bit registers will be present in the seccomp data.
440 A less surprising example is that if the x86-64 ABI is used to perform
441 a system call that takes an argument of type
442 .IR int ,
443 the more-significant half of the argument register is ignored by
444 the system call, but visible in the seccomp data.
445 .P
446 A seccomp filter returns a 32-bit value consisting of two parts:
447 the most significant 16 bits
448 (corresponding to the mask defined by the constant
449 .BR SECCOMP_RET_ACTION_FULL )
450 contain one of the "action" values listed below;
451 the least significant 16-bits (defined by the constant
452 .BR SECCOMP_RET_DATA )
453 are "data" to be associated with this return value.
454 .P
455 If multiple filters exist, they are
456 .I all
457 executed,
458 in reverse order of their addition to the filter tree\[em]that is,
459 the most recently installed filter is executed first.
460 (Note that all filters will be called
461 even if one of the earlier filters returns
462 .BR SECCOMP_RET_KILL .
463 This is done to simplify the kernel code and to provide a
464 tiny speed-up in the execution of sets of filters by
465 avoiding a check for this uncommon case.)
466 .\" From an Aug 2015 conversation with Kees Cook where I asked why *all*
467 .\" filters are applied even if one of the early filters returns
468 .\" SECCOMP_RET_KILL:
469 .\"
470 .\" It's just because it would be an optimization that would only speed up
471 .\" the RET_KILL case, but it's the uncommon one and the one that doesn't
472 .\" benefit meaningfully from such a change (you need to kill the process
473 .\" really quickly?). We would speed up killing a program at the (albeit
474 .\" tiny) expense to all other filtered programs. Best to keep the filter
475 .\" execution logic clear, simple, and as fast as possible for all
476 .\" filters.
477 The return value for the evaluation of a given system call is the first-seen
478 action value of highest precedence (along with its accompanying data)
479 returned by execution of all of the filters.
480 .P
481 In decreasing order of precedence,
482 the action values that may be returned by a seccomp filter are:
483 .TP
484 .BR SECCOMP_RET_KILL_PROCESS " (since Linux 4.14)"
485 .\" commit 4d3b0b05aae9ee9ce0970dc4cc0fb3fad5e85945
486 .\" commit 0466bdb99e8744bc9befa8d62a317f0fd7fd7421
487 This value results in immediate termination of the process,
488 with a core dump.
489 The system call is not executed.
490 By contrast with
491 .B SECCOMP_RET_KILL_THREAD
492 below, all threads in the thread group are terminated.
493 (For a discussion of thread groups, see the description of the
494 .B CLONE_THREAD
495 flag in
496 .BR clone (2).)
497 .IP
498 The process terminates
499 .I "as though"
500 killed by a
501 .B SIGSYS
502 signal.
503 Even if a signal handler has been registered for
504 .BR SIGSYS ,
505 the handler will be ignored in this case and the process always terminates.
506 To a parent process that is waiting on this process (using
507 .BR waitpid (2)
508 or similar), the returned
509 .I wstatus
510 will indicate that its child was terminated as though by a
511 .B SIGSYS
512 signal.
513 .TP
514 .BR SECCOMP_RET_KILL_THREAD " (or " SECCOMP_RET_KILL )
515 This value results in immediate termination of the thread
516 that made the system call.
517 The system call is not executed.
518 Other threads in the same thread group will continue to execute.
519 .IP
520 The thread terminates
521 .I "as though"
522 killed by a
523 .B SIGSYS
524 signal.
525 See
526 .B SECCOMP_RET_KILL_PROCESS
527 above.
528 .IP
529 .\" See these commits:
530 .\" seccomp: dump core when using SECCOMP_RET_KILL
531 .\" (b25e67161c295c98acda92123b2dd1e7d8642901)
532 .\" seccomp: Only dump core when single-threaded
533 .\" (d7276e321ff8a53106a59c85ca46d03e34288893)
534 Before Linux 4.11,
535 any process terminated in this way would not trigger a coredump
536 (even though
537 .B SIGSYS
538 is documented in
539 .BR signal (7)
540 as having a default action of termination with a core dump).
541 Since Linux 4.11,
542 a single-threaded process will dump core if terminated in this way.
543 .IP
544 With the addition of
545 .B SECCOMP_RET_KILL_PROCESS
546 in Linux 4.14,
547 .B SECCOMP_RET_KILL_THREAD
548 was added as a synonym for
549 .BR SECCOMP_RET_KILL ,
550 in order to more clearly distinguish the two actions.
551 .IP
552 .BR Note :
553 the use of
554 .B SECCOMP_RET_KILL_THREAD
555 to kill a single thread in a multithreaded process is likely to leave the
556 process in a permanently inconsistent and possibly corrupt state.
557 .TP
558 .B SECCOMP_RET_TRAP
559 This value results in the kernel sending a thread-directed
560 .B SIGSYS
561 signal to the triggering thread.
562 (The system call is not executed.)
563 Various fields will be set in the
564 .I siginfo_t
565 structure (see
566 .BR sigaction (2))
567 associated with signal:
568 .RS
569 .IP \[bu] 3
570 .I si_signo
571 will contain
572 .BR SIGSYS .
573 .IP \[bu]
574 .I si_call_addr
575 will show the address of the system call instruction.
576 .IP \[bu]
577 .I si_syscall
578 and
579 .I si_arch
580 will indicate which system call was attempted.
581 .IP \[bu]
582 .I si_code
583 will contain
584 .BR SYS_SECCOMP .
585 .IP \[bu]
586 .I si_errno
587 will contain the
588 .B SECCOMP_RET_DATA
589 portion of the filter return value.
590 .RE
591 .IP
592 The program counter will be as though the system call happened
593 (i.e., the program counter will not point to the system call instruction).
594 The return value register will contain an architecture\-dependent value;
595 if resuming execution, set it to something appropriate for the system call.
596 (The architecture dependency is because replacing it with
597 .B ENOSYS
598 could overwrite some useful information.)
599 .TP
600 .B SECCOMP_RET_ERRNO
601 This value results in the
602 .B SECCOMP_RET_DATA
603 portion of the filter's return value being passed to user space as the
604 .I errno
605 value without executing the system call.
606 .TP
607 .BR SECCOMP_RET_USER_NOTIF " (since Linux 5.0)"
608 .\" commit 6a21cc50f0c7f87dae5259f6cfefe024412313f6
609 Forward the system call to an attached user-space supervisor
610 process to allow that process to decide what to do with the system call.
611 If there is no attached supervisor (either
612 because the filter was not installed with the
613 .B SECCOMP_FILTER_FLAG_NEW_LISTENER
614 flag or because the file descriptor was closed), the filter returns
615 .B ENOSYS
616 (similar to what happens when a filter returns
617 .B SECCOMP_RET_TRACE
618 and there is no tracer).
619 See
620 .BR seccomp_unotify (2)
621 for further details.
622 .IP
623 Note that the supervisor process will not be notified
624 if another filter returns an action value with a precedence greater than
625 .BR SECCOMP_RET_USER_NOTIF .
626 .TP
627 .B SECCOMP_RET_TRACE
628 When returned, this value will cause the kernel to attempt to notify a
629 .BR ptrace (2)-based
630 tracer prior to executing the system call.
631 If there is no tracer present,
632 the system call is not executed and returns a failure status with
633 .I errno
634 set to
635 .BR ENOSYS .
636 .IP
637 A tracer will be notified if it requests
638 .B PTRACE_O_TRACESECCOMP
639 using
640 .IR ptrace(PTRACE_SETOPTIONS) .
641 The tracer will be notified of a
642 .B PTRACE_EVENT_SECCOMP
643 and the
644 .B SECCOMP_RET_DATA
645 portion of the filter's return value will be available to the tracer via
646 .BR PTRACE_GETEVENTMSG .
647 .IP
648 The tracer can skip the system call by changing the system call number
649 to \-1.
650 Alternatively, the tracer can change the system call
651 requested by changing the system call to a valid system call number.
652 If the tracer asks to skip the system call, then the system call will
653 appear to return the value that the tracer puts in the return value register.
654 .IP
655 .\" This was changed in ce6526e8afa4.
656 .\" A related hole, using PTRACE_SYSCALL instead of SECCOMP_RET_TRACE, was
657 .\" changed in arch-specific commits, e.g., 93e35efb8de4 for X86 and
658 .\" 0f3912fd934c for ARM.
659 Before Linux 4.8, the seccomp check will not be run again after the tracer is
660 notified.
661 (This means that, on older kernels, seccomp-based sandboxes
662 .B "must not"
663 allow use of
664 .BR ptrace (2)\[em]even
665 of other
666 sandboxed processes\[em]without extreme care;
667 ptracers can use this mechanism to escape from the seccomp sandbox.)
668 .IP
669 Note that a tracer process will not be notified
670 if another filter returns an action value with a precedence greater than
671 .BR SECCOMP_RET_TRACE .
672 .TP
673 .BR SECCOMP_RET_LOG " (since Linux 4.14)"
674 .\" commit 59f5cf44a38284eb9e76270c786fb6cc62ef8ac4
675 This value results in the system call being executed after
676 the filter return action is logged.
677 An administrator may override the logging of this action via
678 the
679 .I /proc/sys/kernel/seccomp/actions_logged
680 file.
681 .TP
682 .B SECCOMP_RET_ALLOW
683 This value results in the system call being executed.
684 .P
685 If an action value other than one of the above is specified,
686 then the filter action is treated as either
687 .B SECCOMP_RET_KILL_PROCESS
688 (since Linux 4.14)
689 .\" commit 4d3b0b05aae9ee9ce0970dc4cc0fb3fad5e85945
690 or
691 .B SECCOMP_RET_KILL_THREAD
692 (in Linux 4.13 and earlier).
693 .\"
694 .SS /proc interfaces
695 The files in the directory
696 .I /proc/sys/kernel/seccomp
697 provide additional seccomp information and configuration:
698 .TP
699 .IR actions_avail " (since Linux 4.14)"
700 .\" commit 8e5f1ad116df6b0de65eac458d5e7c318d1c05af
701 A read-only ordered list of seccomp filter return actions in string form.
702 The ordering, from left-to-right, is in decreasing order of precedence.
703 The list represents the set of seccomp filter return actions
704 supported by the kernel.
705 .TP
706 .IR actions_logged " (since Linux 4.14)"
707 .\" commit 0ddec0fc8900201c0897b87b762b7c420436662f
708 A read-write ordered list of seccomp filter return actions that
709 are allowed to be logged.
710 Writes to the file do not need to be in ordered form but reads from
711 the file will be ordered in the same way as the
712 .I actions_avail
713 file.
714 .IP
715 It is important to note that the value of
716 .I actions_logged
717 does not prevent certain filter return actions from being logged when
718 the audit subsystem is configured to audit a task.
719 If the action is not found in the
720 .I actions_logged
721 file, the final decision on whether to audit the action for that task is
722 ultimately left up to the audit subsystem to decide for all filter return
723 actions other than
724 .BR SECCOMP_RET_ALLOW .
725 .IP
726 The "allow" string is not accepted in the
727 .I actions_logged
728 file as it is not possible to log
729 .B SECCOMP_RET_ALLOW
730 actions.
731 Attempting to write "allow" to the file will fail with the error
732 .BR EINVAL .
733 .\"
734 .SS Audit logging of seccomp actions
735 .\" commit 59f5cf44a38284eb9e76270c786fb6cc62ef8ac4
736 Since Linux 4.14, the kernel provides the facility to log the
737 actions returned by seccomp filters in the audit log.
738 The kernel makes the decision to log an action based on
739 the action type, whether or not the action is present in the
740 .I actions_logged
741 file, and whether kernel auditing is enabled
742 (e.g., via the kernel boot option
743 .IR audit=1 ).
744 .\" or auditing could be enabled via the netlink API (AUDIT_SET)
745 The rules are as follows:
746 .IP \[bu] 3
747 If the action is
748 .BR SECCOMP_RET_ALLOW ,
749 the action is not logged.
750 .IP \[bu]
751 Otherwise, if the action is either
752 .B SECCOMP_RET_KILL_PROCESS
753 or
754 .BR SECCOMP_RET_KILL_THREAD ,
755 and that action appears in the
756 .I actions_logged
757 file, the action is logged.
758 .IP \[bu]
759 Otherwise, if the filter has requested logging (the
760 .B SECCOMP_FILTER_FLAG_LOG
761 flag)
762 and the action appears in the
763 .I actions_logged
764 file, the action is logged.
765 .IP \[bu]
766 Otherwise, if kernel auditing is enabled and the process is being audited
767 .RB ( autrace (8)),
768 the action is logged.
769 .IP \[bu]
770 Otherwise, the action is not logged.
771 .SH RETURN VALUE
772 On success,
773 .BR seccomp ()
774 returns 0.
775 On error, if
776 .B SECCOMP_FILTER_FLAG_TSYNC
777 was used,
778 the return value is the ID of the thread
779 that caused the synchronization failure.
780 (This ID is a kernel thread ID of the type returned by
781 .BR clone (2)
782 and
783 .BR gettid (2).)
784 On other errors, \-1 is returned, and
785 .I errno
786 is set to indicate the error.
787 .SH ERRORS
788 .BR seccomp ()
789 can fail for the following reasons:
790 .TP
791 .B EACCES
792 The caller did not have the
793 .B CAP_SYS_ADMIN
794 capability in its user namespace, or had not set
795 .I no_new_privs
796 before using
797 .BR SECCOMP_SET_MODE_FILTER .
798 .TP
799 .B EBUSY
800 While installing a new filter, the
801 .B SECCOMP_FILTER_FLAG_NEW_LISTENER
802 flag was specified,
803 but a previous filter had already been installed with that flag.
804 .TP
805 .B EFAULT
806 .I args
807 was not a valid address.
808 .TP
809 .B EINVAL
810 .I operation
811 is unknown or is not supported by this kernel version or configuration.
812 .TP
813 .B EINVAL
814 The specified
815 .I flags
816 are invalid for the given
817 .IR operation .
818 .TP
819 .B EINVAL
820 .I operation
821 included
822 .BR BPF_ABS ,
823 but the specified offset was not aligned to a 32-bit boundary or exceeded
824 .IR "sizeof(struct\~seccomp_data)" .
825 .TP
826 .B EINVAL
827 .\" See kernel/seccomp.c::seccomp_may_assign_mode() in Linux 3.18 sources
828 A secure computing mode has already been set, and
829 .I operation
830 differs from the existing setting.
831 .TP
832 .B EINVAL
833 .I operation
834 specified
835 .BR SECCOMP_SET_MODE_FILTER ,
836 but the filter program pointed to by
837 .I args
838 was not valid or the length of the filter program was zero or exceeded
839 .B BPF_MAXINSNS
840 (4096) instructions.
841 .TP
842 .B ENOMEM
843 Out of memory.
844 .TP
845 .B ENOMEM
846 .\" ENOMEM in kernel/seccomp.c::seccomp_attach_filter() in Linux 3.18 sources
847 The total length of all filter programs attached
848 to the calling thread would exceed
849 .B MAX_INSNS_PER_PATH
850 (32768) instructions.
851 Note that for the purposes of calculating this limit,
852 each already existing filter program incurs an
853 overhead penalty of 4 instructions.
854 .TP
855 .B EOPNOTSUPP
856 .I operation
857 specified
858 .BR SECCOMP_GET_ACTION_AVAIL ,
859 but the kernel does not support the filter return action specified by
860 .IR args .
861 .TP
862 .B ESRCH
863 Another thread caused a failure during thread sync, but its ID could not
864 be determined.
865 .SH STANDARDS
866 Linux.
867 .SH HISTORY
868 Linux 3.17.
869 .\" FIXME . Add glibc version
870 .SH NOTES
871 Rather than hand-coding seccomp filters as shown in the example below,
872 you may prefer to employ the
873 .I libseccomp
874 library, which provides a front-end for generating seccomp filters.
875 .P
876 The
877 .I Seccomp
878 field of the
879 .IR /proc/ pid /status
880 file provides a method of viewing the seccomp mode of a process;
881 see
882 .BR proc (5).
883 .P
884 .BR seccomp ()
885 provides a superset of the functionality provided by the
886 .BR prctl (2)
887 .B PR_SET_SECCOMP
888 operation (which does not support
889 .IR flags ).
890 .P
891 Since Linux 4.4, the
892 .BR ptrace (2)
893 .B PTRACE_SECCOMP_GET_FILTER
894 operation can be used to dump a process's seccomp filters.
895 .\"
896 .SS Architecture support for seccomp BPF
897 Architecture support for seccomp BPF filtering
898 .\" Check by grepping for HAVE_ARCH_SECCOMP_FILTER in Kconfig files in
899 .\" kernel source. Last checked in Linux 4.16-rc source.
900 is available on the following architectures:
901 .IP \[bu] 3
902 x86-64, i386, x32 (since Linux 3.5)
903 .PD 0
904 .IP \[bu]
905 ARM (since Linux 3.8)
906 .IP \[bu]
907 s390 (since Linux 3.8)
908 .IP \[bu]
909 MIPS (since Linux 3.16)
910 .IP \[bu]
911 ARM-64 (since Linux 3.19)
912 .IP \[bu]
913 PowerPC (since Linux 4.3)
914 .IP \[bu]
915 Tile (since Linux 4.3)
916 .IP \[bu]
917 PA-RISC (since Linux 4.6)
918 .\" User mode Linux since Linux 4.6
919 .PD
920 .\"
921 .SS Caveats
922 There are various subtleties to consider when applying seccomp filters
923 to a program, including the following:
924 .IP \[bu] 3
925 Some traditional system calls have user-space implementations in the
926 .BR vdso (7)
927 on many architectures.
928 Notable examples include
929 .BR clock_gettime (2),
930 .BR gettimeofday (2),
931 and
932 .BR time (2).
933 On such architectures,
934 seccomp filtering for these system calls will have no effect.
935 (However, there are cases where the
936 .BR vdso (7)
937 implementations may fall back to invoking the true system call,
938 in which case seccomp filters would see the system call.)
939 .IP \[bu]
940 Seccomp filtering is based on system call numbers.
941 However, applications typically do not directly invoke system calls,
942 but instead call wrapper functions in the C library which
943 in turn invoke the system calls.
944 Consequently, one must be aware of the following:
945 .RS
946 .IP \[bu] 3
947 The glibc wrappers for some traditional system calls may actually
948 employ system calls with different names in the kernel.
949 For example, the
950 .BR exit (2)
951 wrapper function actually employs the
952 .BR exit_group (2)
953 system call, and the
954 .BR fork (2)
955 wrapper function actually calls
956 .BR clone (2).
957 .IP \[bu]
958 The behavior of wrapper functions may vary across architectures,
959 according to the range of system calls provided on those architectures.
960 In other words, the same wrapper function may invoke
961 different system calls on different architectures.
962 .IP \[bu]
963 Finally, the behavior of wrapper functions can change across glibc versions.
964 For example, in older versions, the glibc wrapper function for
965 .BR open (2)
966 invoked the system call of the same name,
967 but starting in glibc 2.26, the implementation switched to calling
968 .BR openat (2)
969 on all architectures.
970 .RE
971 .P
972 The consequence of the above points is that it may be necessary
973 to filter for a system call other than might be expected.
974 Various manual pages in Section 2 provide helpful details
975 about the differences between wrapper functions and
976 the underlying system calls in subsections entitled
977 .IR "C library/kernel differences" .
978 .P
979 Furthermore, note that the application of seccomp filters
980 even risks causing bugs in an application,
981 when the filters cause unexpected failures for legitimate operations
982 that the application might need to perform.
983 Such bugs may not easily be discovered when testing the seccomp
984 filters if the bugs occur in rarely used application code paths.
985 .\"
986 .SS Seccomp-specific BPF details
987 Note the following BPF details specific to seccomp filters:
988 .IP \[bu] 3
989 The
990 .B BPF_H
991 and
992 .B BPF_B
993 size modifiers are not supported: all operations must load and store
994 (4-byte) words
995 .RB ( BPF_W ).
996 .IP \[bu]
997 To access the contents of the
998 .I seccomp_data
999 buffer, use the
1000 .B BPF_ABS
1001 addressing mode modifier.
1002 .IP \[bu]
1003 The
1004 .B BPF_LEN
1005 addressing mode modifier yields an immediate mode operand
1006 whose value is the size of the
1007 .I seccomp_data
1008 buffer.
1009 .SH EXAMPLES
1010 The program below accepts four or more arguments.
1011 The first three arguments are a system call number,
1012 a numeric architecture identifier, and an error number.
1013 The program uses these values to construct a BPF filter
1014 that is used at run time to perform the following checks:
1015 .IP \[bu] 3
1016 If the program is not running on the specified architecture,
1017 the BPF filter causes system calls to fail with the error
1018 .BR ENOSYS .
1019 .IP \[bu]
1020 If the program attempts to execute the system call with the specified number,
1021 the BPF filter causes the system call to fail, with
1022 .I errno
1023 being set to the specified error number.
1024 .P
1025 The remaining command-line arguments specify
1026 the pathname and additional arguments of a program
1027 that the example program should attempt to execute using
1028 .BR execv (3)
1029 (a library function that employs the
1030 .BR execve (2)
1031 system call).
1032 Some example runs of the program are shown below.
1033 .P
1034 First, we display the architecture that we are running on (x86-64)
1035 and then construct a shell function that looks up system call
1036 numbers on this architecture:
1037 .P
1038 .in +4n
1039 .EX
1040 .RB $ " uname \-m" ;
1041 x86_64
1042 $ \f[B]syscall_nr() {
1043 cat /usr/src/linux/arch/x86/syscalls/syscall_64.tbl | \[rs]
1044 awk \[aq]$2 != \[dq]x32\[dq] && $3 == \[dq]\[aq]$1\[aq]\[dq] { print $1 }\[aq]
1045 }\f[];
1046 .EE
1047 .in
1048 .P
1049 When the BPF filter rejects a system call (case [2] above),
1050 it causes the system call to fail with the error number
1051 specified on the command line.
1052 In the experiments shown here, we'll use error number 99:
1053 .P
1054 .in +4n
1055 .EX
1056 .RB $ " errno 99" ;
1057 EADDRNOTAVAIL 99 Cannot assign requested address
1058 .EE
1059 .in
1060 .P
1061 In the following example, we attempt to run the command
1062 .BR whoami (1),
1063 but the BPF filter rejects the
1064 .BR execve (2)
1065 system call, so that the command is not even executed:
1066 .P
1067 .in +4n
1068 .EX
1069 .RB $ " syscall_nr execve" ;
1070 59
1071 .RB $ " ./a.out" ;
1072 Usage: ./a.out <syscall_nr> <arch> <errno> <prog> [<args>]
1073 Hint for <arch>: AUDIT_ARCH_I386: 0x40000003
1074 AUDIT_ARCH_X86_64: 0xC000003E
1075 .RB $ " ./a.out 59 0xC000003E 99 /bin/whoami" ;
1076 execv: Cannot assign requested address
1077 .EE
1078 .in
1079 .P
1080 In the next example, the BPF filter rejects the
1081 .BR write (2)
1082 system call, so that, although it is successfully started, the
1083 .BR whoami (1)
1084 command is not able to write output:
1085 .P
1086 .in +4n
1087 .EX
1088 .RB $ " syscall_nr write" ;
1089 1
1090 .RB $ " ./a.out 1 0xC000003E 99 /bin/whoami" ;
1091 .EE
1092 .in
1093 .P
1094 In the final example,
1095 the BPF filter rejects a system call that is not used by the
1096 .BR whoami (1)
1097 command, so it is able to successfully execute and produce output:
1098 .P
1099 .in +4n
1100 .EX
1101 .RB $ " syscall_nr preadv" ;
1102 295
1103 .RB $ " ./a.out 295 0xC000003E 99 /bin/whoami" ;
1104 cecilia
1105 .EE
1106 .in
1107 .SS Program source
1108 .\" SRC BEGIN (seccomp.c)
1109 .EX
1110 #include <linux/audit.h>
1111 #include <linux/filter.h>
1112 #include <linux/seccomp.h>
1113 #include <stdcountof.h>
1114 #include <stddef.h>
1115 #include <stdio.h>
1116 #include <stdlib.h>
1117 #include <sys/prctl.h>
1118 #include <sys/syscall.h>
1119 #include <unistd.h>
1120 \&
1121 #define X32_SYSCALL_BIT 0x40000000
1122 \&
1123 static int
1124 install_filter(int syscall_nr, unsigned int t_arch, int f_errno)
1125 {
1126 unsigned int upper_nr_limit = 0xffffffff;
1127 \&
1128 /* Assume that AUDIT_ARCH_X86_64 means the normal x86\-64 ABI
1129 (in the x32 ABI, all system calls have bit 30 set in the
1130 \[aq]nr\[aq] field, meaning the numbers are >= X32_SYSCALL_BIT). */
1131 if (t_arch == AUDIT_ARCH_X86_64)
1132 upper_nr_limit = X32_SYSCALL_BIT \- 1;
1133 \&
1134 struct sock_filter filter[] = {
1135 /* [0] Load architecture from \[aq]seccomp_data\[aq] buffer into
1136 accumulator. */
1137 BPF_STMT(BPF_LD | BPF_W | BPF_ABS,
1138 (offsetof(struct seccomp_data, arch))),
1139 \&
1140 /* [1] Jump forward 5 instructions if architecture does not
1141 match \[aq]t_arch\[aq]. */
1142 BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, t_arch, 0, 5),
1143 \&
1144 /* [2] Load system call number from \[aq]seccomp_data\[aq] buffer into
1145 accumulator. */
1146 BPF_STMT(BPF_LD | BPF_W | BPF_ABS,
1147 (offsetof(struct seccomp_data, nr))),
1148 \&
1149 /* [3] Check ABI \- only needed for x86\-64 in deny\-list use
1150 cases. Use BPF_JGT instead of checking against the bit
1151 mask to avoid having to reload the syscall number. */
1152 BPF_JUMP(BPF_JMP | BPF_JGT | BPF_K, upper_nr_limit, 3, 0),
1153 \&
1154 /* [4] Jump forward 1 instruction if system call number
1155 does not match \[aq]syscall_nr\[aq]. */
1156 BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, syscall_nr, 0, 1),
1157 \&
1158 /* [5] Matching architecture and system call: don\[aq]t execute
1159 the system call, and return \[aq]f_errno\[aq] in \[aq]errno\[aq]. */
1160 BPF_STMT(BPF_RET | BPF_K,
1161 SECCOMP_RET_ERRNO | (f_errno & SECCOMP_RET_DATA)),
1162 \&
1163 /* [6] Destination of system call number mismatch: allow other
1164 system calls. */
1165 BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW),
1166 \&
1167 /* [7] Destination of architecture mismatch: kill process. */
1168 BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_KILL_PROCESS),
1169 };
1170 \&
1171 struct sock_fprog prog = {
1172 .len = countof(filter),
1173 .filter = filter,
1174 };
1175 \&
1176 if (syscall(SYS_seccomp, SECCOMP_SET_MODE_FILTER, 0, &prog)) {
1177 perror("seccomp");
1178 return 1;
1179 }
1180 \&
1181 return 0;
1182 }
1183 \&
1184 int
1185 main(int argc, char *argv[])
1186 {
1187 if (argc < 5) {
1188 fprintf(stderr, "Usage: "
1189 "%s <syscall_nr> <arch> <errno> <prog> [<args>]\[rs]n"
1190 "Hint for <arch>: AUDIT_ARCH_I386: 0x%X\[rs]n"
1191 " AUDIT_ARCH_X86_64: 0x%X\[rs]n"
1192 "\[rs]n", argv[0], AUDIT_ARCH_I386, AUDIT_ARCH_X86_64);
1193 exit(EXIT_FAILURE);
1194 }
1195 \&
1196 if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) {
1197 perror("prctl");
1198 exit(EXIT_FAILURE);
1199 }
1200 \&
1201 if (install_filter(strtol(argv[1], NULL, 0),
1202 strtoul(argv[2], NULL, 0),
1203 strtol(argv[3], NULL, 0)))
1204 exit(EXIT_FAILURE);
1205 \&
1206 execv(argv[4], &argv[4]);
1207 perror("execv");
1208 exit(EXIT_FAILURE);
1209 }
1210 .EE
1211 .\" SRC END
1212 .SH SEE ALSO
1213 .BR bpfc (1),
1214 .BR strace (1),
1215 .BR bpf (2),
1216 .BR prctl (2),
1217 .BR ptrace (2),
1218 .BR seccomp_unotify (2),
1219 .BR sigaction (2),
1220 .BR proc (5),
1221 .BR signal (7),
1222 .BR socket (7)
1223 .P
1224 Various pages from the
1225 .I libseccomp
1226 library, including:
1227 .BR scmp_sys_resolver (1),
1228 .BR seccomp_export_bpf (3),
1229 .BR seccomp_init (3),
1230 .BR seccomp_load (3),
1231 and
1232 .BR seccomp_rule_add (3).
1233 .P
1234 The kernel source files
1235 .I Documentation/networking/filter.rst
1236 and
1237 .IR Documentation/userspace\-api/seccomp_filter.rst .
1238 .P
1239 McCanne, S.\& and Jacobson, V.\& (1992)
1240 .IR "The BSD Packet Filter: A New Architecture for User-level Packet Capture" ,
1241 Proceedings of the USENIX Winter 1993 Conference
1242 .UR http:\://www.tcpdump.org/papers/bpf\-usenix93.pdf
1243 .UE
1244 .P
1245 Terence Kelly and Edison Fuh (2025)
1246 Sandboxing: Foolproof Boundaries vs.\& Unbounded Foolishness
1247 .UR https:\://dl.acm.org/doi/pdf/10.1145/3733699
1248 .UE