Linux/Documentation/admin-guide/perf-security.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

1 .. _perf_security: 1 .. _perf_security: 2 2 3 Perf events and tool security !! 3 Perf Events and tool security 4 ============================= 4 ============================= 5 5 6 Overview 6 Overview 7 -------- 7 -------- 8 8 9 Usage of Performance Counters for Linux (perf_ !! 9 Usage of Performance Counters for Linux (perf_events) [1]_ , [2]_ , [3]_ can 10 can impose a considerable risk of leaking sens !! 10 impose a considerable risk of leaking sensitive data accessed by monitored 11 monitored processes. The data leakage is possi !! 11 processes. The data leakage is possible both in scenarios of direct usage of 12 direct usage of perf_events system call API [2 !! 12 perf_events system call API [2]_ and over data files generated by Perf tool user 13 generated by Perf tool user mode utility (Perf !! 13 mode utility (Perf) [3]_ , [4]_ . The risk depends on the nature of data that 14 depends on the nature of data that perf_events !! 14 perf_events performance monitoring units (PMU) [2]_ collect and expose for 15 units (PMU) [2]_ and Perf collect and expose f !! 15 performance analysis. Having that said perf_events/Perf performance monitoring 16 Collected system and performance data may be s !! 16 is the subject for security access control management [5]_ . 17 categories: << 18 << 19 1. System hardware and software configuration << 20 model and its cache configuration, an amoun << 21 its topology, used kernel and Perf versions << 22 setup including experiment time, events con << 23 line parameters, etc. << 24 << 25 2. User and kernel module paths and their load << 26 process and thread names with their PIDs an << 27 captured hardware and software events. << 28 << 29 3. Content of kernel software counters (e.g., << 30 faults, CPU migrations), architectural hard << 31 (PMC) [8]_ and machine specific registers ( << 32 execution metrics for various monitored par << 33 memory controller (IMC), interconnect (QPI/ << 34 uncore counters) without direct attribution << 35 state. << 36 << 37 4. Content of architectural execution context << 38 RBP on x86_64), process user and kernel spa << 39 data, content of various architectural MSRs << 40 this category. << 41 << 42 Data that belong to the fourth category can po << 43 sensitive process data. If PMUs in some monito << 44 of execution context registers or data from pr << 45 to such monitoring modes requires to be ordere << 46 So, perf_events performance monitoring and obs << 47 the subject for security access control manage << 48 17 49 perf_events access control !! 18 perf_events/Perf access control 50 ------------------------------- 19 ------------------------------- 51 20 52 To perform security checks, the Linux implemen !! 21 To perform security checks, the Linux implementation splits processes into two 53 into two categories [6]_ : a) privileged proce !! 22 categories [6]_ : a) privileged processes (whose effective user ID is 0, referred 54 ID is 0, referred to as superuser or root), an !! 23 to as superuser or root), and b) unprivileged processes (whose effective UID is 55 processes (whose effective UID is nonzero). Pr !! 24 nonzero). Privileged processes bypass all kernel security permission checks so 56 all kernel security permission checks so perf_ !! 25 perf_events performance monitoring is fully available to privileged processes 57 monitoring is fully available to privileged pr !! 26 without access, scope and resource restrictions. 58 scope and resource restrictions. !! 27 59 !! 28 Unprivileged processes are subject to a full security permission check based on 60 Unprivileged processes are subject to a full s !! 29 the process's credentials [5]_ (usually: effective UID, effective GID, and 61 based on the process's credentials [5]_ (usual !! 30 supplementary group list). 62 effective GID, and supplementary group list). !! 31 63 !! 32 Linux divides the privileges traditionally associated with superuser into 64 Linux divides the privileges traditionally ass !! 33 distinct units, known as capabilities [6]_ , which can be independently enabled 65 into distinct units, known as capabilities [6] !! 34 and disabled on per-thread basis for processes and files of unprivileged users. 66 independently enabled and disabled on per-thre !! 35 67 files of unprivileged users. !! 36 Unprivileged processes with enabled CAP_SYS_ADMIN capability are treated as 68 !! 37 privileged processes with respect to perf_events performance monitoring and 69 Unprivileged processes with enabled CAP_PERFMO !! 38 bypass *scope* permissions checks in the kernel. 70 as privileged processes with respect to perf_e !! 39 71 monitoring and observability operations, thus, !! 40 Unprivileged processes using perf_events system call API is also subject for 72 checks in the kernel. CAP_PERFMON implements t !! 41 PTRACE_MODE_READ_REALCREDS ptrace access mode check [7]_ , whose outcome 73 privilege [13]_ (POSIX 1003.1e: 2.2.2.39) for !! 42 determines whether monitoring is permitted. So unprivileged processes provided 74 observability operations in the kernel and pro !! 43 with CAP_SYS_PTRACE capability are effectively permitted to pass the check. 75 performance monitoring and observability in th !! 44 76 !! 45 Other capabilities being granted to unprivileged processes can effectively 77 For backward compatibility reasons the access !! 46 enable capturing of additional data required for later performance analysis of 78 observability operations is also open for CAP_ !! 47 monitored processes or a system. For example, CAP_SYSLOG capability permits 79 processes but CAP_SYS_ADMIN usage for secure m !! 48 reading kernel space memory addresses from /proc/kallsyms file. 80 use cases is discouraged with respect to the C << 81 If system audit records [14]_ for a process us << 82 API contain denial records of acquiring both C << 83 capabilities then providing the process with C << 84 is recommended as the preferred secure approac << 85 denial logging related to usage of performance << 86 << 87 Prior Linux v5.9 unprivileged processes using << 88 are also subject for PTRACE_MODE_READ_REALCRED << 89 [7]_ , whose outcome determines whether monito << 90 So unprivileged processes provided with CAP_SY << 91 effectively permitted to pass the check. Start << 92 CAP_SYS_PTRACE capability is not required and << 93 be provided for processes to make performance << 94 operations. << 95 << 96 Other capabilities being granted to unprivileg << 97 effectively enable capturing of additional dat << 98 performance analysis of monitored processes or << 99 CAP_SYSLOG capability permits reading kernel s << 100 /proc/kallsyms file. << 101 << 102 Privileged Perf users groups << 103 --------------------------------- << 104 << 105 Mechanisms of capabilities, privileged capabil << 106 file system ACLs [10]_ and sudo [15]_ utility << 107 dedicated groups of privileged Perf users who << 108 performance monitoring and observability witho << 109 steps can be taken to create such groups of pr << 110 << 111 1. Create perf_users group of privileged Perf << 112 group to Perf tool executable and limit acc << 113 other users in the system who are not in th << 114 << 115 :: << 116 << 117 # groupadd perf_users << 118 # ls -alhF << 119 -rwxr-xr-x 2 root root 11M Oct 19 15:12 p << 120 # chgrp perf_users perf << 121 # ls -alhF << 122 -rwxr-xr-x 2 root perf_users 11M Oct 19 1 << 123 # chmod o-rwx perf << 124 # ls -alhF << 125 -rwxr-x--- 2 root perf_users 11M Oct 19 1 << 126 << 127 2. Assign the required capabilities to the Per << 128 enable members of perf_users group with mon << 129 privileges [6]_ : << 130 << 131 :: << 132 << 133 # setcap "cap_perfmon,cap_sys_ptrace,cap_sy << 134 # setcap -v "cap_perfmon,cap_sys_ptrace,cap << 135 perf: OK << 136 # getcap perf << 137 perf = cap_sys_ptrace,cap_syslog,cap_perfmo << 138 << 139 If the libcap [16]_ installed doesn't yet supp << 140 i.e.: << 141 << 142 :: << 143 << 144 # setcap "38,cap_ipc_lock,cap_sys_ptrace,ca << 145 << 146 Note that you may need to have 'cap_ipc_lock' << 147 'perf top', alternatively use 'perf top -m N', << 148 it uses for the perf ring buffer, see the memo << 149 << 150 Using a libcap without support for CAP_PERFMON << 151 CAP_EFFECTIVE, &val) fail, which will lead the << 152 so as a workaround explicitly ask for the 'cyc << 153 << 154 :: << 155 << 156 # perf top -e cycles << 157 << 158 To get kernel and user samples with a perf bin << 159 << 160 As a result, members of perf_users group are c << 161 performance monitoring and observability by us << 162 configured Perf tool executable that, when exe << 163 subsystem scope checks. << 164 << 165 In case Perf tool executable can't be assigned << 166 file system is mounted with nosuid option or e << 167 not supported by the file system) then creatio << 168 privileged environment, naturally shell, is po << 169 inherent processes with CAP_PERFMON and other << 170 performance monitoring and observability opera << 171 environment without limits. Access to the envi << 172 utility for members of perf_users group only. << 173 environment: << 174 << 175 1. Create shell script that uses capsh utility << 176 and other required capabilities into ambien << 177 process, lock the process security bits aft << 178 SECBIT_NOROOT and SECBIT_NO_CAP_AMBIENT_RAI << 179 the process identity to sudo caller of the << 180 be a member of perf_users group: << 181 << 182 :: << 183 << 184 # ls -alh /usr/local/bin/perf.shell << 185 -rwxr-xr-x. 1 root root 83 Oct 13 23:57 /us << 186 # cat /usr/local/bin/perf.shell << 187 exec /usr/sbin/capsh --iab=^cap_perfmon --s << 188 << 189 2. Extend sudo policy at /etc/sudoers file wit << 190 << 191 :: << 192 << 193 # grep perf_users /etc/sudoers << 194 %perf_users ALL=/usr/local/bin/perf.shel << 195 << 196 3. Check that members of perf_users group have << 197 shell and have CAP_PERFMON and other requir << 198 in permitted, effective and ambient capabil << 199 << 200 :: << 201 << 202 $ id << 203 uid=1003(capsh_test) gid=1004(capsh_test) gr << 204 $ sudo perf.shell << 205 [sudo] password for capsh_test: << 206 $ grep Cap /proc/self/status << 207 CapInh: 0000004000000000 << 208 CapPrm: 0000004000000000 << 209 CapEff: 0000004000000000 << 210 CapBnd: 000000ffffffffff << 211 CapAmb: 0000004000000000 << 212 $ capsh --decode=0000004000000000 << 213 0x0000004000000000=cap_perfmon << 214 << 215 As a result, members of perf_users group have << 216 environment where they can use tools employing << 217 governed by CAP_PERFMON Linux capability. << 218 << 219 This specific access control management is onl << 220 or root running processes with CAP_SETPCAP, CA << 221 capabilities. << 222 49 223 Unprivileged users !! 50 perf_events/Perf unprivileged users 224 ----------------------------------- 51 ----------------------------------- 225 52 226 perf_events *scope* and *access* control for u !! 53 perf_events/Perf *scope* and *access* control for unprivileged processes is 227 is governed by perf_event_paranoid [2]_ settin !! 54 governed by perf_event_paranoid [2]_ setting: 228 55 229 -1: 56 -1: 230 Impose no *scope* and *access* restrictio !! 57 Impose no *scope* and *access* restrictions on using perf_events performance 231 performance monitoring. Per-user per-cpu !! 58 monitoring. Per-user per-cpu perf_event_mlock_kb [2]_ locking limit is 232 locking limit is ignored when allocating !! 59 ignored when allocating memory buffers for storing performance data. 233 performance data. This is the least secur !! 60 This is the least secure mode since allowed monitored *scope* is 234 monitored *scope* is maximized and no per !! 61 maximized and no perf_events specific limits are imposed on *resources* 235 are imposed on *resources* allocated for !! 62 allocated for performance monitoring. 236 63 237 >=0: 64 >=0: 238 *scope* includes per-process and system w 65 *scope* includes per-process and system wide performance monitoring 239 but excludes raw tracepoints and ftrace f !! 66 but excludes raw tracepoints and ftrace function tracepoints monitoring. 240 monitoring. CPU and system events happene !! 67 CPU and system events happened when executing either in user or 241 user or in kernel space can be monitored !! 68 in kernel space can be monitored and captured for later analysis. 242 analysis. Per-user per-cpu perf_event_mlo !! 69 Per-user per-cpu perf_event_mlock_kb locking limit is imposed but 243 imposed but ignored for unprivileged proc !! 70 ignored for unprivileged processes with CAP_IPC_LOCK [6]_ capability. 244 [6]_ capability. << 245 71 246 >=1: 72 >=1: 247 *scope* includes per-process performance !! 73 *scope* includes per-process performance monitoring only and excludes 248 excludes system wide performance monitori !! 74 system wide performance monitoring. CPU and system events happened when 249 happened when executing either in user or !! 75 executing either in user or in kernel space can be monitored and 250 monitored and captured for later analysis !! 76 captured for later analysis. Per-user per-cpu perf_event_mlock_kb 251 perf_event_mlock_kb locking limit is impo !! 77 locking limit is imposed but ignored for unprivileged processes with 252 unprivileged processes with CAP_IPC_LOCK !! 78 CAP_IPC_LOCK capability. 253 79 254 >=2: 80 >=2: 255 *scope* includes per-process performance !! 81 *scope* includes per-process performance monitoring only. CPU and system 256 system events happened when executing in !! 82 events happened when executing in user space only can be monitored and 257 monitored and captured for later analysis !! 83 captured for later analysis. Per-user per-cpu perf_event_mlock_kb 258 perf_event_mlock_kb locking limit is impo !! 84 locking limit is imposed but ignored for unprivileged processes with 259 unprivileged processes with CAP_IPC_LOCK !! 85 CAP_IPC_LOCK capability. 260 << 261 Resource control << 262 --------------------------------- << 263 << 264 Open file descriptors << 265 +++++++++++++++++++++ << 266 << 267 The perf_events system call API [2]_ allocates << 268 every configured PMU event. Open file descript << 269 accountable resource governed by the RLIMIT_NO << 270 (ulimit -n), which is usually derived from the << 271 configuring Perf collection for a long list of << 272 system, this limit can be easily hit preventin << 273 configuration. RLIMIT_NOFILE limit can be incr << 274 modifying content of the limits.conf file [12] << 275 sampling session (perf record) requires an amo << 276 file descriptors that is not less than the num << 277 multiplied by the number of monitored CPUs. << 278 << 279 Memory allocation << 280 +++++++++++++++++ << 281 << 282 The amount of memory available to user process << 283 performance monitoring data is governed by the << 284 setting. This perf_event specific resource set << 285 per-cpu limits of memory allowed for mapping b << 286 execute performance monitoring. The setting es << 287 RLIMIT_MEMLOCK [11]_ limit, but only for memor << 288 specifically for capturing monitored performan << 289 << 290 For example, if a machine has eight cores and << 291 is set to 516 KiB, then a user process is prov << 292 4128 KiB of memory above the RLIMIT_MEMLOCK li << 293 perf_event mmap buffers. In particular, this m << 294 wants to start two or more performance monitor << 295 required to manually distribute the available << 296 monitoring processes, for example, using the - << 297 mode option. Otherwise, the first started perf << 298 allocates all available 4128 KiB and the other << 299 proceed due to the lack of memory. << 300 << 301 RLIMIT_MEMLOCK and perf_event_mlock_kb resourc << 302 for processes with the CAP_IPC_LOCK capability << 303 privileged users can be provided with memory a << 304 perf_events/Perf performance monitoring purpos << 305 executable with CAP_IPC_LOCK capability. << 306 86 307 Bibliography 87 Bibliography 308 ------------ 88 ------------ 309 89 310 .. [1] `<https://lwn.net/Articles/337493/>`_ 90 .. [1] `<https://lwn.net/Articles/337493/>`_ 311 .. [2] `<http://man7.org/linux/man-pages/man2/ 91 .. [2] `<http://man7.org/linux/man-pages/man2/perf_event_open.2.html>`_ 312 .. [3] `<http://web.eece.maine.edu/~vweaver/pr 92 .. [3] `<http://web.eece.maine.edu/~vweaver/projects/perf_events/>`_ 313 .. [4] `<https://perf.wiki.kernel.org/index.ph 93 .. [4] `<https://perf.wiki.kernel.org/index.php/Main_Page>`_ 314 .. [5] `<https://www.kernel.org/doc/html/lates 94 .. [5] `<https://www.kernel.org/doc/html/latest/security/credentials.html>`_ 315 .. [6] `<http://man7.org/linux/man-pages/man7/ 95 .. [6] `<http://man7.org/linux/man-pages/man7/capabilities.7.html>`_ 316 .. [7] `<http://man7.org/linux/man-pages/man2/ 96 .. [7] `<http://man7.org/linux/man-pages/man2/ptrace.2.html>`_ 317 .. [8] `<https://en.wikipedia.org/wiki/Hardwar !! 97 318 .. [9] `<https://en.wikipedia.org/wiki/Model-s << 319 .. [10] `<http://man7.org/linux/man-pages/man5 << 320 .. [11] `<http://man7.org/linux/man-pages/man2 << 321 .. [12] `<http://man7.org/linux/man-pages/man5 << 322 .. [13] `<https://sites.google.com/site/fullyc << 323 .. [14] `<http://man7.org/linux/man-pages/man8 << 324 .. [15] `<https://man7.org/linux/man-pages/man << 325 .. [16] `<https://git.kernel.org/pub/scm/libs/ <<

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

TOMOYO Linux Cross Reference
Linux/Documentation/admin-guide/perf-security.rst

Diff markup

Differences between /Documentation/admin-guide/perf-security.rst (Version linux-6.12-rc7) and /Documentation/admin-guide/perf-security.rst (Version linux-5.0.21)

TOMOYO Linux Cross Reference Linux/Documentation/admin-guide/perf-security.rst

Diff markup

Differences between /Documentation/admin-guide/perf-security.rst (Version linux-6.12-rc7) and /Documentation/admin-guide/perf-security.rst (Version linux-5.0.21)

TOMOYO Linux Cross Reference
Linux/Documentation/admin-guide/perf-security.rst