Re: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

Stephen,

On 06/23/2016 08:05 PM, Stephen Smalley wrote:
> On 06/21/2016 05:41 AM, 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.
> >
> > [[
> >    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.)
>
> That was the intent when the distinction was introduced, but it doesn't
> appear to have been properly maintained, e.g. there is now a common
> helper lock_trace() that is used for
> /proc/pid/{stack,syscall,personality} but checks PTRACE_MODE_ATTACH, and
> PTRACE_MODE_ATTACH is also used in timerslack_ns_write/show().  Likely
> should review and make them consistent.  There was also some debate
> about proper handling of /proc/pid/fd.  Arguably that one might belong
> back in the _ATTACH camp.

Thanks for the background info.

> >        Since  Linux  4.5, the above access mode checks may be combined
> >        (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.]
>
> Some ptrace access mode checks, such as checks when reading
> /proc/pid/stat, merely cause the output to be filtered/sanitized rather
> than an error to be returned to the caller.  In these cases, accessing
> the file is not a security violation and there is no reason to generate
> a security audit record.  This modifier suppresses the generation of
> such an audit record for the particular access check.

Thanks, I've added that text to the man page more or less as you
gave it here.

Cheers,

Michael



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