1.. _perf_security:
2
3Perf Events and tool security
4=============================
5
6Overview
7--------
8
9Usage of Performance Counters for Linux (perf_events) [1]_ , [2]_ , [3]_
10can impose a considerable risk of leaking sensitive data accessed by
11monitored processes. The data leakage is possible both in scenarios of
12direct usage of perf_events system call API [2]_ and over data files
13generated by Perf tool user mode utility (Perf) [3]_ , [4]_ . The risk
14depends on the nature of data that perf_events performance monitoring
15units (PMU) [2]_ and Perf collect and expose for performance analysis.
16Collected system and performance data may be split into several
17categories:
18
191. System hardware and software configuration data, for example: a CPU
20   model and its cache configuration, an amount of available memory and
21   its topology, used kernel and Perf versions, performance monitoring
22   setup including experiment time, events configuration, Perf command
23   line parameters, etc.
24
252. User and kernel module paths and their load addresses with sizes,
26   process and thread names with their PIDs and TIDs, timestamps for
27   captured hardware and software events.
28
293. Content of kernel software counters (e.g., for context switches, page
30   faults, CPU migrations), architectural hardware performance counters
31   (PMC) [8]_ and machine specific registers (MSR) [9]_ that provide
32   execution metrics for various monitored parts of the system (e.g.,
33   memory controller (IMC), interconnect (QPI/UPI) or peripheral (PCIe)
34   uncore counters) without direct attribution to any execution context
35   state.
36
374. Content of architectural execution context registers (e.g., RIP, RSP,
38   RBP on x86_64), process user and kernel space memory addresses and
39   data, content of various architectural MSRs that capture data from
40   this category.
41
42Data that belong to the fourth category can potentially contain
43sensitive process data. If PMUs in some monitoring modes capture values
44of execution context registers or data from process memory then access
45to such monitoring capabilities requires to be ordered and secured
46properly. So, perf_events/Perf performance monitoring is the subject for
47security access control management [5]_ .
48
49perf_events/Perf access control
50-------------------------------
51
52To perform security checks, the Linux implementation splits processes
53into two categories [6]_ : a) privileged processes (whose effective user
54ID is 0, referred to as superuser or root), and b) unprivileged
55processes (whose effective UID is nonzero). Privileged processes bypass
56all kernel security permission checks so perf_events performance
57monitoring is fully available to privileged processes without access,
58scope and resource restrictions.
59
60Unprivileged processes are subject to a full security permission check
61based on the process's credentials [5]_ (usually: effective UID,
62effective GID, and supplementary group list).
63
64Linux divides the privileges traditionally associated with superuser
65into distinct units, known as capabilities [6]_ , which can be
66independently enabled and disabled on per-thread basis for processes and
67files of unprivileged users.
68
69Unprivileged processes with enabled CAP_SYS_ADMIN capability are treated
70as privileged processes with respect to perf_events performance
71monitoring and bypass *scope* permissions checks in the kernel.
72
73Unprivileged processes using perf_events system call API is also subject
74for PTRACE_MODE_READ_REALCREDS ptrace access mode check [7]_ , whose
75outcome determines whether monitoring is permitted. So unprivileged
76processes provided with CAP_SYS_PTRACE capability are effectively
77permitted to pass the check.
78
79Other capabilities being granted to unprivileged processes can
80effectively enable capturing of additional data required for later
81performance analysis of monitored processes or a system. For example,
82CAP_SYSLOG capability permits reading kernel space memory addresses from
83/proc/kallsyms file.
84
85perf_events/Perf privileged users
86---------------------------------
87
88Mechanisms of capabilities, privileged capability-dumb files [6]_ and
89file system ACLs [10]_ can be used to create a dedicated group of
90perf_events/Perf privileged users who are permitted to execute
91performance monitoring without scope limits. The following steps can be
92taken to create such a group of privileged Perf users.
93
941. Create perf_users group of privileged Perf users, assign perf_users
95   group to Perf tool executable and limit access to the executable for
96   other users in the system who are not in the perf_users group:
97
98::
99
100   # groupadd perf_users
101   # ls -alhF
102   -rwxr-xr-x  2 root root  11M Oct 19 15:12 perf
103   # chgrp perf_users perf
104   # ls -alhF
105   -rwxr-xr-x  2 root perf_users  11M Oct 19 15:12 perf
106   # chmod o-rwx perf
107   # ls -alhF
108   -rwxr-x---  2 root perf_users  11M Oct 19 15:12 perf
109
1102. Assign the required capabilities to the Perf tool executable file and
111   enable members of perf_users group with performance monitoring
112   privileges [6]_ :
113
114::
115
116   # setcap "cap_sys_admin,cap_sys_ptrace,cap_syslog=ep" perf
117   # setcap -v "cap_sys_admin,cap_sys_ptrace,cap_syslog=ep" perf
118   perf: OK
119   # getcap perf
120   perf = cap_sys_ptrace,cap_sys_admin,cap_syslog+ep
121
122As a result, members of perf_users group are capable of conducting
123performance monitoring by using functionality of the configured Perf
124tool executable that, when executes, passes perf_events subsystem scope
125checks.
126
127This specific access control management is only available to superuser
128or root running processes with CAP_SETPCAP, CAP_SETFCAP [6]_
129capabilities.
130
131perf_events/Perf unprivileged users
132-----------------------------------
133
134perf_events/Perf *scope* and *access* control for unprivileged processes
135is governed by perf_event_paranoid [2]_ setting:
136
137-1:
138     Impose no *scope* and *access* restrictions on using perf_events
139     performance monitoring. Per-user per-cpu perf_event_mlock_kb [2]_
140     locking limit is ignored when allocating memory buffers for storing
141     performance data. This is the least secure mode since allowed
142     monitored *scope* is maximized and no perf_events specific limits
143     are imposed on *resources* allocated for performance monitoring.
144
145>=0:
146     *scope* includes per-process and system wide performance monitoring
147     but excludes raw tracepoints and ftrace function tracepoints
148     monitoring. CPU and system events happened when executing either in
149     user or in kernel space can be monitored and captured for later
150     analysis. Per-user per-cpu perf_event_mlock_kb locking limit is
151     imposed but ignored for unprivileged processes with CAP_IPC_LOCK
152     [6]_ capability.
153
154>=1:
155     *scope* includes per-process performance monitoring only and
156     excludes system wide performance monitoring. CPU and system events
157     happened when executing either in user or in kernel space can be
158     monitored and captured for later analysis. Per-user per-cpu
159     perf_event_mlock_kb locking limit is imposed but ignored for
160     unprivileged processes with CAP_IPC_LOCK capability.
161
162>=2:
163     *scope* includes per-process performance monitoring only. CPU and
164     system events happened when executing in user space only can be
165     monitored and captured for later analysis. Per-user per-cpu
166     perf_event_mlock_kb locking limit is imposed but ignored for
167     unprivileged processes with CAP_IPC_LOCK capability.
168
169perf_events/Perf resource control
170---------------------------------
171
172Open file descriptors
173+++++++++++++++++++++
174
175The perf_events system call API [2]_ allocates file descriptors for
176every configured PMU event. Open file descriptors are a per-process
177accountable resource governed by the RLIMIT_NOFILE [11]_ limit
178(ulimit -n), which is usually derived from the login shell process. When
179configuring Perf collection for a long list of events on a large server
180system, this limit can be easily hit preventing required monitoring
181configuration. RLIMIT_NOFILE limit can be increased on per-user basis
182modifying content of the limits.conf file [12]_ . Ordinarily, a Perf
183sampling session (perf record) requires an amount of open perf_event
184file descriptors that is not less than the number of monitored events
185multiplied by the number of monitored CPUs.
186
187Memory allocation
188+++++++++++++++++
189
190The amount of memory available to user processes for capturing
191performance monitoring data is governed by the perf_event_mlock_kb [2]_
192setting. This perf_event specific resource setting defines overall
193per-cpu limits of memory allowed for mapping by the user processes to
194execute performance monitoring. The setting essentially extends the
195RLIMIT_MEMLOCK [11]_ limit, but only for memory regions mapped
196specifically for capturing monitored performance events and related data.
197
198For example, if a machine has eight cores and perf_event_mlock_kb limit
199is set to 516 KiB, then a user process is provided with 516 KiB * 8 =
2004128 KiB of memory above the RLIMIT_MEMLOCK limit (ulimit -l) for
201perf_event mmap buffers. In particular, this means that, if the user
202wants to start two or more performance monitoring processes, the user is
203required to manually distribute the available 4128 KiB between the
204monitoring processes, for example, using the --mmap-pages Perf record
205mode option. Otherwise, the first started performance monitoring process
206allocates all available 4128 KiB and the other processes will fail to
207proceed due to the lack of memory.
208
209RLIMIT_MEMLOCK and perf_event_mlock_kb resource constraints are ignored
210for processes with the CAP_IPC_LOCK capability. Thus, perf_events/Perf
211privileged users can be provided with memory above the constraints for
212perf_events/Perf performance monitoring purpose by providing the Perf
213executable with CAP_IPC_LOCK capability.
214
215Bibliography
216------------
217
218.. [1] `<https://lwn.net/Articles/337493/>`_
219.. [2] `<http://man7.org/linux/man-pages/man2/perf_event_open.2.html>`_
220.. [3] `<http://web.eece.maine.edu/~vweaver/projects/perf_events/>`_
221.. [4] `<https://perf.wiki.kernel.org/index.php/Main_Page>`_
222.. [5] `<https://www.kernel.org/doc/html/latest/security/credentials.html>`_
223.. [6] `<http://man7.org/linux/man-pages/man7/capabilities.7.html>`_
224.. [7] `<http://man7.org/linux/man-pages/man2/ptrace.2.html>`_
225.. [8] `<https://en.wikipedia.org/wiki/Hardware_performance_counter>`_
226.. [9] `<https://en.wikipedia.org/wiki/Model-specific_register>`_
227.. [10] `<http://man7.org/linux/man-pages/man5/acl.5.html>`_
228.. [11] `<http://man7.org/linux/man-pages/man2/getrlimit.2.html>`_
229.. [12] `<http://man7.org/linux/man-pages/man5/limits.conf.5.html>`_
230
231