[PATCH 2/2] ptrace.2: Expand documentation PTRACE_EVENT_SECCOMP traps

[PATCH 2/2] ptrace.2: Expand documentation PTRACE_EVENT_SECCOMP traps

[Keno Fischer]

In Linux 4.8 (through a series of commits, 93e35efb8de45393cf61ed07f7b407629bf698ea
being the actual reordering on x86), the order of PTRACE_EVENT_SECCOMP and
syscall-entry-stops was reversed. Document both behaviors and their
interaction with the various forms of restart.

Signed-off-by: Keno Fischer <keno-9DCaDmOhoh+8M3too/+dENBPR1lH4CV8@public.gmane.org>
---
 man2/ptrace.2 | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 74 insertions(+), 5 deletions(-)

diff --git a/man2/ptrace.2 b/man2/ptrace.2
index cb1b976..a821b7b 100644
--- a/man2/ptrace.2
+++ b/man2/ptrace.2
@@ -646,8 +646,8 @@ value such that
 
 While this triggers a
 .BR PTRACE_EVENT
-stop, it is similar to a syscall-enter-stop, in that the tracee has
-not yet entered the syscall that seccomp triggered on.
+stop, it is similar to a syscall-enter-stop. For details,
+see the note on PTRACE_EVENT_SECCOMP below.
 The seccomp event message data (from the
 .BR SECCOMP_RET_DATA
 portion of the seccomp filter rule) can be retrieved with
@@ -1133,6 +1133,7 @@ be further subdivided into
 .IR signal-delivery-stop ,
 .IR group-stop ,
 .IR syscall-stop ,
+.IR PTRACE_EVENT stops,
 and so on.
 These stopped states are described in detail below.
 .LP
@@ -1553,7 +1554,8 @@ has been set by the tracer.
 The seccomp event message data (from the
 .BR SECCOMP_RET_DATA
 portion of the seccomp filter rule) can be retrieved with
-.BR PTRACE_GETEVENTMSG .
+.BR PTRACE_GETEVENTMSG . The semantics of this stop are described in
+detail in a separate section below.
 .LP
 .B PTRACE_GETSIGINFO
 on
@@ -1599,7 +1601,7 @@ However, even if the tracee is was continued using
 , it is not guaranteed that the next stop will be a syscall-exit-stop.
 Other possibilities are that the tracee may stop in a
 .B PTRACE_EVENT
-stop, exit (if it entered
+stop (including seccomp stops), exit (if it entered
 .BR _exit (2)
 or
 .BR exit_group (2)),
@@ -1690,11 +1692,14 @@ indistinguishable from each other by the tracer.
 The tracer needs to keep track of the sequence of
 ptrace-stops in order to not misinterpret syscall-enter-stop as
 syscall-exit-stop or vice versa.
-The rule is that syscall-enter-stop is
+In general a syscall-enter-stop is
 always followed by syscall-exit-stop,
 .B PTRACE_EVENT
 stop or the tracee's death;
 no other kinds of ptrace-stop can occur in between.
+However, note that seccomp stops (see below) can cause syscall-exit-stops,
+without preceeding syscall-entry-stops. If seccomp is in use, care needs
+to be taken not to mis-interpret such stops as syscall-entry-stops.
 .LP
 If after syscall-enter-stop,
 the tracer uses a restarting command other than
@@ -1712,6 +1717,70 @@ set to
 .B SIGTRAP
 or
 .IR (SIGTRAP|0x80) .
+.SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 - 4.7)
+The behavior of
+.BR PTRACE_EVENT_SECCOMP
+stops and their interaction with other kinds
+of ptrace stops has changed between kernel versions. This documents the behavior
+from their introduction until Linux 4.7 (inclusive). The behavior in later kernel
+versions is documented in the next section.
+
+A
+.BR PTRACE_EVENT_SECCOMP
+stop occurs whenever a
+.BR SECCOMP_RET_TRACE
+rule is triggered. This is independent of which methods was used to restart
+the system call. Notably, seccomp still runs even if the tracee
+was restarted using
+.BR PTRACE_SYSEMU
+and this system call is unconditionally skipped.
+
+Restarts from this stop will behave as if the stop had occurred right
+before the system call in question. In particular, both
+.BR PTRACE_SYSCALL
+and
+.BR PTRACE_SYSEMU
+will normally cause a subsequent syscall-entry-stop. However, if after the
+.BR PTRACE_EVENT_SECCOMP
+the system call number is negative, both the syscall-entry-stop
+and the system call itself will be skipped. This means that if the
+system call number is negative after a
+.BR PTRACE_EVENT_SECCOMP
+and the tracee is restarted using
+.BR PTRACE_SYSCALL,
+the next observed stop will be a syscall-exit-stop,
+rather than the syscall-entry-stop
+that may have been expected.
+
+.SS PTRACE_EVENT_SECCOMP stops (Linux 4.8+)
+
+In Linux 4.8, the
+.BR PTRACE_EVENT_SECCOMP
+stop was re-ordered to occur between syscall-entry-stop and
+syscall-exit-stop. Note that, seccomp no longer
+runs (and no `PTRACE_EVENT_SECCOMP` will be reported) if
+the system call is skipped
+due to
+.BR PTRACE_SYSEMU
+.
+
+Functionally, a PTRACE_EVENT_SECCOMP stop functions comparably
+to a syscall-entry-stop (i.e. continuations using
+.BR PTRACE_SYSCALL
+will cause syscall-exit-stops, the system call number may be changed
+and any other modified registers are visible to the to-be-executed syscall as well).
+Note that there may, but need not have been a preceeding syscall-entry-stop.
+
+After a
+.BR PTRACE_EVENT_SECCOMP
+stop, seccomp will be re-run, with a
+.BR SECCOMP_RET_TRACE
+rule now functioning the same as a
+.BR SECCOMP_RET_ALLOW
+. Specifically, this means that if registers are not modified during the
+.BR PTRACE_EVENT_SECCOMP
+stop, the system call will then be allowed.
+
 .SS PTRACE_SINGLESTEP stops
 [Details of these kinds of stops are yet to be documented.]
 .\"
-- 
2.8.1

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/2] ptrace.2: Expand documentation PTRACE_EVENT_SECCOMP traps

[Kees Cook]

On Tue, Nov 15, 2016 at 9:52 PM, Keno Fischer <keno-9DCaDmOhoh+8M3too/+dENBPR1lH4CV8@public.gmane.org> wrote:
> In Linux 4.8 (through a series of commits, 93e35efb8de45393cf61ed07f7b407629bf698ea
> being the actual reordering on x86), the order of PTRACE_EVENT_SECCOMP and
> syscall-entry-stops was reversed. Document both behaviors and their
> interaction with the various forms of restart.
>
> Signed-off-by: Keno Fischer <keno-9DCaDmOhoh+8M3too/+dENBPR1lH4CV8@public.gmane.org>

Awesome, this looks quite comprehensive to me. Thanks!

-Kees

> ---
>  man2/ptrace.2 | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 74 insertions(+), 5 deletions(-)
>
> diff --git a/man2/ptrace.2 b/man2/ptrace.2
> index cb1b976..a821b7b 100644
> --- a/man2/ptrace.2
> +++ b/man2/ptrace.2
> @@ -646,8 +646,8 @@ value such that
>
>  While this triggers a
>  .BR PTRACE_EVENT
> -stop, it is similar to a syscall-enter-stop, in that the tracee has
> -not yet entered the syscall that seccomp triggered on.
> +stop, it is similar to a syscall-enter-stop. For details,
> +see the note on PTRACE_EVENT_SECCOMP below.
>  The seccomp event message data (from the
>  .BR SECCOMP_RET_DATA
>  portion of the seccomp filter rule) can be retrieved with
> @@ -1133,6 +1133,7 @@ be further subdivided into
>  .IR signal-delivery-stop ,
>  .IR group-stop ,
>  .IR syscall-stop ,
> +.IR PTRACE_EVENT stops,
>  and so on.
>  These stopped states are described in detail below.
>  .LP
> @@ -1553,7 +1554,8 @@ has been set by the tracer.
>  The seccomp event message data (from the
>  .BR SECCOMP_RET_DATA
>  portion of the seccomp filter rule) can be retrieved with
> -.BR PTRACE_GETEVENTMSG .
> +.BR PTRACE_GETEVENTMSG . The semantics of this stop are described in
> +detail in a separate section below.
>  .LP
>  .B PTRACE_GETSIGINFO
>  on
> @@ -1599,7 +1601,7 @@ However, even if the tracee is was continued using
>  , it is not guaranteed that the next stop will be a syscall-exit-stop.
>  Other possibilities are that the tracee may stop in a
>  .B PTRACE_EVENT
> -stop, exit (if it entered
> +stop (including seccomp stops), exit (if it entered
>  .BR _exit (2)
>  or
>  .BR exit_group (2)),
> @@ -1690,11 +1692,14 @@ indistinguishable from each other by the tracer.
>  The tracer needs to keep track of the sequence of
>  ptrace-stops in order to not misinterpret syscall-enter-stop as
>  syscall-exit-stop or vice versa.
> -The rule is that syscall-enter-stop is
> +In general a syscall-enter-stop is
>  always followed by syscall-exit-stop,
>  .B PTRACE_EVENT
>  stop or the tracee's death;
>  no other kinds of ptrace-stop can occur in between.
> +However, note that seccomp stops (see below) can cause syscall-exit-stops,
> +without preceeding syscall-entry-stops. If seccomp is in use, care needs
> +to be taken not to mis-interpret such stops as syscall-entry-stops.
>  .LP
>  If after syscall-enter-stop,
>  the tracer uses a restarting command other than
> @@ -1712,6 +1717,70 @@ set to
>  .B SIGTRAP
>  or
>  .IR (SIGTRAP|0x80) .
> +.SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 - 4.7)
> +The behavior of
> +.BR PTRACE_EVENT_SECCOMP
> +stops and their interaction with other kinds
> +of ptrace stops has changed between kernel versions. This documents the behavior
> +from their introduction until Linux 4.7 (inclusive). The behavior in later kernel
> +versions is documented in the next section.
> +
> +A
> +.BR PTRACE_EVENT_SECCOMP
> +stop occurs whenever a
> +.BR SECCOMP_RET_TRACE
> +rule is triggered. This is independent of which methods was used to restart
> +the system call. Notably, seccomp still runs even if the tracee
> +was restarted using
> +.BR PTRACE_SYSEMU
> +and this system call is unconditionally skipped.
> +
> +Restarts from this stop will behave as if the stop had occurred right
> +before the system call in question. In particular, both
> +.BR PTRACE_SYSCALL
> +and
> +.BR PTRACE_SYSEMU
> +will normally cause a subsequent syscall-entry-stop. However, if after the
> +.BR PTRACE_EVENT_SECCOMP
> +the system call number is negative, both the syscall-entry-stop
> +and the system call itself will be skipped. This means that if the
> +system call number is negative after a
> +.BR PTRACE_EVENT_SECCOMP
> +and the tracee is restarted using
> +.BR PTRACE_SYSCALL,
> +the next observed stop will be a syscall-exit-stop,
> +rather than the syscall-entry-stop
> +that may have been expected.
> +
> +.SS PTRACE_EVENT_SECCOMP stops (Linux 4.8+)
> +
> +In Linux 4.8, the
> +.BR PTRACE_EVENT_SECCOMP
> +stop was re-ordered to occur between syscall-entry-stop and
> +syscall-exit-stop. Note that, seccomp no longer
> +runs (and no `PTRACE_EVENT_SECCOMP` will be reported) if
> +the system call is skipped
> +due to
> +.BR PTRACE_SYSEMU
> +.
> +
> +Functionally, a PTRACE_EVENT_SECCOMP stop functions comparably
> +to a syscall-entry-stop (i.e. continuations using
> +.BR PTRACE_SYSCALL
> +will cause syscall-exit-stops, the system call number may be changed
> +and any other modified registers are visible to the to-be-executed syscall as well).
> +Note that there may, but need not have been a preceeding syscall-entry-stop.
> +
> +After a
> +.BR PTRACE_EVENT_SECCOMP
> +stop, seccomp will be re-run, with a
> +.BR SECCOMP_RET_TRACE
> +rule now functioning the same as a
> +.BR SECCOMP_RET_ALLOW
> +. Specifically, this means that if registers are not modified during the
> +.BR PTRACE_EVENT_SECCOMP
> +stop, the system call will then be allowed.
> +
>  .SS PTRACE_SINGLESTEP stops
>  [Details of these kinds of stops are yet to be documented.]
>  .\"
> --
> 2.8.1
>



-- 
Kees Cook
Nexus Security
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/2] ptrace.2: Expand documentation PTRACE_EVENT_SECCOMP traps

[Michael Kerrisk (man-pages)]

Hi Keno,

On 16 November 2016 at 06:52, Keno Fischer <keno-9DCaDmOhoh+8M3too/+dENBPR1lH4CV8@public.gmane.org> wrote:
> In Linux 4.8 (through a series of commits, 93e35efb8de45393cf61ed07f7b407629bf698ea
> being the actual reordering on x86), the order of PTRACE_EVENT_SECCOMP and
> syscall-entry-stops was reversed. Document both behaviors and their
> interaction with the various forms of restart.

Thanks !! Patch applied.

Cheers,

Michael



> Signed-off-by: Keno Fischer <keno-9DCaDmOhoh+8M3too/+dENBPR1lH4CV8@public.gmane.org>
> ---
>  man2/ptrace.2 | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 74 insertions(+), 5 deletions(-)
>
> diff --git a/man2/ptrace.2 b/man2/ptrace.2
> index cb1b976..a821b7b 100644
> --- a/man2/ptrace.2
> +++ b/man2/ptrace.2
> @@ -646,8 +646,8 @@ value such that
>
>  While this triggers a
>  .BR PTRACE_EVENT
> -stop, it is similar to a syscall-enter-stop, in that the tracee has
> -not yet entered the syscall that seccomp triggered on.
> +stop, it is similar to a syscall-enter-stop. For details,
> +see the note on PTRACE_EVENT_SECCOMP below.
>  The seccomp event message data (from the
>  .BR SECCOMP_RET_DATA
>  portion of the seccomp filter rule) can be retrieved with
> @@ -1133,6 +1133,7 @@ be further subdivided into
>  .IR signal-delivery-stop ,
>  .IR group-stop ,
>  .IR syscall-stop ,
> +.IR PTRACE_EVENT stops,
>  and so on.
>  These stopped states are described in detail below.
>  .LP
> @@ -1553,7 +1554,8 @@ has been set by the tracer.
>  The seccomp event message data (from the
>  .BR SECCOMP_RET_DATA
>  portion of the seccomp filter rule) can be retrieved with
> -.BR PTRACE_GETEVENTMSG .
> +.BR PTRACE_GETEVENTMSG . The semantics of this stop are described in
> +detail in a separate section below.
>  .LP
>  .B PTRACE_GETSIGINFO
>  on
> @@ -1599,7 +1601,7 @@ However, even if the tracee is was continued using
>  , it is not guaranteed that the next stop will be a syscall-exit-stop.
>  Other possibilities are that the tracee may stop in a
>  .B PTRACE_EVENT
> -stop, exit (if it entered
> +stop (including seccomp stops), exit (if it entered
>  .BR _exit (2)
>  or
>  .BR exit_group (2)),
> @@ -1690,11 +1692,14 @@ indistinguishable from each other by the tracer.
>  The tracer needs to keep track of the sequence of
>  ptrace-stops in order to not misinterpret syscall-enter-stop as
>  syscall-exit-stop or vice versa.
> -The rule is that syscall-enter-stop is
> +In general a syscall-enter-stop is
>  always followed by syscall-exit-stop,
>  .B PTRACE_EVENT
>  stop or the tracee's death;
>  no other kinds of ptrace-stop can occur in between.
> +However, note that seccomp stops (see below) can cause syscall-exit-stops,
> +without preceeding syscall-entry-stops. If seccomp is in use, care needs
> +to be taken not to mis-interpret such stops as syscall-entry-stops.
>  .LP
>  If after syscall-enter-stop,
>  the tracer uses a restarting command other than
> @@ -1712,6 +1717,70 @@ set to
>  .B SIGTRAP
>  or
>  .IR (SIGTRAP|0x80) .
> +.SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 - 4.7)
> +The behavior of
> +.BR PTRACE_EVENT_SECCOMP
> +stops and their interaction with other kinds
> +of ptrace stops has changed between kernel versions. This documents the behavior
> +from their introduction until Linux 4.7 (inclusive). The behavior in later kernel
> +versions is documented in the next section.
> +
> +A
> +.BR PTRACE_EVENT_SECCOMP
> +stop occurs whenever a
> +.BR SECCOMP_RET_TRACE
> +rule is triggered. This is independent of which methods was used to restart
> +the system call. Notably, seccomp still runs even if the tracee
> +was restarted using
> +.BR PTRACE_SYSEMU
> +and this system call is unconditionally skipped.
> +
> +Restarts from this stop will behave as if the stop had occurred right
> +before the system call in question. In particular, both
> +.BR PTRACE_SYSCALL
> +and
> +.BR PTRACE_SYSEMU
> +will normally cause a subsequent syscall-entry-stop. However, if after the
> +.BR PTRACE_EVENT_SECCOMP
> +the system call number is negative, both the syscall-entry-stop
> +and the system call itself will be skipped. This means that if the
> +system call number is negative after a
> +.BR PTRACE_EVENT_SECCOMP
> +and the tracee is restarted using
> +.BR PTRACE_SYSCALL,
> +the next observed stop will be a syscall-exit-stop,
> +rather than the syscall-entry-stop
> +that may have been expected.
> +
> +.SS PTRACE_EVENT_SECCOMP stops (Linux 4.8+)
> +
> +In Linux 4.8, the
> +.BR PTRACE_EVENT_SECCOMP
> +stop was re-ordered to occur between syscall-entry-stop and
> +syscall-exit-stop. Note that, seccomp no longer
> +runs (and no `PTRACE_EVENT_SECCOMP` will be reported) if
> +the system call is skipped
> +due to
> +.BR PTRACE_SYSEMU
> +.
> +
> +Functionally, a PTRACE_EVENT_SECCOMP stop functions comparably
> +to a syscall-entry-stop (i.e. continuations using
> +.BR PTRACE_SYSCALL
> +will cause syscall-exit-stops, the system call number may be changed
> +and any other modified registers are visible to the to-be-executed syscall as well).
> +Note that there may, but need not have been a preceeding syscall-entry-stop.
> +
> +After a
> +.BR PTRACE_EVENT_SECCOMP
> +stop, seccomp will be re-run, with a
> +.BR SECCOMP_RET_TRACE
> +rule now functioning the same as a
> +.BR SECCOMP_RET_ALLOW
> +. Specifically, this means that if registers are not modified during the
> +.BR PTRACE_EVENT_SECCOMP
> +stop, the system call will then be allowed.
> +
>  .SS PTRACE_SINGLESTEP stops
>  [Details of these kinds of stops are yet to be documented.]
>  .\"
> --
> 2.8.1
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html