seccomp_rule_add_exact(3)

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).
74
75       The   SCMP_CMP(),  SCMP_CMP64(),  SCMP_A{0-5}(),  and  SCMP_A{0-5}_64()
76       macros generate a scmp_arg_cmp structure for use with the  above  func‐
77       tions.  The  SCMP_CMP()  and  SCMP_CMP64()  macros allows the caller to
78       specify an arbitrary  argument  along  with  the  comparison  operator,
79       64-bit  mask,  and  64-bit  datum  values  where  the SCMP_A{0-5}() and
80       SCMP_A{0-5}_64() macros are specific to a certain argument.
81
82       The SCMP_CMP32() and SCMP_A{0-5}_32() macros are similar to  the  vari‐
83       ants above, but they take 32-bit mask and 32-bit datum values.
84
85       It  is  recommended  that  whenever possible developers avoid using the
86       SCMP_CMP() and SCMP_A{0-5}() macros and  use  the  variants  which  are
87       explicitly 32 or 64-bit.  This should help eliminate problems caused by
88       an unwanted sign extension of negative datum values.
89
90       While it is possible to specify the syscall value  directly  using  the
91       standard  __NR_syscall  values,  in  order  to  ensure proper operation
92       across multiple architectures it  is  highly  recommended  to  use  the
93       SCMP_SYS() macro instead.  See the EXAMPLES section below.
94
95       Starting  with  Linux v4.8, there may be a need to create a rule with a
96       syscall value of -1 to allow tracing programs to skip a syscall invoca‐
97       tion; in order to create a rule with a -1 syscall value it is necessary
98       to  first  set   the   SCMP_FLTATR_API_TSKIP   attribute.    See   sec‐
99       comp_attr_set(3) for more information.
100
101       The  filter  context  ctx  is  the  value  returned by the call to sec‐
102       comp_init(3).
103
104       Valid action values are as follows:
105
106       SCMP_ACT_KILL
107              The thread will be killed by the kernel when it calls a  syscall
108              that matches the filter rule.
109
110       SCMP_ACT_KILL_PROCESS
111              The process will be killed by the kernel when it calls a syscall
112              that matches the filter rule.
113
114       SCMP_ACT_TRAP
115              The thread will throw a SIGSYS signal when it  calls  a  syscall
116              that matches the filter rule.
117
118       SCMP_ACT_ERRNO(uint16_t errno)
119              The  thread will receive a return value of errno when it calls a
120              syscall that matches the filter rule.
121
122       SCMP_ACT_TRACE(uint16_t msg_num)
123              If the thread is being traced and the tracing process  specified
124              the  PTRACE_O_TRACESECCOMP  option in the call to ptrace(2), the
125              tracing process will be notified, via PTRACE_EVENT_SECCOMP , and
126              the  value  provided  in  msg_num  can  be  retrieved  using the
127              PTRACE_GETEVENTMSG option.
128
129       SCMP_ACT_LOG
130              The seccomp filter will have no effect on the thread calling the
131              syscall  if  it  matches the filter rule but the syscall will be
132              logged.
133
134       SCMP_ACT_ALLOW
135              The seccomp filter will have no effect on the thread calling the
136              syscall if it matches the filter rule.
137
138       Valid comparison op values are as follows:
139
140       SCMP_CMP_NE
141              Matches when the argument value is not equal to the datum value,
142              example:
143
144              SCMP_CMP( arg , SCMP_CMP_NE , datum )
145
146       SCMP_CMP_LT
147              Matches when the argument value is less than  the  datum  value,
148              example:
149
150              SCMP_CMP( arg , SCMP_CMP_LT , datum )
151
152       SCMP_CMP_LE
153              Matches  when  the  argument  value is less than or equal to the
154              datum value, example:
155
156              SCMP_CMP( arg , SCMP_CMP_LE , datum )
157
158       SCMP_CMP_EQ
159              Matches when the argument value is equal  to  the  datum  value,
160              example:
161
162              SCMP_CMP( arg , SCMP_CMP_EQ , datum )
163
164       SCMP_CMP_GE
165              Matches  when the argument value is greater than or equal to the
166              datum value, example:
167
168              SCMP_CMP( arg , SCMP_CMP_GE , datum )
169
170       SCMP_CMP_GT
171              Matches when the argument value is greater than the datum value,
172              example:
173
174              SCMP_CMP( arg , SCMP_CMP_GT , datum )
175
176       SCMP_CMP_MASKED_EQ
177              Matches  when  the  masked argument value is equal to the masked
178              datum value, example:
179
180              SCMP_CMP( arg , SCMP_CMP_MASKED_EQ , mask , datum )
181

RETURN VALUE

183       The      seccomp_rule_add(),       seccomp_rule_add_array(),       sec‐
184       comp_rule_add_exact(),   and  seccomp_rule_add_exact_array()  functions
185       return zero on success, negative errno values on failure.
186

EXAMPLES

188       #include <fcntl.h>
189       #include <seccomp.h>
190       #include <sys/stat.h>
191       #include <sys/types.h>
192       #include <stddef.h>
193
194       #define BUF_SIZE    256
195
196       int main(int argc, char *argv[])
197       {
198            int rc = -1;
199            scmp_filter_ctx ctx;
200            struct scmp_arg_cmp arg_cmp[] = { SCMP_A0(SCMP_CMP_EQ, 2) };
201            int fd;
202            unsigned char buf[BUF_SIZE];
203
204            ctx = seccomp_init(SCMP_ACT_KILL);
205            if (ctx == NULL)
206                 goto out;
207
208            /* ... */
209
210            fd = open("file.txt", 0);
211
212            /* ... */
213
214            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0);
215            if (rc < 0)
216                 goto out;
217
218            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(exit_group), 0);
219            if (rc < 0)
220                 goto out;
221
222            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(exit), 0);
223            if (rc < 0)
224                 goto out;
225
226            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(read), 3,
227                            SCMP_A0(SCMP_CMP_EQ, fd),
228                            SCMP_A1(SCMP_CMP_EQ, (scmp_datum_t)buf),
229                            SCMP_A2(SCMP_CMP_LE, BUF_SIZE));
230            if (rc < 0)
231                 goto out;
232
233            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
234                            SCMP_CMP(0, SCMP_CMP_EQ, fd));
235            if (rc < 0)
236                 goto out;
237
238            rc = seccomp_rule_add_array(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
239                                  arg_cmp);
240            if (rc < 0)
241                 goto out;
242
243            rc = seccomp_load(ctx);
244            if (rc < 0)
245                 goto out;
246
247            /* ... */
248
249       out:
250            seccomp_release(ctx);
251            return -rc;
252       }
253

NOTES

255       While the seccomp filter can be generated independent  of  the  kernel,
256       kernel  support is required to load and enforce the seccomp filter gen‐
257       erated by libseccomp.
258
259       The libseccomp project site, with more information and the source  code
260       repository,  can  be  found  at  https://github.com/seccomp/libseccomp.
261       This tool, as well as the libseccomp library, is currently under devel‐
262       opment,  please  report any bugs at the project site or directly to the
263       author.
264

AUTHOR

266       Paul Moore <paul@paul-moore.com>
267