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       int seccomp_rule_add(scmp_filter_ctx ctx, uint32_t action,
25                            int syscall, unsigned int arg_cnt, ...);
26       int seccomp_rule_add_exact(scmp_filter_ctx ctx, uint32_t action,
27                                  int syscall, unsigned int arg_cnt, ...);
28
29       int seccomp_rule_add_array(scmp_filter_ctx ctx,
30                                  uint32_t action, int syscall,
31                                  unsigned int arg_cnt,
32                                  const struct scmp_arg_cmp *arg_array);
33       int seccomp_rule_add_exact_array(scmp_filter_ctx ctx,
34                                        uint32_t action, int syscall,
35                                        unsigned int arg_cnt,
36                                        const struct scmp_arg_cmp *arg_array);
37
38       Link with -lseccomp.
39

DESCRIPTION

41       The       seccomp_rule_add(),       seccomp_rule_add_array(),      sec‐
42       comp_rule_add_exact(), and seccomp_rule_add_exact_array() functions all
43       add  a  new  filter  rule  to  the  current  seccomp  filter.  The sec‐
44       comp_rule_add() and  seccomp_rule_add_array()  functions  will  make  a
45       "best  effort"  to  add  the  rule as specified, but may alter the rule
46       slightly due to architecture specifics, e.g. socket and  ipc  functions
47       on      x86.       The      seccomp_rule_add_exact()      and      sec‐
48       comp_rule_add_exact_array() functions will  attempt  to  add  the  rule
49       exactly  as  specified so it may behave differently on different archi‐
50       tectures.  While it does not guarantee a  exact  filter  ruleset,  sec‐
51       comp_rule_add()  and  seccomp_rule_add_array()  do  guarantee  the same
52       behavior regardless of the architecture.
53
54       The newly added filter rule does not take effect until the entire  fil‐
55       ter is loaded into the kernel using seccomp_load(3).
56
57       The  SCMP_CMP() and SCMP_A{0-5}() macros generate a scmp_arg_cmp struc‐
58       ture for use with the above functions. The SCMP_CMP() macro allows  the
59       caller to specify an arbitrary argument along with the comparison oper‐
60       ator, mask, and datum values where the SCMP_A{0-5}()  macros  are  spe‐
61       cific to a certain argument.  See the EXAMPLES section below.
62
63       While  it  is  possible to specify the syscall value directly using the
64       standard __NR_syscall values,  in  order  to  ensure  proper  operation
65       across  multiple  architectures  it  is  highly  recommended to use the
66       SCMP_SYS() macro instead.  See the EXAMPLES section below.
67
68       The filter context ctx is the  value  returned  by  the  call  to  sec‐
69       comp_init(3).
70
71       Valid action values are as follows:
72
73       SCMP_ACT_KILL
74              The  thread will be killed by the kernel when it calls a syscall
75              that does not match any of the configured seccomp filter rules.
76
77       SCMP_ACT_TRAP
78              The thread will throw a SIGSYS signal when it  calls  a  syscall
79              that does not match any of the configured seccomp filter rules.
80
81       SCMP_ACT_ERRNO(uint16_t errno)
82              The  thread will receive a return value of errno when it calls a
83              syscall that does not match any of the configured seccomp filter
84              rules.
85
86       SCMP_ACT_TRACE(uint16_t msg_num)
87              If  the thread is being traced and the tracing process specified
88              the PTRACE_O_TRACESECCOMP option in the call to  ptrace(2),  the
89              tracing process will be notified, via PTRACE_EVENT_SECCOMP , and
90              the value  provided  in  msg_num  can  be  retrieved  using  the
91              PTRACE_GETEVENTMSG option.
92
93       SCMP_ACT_ALLOW
94              The seccomp filter will have no effect on the thread calling the
95              syscall if it does not match any of the configured seccomp  fil‐
96              ter rules.
97
98       Valid comparison op values are as follows:
99
100       SCMP_CMP_NE
101              Matches when the argument value is not equal to the datum value,
102              example:
103
104              SCMP_CMP( arg , SCMP_CMP_NE , datum )
105
106       SCMP_CMP_LT
107              Matches when the argument value is less than  the  datum  value,
108              example:
109
110              SCMP_CMP( arg , SCMP_CMP_LT , datum )
111
112       SCMP_CMP_LE
113              Matches  when  the  argument  value is less than or equal to the
114              datum value, example:
115
116              SCMP_CMP( arg , SCMP_CMP_LE , datum )
117
118       SCMP_CMP_EQ
119              Matches when the argument value is equal  to  the  datum  value,
120              example:
121
122              SCMP_CMP( arg , SCMP_CMP_EQ , datum )
123
124       SCMP_CMP_GE
125              Matches  when the argument value is greater than or equal to the
126              datum value, example:
127
128              SCMP_CMP( arg , SCMP_CMP_GE , datum )
129
130       SCMP_CMP_GT
131              Matches when the argument value is greater than the datum value,
132              example:
133
134              SCMP_CMP( arg , SCMP_CMP_GT , datum )
135
136       SCMP_CMP_MASKED_EQ
137              Matches  when  the  masked argument value is equal to the masked
138              datum value, example:
139
140              SCMP_CMP( arg , SCMP_CMP_MASKED_EQ , mask , datum )
141

RETURN VALUE

143       The      seccomp_rule_add(),       seccomp_rule_add_array(),       sec‐
144       comp_rule_add_exact(),   and  seccomp_rule_add_exact_array()  functions
145       return zero on success, negative errno values on failure.
146

EXAMPLES

148       #include <fcntl.h>
149       #include <seccomp.h>
150       #include <sys/stat.h>
151       #include <sys/types.h>
152
153       #define BUF_SIZE    256
154
155       int main(int argc, char *argv[])
156       {
157            int rc = -1;
158            scmp_filter_ctx ctx;
159            struct scmp_arg_cmp arg_cmp[] = { SCMP_A0(SCMP_CMP_EQ, 2) };
160            int fd;
161            unsigned char buf[BUF_SIZE];
162
163            ctx = seccomp_init(SCMP_ACT_KILL);
164            if (ctx == NULL)
165                 goto out;
166
167            /* ... */
168
169            fd = open("file.txt", 0);
170
171            /* ... */
172
173            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0);
174            if (rc < 0)
175                 goto out;
176
177            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(read), 3,
178                            SCMP_A0(SCMP_CMP_EQ, fd),
179                            SCMP_A1(SCMP_CMP_EQ, (scmp_datum_t)buf),
180                            SCMP_A2(SCMP_CMP_LE, BUF_SIZE));
181            if (rc < 0)
182                 goto out;
183
184            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
185                            SCMP_CMP(0, SCMP_CMP_EQ, fd));
186            if (rc < 0)
187                 goto out;
188
189            rc = seccomp_rule_add_array(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
190                                  arg_cmp);
191            if (rc < 0)
192                 goto out;
193
194            rc = seccomp_load(ctx);
195            if (rc < 0)
196                 goto out;
197
198            /* ... */
199
200       out:
201            seccomp_release(ctx);
202            return -rc;
203       }
204

NOTES

206       While the seccomp filter can be generated independent  of  the  kernel,
207       kernel  support is required to load and enforce the seccomp filter gen‐
208       erated by libseccomp.
209
210       The libseccomp project site, with more information and the source  code
211       repository,  can  be  found  at  https://github.com/seccomp/libseccomp.
212       This tool, as well as the libseccomp library, is currently under devel‐
213       opment,  please  report any bugs at the project site or directly to the
214       author.
215

AUTHOR

217       Paul Moore <paul@paul-moore.com>
218