About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / prctl / seccomp_filter.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:40 EST.

1			SECure COMPuting with filters
2			=============================
3	
4	Introduction
5	------------
6	
7	A large number of system calls are exposed to every userland process
8	with many of them going unused for the entire lifetime of the process.
9	As system calls change and mature, bugs are found and eradicated.  A
10	certain subset of userland applications benefit by having a reduced set
11	of available system calls.  The resulting set reduces the total kernel
12	surface exposed to the application.  System call filtering is meant for
13	use with those applications.
14	
15	Seccomp filtering provides a means for a process to specify a filter for
16	incoming system calls.  The filter is expressed as a Berkeley Packet
17	Filter (BPF) program, as with socket filters, except that the data
18	operated on is related to the system call being made: system call
19	number and the system call arguments.  This allows for expressive
20	filtering of system calls using a filter program language with a long
21	history of being exposed to userland and a straightforward data set.
22	
23	Additionally, BPF makes it impossible for users of seccomp to fall prey
24	to time-of-check-time-of-use (TOCTOU) attacks that are common in system
25	call interposition frameworks.  BPF programs may not dereference
26	pointers which constrains all filters to solely evaluating the system
27	call arguments directly.
28	
29	What it isn't
30	-------------
31	
32	System call filtering isn't a sandbox.  It provides a clearly defined
33	mechanism for minimizing the exposed kernel surface.  It is meant to be
34	a tool for sandbox developers to use.  Beyond that, policy for logical
35	behavior and information flow should be managed with a combination of
36	other system hardening techniques and, potentially, an LSM of your
37	choosing.  Expressive, dynamic filters provide further options down this
38	path (avoiding pathological sizes or selecting which of the multiplexed
39	system calls in socketcall() is allowed, for instance) which could be
40	construed, incorrectly, as a more complete sandboxing solution.
41	
42	Usage
43	-----
44	
45	An additional seccomp mode is added and is enabled using the same
46	prctl(2) call as the strict seccomp.  If the architecture has
47	CONFIG_HAVE_ARCH_SECCOMP_FILTER, then filters may be added as below:
48	
49	PR_SET_SECCOMP:
50		Now takes an additional argument which specifies a new filter
51		using a BPF program.
52		The BPF program will be executed over struct seccomp_data
53		reflecting the system call number, arguments, and other
54		metadata.  The BPF program must then return one of the
55		acceptable values to inform the kernel which action should be
56		taken.
57	
58		Usage:
59			prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, prog);
60	
61		The 'prog' argument is a pointer to a struct sock_fprog which
62		will contain the filter program.  If the program is invalid, the
63		call will return -1 and set errno to EINVAL.
64	
65		If fork/clone and execve are allowed by @prog, any child
66		processes will be constrained to the same filters and system
67		call ABI as the parent.
68	
69		Prior to use, the task must call prctl(PR_SET_NO_NEW_PRIVS, 1) or
70		run with CAP_SYS_ADMIN privileges in its namespace.  If these are not
71		true, -EACCES will be returned.  This requirement ensures that filter
72		programs cannot be applied to child processes with greater privileges
73		than the task that installed them.
74	
75		Additionally, if prctl(2) is allowed by the attached filter,
76		additional filters may be layered on which will increase evaluation
77		time, but allow for further decreasing the attack surface during
78		execution of a process.
79	
80	The above call returns 0 on success and non-zero on error.
81	
82	Return values
83	-------------
84	A seccomp filter may return any of the following values. If multiple
85	filters exist, the return value for the evaluation of a given system
86	call will always use the highest precedent value. (For example,
87	SECCOMP_RET_KILL will always take precedence.)
88	
89	In precedence order, they are:
90	
91	SECCOMP_RET_KILL:
92		Results in the task exiting immediately without executing the
93		system call.  The exit status of the task (status & 0x7f) will
94		be SIGSYS, not SIGKILL.
95	
96	SECCOMP_RET_TRAP:
97		Results in the kernel sending a SIGSYS signal to the triggering
98		task without executing the system call.  siginfo->si_call_addr
99		will show the address of the system call instruction, and
100		siginfo->si_syscall and siginfo->si_arch will indicate which
101		syscall was attempted.  The program counter will be as though
102		the syscall happened (i.e. it will not point to the syscall
103		instruction).  The return value register will contain an arch-
104		dependent value -- if resuming execution, set it to something
105		sensible.  (The architecture dependency is because replacing
106		it with -ENOSYS could overwrite some useful information.)
107	
108		The SECCOMP_RET_DATA portion of the return value will be passed
109		as si_errno.
110	
111		SIGSYS triggered by seccomp will have a si_code of SYS_SECCOMP.
112	
113	SECCOMP_RET_ERRNO:
114		Results in the lower 16-bits of the return value being passed
115		to userland as the errno without executing the system call.
116	
117	SECCOMP_RET_TRACE:
118		When returned, this value will cause the kernel to attempt to
119		notify a ptrace()-based tracer prior to executing the system
120		call.  If there is no tracer present, -ENOSYS is returned to
121		userland and the system call is not executed.
122	
123		A tracer will be notified if it requests PTRACE_O_TRACESECCOMP
124		using ptrace(PTRACE_SETOPTIONS).  The tracer will be notified
125		of a PTRACE_EVENT_SECCOMP and the SECCOMP_RET_DATA portion of
126		the BPF program return value will be available to the tracer
127		via PTRACE_GETEVENTMSG.
128	
129		The tracer can skip the system call by changing the syscall number
130		to -1.  Alternatively, the tracer can change the system call
131		requested by changing the system call to a valid syscall number.  If
132		the tracer asks to skip the system call, then the system call will
133		appear to return the value that the tracer puts in the return value
134		register.
135	
136		The seccomp check will not be run again after the tracer is
137		notified.  (This means that seccomp-based sandboxes MUST NOT
138		allow use of ptrace, even of other sandboxed processes, without
139		extreme care; ptracers can use this mechanism to escape.)
140	
141	SECCOMP_RET_ALLOW:
142		Results in the system call being executed.
143	
144	If multiple filters exist, the return value for the evaluation of a
145	given system call will always use the highest precedent value.
146	
147	Precedence is only determined using the SECCOMP_RET_ACTION mask.  When
148	multiple filters return values of the same precedence, only the
149	SECCOMP_RET_DATA from the most recently installed filter will be
150	returned.
151	
152	Pitfalls
153	--------
154	
155	The biggest pitfall to avoid during use is filtering on system call
156	number without checking the architecture value.  Why?  On any
157	architecture that supports multiple system call invocation conventions,
158	the system call numbers may vary based on the specific invocation.  If
159	the numbers in the different calling conventions overlap, then checks in
160	the filters may be abused.  Always check the arch value!
161	
162	Example
163	-------
164	
165	The samples/seccomp/ directory contains both an x86-specific example
166	and a more generic example of a higher level macro interface for BPF
167	program generation.
168	
169	
170	
171	Adding architecture support
172	-----------------------
173	
174	See arch/Kconfig for the authoritative requirements.  In general, if an
175	architecture supports both ptrace_event and seccomp, it will be able to
176	support seccomp filter with minor fixup: SIGSYS support and seccomp return
177	value checking.  Then it must just add CONFIG_HAVE_ARCH_SECCOMP_FILTER
178	to its arch-specific Kconfig.
179	
180	
181	
182	Caveats
183	-------
184	
185	The vDSO can cause some system calls to run entirely in userspace,
186	leading to surprises when you run programs on different machines that
187	fall back to real syscalls.  To minimize these surprises on x86, make
188	sure you test with
189	/sys/devices/system/clocksource/clocksource0/current_clocksource set to
190	something like acpi_pm.
191	
192	On x86-64, vsyscall emulation is enabled by default.  (vsyscalls are
193	legacy variants on vDSO calls.)  Currently, emulated vsyscalls will honor seccomp, with a few oddities:
194	
195	- A return value of SECCOMP_RET_TRAP will set a si_call_addr pointing to
196	  the vsyscall entry for the given call and not the address after the
197	  'syscall' instruction.  Any code which wants to restart the call
198	  should be aware that (a) a ret instruction has been emulated and (b)
199	  trying to resume the syscall will again trigger the standard vsyscall
200	  emulation security checks, making resuming the syscall mostly
201	  pointless.
202	
203	- A return value of SECCOMP_RET_TRACE will signal the tracer as usual,
204	  but the syscall may not be changed to another system call using the
205	  orig_rax register. It may only be changed to -1 order to skip the
206	  currently emulated call. Any other change MAY terminate the process.
207	  The rip value seen by the tracer will be the syscall entry address;
208	  this is different from normal behavior.  The tracer MUST NOT modify
209	  rip or rsp.  (Do not rely on other changes terminating the process.
210	  They might work.  For example, on some kernels, choosing a syscall
211	  that only exists in future kernels will be correctly emulated (by
212	  returning -ENOSYS).
213	
214	To detect this quirky behavior, check for addr & ~0x0C00 ==
215	0xFFFFFFFFFF600000.  (For SECCOMP_RET_TRACE, use rip.  For
216	SECCOMP_RET_TRAP, use siginfo->si_call_addr.)  Do not check any other
217	condition: future kernels may improve vsyscall emulation and current
218	kernels in vsyscall=native mode will behave differently, but the
219	instructions at 0xF...F600{0,4,8,C}00 will not be system calls in these
220	cases.
221	
222	Note that modern systems are unlikely to use vsyscalls at all -- they
223	are a legacy feature and they are considerably slower than standard
224	syscalls.  New code will use the vDSO, and vDSO-issued system calls
225	are indistinguishable from normal system calls.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.