On Tue, Jun 21, 2016 at 11:41:16AM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Jann, Stephen, et al.
> 
> Jann, since you recently committed a patch in this area, and Stephen,
> since you committed 006ebb40d3d much further back in time, I wonder if
> you might help me by reviewing the text below that I propose to add to
> the ptrace(2) man page, in order to document "ptrace access mode 
> checking" that is performed in various parts of the kernel-user-space
> interface. Of course, I welcome input from anyone else as well.
> 
> Here's the new ptrace(2) text. Any comments, technical or terminological
> fixes, other improvements, etc. are welcome.

As others have said, I'm surprised about seeing documentation about
kernel-internal constants in manpages - but I think it might be a good
thing to have there, given that people who look at ptrace(2) are likely
to be interested in low-level details.


> [[
>    Ptrace access mode checking
>        Various parts of the kernel-user-space API (not just  ptrace(2)
>        operations), require so-called "ptrace access mode permissions"
>        which are gated  by  Linux  Security  Modules  (LSMs)  such  as
>        SELinux,  Yama,  Smack,  or  the  default  LSM.  Prior to Linux
>        2.6.27, all such checks were of a  single  type.   Since  Linux
>        2.6.27, two access mode levels are distinguished:
> 
>        PTRACE_MODE_READ
>               For  "read" operations or other operations that are less
>               dangerous, such as: get_robust_list(2); kcmp(2); reading
>               /proc/[pid]/auxv,         /proc/[pid]/environ,        or
>               /proc/[pid]/stat; or readlink(2) of  a  /proc/[pid]/ns/*
>               file.
> 
>        PTRACE_MODE_ATTACH
>               For  "write"  operations,  or  other operations that are
>               more    dangerous,    such    as:    ptrace    attaching
>               (PTRACE_ATTACH)    to   another   process   or   calling
>               process_vm_writev(2).   (PTRACE_MODE_ATTACH  was  effec‐
>               tively the default before Linux 2.6.27.)
> 
>        Since  Linux  4.5, the above access mode checks may be combined

s/may/must/; otherwise __ptrace_may_access() will yell about the kernel
code being broken and deny access.

>        (ORed) with one of the following modifiers:
> 
>        PTRACE_MODE_FSCREDS
>               Use the caller's filesystem UID  and  GID  (see  creden‐
>               tials(7)) or effective capabilities for LSM checks.
> 
>        PTRACE_MODE_REALCREDS
>               Use the caller's real UID and GID or permitted capabili‐
>               ties for LSM checks.  This was effectively  the  default
>               before Linux 4.5.
> 
>        Because  combining  one of the credential modifiers with one of
>        the aforementioned access modes is  typical,  some  macros  are
>        defined in the kernel sources for the combinations:
> 
>        PTRACE_MODE_READ_FSCREDS
>               Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.
> 
>        PTRACE_MODE_READ_REALCREDS
>               Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.
> 
>        PTRACE_MODE_ATTACH_FSCREDS
>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.
> 
>        PTRACE_MODE_ATTACH_REALCREDS
>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.
> 
>        One further modifier can be ORed with the access mode:
> 
>        PTRACE_MODE_NOAUDIT (since Linux 3.3)
>               Don't audit this access mode check.
> 
> [I'd quite welcome some text to explain "auditing" here.]
> 
>        The  algorithm  employed for ptrace access mode checking deter‐
>        mines whether the calling process is  allowed  to  perform  the
>        corresponding action on the target process, as follows:
> 
>        1.  If the calling thread and the target thread are in the same
>            thread group, access is always allowed.
> 
>        2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
>            the  check in the next step, employ the caller's filesystem
>            user ID and group ID (see credentials(7));  otherwise  (the
>            access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
>            caller's real user ID and group ID.

Might want to add a "for historical reasons" or so here.


>        3.  Deny access if neither of the following is true:
> 
>            · The real, effective, and saved-set user IDs of the target
>              match  the caller's user ID, and the real, effective, and
>              saved-set group IDs of  the  target  match  the  caller's
>              group ID.
> 
>            · The caller has the CAP_SYS_PTRACE capability.

Might want to also specify here (like below) that the caller needs to
have the capability relative to the user ns of the target.


>        4.  Deny  access if the target process "dumpable" attribute has
>            a value other than 1 (SUID_DUMP_USER; see the discussion of
>            PR_SET_DUMPABLE  in prctl(2)), and the caller does not have
>            the CAP_SYS_PTRACE capability in the user namespace of  the
>            target process.
> 
>        5.  The  kernel LSM security_ptrace_access_check() interface is
>            invoked to see if ptrace access is permitted.  The  results
>            depend on the LSM.  The implementation of this interface in
>            the default LSM performs the following steps:

For people who are unaware of how the LSM API works, it might be good to
clarify that the commoncap LSM is *always* invoked; otherwise, it might
give the impression that using another LSM would replace it.
(Also, are there other documents that refer to it as "default LSM"? I
think that that term is slightly confusing.)


>            a) If the access mode  includes  PTRACE_MODE_FSCREDS,  then
>               use the caller's effective capability set in the follow‐
>               ing  check;  otherwise  (the   access   mode   specifies
>               PTRACE_MODE_REALCREDS,  so)  use  the caller's permitted
>               capability set.
> 
>            b) Deny access if neither of the following is true:
> 
>               · The caller's capabilities are a proper superset of the
>                 target process's permitted capabilities.

This also requires the caller and the target to be in the same user
namespace.


>               · The  caller  has  the CAP_SYS_PTRACE capability in the
>                 target process's user namespace.
> 
>               Note that the default LSM does not  distinguish  between
>               PTRACE_MODE_READ and PTRACE_MODE_ATTACH.
> 
>        6.  If  access  has  not  been  denied  by any of the preceding
>            steps, then access is allowed.
> ]]
> 
> There are accompanying changes to various pages that refer to 
> the new text in ptrace(2), so that, for example, kcmp(2) adds:
> 
>        Permission  to  employ kcmp() is governed by ptrace access mode
>        PTRACE_MODE_ATTACH_REALCREDS checks against both pid1 and pid2;
>        see ptrace(2).

(Actually, kcmp() just needs READ access - you described that accurately
earlier, but it's wrong here.)


> and proc.5 has additions such as:
> 
>        /proc/[pid]/auxv (since 2.6.0-test7)
>               ...
>               Permission to access this file is governed by  a  ptrace
>               access    mode   PTRACE_MODE_READ_FSCREDS   check;   see
>               ptrace(2).
> 
>        /proc/[pid]/cwd
>               ...
>               Permission to dereference  or  read  (readlink(2))  this
>               symbolic  link  is  governed  by  a  ptrace  access mode
>               PTRACE_MODE_READ_FSCREDS check; see ptrace(2).

That sounds great! :)