tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

doc/admin-guide: Update perf-security.rst with CAP_PERFMON information

Update perf-security.rst documentation file with the information
related to usage of CAP_PERFMON capability to secure performance
monitoring and observability operations in system.

Committer notes:

While testing 'perf top' under cap_perfmon I noticed that it needs
some more capability and Alexey pointed out cap_ipc_lock, as needed by
this kernel chunk:

kernel/events/core.c: 6101
if ((locked > lock_limit) && perf_is_paranoid() &&
!capable(CAP_IPC_LOCK)) {
ret = -EPERM;
goto unlock;
}

So I added it to the documentation, and also mentioned that if the
libcap version doesn't yet supports 'cap_perfmon', its numeric value can
be used instead, i.e. if:

# setcap "cap_perfmon,cap_ipc_lock,cap_sys_ptrace,cap_syslog=ep" perf

Fails, try:

# setcap "38,cap_ipc_lock,cap_sys_ptrace,cap_syslog=ep" perf

I also added a paragraph stating that using an unpatched libcap will
fail the check for CAP_PERFMON, as it checks the cap number against a
maximum to see if it is valid, which makes it use as the default the
'cycles:u' event, even tho a cap_perfmon capable perf binary can get
kernel samples, to workaround that just use, e.g.:

# perf top -e cycles
# perf record -e cycles

And it will sample kernel and user modes.

Signed-off-by: Alexey Budankov <alexey.budankov@linux.intel.com>
Tested-by: Arnaldo Carvalho de Melo <acme@redhat.com>
Cc: Alexei Starovoitov <ast@kernel.org>
Cc: Andi Kleen <ak@linux.intel.com>
Cc: Igor Lubashev <ilubashe@akamai.com>
Cc: James Morris <jmorris@namei.org>
Cc: Jiri Olsa <jolsa@redhat.com>
Cc: Namhyung Kim <namhyung@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Serge Hallyn <serge@hallyn.com>
Cc: Song Liu <songliubraving@fb.com>
Cc: Stephane Eranian <eranian@google.com>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: intel-gfx@lists.freedesktop.org
Cc: linux-doc@vger.kernel.org
Cc: linux-man@vger.kernel.org
Cc: linux-security-module@vger.kernel.org
Cc: selinux@vger.kernel.org
Link: http://lore.kernel.org/lkml/17278551-9399-9ebe-d665-8827016a217d@linux.intel.com
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>

authored by

Alexey Budankov and committed by
Arnaldo Carvalho de Melo 902a8dcc ab76878b

+60 -24
+60 -24
Documentation/admin-guide/perf-security.rst
··· 1 1 .. _perf_security: 2 2 3 - Perf Events and tool security 3 + Perf events and tool security 4 4 ============================= 5 5 6 6 Overview ··· 42 42 Data that belong to the fourth category can potentially contain 43 43 sensitive process data. If PMUs in some monitoring modes capture values 44 44 of execution context registers or data from process memory then access 45 - to such monitoring capabilities requires to be ordered and secured 46 - properly. So, perf_events/Perf performance monitoring is the subject for 47 - security access control management [5]_ . 45 + to such monitoring modes requires to be ordered and secured properly. 46 + So, perf_events performance monitoring and observability operations are 47 + the subject for security access control management [5]_ . 48 48 49 - perf_events/Perf access control 49 + perf_events access control 50 50 ------------------------------- 51 51 52 52 To perform security checks, the Linux implementation splits processes ··· 66 66 independently enabled and disabled on per-thread basis for processes and 67 67 files of unprivileged users. 68 68 69 - Unprivileged processes with enabled CAP_SYS_ADMIN capability are treated 69 + Unprivileged processes with enabled CAP_PERFMON capability are treated 70 70 as privileged processes with respect to perf_events performance 71 - monitoring and bypass *scope* permissions checks in the kernel. 71 + monitoring and observability operations, thus, bypass *scope* permissions 72 + checks in the kernel. CAP_PERFMON implements the principle of least 73 + privilege [13]_ (POSIX 1003.1e: 2.2.2.39) for performance monitoring and 74 + observability operations in the kernel and provides a secure approach to 75 + perfomance monitoring and observability in the system. 72 76 73 - Unprivileged processes using perf_events system call API is also subject 77 + For backward compatibility reasons the access to perf_events monitoring and 78 + observability operations is also open for CAP_SYS_ADMIN privileged 79 + processes but CAP_SYS_ADMIN usage for secure monitoring and observability 80 + use cases is discouraged with respect to the CAP_PERFMON capability. 81 + If system audit records [14]_ for a process using perf_events system call 82 + API contain denial records of acquiring both CAP_PERFMON and CAP_SYS_ADMIN 83 + capabilities then providing the process with CAP_PERFMON capability singly 84 + is recommended as the preferred secure approach to resolve double access 85 + denial logging related to usage of performance monitoring and observability. 86 + 87 + Unprivileged processes using perf_events system call are also subject 74 88 for PTRACE_MODE_READ_REALCREDS ptrace access mode check [7]_ , whose 75 89 outcome determines whether monitoring is permitted. So unprivileged 76 90 processes provided with CAP_SYS_PTRACE capability are effectively ··· 96 82 CAP_SYSLOG capability permits reading kernel space memory addresses from 97 83 /proc/kallsyms file. 98 84 99 - perf_events/Perf privileged users 85 + Privileged Perf users groups 100 86 --------------------------------- 101 87 102 88 Mechanisms of capabilities, privileged capability-dumb files [6]_ and 103 - file system ACLs [10]_ can be used to create a dedicated group of 104 - perf_events/Perf privileged users who are permitted to execute 105 - performance monitoring without scope limits. The following steps can be 106 - taken to create such a group of privileged Perf users. 89 + file system ACLs [10]_ can be used to create dedicated groups of 90 + privileged Perf users who are permitted to execute performance monitoring 91 + and observability without scope limits. The following steps can be 92 + taken to create such groups of privileged Perf users. 107 93 108 94 1. Create perf_users group of privileged Perf users, assign perf_users 109 95 group to Perf tool executable and limit access to the executable for ··· 122 108 -rwxr-x--- 2 root perf_users 11M Oct 19 15:12 perf 123 109 124 110 2. Assign the required capabilities to the Perf tool executable file and 125 - enable members of perf_users group with performance monitoring 111 + enable members of perf_users group with monitoring and observability 126 112 privileges [6]_ : 127 113 128 114 :: 129 115 130 - # setcap "cap_sys_admin,cap_sys_ptrace,cap_syslog=ep" perf 131 - # setcap -v "cap_sys_admin,cap_sys_ptrace,cap_syslog=ep" perf 116 + # setcap "cap_perfmon,cap_sys_ptrace,cap_syslog=ep" perf 117 + # setcap -v "cap_perfmon,cap_sys_ptrace,cap_syslog=ep" perf 132 118 perf: OK 133 119 # getcap perf 134 - perf = cap_sys_ptrace,cap_sys_admin,cap_syslog+ep 120 + perf = cap_sys_ptrace,cap_syslog,cap_perfmon+ep 121 + 122 + If the libcap installed doesn't yet support "cap_perfmon", use "38" instead, 123 + i.e.: 124 + 125 + :: 126 + 127 + # setcap "38,cap_ipc_lock,cap_sys_ptrace,cap_syslog=ep" perf 128 + 129 + Note that you may need to have 'cap_ipc_lock' in the mix for tools such as 130 + 'perf top', alternatively use 'perf top -m N', to reduce the memory that 131 + it uses for the perf ring buffer, see the memory allocation section below. 132 + 133 + Using a libcap without support for CAP_PERFMON will make cap_get_flag(caps, 38, 134 + CAP_EFFECTIVE, &val) fail, which will lead the default event to be 'cycles:u', 135 + so as a workaround explicitly ask for the 'cycles' event, i.e.: 136 + 137 + :: 138 + 139 + # perf top -e cycles 140 + 141 + To get kernel and user samples with a perf binary with just CAP_PERFMON. 135 142 136 143 As a result, members of perf_users group are capable of conducting 137 - performance monitoring by using functionality of the configured Perf 138 - tool executable that, when executes, passes perf_events subsystem scope 139 - checks. 144 + performance monitoring and observability by using functionality of the 145 + configured Perf tool executable that, when executes, passes perf_events 146 + subsystem scope checks. 140 147 141 148 This specific access control management is only available to superuser 142 149 or root running processes with CAP_SETPCAP, CAP_SETFCAP [6]_ 143 150 capabilities. 144 151 145 - perf_events/Perf unprivileged users 152 + Unprivileged users 146 153 ----------------------------------- 147 154 148 - perf_events/Perf *scope* and *access* control for unprivileged processes 155 + perf_events *scope* and *access* control for unprivileged processes 149 156 is governed by perf_event_paranoid [2]_ setting: 150 157 151 158 -1: ··· 201 166 perf_event_mlock_kb locking limit is imposed but ignored for 202 167 unprivileged processes with CAP_IPC_LOCK capability. 203 168 204 - perf_events/Perf resource control 169 + Resource control 205 170 --------------------------------- 206 171 207 172 Open file descriptors ··· 262 227 .. [10] `<http://man7.org/linux/man-pages/man5/acl.5.html>`_ 263 228 .. [11] `<http://man7.org/linux/man-pages/man2/getrlimit.2.html>`_ 264 229 .. [12] `<http://man7.org/linux/man-pages/man5/limits.conf.5.html>`_ 265 - 230 + .. [13] `<https://sites.google.com/site/fullycapable>`_ 231 + .. [14] `<http://man7.org/linux/man-pages/man8/auditd.8.html>`_