From 23bc6267f5705b18c3143c8a509d0a0d33e5e62e Mon Sep 17 00:00:00 2001 From: Paul Moore Date: Mon, 23 Mar 2020 21:22:36 -0400 Subject: doc: improve the manpages for seccomp_rule_add() and seccomp_load() Add some text to clarify that you can only have one comparison per syscall argument in a given rule as well as better explain what happens when you have multiple filters loaded. Reviewed-by: Tom Hromatka Signed-off-by: Paul Moore --- doc/man/man3/seccomp_load.3 | 10 ++++++++++ doc/man/man3/seccomp_rule_add.3 | 20 ++++++++++++++++++++ 2 files changed, 30 insertions(+) diff --git a/doc/man/man3/seccomp_load.3 b/doc/man/man3/seccomp_load.3 index e86bac4..fb40660 100644 --- a/doc/man/man3/seccomp_load.3 +++ b/doc/man/man3/seccomp_load.3 @@ -23,6 +23,16 @@ Loads the seccomp filter provided by .I ctx into the kernel; if the function succeeds the new seccomp filter will be active when the function returns. +.P +As it is possible to have multiple stacked seccomp filters for a given task +(defined as either a process or a thread), it is important to remember that +each of the filters loaded for a given task are executed when a syscall is +made and the "strictest" rule is the rule that is applied. In the case of +seccomp, "strictest" is defined as the action with the lowest value (e.g. +.I SCMP_ACT_KILL +is "stricter" than +.I SCMP_ACT_ALLOW +). .\" ////////////////////////////////////////////////////////////////////////// .SH RETURN VALUE .\" ////////////////////////////////////////////////////////////////////////// diff --git a/doc/man/man3/seccomp_rule_add.3 b/doc/man/man3/seccomp_rule_add.3 index e86f41b..0b9bcff 100644 --- a/doc/man/man3/seccomp_rule_add.3 +++ b/doc/man/man3/seccomp_rule_add.3 @@ -87,6 +87,17 @@ do guarantee the same behavior regardless of the architecture. The newly added filter rule does not take effect until the entire filter is loaded into the kernel using .BR seccomp_load (3). +When adding rules to a filter, it is important to consider the impact of +previously loaded filters; see the +.BR seccomp_load (3) +documentation for more information. +.P +All of the filter rules supplied by the calling application are combined into +a union, with additional logic to eliminate redundant syscall filters. For +example, if a rule is added which allows a given syscall with a specific set of +argument values and later a rule is added which allows the same syscall +regardless the argument values then the first, more specific rule, is +effectively dropped from the filter by the second more generic rule. .P The .BR SCMP_CMP (), @@ -120,6 +131,15 @@ macros and use the variants which are explicitly 32 or 64-bit. This should help eliminate problems caused by an unwanted sign extension of negative datum values. .P +If syscall argument comparisons are included in the filter rule, all of the +comparisons must be true for the rule to match. +.P +When adding syscall argument comparisons to the filter it is important to +remember that while it is possible to have multiple comparisons in a single +rule, you can only compare each argument once in a single rule. In other words, +you can not have multiple comparisons of the 3rd syscall argument in a single +rule. +.P While it is possible to specify the .I syscall value directly using the standard -- cgit v1.2.1