1seccomp_rule_add(3)        libseccomp Documentation        seccomp_rule_add(3)
2
3
4

NAME

6       seccomp_rule_add, seccomp_rule_add_exact - Add a seccomp filter rule
7

SYNOPSIS

9       #include <seccomp.h>
10
11       typedef void * scmp_filter_ctx;
12
13       int SCMP_SYS(syscall_name);
14
15       struct scmp_arg_cmp SCMP_CMP(unsigned int arg,
16                                    enum scmp_compare op, ...);
17       struct scmp_arg_cmp SCMP_A0(enum scmp_compare op, ...);
18       struct scmp_arg_cmp SCMP_A1(enum scmp_compare op, ...);
19       struct scmp_arg_cmp SCMP_A2(enum scmp_compare op, ...);
20       struct scmp_arg_cmp SCMP_A3(enum scmp_compare op, ...);
21       struct scmp_arg_cmp SCMP_A4(enum scmp_compare op, ...);
22       struct scmp_arg_cmp SCMP_A5(enum scmp_compare op, ...);
23
24       struct scmp_arg_cmp SCMP_CMP64(unsigned int arg,
25                                    enum scmp_compare op, ...);
26       struct scmp_arg_cmp SCMP_A0_64(enum scmp_compare op, ...);
27       struct scmp_arg_cmp SCMP_A1_64(enum scmp_compare op, ...);
28       struct scmp_arg_cmp SCMP_A2_64(enum scmp_compare op, ...);
29       struct scmp_arg_cmp SCMP_A3_64(enum scmp_compare op, ...);
30       struct scmp_arg_cmp SCMP_A4_64(enum scmp_compare op, ...);
31       struct scmp_arg_cmp SCMP_A5_64(enum scmp_compare op, ...);
32
33       struct scmp_arg_cmp SCMP_CMP32(unsigned int arg,
34                                    enum scmp_compare op, ...);
35       struct scmp_arg_cmp SCMP_A0_32(enum scmp_compare op, ...);
36       struct scmp_arg_cmp SCMP_A1_32(enum scmp_compare op, ...);
37       struct scmp_arg_cmp SCMP_A2_32(enum scmp_compare op, ...);
38       struct scmp_arg_cmp SCMP_A3_32(enum scmp_compare op, ...);
39       struct scmp_arg_cmp SCMP_A4_32(enum scmp_compare op, ...);
40       struct scmp_arg_cmp SCMP_A5_32(enum scmp_compare op, ...);
41
42       int seccomp_rule_add(scmp_filter_ctx ctx, uint32_t action,
43                            int syscall, unsigned int arg_cnt, ...);
44       int seccomp_rule_add_exact(scmp_filter_ctx ctx, uint32_t action,
45                                  int syscall, unsigned int arg_cnt, ...);
46
47       int seccomp_rule_add_array(scmp_filter_ctx ctx,
48                                  uint32_t action, int syscall,
49                                  unsigned int arg_cnt,
50                                  const struct scmp_arg_cmp *arg_array);
51       int seccomp_rule_add_exact_array(scmp_filter_ctx ctx,
52                                        uint32_t action, int syscall,
53                                        unsigned int arg_cnt,
54                                        const struct scmp_arg_cmp *arg_array);
55
56       Link with -lseccomp.
57

DESCRIPTION

59       The       seccomp_rule_add(),       seccomp_rule_add_array(),      sec‐
60       comp_rule_add_exact(), and seccomp_rule_add_exact_array() functions all
61       add  a  new  filter  rule  to  the  current  seccomp  filter.  The sec‐
62       comp_rule_add() and  seccomp_rule_add_array()  functions  will  make  a
63       "best  effort"  to  add  the  rule as specified, but may alter the rule
64       slightly due to architecture specifics (e.g. internal rewriting of mul‐
65       tiplexed  syscalls,  like  socket  and ipc functions on x86).  The sec‐
66       comp_rule_add_exact() and seccomp_rule_add_exact_array() functions will
67       attempt  to  add the rule exactly as specified so it may behave differ‐
68       ently on different architectures.  While it does not guarantee a  exact
69       filter  ruleset,  seccomp_rule_add()  and  seccomp_rule_add_array()  do
70       guarantee the same behavior regardless of the architecture.
71
72       The newly added filter rule does not take effect until the entire  fil‐
73       ter is loaded into the kernel using seccomp_load(3).  When adding rules
74       to a filter, it is important  to  consider  the  impact  of  previously
75       loaded filters; see the seccomp_load(3) documentation for more informa‐
76       tion.
77
78       All of the filter rules supplied by the calling  application  are  com‐
79       bined  into  a  union,  with  additional  logic  to eliminate redundant
80       syscall filters.  For example, if a rule is added which allows a  given
81       syscall  with  a  specific  set  of argument values and later a rule is
82       added which allows the same syscall regardless the argument values then
83       the  first,  more specific rule, is effectively dropped from the filter
84       by the second more generic rule.
85
86       The  SCMP_CMP(),  SCMP_CMP64(),  SCMP_A{0-5}(),  and   SCMP_A{0-5}_64()
87       macros  generate  a scmp_arg_cmp structure for use with the above func‐
88       tions. The SCMP_CMP() and SCMP_CMP64()  macros  allows  the  caller  to
89       specify  an  arbitrary  argument  along  with  the comparison operator,
90       64-bit mask, and  64-bit  datum  values  where  the  SCMP_A{0-5}()  and
91       SCMP_A{0-5}_64() macros are specific to a certain argument.
92
93       The  SCMP_CMP32()  and SCMP_A{0-5}_32() macros are similar to the vari‐
94       ants above, but they take 32-bit mask and 32-bit datum values.
95
96       It is recommended that whenever possible  developers  avoid  using  the
97       SCMP_CMP()  and  SCMP_A{0-5}()  macros  and  use the variants which are
98       explicitly 32 or 64-bit.  This should help eliminate problems caused by
99       an unwanted sign extension of negative datum values.
100
101       If syscall argument comparisons are included in the filter rule, all of
102       the comparisons must be true for the rule to match.
103
104       When adding syscall argument comparisons to the filter it is  important
105       to remember that while it is possible to have multiple comparisons in a
106       single rule, you can only compare each argument once in a single  rule.
107       In  other  words,  you  can  not  have  multiple comparisons of the 3rd
108       syscall argument in a single rule.
109
110       In a filter containing multiple architectures, it is an error to add  a
111       filter  rule  for  a syscall that does not exist in all of the filter's
112       architectures.
113
114       While it is possible to specify the syscall value  directly  using  the
115       standard  __NR_syscall  values,  in  order  to  ensure proper operation
116       across multiple architectures it  is  highly  recommended  to  use  the
117       SCMP_SYS()  macro instead.  See the EXAMPLES section below.  It is also
118       important to remember that regardless of the architectures  present  in
119       the filter, the syscall numbers used in filter rules are interpreted in
120       the context of the native architecture.
121
122       Starting with Linux v4.8, there may be a need to create a rule  with  a
123       syscall value of -1 to allow tracing programs to skip a syscall invoca‐
124       tion; in order to create a rule with a -1 syscall value it is necessary
125       to   first   set   the   SCMP_FLTATR_API_TSKIP   attribute.   See  sec‐
126       comp_attr_set(3) for more information.
127
128       The filter context ctx is the  value  returned  by  the  call  to  sec‐
129       comp_init(3).
130
131       Valid action values are as follows:
132
133       SCMP_ACT_KILL
134              The  thread will be killed by the kernel when it calls a syscall
135              that matches the filter rule.
136
137       SCMP_ACT_KILL_PROCESS
138              The process will be killed by the kernel when it calls a syscall
139              that matches the filter rule.
140
141       SCMP_ACT_TRAP
142              The  thread  will  throw a SIGSYS signal when it calls a syscall
143              that matches the filter rule.
144
145       SCMP_ACT_ERRNO(uint16_t errno)
146              The thread will receive a return value of errno when it calls  a
147              syscall that matches the filter rule.
148
149       SCMP_ACT_TRACE(uint16_t msg_num)
150              If  the thread is being traced and the tracing process specified
151              the PTRACE_O_TRACESECCOMP option in the call to  ptrace(2),  the
152              tracing process will be notified, via PTRACE_EVENT_SECCOMP , and
153              the value  provided  in  msg_num  can  be  retrieved  using  the
154              PTRACE_GETEVENTMSG option.
155
156       SCMP_ACT_LOG
157              The seccomp filter will have no effect on the thread calling the
158              syscall if it matches the filter rule but the  syscall  will  be
159              logged.
160
161       SCMP_ACT_ALLOW
162              The seccomp filter will have no effect on the thread calling the
163              syscall if it matches the filter rule.
164
165       Valid comparison op values are as follows:
166
167       SCMP_CMP_NE
168              Matches when the argument value is not equal to the datum value,
169              example:
170
171              SCMP_CMP( arg , SCMP_CMP_NE , datum )
172
173       SCMP_CMP_LT
174              Matches  when  the  argument value is less than the datum value,
175              example:
176
177              SCMP_CMP( arg , SCMP_CMP_LT , datum )
178
179       SCMP_CMP_LE
180              Matches when the argument value is less than  or  equal  to  the
181              datum value, example:
182
183              SCMP_CMP( arg , SCMP_CMP_LE , datum )
184
185       SCMP_CMP_EQ
186              Matches  when  the  argument  value is equal to the datum value,
187              example:
188
189              SCMP_CMP( arg , SCMP_CMP_EQ , datum )
190
191       SCMP_CMP_GE
192              Matches when the argument value is greater than or equal to  the
193              datum value, example:
194
195              SCMP_CMP( arg , SCMP_CMP_GE , datum )
196
197       SCMP_CMP_GT
198              Matches when the argument value is greater than the datum value,
199              example:
200
201              SCMP_CMP( arg , SCMP_CMP_GT , datum )
202
203       SCMP_CMP_MASKED_EQ
204              Matches when the masked argument value is equal  to  the  masked
205              datum value, example:
206
207              SCMP_CMP( arg , SCMP_CMP_MASKED_EQ , mask , datum )
208

RETURN VALUE

210       The  SCMP_SYS()  macro  returns a value suitable for use as the syscall
211       value in the seccomp_rule_add*() functions.  In a similar  manner,  the
212       SCMP_CMP() and SCMP_A*() macros return values suitable for use as argu‐
213       ment comparisons in the seccomp_rule_add() and seccomp_rule_add_exact()
214       functions.
215
216       The       seccomp_rule_add(),       seccomp_rule_add_array(),      sec‐
217       comp_rule_add_exact(),  and  seccomp_rule_add_exact_array()   functions
218       return zero on success or one of the following error codes on failure:
219
220       -EDOM  Architecture specific failure.
221
222       -EEXIST
223              The rule already exists.
224
225       -EFAULT
226              Internal libseccomp failure.
227
228       -EINVAL
229              Invalid  input,  either  the  context  or  architecture token is
230              invalid.
231
232       -ENOMEM
233              The library was unable to allocate enough memory.
234
235       -EOPNOTSUPP
236              The library doesn't support the particular operation.
237

EXAMPLES

239       #include <fcntl.h>
240       #include <seccomp.h>
241       #include <sys/stat.h>
242       #include <sys/types.h>
243       #include <stddef.h>
244
245       #define BUF_SIZE    256
246
247       int main(int argc, char *argv[])
248       {
249            int rc = -1;
250            scmp_filter_ctx ctx;
251            struct scmp_arg_cmp arg_cmp[] = { SCMP_A0(SCMP_CMP_EQ, 2) };
252            int fd;
253            unsigned char buf[BUF_SIZE];
254
255            ctx = seccomp_init(SCMP_ACT_KILL);
256            if (ctx == NULL)
257                 goto out;
258
259            /* ... */
260
261            fd = open("file.txt", 0);
262
263            /* ... */
264
265            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0);
266            if (rc < 0)
267                 goto out;
268
269            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(exit_group), 0);
270            if (rc < 0)
271                 goto out;
272
273            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(exit), 0);
274            if (rc < 0)
275                 goto out;
276
277            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(read), 3,
278                            SCMP_A0(SCMP_CMP_EQ, fd),
279                            SCMP_A1(SCMP_CMP_EQ, (scmp_datum_t)buf),
280                            SCMP_A2(SCMP_CMP_LE, BUF_SIZE));
281            if (rc < 0)
282                 goto out;
283
284            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
285                            SCMP_CMP(0, SCMP_CMP_EQ, fd));
286            if (rc < 0)
287                 goto out;
288
289            rc = seccomp_rule_add_array(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
290                                  arg_cmp);
291            if (rc < 0)
292                 goto out;
293
294            rc = seccomp_load(ctx);
295            if (rc < 0)
296                 goto out;
297
298            /* ... */
299
300       out:
301            seccomp_release(ctx);
302            return -rc;
303       }
304

NOTES

306       While the seccomp filter can be generated independent  of  the  kernel,
307       kernel  support is required to load and enforce the seccomp filter gen‐
308       erated by libseccomp.
309
310       The libseccomp project site, with more information and the source  code
311       repository,  can  be  found  at  https://github.com/seccomp/libseccomp.
312       This tool, as well as the libseccomp library, is currently under devel‐
313       opment,  please  report any bugs at the project site or directly to the
314       author.
315

AUTHOR

317       Paul Moore <paul@paul-moore.com>
318

SEE ALSO

320       seccomp_syscall_resolve_name_rewrite(3),   seccomp_syscall_priority(3),
321       seccomp_load(3), seccomp_attr_set(3)
322
323
324
325paul@paul-moore.com               30 May 2020              seccomp_rule_add(3)
Impressum