1seccomp_rule_add(3) libseccomp Documentation seccomp_rule_add(3)
2
3
4
6 seccomp_rule_add, seccomp_rule_add_exact - Add a seccomp filter rule
7
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
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
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
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
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
266 Paul Moore <paul@paul-moore.com>
267
269 seccomp_syscall_resolve_name_rewrite(3), seccomp_syscall_priority(3),
270 seccomp_load(3), seccomp_attr_set(3)
271
272
273
274paul@paul-moore.com 17 February 2019 seccomp_rule_add(3)