From 90bb766440f2147486a2acc3e793d7b8348b0c22 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Sat, 13 May 2017 04:51:47 -0700 Subject: doc: ReSTify Yama.txt Adjusts for ReST markup and moves under LSM admin guide. Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/LSM/Yama.rst | 74 +++++++++++++++++++++++++++++++++ Documentation/admin-guide/LSM/index.rst | 1 + Documentation/security/00-INDEX | 2 - Documentation/security/Yama.txt | 71 ------------------------------- MAINTAINERS | 1 + security/yama/Kconfig | 3 +- 6 files changed, 78 insertions(+), 74 deletions(-) create mode 100644 Documentation/admin-guide/LSM/Yama.rst delete mode 100644 Documentation/security/Yama.txt diff --git a/Documentation/admin-guide/LSM/Yama.rst b/Documentation/admin-guide/LSM/Yama.rst new file mode 100644 index 000000000000..13468ea696b7 --- /dev/null +++ b/Documentation/admin-guide/LSM/Yama.rst @@ -0,0 +1,74 @@ +==== +Yama +==== + +Yama is a Linux Security Module that collects system-wide DAC security +protections that are not handled by the core kernel itself. This is +selectable at build-time with ``CONFIG_SECURITY_YAMA``, and can be controlled +at run-time through sysctls in ``/proc/sys/kernel/yama``: + +ptrace_scope +============ + +As Linux grows in popularity, it will become a larger target for +malware. One particularly troubling weakness of the Linux process +interfaces is that a single user is able to examine the memory and +running state of any of their processes. For example, if one application +(e.g. Pidgin) was compromised, it would be possible for an attacker to +attach to other running processes (e.g. Firefox, SSH sessions, GPG agent, +etc) to extract additional credentials and continue to expand the scope +of their attack without resorting to user-assisted phishing. + +This is not a theoretical problem. SSH session hijacking +(http://www.storm.net.nz/projects/7) and arbitrary code injection +(http://c-skills.blogspot.com/2007/05/injectso.html) attacks already +exist and remain possible if ptrace is allowed to operate as before. +Since ptrace is not commonly used by non-developers and non-admins, system +builders should be allowed the option to disable this debugging system. + +For a solution, some applications use ``prctl(PR_SET_DUMPABLE, ...)`` to +specifically disallow such ptrace attachment (e.g. ssh-agent), but many +do not. A more general solution is to only allow ptrace directly from a +parent to a child process (i.e. direct "gdb EXE" and "strace EXE" still +work), or with ``CAP_SYS_PTRACE`` (i.e. "gdb --pid=PID", and "strace -p PID" +still work as root). + +In mode 1, software that has defined application-specific relationships +between a debugging process and its inferior (crash handlers, etc), +``prctl(PR_SET_PTRACER, pid, ...)`` can be used. An inferior can declare which +other process (and its descendants) are allowed to call ``PTRACE_ATTACH`` +against it. Only one such declared debugging process can exists for +each inferior at a time. For example, this is used by KDE, Chromium, and +Firefox's crash handlers, and by Wine for allowing only Wine processes +to ptrace each other. If a process wishes to entirely disable these ptrace +restrictions, it can call ``prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...)`` +so that any otherwise allowed process (even those in external pid namespaces) +may attach. + +The sysctl settings (writable only with ``CAP_SYS_PTRACE``) are: + +0 - classic ptrace permissions: + a process can ``PTRACE_ATTACH`` to any other + process running under the same uid, as long as it is dumpable (i.e. + did not transition uids, start privileged, or have called + ``prctl(PR_SET_DUMPABLE...)`` already). Similarly, ``PTRACE_TRACEME`` is + unchanged. + +1 - restricted ptrace: + a process must have a predefined relationship + with the inferior it wants to call ``PTRACE_ATTACH`` on. By default, + this relationship is that of only its descendants when the above + classic criteria is also met. To change the relationship, an + inferior can call ``prctl(PR_SET_PTRACER, debugger, ...)`` to declare + an allowed debugger PID to call ``PTRACE_ATTACH`` on the inferior. + Using ``PTRACE_TRACEME`` is unchanged. + +2 - admin-only attach: + only processes with ``CAP_SYS_PTRACE`` may use ptrace + with ``PTRACE_ATTACH``, or through children calling ``PTRACE_TRACEME``. + +3 - no attach: + no processes may use ptrace with ``PTRACE_ATTACH`` nor via + ``PTRACE_TRACEME``. Once set, this sysctl value cannot be changed. + +The original children-only logic was based on the restrictions in grsecurity. diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst index 6aa4e0dc588b..e5ba2c69b8ef 100644 --- a/Documentation/admin-guide/LSM/index.rst +++ b/Documentation/admin-guide/LSM/index.rst @@ -36,3 +36,4 @@ the one "major" module (e.g. SELinux) if there is one configured. apparmor SELinux tomoyo + Yama diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX index 04ef62511ea1..a55f781be0dd 100644 --- a/Documentation/security/00-INDEX +++ b/Documentation/security/00-INDEX @@ -2,8 +2,6 @@ - this file. Smack.txt - documentation on the Smack Linux Security Module. -Yama.txt - - documentation on the Yama Linux Security Module. keys-ecryptfs.txt - description of the encryption keys for the ecryptfs filesystem. keys-request-key.txt diff --git a/Documentation/security/Yama.txt b/Documentation/security/Yama.txt deleted file mode 100644 index d9ee7d7a6c7f..000000000000 --- a/Documentation/security/Yama.txt +++ /dev/null @@ -1,71 +0,0 @@ -Yama is a Linux Security Module that collects system-wide DAC security -protections that are not handled by the core kernel itself. This is -selectable at build-time with CONFIG_SECURITY_YAMA, and can be controlled -at run-time through sysctls in /proc/sys/kernel/yama: - -- ptrace_scope - -============================================================== - -ptrace_scope: - -As Linux grows in popularity, it will become a larger target for -malware. One particularly troubling weakness of the Linux process -interfaces is that a single user is able to examine the memory and -running state of any of their processes. For example, if one application -(e.g. Pidgin) was compromised, it would be possible for an attacker to -attach to other running processes (e.g. Firefox, SSH sessions, GPG agent, -etc) to extract additional credentials and continue to expand the scope -of their attack without resorting to user-assisted phishing. - -This is not a theoretical problem. SSH session hijacking -(http://www.storm.net.nz/projects/7) and arbitrary code injection -(http://c-skills.blogspot.com/2007/05/injectso.html) attacks already -exist and remain possible if ptrace is allowed to operate as before. -Since ptrace is not commonly used by non-developers and non-admins, system -builders should be allowed the option to disable this debugging system. - -For a solution, some applications use prctl(PR_SET_DUMPABLE, ...) to -specifically disallow such ptrace attachment (e.g. ssh-agent), but many -do not. A more general solution is to only allow ptrace directly from a -parent to a child process (i.e. direct "gdb EXE" and "strace EXE" still -work), or with CAP_SYS_PTRACE (i.e. "gdb --pid=PID", and "strace -p PID" -still work as root). - -In mode 1, software that has defined application-specific relationships -between a debugging process and its inferior (crash handlers, etc), -prctl(PR_SET_PTRACER, pid, ...) can be used. An inferior can declare which -other process (and its descendants) are allowed to call PTRACE_ATTACH -against it. Only one such declared debugging process can exists for -each inferior at a time. For example, this is used by KDE, Chromium, and -Firefox's crash handlers, and by Wine for allowing only Wine processes -to ptrace each other. If a process wishes to entirely disable these ptrace -restrictions, it can call prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...) -so that any otherwise allowed process (even those in external pid namespaces) -may attach. - -The sysctl settings (writable only with CAP_SYS_PTRACE) are: - -0 - classic ptrace permissions: a process can PTRACE_ATTACH to any other - process running under the same uid, as long as it is dumpable (i.e. - did not transition uids, start privileged, or have called - prctl(PR_SET_DUMPABLE...) already). Similarly, PTRACE_TRACEME is - unchanged. - -1 - restricted ptrace: a process must have a predefined relationship - with the inferior it wants to call PTRACE_ATTACH on. By default, - this relationship is that of only its descendants when the above - classic criteria is also met. To change the relationship, an - inferior can call prctl(PR_SET_PTRACER, debugger, ...) to declare - an allowed debugger PID to call PTRACE_ATTACH on the inferior. - Using PTRACE_TRACEME is unchanged. - -2 - admin-only attach: only processes with CAP_SYS_PTRACE may use ptrace - with PTRACE_ATTACH, or through children calling PTRACE_TRACEME. - -3 - no attach: no processes may use ptrace with PTRACE_ATTACH nor via - PTRACE_TRACEME. Once set, this sysctl value cannot be changed. - -The original children-only logic was based on the restrictions in grsecurity. - -============================================================== diff --git a/MAINTAINERS b/MAINTAINERS index 4d8914ad710a..816947653ea2 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -11573,6 +11573,7 @@ M: Kees Cook T: git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git yama/tip S: Supported F: security/yama/ +F: Documentation/admin-guide/LSM/Yama.rst SENSABLE PHANTOM M: Jiri Slaby diff --git a/security/yama/Kconfig b/security/yama/Kconfig index 90c605eea892..96b27405558a 100644 --- a/security/yama/Kconfig +++ b/security/yama/Kconfig @@ -7,6 +7,7 @@ config SECURITY_YAMA system-wide security settings beyond regular Linux discretionary access controls. Currently available is ptrace scope restriction. Like capabilities, this security module stacks with other LSMs. - Further information can be found in Documentation/security/Yama.txt. + Further information can be found in + Documentation/admin-guide/LSM/Yama.rst. If you are unsure how to answer this question, answer N. -- cgit v1.2.3