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