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

[PATCH v4 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 | 97 +++++++++++++++++++++
 2 files changed, 98 insertions(+)
 create mode 100644 Documentation/admin-guide/perf-security.rst

---
Changes in v4:
- added docs for perf_event related capabilities
Changes in v3:
- toning down of the markup for "scope, access and resource"
- adding definite article for "Linux implementation"
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 v4 1/2] Documentation/admin-guide: introduce perf-security.rst file

[Alexey Budankov]

Implement initial version of perf-security.rst documentation file
covering security concerns of perf_event_paranoid settings.

Suggested-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Alexey Budankov <alexey.budankov@linux.intel.com>
---
Changes in v4:
- added docs for perf_event related capabilities
Changes in v3:
- toning down of the markup for "scope, access and resource"
- adding definite article for "Linux implementation"
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
---
 Documentation/admin-guide/perf-security.rst | 97 +++++++++++++++++++++
 1 file changed, 97 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..f73ebfe9bfe2
--- /dev/null
+++ b/Documentation/admin-guide/perf-security.rst
@@ -0,0 +1,97 @@
+.. _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
+-------------------------------
+
+To perform 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 a 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 processes 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 a system. For example, CAP_SYSLOG capability permits
+reading kernel space memory addresses from /proc/kallsyms file.
+
+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>`_
+.. [7] `<http://man7.org/linux/man-pages/man2/ptrace.2.html>`_
+

[PATCH v4 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

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

[Kees Cook]

On Tue, Nov 27, 2018 at 12:16 AM, Alexey Budankov
<alexey.budankov@linux.intel.com> wrote:
>
> 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(+)

Seems like this could just be folded into patch 1? I'm not sure Jon's
preference here, though.

-Kees

>
> 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



-- 
Kees Cook

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

[Jonathan Corbet]

On Tue, 27 Nov 2018 11:15:37 +0300
Alexey Budankov <alexey.budankov@linux.intel.com> wrote:

> +To perform 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 a 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 processes provided
> +with CAP_SYS_PTRACE capability are effectively permitted to pass the check.

It's good to have more information here.  I could certainly quibble
further with things - a process with CAP_SYS_ADMIN is not "unprivileged"!
- but I don't want to stand in the way of this any further.  I *would*
still like to see an ack from the perf world, though.

With regard to Kees's comment on merging the two patches; I would probably
add the new document to index.rst in the same patch, but it doesn't matter
that much.  Not worth redoing the patch just for that.

jon

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

[Alexey Budankov]

On 27.11.2018 21:11, Jonathan Corbet wrote:
> On Tue, 27 Nov 2018 11:15:37 +0300
> Alexey Budankov <alexey.budankov@linux.intel.com> wrote:
> 
>> +To perform 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 a 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 processes provided
>> +with CAP_SYS_PTRACE capability are effectively permitted to pass the check.
> 
> It's good to have more information here.  I could certainly quibble
> further with things - a process with CAP_SYS_ADMIN is not "unprivileged"!
> - but I don't want to stand in the way of this any further.  I *would*
> still like to see an ack from the perf world, though.

Thanks for meaningful comments! Looking forward to ack from perf world.

> 
> With regard to Kees's comment on merging the two patches; I would probably
> add the new document to index.rst in the same patch, but it doesn't matter
> that much.  Not worth redoing the patch just for that.

Thanks,
Alexey

> 
> jon
> 

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

[Alexey Budankov]

Hello Kees,

On 27.11.2018 20:23, Kees Cook wrote:
> On Tue, Nov 27, 2018 at 12:16 AM, Alexey Budankov
> <alexey.budankov@linux.intel.com> wrote:
>>
>> 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(+)
> 
> Seems like this could just be folded into patch 1? I'm not sure Jon's
> preference here, though.

Let's stick to Jon's preference in comments on v4 2/2.

Thanks for review!

-Alexey

> 
> -Kees
> 
>>
>> 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
> 
> 
> 

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

[Alexey Budankov]

Hi Peter,

On 27.11.2018 22:13, Alexey Budankov wrote:
> On 27.11.2018 21:11, Jonathan Corbet wrote:
>> On Tue, 27 Nov 2018 11:15:37 +0300
>> Alexey Budankov <alexey.budankov@linux.intel.com> wrote:
>>
>>> +To perform 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 a 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 processes provided
>>> +with CAP_SYS_PTRACE capability are effectively permitted to pass the check.
>>
>> It's good to have more information here.  I could certainly quibble
>> further with things - a process with CAP_SYS_ADMIN is not "unprivileged"!
>> - but I don't want to stand in the way of this any further.  I *would*
>> still like to see an ack from the perf world, though.
> 
> Thanks for meaningful comments! Looking forward to ack from perf world.

May I ask you to review v4 of the patches? 
Your comments on v1 have been addressed in there.

Thanks,
Alexey

> 
>>
>> With regard to Kees's comment on merging the two patches; I would probably
>> add the new document to index.rst in the same patch, but it doesn't matter
>> that much.  Not worth redoing the patch just for that.
> 
> Thanks,
> Alexey
> 
>>
>> jon
>>
> 

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

[Kees Cook]

On Tue, Nov 27, 2018 at 12:15 AM Alexey Budankov
<alexey.budankov@linux.intel.com> wrote:
>
>
> Implement initial version of perf-security.rst documentation file
> covering security concerns of perf_event_paranoid settings.
>
> Suggested-by: Thomas Gleixner <tglx@linutronix.de>
> Signed-off-by: Alexey Budankov <alexey.budankov@linux.intel.com>

Reviewed-by: Kees Cook <keescook@chromium.org>

-Kees

> ---
> Changes in v4:
> - added docs for perf_event related capabilities
> Changes in v3:
> - toning down of the markup for "scope, access and resource"
> - adding definite article for "Linux implementation"
> 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
> ---
>  Documentation/admin-guide/perf-security.rst | 97 +++++++++++++++++++++
>  1 file changed, 97 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..f73ebfe9bfe2
> --- /dev/null
> +++ b/Documentation/admin-guide/perf-security.rst
> @@ -0,0 +1,97 @@
> +.. _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
> +-------------------------------
> +
> +To perform 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 a 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 processes 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 a system. For example, CAP_SYSLOG capability permits
> +reading kernel space memory addresses from /proc/kallsyms file.
> +
> +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>`_
> +.. [7] `<http://man7.org/linux/man-pages/man2/ptrace.2.html>`_
> +



-- 
Kees Cook

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

[Alexey Budankov]

On 06.12.2018 4:10, Kees Cook wrote:
> On Tue, Nov 27, 2018 at 12:15 AM Alexey Budankov
> <alexey.budankov@linux.intel.com> wrote:
>>
>>
>> Implement initial version of perf-security.rst documentation file
>> covering security concerns of perf_event_paranoid settings.
>>
>> Suggested-by: Thomas Gleixner <tglx@linutronix.de>
>> Signed-off-by: Alexey Budankov <alexey.budankov@linux.intel.com>
> 
> Reviewed-by: Kees Cook <keescook@chromium.org>

Thanks!
-Alexey

> 
> -Kees
> 
>> ---
>> Changes in v4:
>> - added docs for perf_event related capabilities
>> Changes in v3:
>> - toning down of the markup for "scope, access and resource"
>> - adding definite article for "Linux implementation"
>> 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
>> ---
>>  Documentation/admin-guide/perf-security.rst | 97 +++++++++++++++++++++
>>  1 file changed, 97 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..f73ebfe9bfe2
>> --- /dev/null
>> +++ b/Documentation/admin-guide/perf-security.rst
>> @@ -0,0 +1,97 @@
>> +.. _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
>> +-------------------------------
>> +
>> +To perform 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 a 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 processes 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 a system. For example, CAP_SYSLOG capability permits
>> +reading kernel space memory addresses from /proc/kallsyms file.
>> +
>> +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>`_
>> +.. [7] `<http://man7.org/linux/man-pages/man2/ptrace.2.html>`_
>> +
> 
> 
> 

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

[Jonathan Corbet]

On Wed, 5 Dec 2018 17:10:48 -0800
Kees Cook <keescook@chromium.org> wrote:

> On Tue, Nov 27, 2018 at 12:15 AM Alexey Budankov
> <alexey.budankov@linux.intel.com> wrote:
> >
> >
> > Implement initial version of perf-security.rst documentation file
> > covering security concerns of perf_event_paranoid settings.
> >
> > Suggested-by: Thomas Gleixner <tglx@linutronix.de>
> > Signed-off-by: Alexey Budankov <alexey.budankov@linux.intel.com>  
> 
> Reviewed-by: Kees Cook <keescook@chromium.org>

OK, series applied, thanks.

jon