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 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .TH SECCOMP 2 2016-10-08 "Linux" "Linux Programmer's Manual"
  28 .SH NAME
  29 seccomp \- operate on Secure Computing state of the process
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <linux/seccomp.h>
  33 .B #include <linux/filter.h>
  34 .B #include <linux/audit.h>
  35 .B #include <linux/signal.h>
  36 .B #include <sys/ptrace.h>
  37 .\" Kees Cook noted: Anything that uses SECCOMP_RET_TRACE returns will
  38 .\"                  need <sys/ptrace.h>
  39
  40 .BI "int seccomp(unsigned int " operation ", unsigned int " flags \
  41 ", void *" args );
  42 .fi
  43 .SH DESCRIPTION
  44 The
  45 .BR seccomp ()
  46 system call operates on the Secure Computing (seccomp) state of the
  47 calling process.
  48
  49 Currently, Linux supports the following
  50 .IR operation
  51 values:
  52 .TP
  53 .BR SECCOMP_SET_MODE_STRICT
  54 The only system calls that the calling thread is permitted to make are
  55 .BR read (2),
  56 .BR write (2),
  57 .BR _exit (2)
  58 (but not
  59 .BR exit_group (2)),
  60 and
  61 .BR sigreturn (2).
  62 Other system calls result in the delivery of a
  63 .BR SIGKILL
  64 signal.
  65 Strict secure computing mode is useful for number-crunching
  66 applications that may need to execute untrusted byte code, perhaps
  67 obtained by reading from a pipe or socket.
  68
  69 Note that although the calling thread can no longer call
  70 .BR sigprocmask (2),
  71 it can use
  72 .BR sigreturn (2)
  73 to block all signals apart from
  74 .BR SIGKILL
  75 and
  76 .BR SIGSTOP .
  77 This means that
  78 .BR alarm (2)
  79 (for example) is not sufficient for restricting the process's execution time.
  80 Instead, to reliably terminate the process,
  81 .BR SIGKILL
  82 must be used.
  83 This can be done by using
  84 .BR timer_create (2)
  85 with
  86 .BR SIGEV_SIGNAL
  87 and
  88 .IR sigev_signo
  89 set to
  90 .BR SIGKILL ,
  91 or by using
  92 .BR setrlimit (2)
  93 to set the hard limit for
  94 .BR RLIMIT_CPU .
  95
  96 This operation is available only if the kernel is configured with
  97 .BR CONFIG_SECCOMP
  98 enabled.
  99
 100 The value of
 101 .IR flags
 102 must be 0, and
 103 .IR args
 104 must be NULL.
 105
 106 This operation is functionally identical to the call:
 107
 108     prctl(PR_SET_SECCOMP, SECCOMP_MODE_STRICT);
 109 .TP
 110 .BR SECCOMP_SET_MODE_FILTER
 111 The system calls allowed are defined by a pointer to a Berkeley Packet
 112 Filter (BPF) passed via
 113 .IR args .
 114 This argument is a pointer to a
 115 .IR "struct\ sock_fprog" ;
 116 it can be designed to filter arbitrary system calls and system call
 117 arguments.
 118 If the filter is invalid,
 119 .BR seccomp ()
 120 fails, returning
 121 .BR EINVAL
 122 in
 123 .IR errno .
 124
 125 If
 126 .BR fork (2)
 127 or
 128 .BR clone (2)
 129 is allowed by the filter, any child processes will be constrained to
 130 the same system call filters as the parent.
 131 If
 132 .BR execve (2)
 133 is allowed,
 134 the existing filters will be preserved across a call to
 135 .BR execve (2).
 136
 137 In order to use the
 138 .BR SECCOMP_SET_MODE_FILTER
 139 operation, either the caller must have the
 140 .BR CAP_SYS_ADMIN
 141 capability in its user namespace, or the thread must already have the
 142 .I no_new_privs
 143 bit set.
 144 If that bit was not already set by an ancestor of this thread,
 145 the thread must make the following call:
 146
 147     prctl(PR_SET_NO_NEW_PRIVS, 1);
 148
 149 Otherwise, the
 150 .BR SECCOMP_SET_MODE_FILTER
 151 operation will fail and return
 152 .BR EACCES
 153 in
 154 .IR errno .
 155 This requirement ensures that an unprivileged process cannot apply
 156 a malicious filter and then invoke a set-user-ID or
 157 other privileged program using
 158 .BR execve (2),
 159 thus potentially compromising that program.
 160 (Such a malicious filter might, for example, cause an attempt to use
 161 .BR setuid (2)
 162 to set the caller's user IDs to non-zero values to instead
 163 return 0 without actually making the system call.
 164 Thus, the program might be tricked into retaining superuser privileges
 165 in circumstances where it is possible to influence it to do
 166 dangerous things because it did not actually drop privileges.)
 167
 168 If
 169 .BR prctl (2)
 170 or
 171 .BR seccomp ()
 172 is allowed by the attached filter, further filters may be added.
 173 This will increase evaluation time, but allows for further reduction of
 174 the attack surface during execution of a thread.
 175
 176 The
 177 .BR SECCOMP_SET_MODE_FILTER
 178 operation is available only if the kernel is configured with
 179 .BR CONFIG_SECCOMP_FILTER
 180 enabled.
 181
 182 When
 183 .IR flags
 184 is 0, this operation is functionally identical to the call:
 185
 186     prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, args);
 187
 188 The recognized
 189 .IR flags
 190 are:
 191 .RS
 192 .TP
 193 .BR SECCOMP_FILTER_FLAG_TSYNC
 194 When adding a new filter, synchronize all other threads of the calling
 195 process to the same seccomp filter tree.
 196 A "filter tree" is the ordered list of filters attached to a thread.
 197 (Attaching identical filters in separate
 198 .BR seccomp ()
 199 calls results in different filters from this perspective.)
 200
 201 If any thread cannot synchronize to the same filter tree,
 202 the call will not attach the new seccomp filter,
 203 and will fail, returning the first thread ID found that cannot synchronize.
 204 Synchronization will fail if another thread in the same process is in
 205 .BR SECCOMP_MODE_STRICT
 206 or if it has attached new seccomp filters to itself,
 207 diverging from the calling thread's filter tree.
 208 .RE
 209 .SS Filters
 210 When adding filters via
 211 .BR SECCOMP_SET_MODE_FILTER ,
 212 .IR args
 213 points to a filter program:
 214
 215 .in +4n
 216 .nf
 217 struct sock_fprog {
 218     unsigned short      len;    /* Number of BPF instructions */
 219     struct sock_filter *filter; /* Pointer to array of
 220                                    BPF instructions */
 221 };
 222 .fi
 223 .in
 224
 225 Each program must contain one or more BPF instructions:
 226
 227 .in +4n
 228 .nf
 229 struct sock_filter {            /* Filter block */
 230     __u16 code;                 /* Actual filter code */
 231     __u8  jt;                   /* Jump true */
 232     __u8  jf;                   /* Jump false */
 233     __u32 k;                    /* Generic multiuse field */
 234 };
 235 .fi
 236 .in
 237
 238 When executing the instructions, the BPF program operates on the
 239 system call information made available (i.e., use the
 240 .BR BPF_ABS
 241 addressing mode) as a (read-only)
 242 .\" Quoting Kees Cook:
 243 .\"     If BPF even allows changing the data, it's not copied back to
 244 .\"     the syscall when it runs. Anything wanting to do things like
 245 .\"     that would need to use ptrace to catch the call an directly
 246 .\"     modify the registers before continuing with the call.
 247 buffer of the following form:
 248
 249 .in +4n
 250 .nf
 251 struct seccomp_data {
 252     int   nr;                   /* System call number */
 253     __u32 arch;                 /* AUDIT_ARCH_* value
 254                                    (see <linux/audit.h>) */
 255     __u64 instruction_pointer;  /* CPU instruction pointer */
 256     __u64 args[6];              /* Up to 6 system call arguments */
 257 };
 258 .fi
 259 .in
 260
 261 Because numbering of system calls varies between architectures and
 262 some architectures (e.g., x86-64) allow user-space code to use
 263 the calling conventions of multiple architectures, it is usually
 264 necessary to verify the value of the
 265 .IR arch
 266 field.
 267
 268 It is strongly recommended to use a whitelisting approach whenever
 269 possible because such an approach is more robust and simple.
 270 A blacklist will have to be updated whenever a potentially
 271 dangerous system call is added (or a dangerous flag or option if those
 272 are blacklisted), and it is often possible to alter the
 273 representation of a value without altering its meaning, leading to
 274 a blacklist bypass.
 275
 276 The
 277 .IR arch
 278 field is not unique for all calling conventions.
 279 The x86-64 ABI and the x32 ABI both use
 280 .BR AUDIT_ARCH_X86_64
 281 as
 282 .IR arch ,
 283 and they run on the same processors.
 284 Instead, the mask
 285 .BR __X32_SYSCALL_BIT
 286 is used on the system call number to tell the two ABIs apart.
 287 .\" As noted by Dave Drysdale in a note at the end of
 288 .\" https://lwn.net/Articles/604515/
 289 .\"     One additional detail to point out for the x32 ABI case:
 290 .\"     the syscall number gets a high bit set (__X32_SYSCALL_BIT),
 291 .\"     to mark it as an x32 call.
 292 .\"
 293 .\"     If x32 support is included in the kernel, then __SYSCALL_MASK
 294 .\"     will have a value that is not all-ones, and this will trigger
 295 .\"     an extra instruction in system_call to mask off the extra bit,
 296 .\"     so that the syscall table indexing still works.
 297
 298 This means that in order to create a seccomp-based
 299 blacklist for system calls performed through the x86-64 ABI,
 300 it is necessary to not only check that
 301 .IR arch
 302 equals
 303 .BR AUDIT_ARCH_X86_64 ,
 304 but also to explicitly reject all system calls that contain
 305 .BR __X32_SYSCALL_BIT
 306 in
 307 .IR nr .
 308
 309 The
 310 .I instruction_pointer
 311 field provides the address of the machine-language instruction that
 312 performed the system call.
 313 This might be useful in conjunction with the use of
 314 .I /proc/[pid]/maps
 315 to perform checks based on which region (mapping) of the program
 316 made the system call.
 317 (Probably, it is wise to lock down the
 318 .BR mmap (2)
 319 and
 320 .BR mprotect (2)
 321 system calls to prevent the program from subverting such checks.)
 322
 323 When checking values from
 324 .IR args
 325 against a blacklist, keep in mind that arguments are often
 326 silently truncated before being processed, but after the seccomp check.
 327 For example, this happens if the i386 ABI is used on an
 328 x86-64 kernel: although the kernel will normally not look beyond
 329 the 32 lowest bits of the arguments, the values of the full
 330 64-bit registers will be present in the seccomp data.
 331 A less surprising example is that if the x86-64 ABI is used to perform
 332 a system call that takes an argument of type
 333 .IR int ,
 334 the more-significant half of the argument register is ignored by
 335 the system call, but visible in the seccomp data.
 336
 337 A seccomp filter returns a 32-bit value consisting of two parts:
 338 the most significant 16 bits
 339 (corresponding to the mask defined by the constant
 340 .BR SECCOMP_RET_ACTION )
 341 contain one of the "action" values listed below;
 342 the least significant 16-bits (defined by the constant
 343 .BR SECCOMP_RET_DATA )
 344 are "data" to be associated with this return value.
 345
 346 If multiple filters exist, they are \fIall\fP executed,
 347 in reverse order of their addition to the filter tree\(emthat is,
 348 the most recently installed filter is executed first.
 349 (Note that all filters will be called
 350 even if one of the earlier filters returns
 351 .BR SECCOMP_RET_KILL .
 352 This is done to simplify the kernel code and to provide a
 353 tiny speed-up in the execution of sets of filters by
 354 avoiding a check for this uncommon case.)
 355 .\" From an Aug 2015  conversation with Kees Cook where I asked why *all*
 356 .\" filters even if one of the early filters returns SECCOMP_RET_KILL:
 357 .\"
 358 .\"     It's just because it would be an optimization that would only speed up
 359 .\"     the RET_KILL case, but it's the uncommon one and the one that doesn't
 360 .\"     benefit meaningfully from such a change (you need to kill the process
 361 .\"     really quickly?). We would speed up killing a program at the (albeit
 362 .\"     tiny) expense to all other filtered programs. Best to keep the filter
 363 .\"     execution logic clear, simple, and as fast as possible for all
 364 .\"     filters.
 365 The return value for the evaluation of a given system call is the first-seen
 366 .BR SECCOMP_RET_ACTION
 367 value of highest precedence (along with its accompanying data)
 368 returned by execution of all of the filters.
 369
 370 In decreasing order of precedence,
 371 the values that may be returned by a seccomp filter are:
 372 .TP
 373 .BR SECCOMP_RET_KILL
 374 This value results in the process exiting immediately
 375 without executing the system call.
 376 The process terminates as though killed by a
 377 .B SIGSYS
 378 signal
 379 .RI ( not
 380 .BR SIGKILL ).
 381 .TP
 382 .BR SECCOMP_RET_TRAP
 383 This value results in the kernel sending a
 384 .BR SIGSYS
 385 signal to the triggering process without executing the system call.
 386 Various fields will be set in the
 387 .I siginfo_t
 388 structure (see
 389 .BR sigaction (2))
 390 associated with signal:
 391 .RS
 392 .IP * 3
 393 .I si_signo
 394 will contain
 395 .BR SIGSYS .
 396 .IP *
 397 .IR si_call_addr
 398 will show the address of the system call instruction.
 399 .IP *
 400 .IR si_syscall
 401 and
 402 .IR si_arch
 403 will indicate which system call was attempted.
 404 .IP *
 405 .I si_code
 406 will contain
 407 .BR SYS_SECCOMP .
 408 .IP *
 409 .I si_errno
 410 will contain the
 411 .BR SECCOMP_RET_DATA
 412 portion of the filter return value.
 413 .RE
 414 .IP
 415 The program counter will be as though the system call happened
 416 (i.e., it will not point to the system call instruction).
 417 The return value register will contain an architecture\-dependent value;
 418 if resuming execution, set it to something appropriate for the system call.
 419 (The architecture dependency is because replacing it with
 420 .BR ENOSYS
 421 could overwrite some useful information.)
 422 .TP
 423 .BR SECCOMP_RET_ERRNO
 424 This value results in the
 425 .B SECCOMP_RET_DATA
 426 portion of the filter's return value being passed to user space as the
 427 .IR errno
 428 value without executing the system call.
 429 .TP
 430 .BR SECCOMP_RET_TRACE
 431 When returned, this value will cause the kernel to attempt to notify a
 432 .BR ptrace (2)-based
 433 tracer prior to executing the system call.
 434 If there is no tracer present,
 435 the system call is not executed and returns a failure status with
 436 .I errno
 437 set to
 438 .BR ENOSYS .
 439
 440 A tracer will be notified if it requests
 441 .BR PTRACE_O_TRACESECCOMP
 442 using
 443 .IR ptrace(PTRACE_SETOPTIONS) .
 444 The tracer will be notified of a
 445 .BR PTRACE_EVENT_SECCOMP
 446 and the
 447 .BR SECCOMP_RET_DATA
 448 portion of the filter's return value will be available to the tracer via
 449 .BR PTRACE_GETEVENTMSG .
 450
 451 The tracer can skip the system call by changing the system call number
 452 to \-1.
 453 Alternatively, the tracer can change the system call
 454 requested by changing the system call to a valid system call number.
 455 If the tracer asks to skip the system call, then the system call will
 456 appear to return the value that the tracer puts in the return value register.
 457
 458 .\" This was changed in ce6526e8afa4.
 459 .\" A related hole, using PTRACE_SYSCALL instead of SECCOMP_RET_TRACE, was
 460 .\" changed in arch-specific commits, e.g. 93e35efb8de4 for X86 and
 461 .\" 0f3912fd934c for ARM.
 462 Before kernel 4.8, the seccomp check will not be run again after the tracer is
 463 notified.
 464 (This means that, on older kernels, seccomp-based sandboxes
 465 .B "must not"
 466 allow use of
 467 .BR ptrace (2)\(emeven
 468 of other
 469 sandboxed processes\(emwithout extreme care;
 470 ptracers can use this mechanism to escape from the seccomp sandbox.)
 471 .TP
 472 .BR SECCOMP_RET_ALLOW
 473 This value results in the system call being executed.
 474 .SH RETURN VALUE
 475 On success,
 476 .BR seccomp ()
 477 returns 0.
 478 On error, if
 479 .BR SECCOMP_FILTER_FLAG_TSYNC
 480 was used,
 481 the return value is the ID of the thread
 482 that caused the synchronization failure.
 483 (This ID is a kernel thread ID of the type returned by
 484 .BR clone (2)
 485 and
 486 .BR gettid (2).)
 487 On other errors, \-1 is returned, and
 488 .IR errno
 489 is set to indicate the cause of the error.
 490 .SH ERRORS
 491 .BR seccomp ()
 492 can fail for the following reasons:
 493 .TP
 494 .BR EACCESS
 495 The caller did not have the
 496 .BR CAP_SYS_ADMIN
 497 capability in its user namespace, or had not set
 498 .IR no_new_privs
 499 before using
 500 .BR SECCOMP_SET_MODE_FILTER .
 501 .TP
 502 .BR EFAULT
 503 .IR args
 504 was not a valid address.
 505 .TP
 506 .BR EINVAL
 507 .IR operation
 508 is unknown; or
 509 .IR flags
 510 are invalid for the given
 511 .IR operation .
 512 .TP
 513 .BR EINVAL
 514 .I operation
 515 included
 516 .BR BPF_ABS ,
 517 but the specified offset was not aligned to a 32-bit boundary or exceeded
 518 .IR "sizeof(struct\ seccomp_data)" .
 519 .TP
 520 .BR EINVAL
 521 .\" See kernel/seccomp.c::seccomp_may_assign_mode() in 3.18 sources
 522 A secure computing mode has already been set, and
 523 .I operation
 524 differs from the existing setting.
 525 .TP
 526 .BR EINVAL
 527 .\" See stub kernel/seccomp.c::seccomp_set_mode_filter() in 3.18 sources
 528 .I operation
 529 specified
 530 .BR SECCOMP_SET_MODE_FILTER ,
 531 but the kernel was not built with
 532 .B CONFIG_SECCOMP_FILTER
 533 enabled.
 534 .TP
 535 .BR EINVAL
 536 .I operation
 537 specified
 538 .BR SECCOMP_SET_MODE_FILTER ,
 539 but the filter program pointed to by
 540 .I args
 541 was not valid or the length of the filter program was zero or exceeded
 542 .B BPF_MAXINSNS
 543 (4096) instructions.
 544 .TP
 545 .BR ENOMEM
 546 Out of memory.
 547 .TP
 548 .BR ENOMEM
 549 .\" ENOMEM in kernel/seccomp.c::seccomp_attach_filter() in 3.18 sources
 550 The total length of all filter programs attached
 551 to the calling thread would exceed
 552 .B MAX_INSNS_PER_PATH
 553 (32768) instructions.
 554 Note that for the purposes of calculating this limit,
 555 each already existing filter program incurs an
 556 overhead penalty of 4 instructions.
 557 .TP
 558 .BR ESRCH
 559 Another thread caused a failure during thread sync, but its ID could not
 560 be determined.
 561 .SH VERSIONS
 562 The
 563 .BR seccomp ()
 564 system call first appeared in Linux 3.17.
 565 .\" FIXME . Add glibc version
 566 .SH CONFORMING TO
 567 The
 568 .BR seccomp ()
 569 system call is a nonstandard Linux extension.
 570 .SH NOTES
 571 Rather than hand-coding seccomp filters as shown in the example below,
 572 you may prefer to employ the
 573 .I libseccomp
 574 library, which provides a front-end for generating seccomp filters.
 575
 576 The
 577 .IR Seccomp
 578 field of the
 579 .IR /proc/[pid]/status
 580 file provides a method of viewing the seccomp mode of a process; see
 581 .BR proc (5).
 582
 583 .BR seccomp ()
 584 provides a superset of the functionality provided by the
 585 .BR prctl (2)
 586 .BR PR_SET_SECCOMP
 587 operation (which does not support
 588 .IR flags ).
 589
 590 Since Linux 4.4, the
 591 .BR prctl (2)
 592 .B PTRACE_SECCOMP_GET_FILTER
 593 operation can be used to dump a process's seccomp filters.
 594 .\"
 595 .SS Seccomp-specific BPF details
 596 Note the following BPF details specific to seccomp filters:
 597 .IP * 3
 598 The
 599 .B BPF_H
 600 and
 601 .B BPF_B
 602 size modifiers are not supported: all operations must load and store
 603 (4-byte) words
 604 .RB ( BPF_W ).
 605 .IP *
 606 To access the contents of the
 607 .I seccomp_data
 608 buffer, use the
 609 .B BPF_ABS
 610 addressing mode modifier.
 611 .IP *
 612 The
 613 .B BPF_LEN
 614 addressing mode modifier yields an immediate mode operand
 615 whose value is the size of the
 616 .IR seccomp_data
 617 buffer.
 618 .SH EXAMPLE
 619 The program below accepts four or more arguments.
 620 The first three arguments are a system call number,
 621 a numeric architecture identifier, and an error number.
 622 The program uses these values to construct a BPF filter
 623 that is used at run time to perform the following checks:
 624 .IP [1] 4
 625 If the program is not running on the specified architecture,
 626 the BPF filter causes system calls to fail with the error
 627 .BR ENOSYS .
 628 .IP [2]
 629 If the program attempts to execute the system call with the specified number,
 630 the BPF filter causes the system call to fail, with
 631 .I errno
 632 being set to the specified error number.
 633 .PP
 634 The remaining command-line arguments specify
 635 the pathname and additional arguments of a program
 636 that the example program should attempt to execute using
 637 .BR execv (3)
 638 (a library function that employs the
 639 .BR execve (2)
 640 system call).
 641 Some example runs of the program are shown below.
 642
 643 First, we display the architecture that we are running on (x86-64)
 644 and then construct a shell function that looks up system call
 645 numbers on this architecture:
 646
 647 .nf
 648 .in +4n
 649 $ \fBuname -m\fP
 650 x86_64
 651 $ \fBsyscall_nr() {
 652     cat /usr/src/linux/arch/x86/syscalls/syscall_64.tbl | \\
 653     awk '$2 != "x32" && $3 == "'$1'" { print $1 }'
 654 }\fP
 655 .in
 656 .fi
 657
 658 When the BPF filter rejects a system call (case [2] above),
 659 it causes the system call to fail with the error number
 660 specified on the command line.
 661 In the experiments shown here, we'll use error number 99:
 662
 663 .nf
 664 .in +4n
 665 $ \fBerrno 99\fP
 666 EADDRNOTAVAIL 99 Cannot assign requested address
 667 .in
 668 .fi
 669
 670 In the following example, we attempt to run the command
 671 .BR whoami (1),
 672 but the BPF filter rejects the
 673 .BR execve (2)
 674 system call, so that the command is not even executed:
 675
 676 .nf
 677 .in +4n
 678 $ \fBsyscall_nr execve\fP
 679 59
 680 $ \fB./a.out\fP
 681 Usage: ./a.out <syscall_nr> <arch> <errno> <prog> [<args>]
 682 Hint for <arch>: AUDIT_ARCH_I386: 0x40000003
 683                  AUDIT_ARCH_X86_64: 0xC000003E
 684 $ \fB./a.out 59 0xC000003E 99 /bin/whoami\fP
 685 execv: Cannot assign requested address
 686 .in
 687 .fi
 688
 689 In the next example, the BPF filter rejects the
 690 .BR write (2)
 691 system call, so that, although it is successfully started, the
 692 .BR whoami (1)
 693 command is not able to write output:
 694
 695 .nf
 696 .in +4n
 697 $ \fBsyscall_nr write\fP
 698 1
 699 $ \fB./a.out 1 0xC000003E 99 /bin/whoami\fP
 700 .in
 701 .fi
 702
 703 In the final example,
 704 the BPF filter rejects a system call that is not used by the
 705 .BR whoami (1)
 706 command, so it is able to successfully execute and produce output:
 707
 708 .nf
 709 .in +4n
 710 $ \fBsyscall_nr preadv\fP
 711 295
 712 $ \fB./a.out 295 0xC000003E 99 /bin/whoami\fP
 713 cecilia
 714 .in
 715 .fi
 716 .SS Program source
 717 .nf
 718 #include <errno.h>
 719 #include <stddef.h>
 720 #include <stdio.h>
 721 #include <stdlib.h>
 722 #include <unistd.h>
 723 #include <linux/audit.h>
 724 #include <linux/filter.h>
 725 #include <linux/seccomp.h>
 726 #include <sys/prctl.h>
 727
 728 #define X32_SYSCALL_BIT 0x40000000
 729
 730 static int
 731 install_filter(int syscall_nr, int t_arch, int f_errno)
 732 {
 733     unsigned int upper_nr_limit = 0xffffffff;
 734
 735     /* Assume that AUDIT_ARCH_X86_64 means the normal x86-64 ABI */
 736     if (t_arch == AUDIT_ARCH_X86_64)
 737         upper_nr_limit = X32_SYSCALL_BIT - 1;
 738
 739     struct sock_filter filter[] = {
 740         /* [0] Load architecture from 'seccomp_data' buffer into
 741                accumulator */
 742         BPF_STMT(BPF_LD | BPF_W | BPF_ABS,
 743                  (offsetof(struct seccomp_data, arch))),
 744
 745         /* [1] Jump forward 5 instructions if architecture does not
 746                match 't_arch' */
 747         BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, t_arch, 0, 5),
 748
 749         /* [2] Load system call number from 'seccomp_data' buffer into
 750                accumulator */
 751         BPF_STMT(BPF_LD | BPF_W | BPF_ABS,
 752                  (offsetof(struct seccomp_data, nr))),
 753
 754         /* [3] Check ABI - only needed for x86-64 in blacklist use
 755                cases.  Use JGT instead of checking against the bit
 756                mask to avoid having to reload the syscall number. */
 757         BPF_JUMP(BPF_JMP | BPF_JGT | BPF_K, upper_nr_limit, 3, 0),
 758
 759         /* [4] Jump forward 1 instruction if system call number
 760                does not match 'syscall_nr' */
 761         BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, syscall_nr, 0, 1),
 762
 763         /* [5] Matching architecture and system call: don't execute
 764                the system call, and return 'f_errno' in 'errno' */
 765         BPF_STMT(BPF_RET | BPF_K,
 766                  SECCOMP_RET_ERRNO | (f_errno & SECCOMP_RET_DATA)),
 767
 768         /* [6] Destination of system call number mismatch: allow other
 769                system calls */
 770         BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW),
 771
 772         /* [7] Destination of architecture mismatch: kill process */
 773         BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_KILL),
 774     };
 775
 776     struct sock_fprog prog = {
 777         .len = (unsigned short) (sizeof(filter) / sizeof(filter[0])),
 778         .filter = filter,
 779     };
 780
 781     if (seccomp(SECCOMP_SET_MODE_FILTER, 0, &prog)) {
 782         perror("seccomp");
 783         return 1;
 784     }
 785
 786     return 0;
 787 }
 788
 789 int
 790 main(int argc, char **argv)
 791 {
 792     if (argc < 5) {
 793         fprintf(stderr, "Usage: "
 794                 "%s <syscall_nr> <arch> <errno> <prog> [<args>]\\n"
 795                 "Hint for <arch>: AUDIT_ARCH_I386: 0x%X\\n"
 796                 "                 AUDIT_ARCH_X86_64: 0x%X\\n"
 797                 "\\n", argv[0], AUDIT_ARCH_I386, AUDIT_ARCH_X86_64);
 798         exit(EXIT_FAILURE);
 799     }
 800
 801     if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) {
 802         perror("prctl");
 803         exit(EXIT_FAILURE);
 804     }
 805
 806     if (install_filter(strtol(argv[1], NULL, 0),
 807                        strtol(argv[2], NULL, 0),
 808                        strtol(argv[3], NULL, 0)))
 809         exit(EXIT_FAILURE);
 810
 811     execv(argv[4], &argv[4]);
 812     perror("execv");
 813     exit(EXIT_FAILURE);
 814 }
 815 .fi
 816 .SH SEE ALSO
 817 .BR bpf (2),
 818 .BR prctl (2),
 819 .BR ptrace (2),
 820 .BR sigaction (2),
 821 .BR proc (5),
 822 .BR signal (7),
 823 .BR socket (7)
 824 .sp
 825 Various pages from the
 826 .I libseccomp
 827 library, including:
 828 .BR scmp_sys_resolver (1),
 829 .BR seccomp_init (3),
 830 .BR seccomp_load (3),
 831 .BR seccomp_rule_add (3),
 832 and
 833 .BR seccomp_export_bpf (3).
 834 .sp
 835 The kernel source files
 836 .IR Documentation/networking/filter.txt
 837 and
 838 .IR Documentation/prctl/seccomp_filter.txt .
 839 .sp
 840 McCanne, S. and Jacobson, V. (1992)
 841 .IR "The BSD Packet Filter: A New Architecture for User-level Packet Capture" ,
 842 Proceedings of the USENIX Winter 1993 Conference
 843 .UR http://www.tcpdump.org/papers/bpf\-usenix93.pdf
 844 .UE