Review of ptrace Yama ptrace_scope description

[Michael Kerrisk (man-pages)]

Hi Kees,

So, last year, I added some documentation to ptrace(2) to describe
the Yama ptrace_scope file. I don't think I asked you for review
at the time, but in the light of other changes to the ptrace(2)
page, it occurred to me that it might be a good idea to ask you
to check the text below to see if anything is missing or could be
improved. Might you have a moment for that?

   /proc/sys/kernel/yama/ptrace_scope
       On systems with the Yama Linux Security Module (LSM)  installed
       (i.e.,  the  kernel  was configured with CONFIG_SECURITY_YAMA),
       the /proc/sys/kernel/yama/ptrace_scope  file  (available  since
       Linux  3.4)  can  be  used  to  restrict the ability to trace a
       process with ptrace(2) (and thus also the ability to use  tools
       such  as  strace(1) and gdb(1)).  The goal of such restrictions
       is to prevent attack escalation whereby a  compromised  process
       can  ptrace-attach  to  other  sensitive processes (e.g., a GPG
       agent or an SSH session) owned by the user  in  order  to  gain
       additional credentials and thus expand the scope of the attack.

       More precisely, the Yama LSM limits two types of operations:

       *  Any   operation   that   performs   a   ptrace  access  mode
          PTRACE_MODE_ATTACH     checkâfor      example,      ptrace()
          PTRACE_ATTACH.   (See the "Ptrace access mode checking" disâ
          cussion above.)

       *  ptrace() PTRACE_TRACEME.

       A process that has the CAP_SYS_PTRACE capability can update the
       /proc/sys/kernel/yama/ptrace_scope file with one of the followâ
       ing values:

       0 ("classic ptrace permissions")
              No additional restrictions on  operations  that  perform
              PTRACE_MODE_ATTACH  checks  (beyond those imposed by the
              commoncap and other LSMs).

              The use of PTRACE_TRACEME is unchanged.

       1 ("restricted ptrace") [default value]
              When   performing   an   operation   that   requires   a
              PTRACE_MODE_ATTACH  check, the calling process must have
              a predefined relationship with the target  process.   By
              default,  the predefined relationship is that the target
              process must be a child of the caller.

              A target process can employ the prctl(2)  PR_SET_PTRACER
              operation  to declare a different PID that is allowed to
              perform PTRACE_MODE_ATTACH  operations  on  the  target.
              See   the   kernel   source   file   Documentation/secuâ
              rity/Yama.txt for further details.

              The use of PTRACE_TRACEME is unchanged.

       2 ("admin-only attach")
              Only processes with the  CAP_SYS_PTRACE  capability  may
              perform  PTRACE_MODE_ATTACH operations or trace children
              that employ PTRACE_TRACEME.

       3 ("no attach")
              No process may perform PTRACE_MODE_ATTACH operations  or
              trace children that employ PTRACE_TRACEME.

              Once  this value has been written to the file, it cannot
              be changed.

Cheers,

Michael


--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/