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