man2/seccomp.2

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