[PATCH v2 0/2]: Documentation/admin-guide: introduce perf-security.rst file and extend perf_event_paranoid documentation

[PATCH v2 0/2]: Documentation/admin-guide: introduce perf-security.rst file and extend perf_event_paranoid documentation

[Alexey Budankov]

To facilitate informed decision making by system administrators [1]
to permit and manage access to Perf Events (PE) / Perf tool (Perf) [2],[3] 
performance monitoring for multiple users perf-security.rst document 
suggested by Thomas Gleixner is introduced [4] that:

a) states PE/Perf access security concerns for multi user environment
b) refers to base Linux access control and management principles
c) extends documentation of possible perf_event_paranoid knob settings 

The file serves as single knowledge source for PE/Perf security and 
access control related matter according to decisions, discussion and  
PoC prototype previously made here [5],[6].

The file can later be extended with information describing:

a) PE/Perf usage models and its security implications
b) PE/Perf user interface, its changes and related security implications
c) security related implications of monitoring by a specific PE PMU [2]

---
Alexey Budankov (2):
  Documentation/admin-guide: introduce perf-security.rst file
  Documentation/admin-guide: update admin-guide index.rst

 Documentation/admin-guide/index.rst         |  1 +
 Documentation/admin-guide/perf-security.rst | 76 +++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 Documentation/admin-guide/perf-security.rst

---
Changes in v2:
- reverted patches order in the set to avoid CI issue
- replaced old PCL referencing by PE (Perf Events)
- skipped >=3 setting documentation at the moment

---
[1] https://marc.info/?l=linux-kernel&m=153815883923913&w=2
[2] http://man7.org/linux/man-pages/man2/perf_event_open.2.html
[3] https://perf.wiki.kernel.org/index.php/Main_Page
[4] https://marc.info/?l=linux-kernel&m=153837512226838&w=2
[5] https://marc.info/?l=linux-kernel&m=153736008310781&w=2
[6] https://lkml.org/lkml/2018/5/21/156

[PATCH v2 1/2] Documentation/admin-guide: introduce perf-security.rst file

[Alexey Budankov]

Implement initial version of perf-security.rst documentation file
initially covering security concerns related to PE/Perf performance
monitoring in multiuser environments.

Suggested-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Alexey Budankov <alexey.budankov@linux.intel.com>
---
Changes in v2:
- replaced old PCL referencing by PE (Perf Events)
- skipped >=3 setting documentation at the moment
---
 Documentation/admin-guide/perf-security.rst | 76 +++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 Documentation/admin-guide/perf-security.rst

diff --git a/Documentation/admin-guide/perf-security.rst b/Documentation/admin-guide/perf-security.rst
new file mode 100644
index 000000000000..d9dcea61ed87
--- /dev/null
+++ b/Documentation/admin-guide/perf-security.rst
@@ -0,0 +1,76 @@
+.. _perf_security:
+
+Perf Events and tool security
+=============================
+
+Overview
+--------
+
+Usage of Perf Events (PE) [1]_ , [2]_ , [3]_ can impose a considerable risk of
+leaking sensitive data accessed by monitored processes. The data leakage is
+possible both in scenarios of direct usage of PE system call API [2]_ and over
+data files generated by Perf tool user mode utility (Perf) [3]_ , [4]_ . The risk
+depends on the nature of data that PE performance monitoring units (PMU) [2]_
+collect and expose for performance analysis. Having that said PE/Perf performance
+monitoring is the subject for security access control management [5]_ .
+
+PE/Perf access control
+----------------------
+
+For the purpose of performing security checks Linux implementation splits
+processes into two categories [6]_ : a) privileged processes (whose effective
+user ID is 0, referred to as superuser or root), and b) unprivileged processes
+(whose effective UID is nonzero). Privileged processes bypass all kernel
+security permission checks so PE performance monitoring is fully available to
+privileged processes without *access*, *scope* and *resource* restrictions.
+Unprivileged processes are subject to full security permission check based
+on the process's credentials [5]_ (usually: effective UID, effective GID,
+and supplementary group list).
+
+PE/Perf unprivileged users
+--------------------------
+
+PE/Perf *scope* and *access* control for unprivileged processes is governed by
+perf_event_paranoid [2]_ setting:
+
+-1:
+     Impose no *scope* and *access* restrictions on using PE performance
+     monitoring. Per-user per-cpu perf_event_mlock_kb [2]_ locking limit is
+     ignored when allocating memory buffers for storing performance data.
+     This is the least secure mode since allowed monitored *scope* is
+     maximized and no PE specific limits are imposed on *resources*
+     allocated for performance monitoring.
+
+>=0:
+     *scope* includes per-process and system wide performance monitoring
+     but excludes raw tracepoints and ftrace function tracepoints monitoring.
+     CPU and system events happened when executing either in user or
+     in kernel space can be monitored and captured for later analysis.
+     Per-user per-cpu perf_event_mlock_kb locking limit is imposed but
+     ignored for unprivileged processes with CAP_IPC_LOCK [6]_ capability.
+
+>=1:
+     *scope* includes per-process performance monitoring only and excludes
+     system wide performance monitoring. CPU and system events happened when
+     executing either in user or in kernel space can be monitored and
+     captured for later analysis. Per-user per-cpu perf_event_mlock_kb
+     locking limit is imposed but ignored for unprivileged processes with
+     CAP_IPC_LOCK capability.
+
+>=2:
+     *scope* includes per-process performance monitoring only. CPU and system
+     events happened when executing in user space only can be monitored and
+     captured for later analysis. Per-user per-cpu perf_event_mlock_kb
+     locking limit is imposed but ignored for unprivileged processes with
+     CAP_IPC_LOCK capability.
+
+Bibliography
+------------
+
+.. [1] `<https://lwn.net/Articles/337493/>`_
+.. [2] `<http://man7.org/linux/man-pages/man2/perf_event_open.2.html>`_
+.. [3] `<http://web.eece.maine.edu/~vweaver/projects/perf_events/>`_
+.. [4] `<https://perf.wiki.kernel.org/index.php/Main_Page>`_
+.. [5] `<https://www.kernel.org/doc/html/latest/security/credentials.html>`_
+.. [6] `<http://man7.org/linux/man-pages/man7/capabilities.7.html>`_
+

[PATCH v2 2/2] Documentation/admin-guide: update admin-guide index.rst

[Alexey Budankov]

Extend index.rst index file at admin-guide root directory with
the reference to perf-security.rst file being introduced.

Signed-off-by: Alexey Budankov <alexey.budankov@linux.intel.com>
---
 Documentation/admin-guide/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 965745d5fb9a..0a491676685e 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -76,6 +76,7 @@ configure specific aspects of kernel behavior to your liking.
    thunderbolt
    LSM/index
    mm/index
+   perf-security
 
 .. only::  subproject and html

[PATCH v2 0/2] Documentation/admin-guide: introduce perf-security.rst file and extend perf_event_paranoid documentation

[Alexey Budankov]

To facilitate informed decision making by system administrators [1]
to permit and manage access to Perf Events (perf_events) / Perf tool (Perf) [2],[3] 
performance monitoring for multiple users perf-security.rst document 
suggested by Thomas Gleixner is introduced [4] that:

a) states perf_events/Perf access security concerns for multi user environment
b) refers to base Linux access control and management principles
c) extends documentation of possible perf_event_paranoid knob settings 

The file serves as single knowledge source for perf_events/Perf security and 
access control related matter according to decisions, discussion and  
PoC prototype previously made here [5],[6].

The file can later be extended with information describing:

a) perf_events/Perf usage models and its security implications
b) perf_events/Perf user interface, its changes and related security implications
c) security related implications of monitoring by a specific perf_events PMU [2]

---
Alexey Budankov (2):
  Documentation/admin-guide: introduce perf-security.rst file
  Documentation/admin-guide: update admin-guide index.rst

 Documentation/admin-guide/index.rst         |  1 +
 Documentation/admin-guide/perf-security.rst | 77 +++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 Documentation/admin-guide/perf-security.rst

[PATCH v2 1/2] Documentation/admin-guide: introduce perf-security.rst file

[Alexey Budankov]

Implement initial version of perf-security.rst documentation file
initially covering security concerns related to perf_events/Perf
performance monitoring in multiuser environments.

Suggested-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Alexey Budankov <alexey.budankov@linux.intel.com>
---
Changes in v2:
- replaced PCL referencing by perf_events
- skipped >=3 setting documentation at the moment
---
 Documentation/admin-guide/perf-security.rst | 77 +++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 Documentation/admin-guide/perf-security.rst

diff --git a/Documentation/admin-guide/perf-security.rst b/Documentation/admin-guide/perf-security.rst
new file mode 100644
index 000000000000..55ccd9394809
--- /dev/null
+++ b/Documentation/admin-guide/perf-security.rst
@@ -0,0 +1,77 @@
+.. _perf_security:
+
+Perf Events and tool security
+=============================
+
+Overview
+--------
+
+Usage of Performance Counters for Linux (perf_events) [1]_ , [2]_ , [3]_ can
+impose a considerable risk of leaking sensitive data accessed by monitored
+processes. The data leakage is possible both in scenarios of direct usage of
+perf_events system call API [2]_ and over data files generated by Perf tool user
+mode utility (Perf) [3]_ , [4]_ . The risk depends on the nature of data that
+perf_events performance monitoring units (PMU) [2]_ collect and expose for
+performance analysis. Having that said perf_events/Perf performance monitoring
+is the subject for security access control management [5]_ .
+
+perf_events/Perf access control
+-------------------------------
+
+For the purpose of performing security checks Linux implementation splits
+processes into two categories [6]_ : a) privileged processes (whose effective
+user ID is 0, referred to as superuser or root), and b) unprivileged processes
+(whose effective UID is nonzero). Privileged processes bypass all kernel
+security permission checks so perf_events performance monitoring is fully
+available to privileged processes without *access*, *scope* and *resource*
+restrictions. Unprivileged processes are subject to full security permission
+check based on the process's credentials [5]_ (usually: effective UID, effective
+GID, and supplementary group list).
+
+perf_events/Perf unprivileged users
+--------------------------
+
+perf_events/Perf *scope* and *access* control for unprivileged processes is
+governed by perf_event_paranoid [2]_ setting:
+
+-1:
+     Impose no *scope* and *access* restrictions on using perf_events performance
+     monitoring. Per-user per-cpu perf_event_mlock_kb [2]_ locking limit is
+     ignored when allocating memory buffers for storing performance data.
+     This is the least secure mode since allowed monitored *scope* is
+     maximized and no perf_events specific limits are imposed on *resources*
+     allocated for performance monitoring.
+
+>=0:
+     *scope* includes per-process and system wide performance monitoring
+     but excludes raw tracepoints and ftrace function tracepoints monitoring.
+     CPU and system events happened when executing either in user or
+     in kernel space can be monitored and captured for later analysis.
+     Per-user per-cpu perf_event_mlock_kb locking limit is imposed but
+     ignored for unprivileged processes with CAP_IPC_LOCK [6]_ capability.
+
+>=1:
+     *scope* includes per-process performance monitoring only and excludes
+     system wide performance monitoring. CPU and system events happened when
+     executing either in user or in kernel space can be monitored and
+     captured for later analysis. Per-user per-cpu perf_event_mlock_kb
+     locking limit is imposed but ignored for unprivileged processes with
+     CAP_IPC_LOCK capability.
+
+>=2:
+     *scope* includes per-process performance monitoring only. CPU and system
+     events happened when executing in user space only can be monitored and
+     captured for later analysis. Per-user per-cpu perf_event_mlock_kb
+     locking limit is imposed but ignored for unprivileged processes with
+     CAP_IPC_LOCK capability.
+
+Bibliography
+------------
+
+.. [1] `<https://lwn.net/Articles/337493/>`_
+.. [2] `<http://man7.org/linux/man-pages/man2/perf_event_open.2.html>`_
+.. [3] `<http://web.eece.maine.edu/~vweaver/projects/perf_events/>`_
+.. [4] `<https://perf.wiki.kernel.org/index.php/Main_Page>`_
+.. [5] `<https://www.kernel.org/doc/html/latest/security/credentials.html>`_
+.. [6] `<http://man7.org/linux/man-pages/man7/capabilities.7.html>`_
+

Re: [PATCH v2 1/2] Documentation/admin-guide: introduce perf-security.rst file

[Jonathan Corbet]

On Wed, 21 Nov 2018 12:14:14 +0300
Alexey Budankov <alexey.budankov@linux.intel.com> wrote:

> +For the purpose of performing security checks Linux implementation splits
> +processes into two categories [6]_ : a) privileged processes (whose effective
> +user ID is 0, referred to as superuser or root), and b) unprivileged processes
> +(whose effective UID is nonzero).

Is that really what's going on here?  If I understand things correctly,
it's looking for CAP_SYS_PTRACE rather than a specific UID; am I missing
something here?

(Also, you would want "*the* Linux implementation" in the first sentence
above).

One other thing:

> +(whose effective UID is nonzero). Privileged processes bypass all kernel
> +security permission checks so perf_events performance monitoring is fully
> +available to privileged processes without *access*, *scope* and *resource*
> +restrictions.

Could I ask for a slight toning down of the markup here?  There's a lot of
*emphasis* here that isn't really needed and tends to get in the way.

Thanks,

jon

Re: [PATCH v2 1/2] Documentation/admin-guide: introduce perf-security.rst file

[Alexey Budankov]

Hello Jon,

On 25.11.2018 22:47, Jonathan Corbet wrote:
> On Wed, 21 Nov 2018 12:14:14 +0300
> Alexey Budankov <alexey.budankov@linux.intel.com> wrote:
> 
>> +For the purpose of performing security checks Linux implementation splits
>> +processes into two categories [6]_ : a) privileged processes (whose effective
>> +user ID is 0, referred to as superuser or root), and b) unprivileged processes
>> +(whose effective UID is nonzero).
> 
> Is that really what's going on here?  If I understand things correctly,
> it's looking for CAP_SYS_PTRACE rather than a specific UID; am I missing
> something here?

You are right regarding CAP_SYS_PTRACE but this capability is not the only 
one which is used by perf_events for security checks, so the capabilities 
clarification is kept aside of these patches, because patches initial intention 
is to clarify security specifics of sysctl_perf_even_paranoid settings.

I agree that the document can be extended with details clarifying capabilities 
used by perf_events for security checks.

> 
> (Also, you would want "*the* Linux implementation" in the first sentence
> above).

Accepted.

> 
> One other thing:
> 
>> +(whose effective UID is nonzero). Privileged processes bypass all kernel
>> +security permission checks so perf_events performance monitoring is fully
>> +available to privileged processes without *access*, *scope* and *resource*
>> +restrictions.
> 
> Could I ask for a slight toning down of the markup here?  There's a lot of
> *emphasis* here that isn't really needed and tends to get in the way.

Accepted.

Thanks,
Alexey

> 
> Thanks,
> 
> jon
> 

Re: [PATCH v2 1/2] Documentation/admin-guide: introduce perf-security.rst file

[Jonathan Corbet]

On Mon, 26 Nov 2018 11:57:21 +0300
Alexey Budankov <alexey.budankov@linux.intel.com> wrote:

> >> +For the purpose of performing security checks Linux implementation splits
> >> +processes into two categories [6]_ : a) privileged processes (whose effective
> >> +user ID is 0, referred to as superuser or root), and b) unprivileged processes
> >> +(whose effective UID is nonzero).  
> > 
> > Is that really what's going on here?  If I understand things correctly,
> > it's looking for CAP_SYS_PTRACE rather than a specific UID; am I missing
> > something here?  
> 
> You are right regarding CAP_SYS_PTRACE but this capability is not the only 
> one which is used by perf_events for security checks, so the capabilities 
> clarification is kept aside of these patches, because patches initial intention 
> is to clarify security specifics of sysctl_perf_even_paranoid settings.
> 
> I agree that the document can be extended with details clarifying capabilities 
> used by perf_events for security checks.

I don't really like the idea of adding a document that we know doesn't
really describe how the security decision is made.  Even a one-line
parenthetical saying that things are more complicated and giving a pointer
to a place to look for details would help, IMO.

Either way, I can merge this, but I'd like to have an ack from the perf
folks first.

Thanks,

jon

Re: [PATCH v2 1/2] Documentation/admin-guide: introduce perf-security.rst file

[Alexey Budankov]

On 26.11.2018 23:28, Jonathan Corbet wrote:
> On Mon, 26 Nov 2018 11:57:21 +0300
> Alexey Budankov <alexey.budankov@linux.intel.com> wrote:
> 
>>>> +For the purpose of performing security checks Linux implementation splits
>>>> +processes into two categories [6]_ : a) privileged processes (whose effective
>>>> +user ID is 0, referred to as superuser or root), and b) unprivileged processes
>>>> +(whose effective UID is nonzero).  
>>>
>>> Is that really what's going on here?  If I understand things correctly,
>>> it's looking for CAP_SYS_PTRACE rather than a specific UID; am I missing
>>> something here?  
>>
>> You are right regarding CAP_SYS_PTRACE but this capability is not the only 
>> one which is used by perf_events for security checks, so the capabilities 
>> clarification is kept aside of these patches, because patches initial intention 
>> is to clarify security specifics of sysctl_perf_even_paranoid settings.
>>
>> I agree that the document can be extended with details clarifying capabilities 
>> used by perf_events for security checks.
> 
> I don't really like the idea of adding a document that we know doesn't
> really describe how the security decision is made.  Even a one-line
> parenthetical saying that things are more complicated and giving a pointer
> to a place to look for details would help, IMO.

Well, makes sense. It is possible to have something similar to this:

...

For the purpose of performing security checks the Linux implementation splits
processes into two categories [6]_ : a) privileged processes (whose effective
user ID is 0, referred to as superuser or root), and b) unprivileged processes
(whose effective UID is nonzero).

Privileged processes bypass all kernel security permission checks so perf_events
performance monitoring is fully available to privileged processes without
access, scope and resource restrictions.

Unprivileged processes are subject to full security permission check based on 
the process's credentials [5]_ (usually: effective UID, effective GID, and 
supplementary group list).

Linux divides the privileges traditionally associated with superuser into
distinct units, known as capabilities [6]_, which can be independently enabled
and disabled on per-thread basis for processes and files of unprivileged users.

Unprivileged processes with enabled CAP_SYS_ADMIN capability are treated as 
privileged processes with respect to perf_events performance monitoring and
bypass *scope* permissions checks in the kernel.

Unprivileged processes using perf_events system call API is also subject for
PTRACE_MODE_READ_REALCREDS ptrace access mode check [7]_ , whose outcome determines
whether monitoring is permitted. So unprivileged process provided with
CAP_SYS_PTRACE capability are effectively permitted to pass the check.

Other capabilities being granted to unprivileged processes can effectively
enable capturing of additional data required for later performance analysis of
monitored processes or system. For example CAP_SYSLOG capability permits
reading kernel space memory addresses from /proc/kallsyms file.

...

Thanks,
Alexey

> 
> Either way, I can merge this, but I'd like to have an ack from the perf
> folks first.
> 
> Thanks,
> 
> jon
>