1 .TH "seccomp_rule_add" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
2 .\" //////////////////////////////////////////////////////////////////////////
4 .\" //////////////////////////////////////////////////////////////////////////
5 seccomp_rule_add, seccomp_rule_add_exact \- Add a seccomp filter rule
6 .\" //////////////////////////////////////////////////////////////////////////
8 .\" //////////////////////////////////////////////////////////////////////////
10 .B #include <seccomp.h>
12 .B typedef void * scmp_filter_ctx;
14 .BI "int SCMP_SYS(" syscall_name ");"
16 .BI "struct scmp_arg_cmp SCMP_CMP(unsigned int " arg ","
17 .BI " enum scmp_compare " op ", " ... ");"
18 .BI "struct scmp_arg_cmp SCMP_A0(enum scmp_compare " op ", " ... ");"
19 .BI "struct scmp_arg_cmp SCMP_A1(enum scmp_compare " op ", " ... ");"
20 .BI "struct scmp_arg_cmp SCMP_A2(enum scmp_compare " op ", " ... ");"
21 .BI "struct scmp_arg_cmp SCMP_A3(enum scmp_compare " op ", " ... ");"
22 .BI "struct scmp_arg_cmp SCMP_A4(enum scmp_compare " op ", " ... ");"
23 .BI "struct scmp_arg_cmp SCMP_A5(enum scmp_compare " op ", " ... ");"
25 .BI "int seccomp_rule_add(scmp_filter_ctx " ctx ", uint32_t " action ","
26 .BI " int " syscall ", unsigned int " arg_cnt ", " ... ");"
27 .BI "int seccomp_rule_add_exact(scmp_filter_ctx " ctx ", uint32_t " action ","
28 .BI " int " syscall ", unsigned int " arg_cnt ", " ... ");"
30 .BI "int seccomp_rule_add_array(scmp_filter_ctx " ctx ","
31 .BI " uint32_t " action ", int " syscall ","
32 .BI " unsigned int " arg_cnt ","
33 .BI " const struct scmp_arg_cmp *"arg_array ");"
34 .BI "int seccomp_rule_add_exact_array(scmp_filter_ctx " ctx ","
35 .BI " uint32_t " action ", int " syscall ","
36 .BI " unsigned int " arg_cnt ","
37 .BI " const struct scmp_arg_cmp *"arg_array ");"
39 Link with \fI\-lseccomp\fP.
41 .\" //////////////////////////////////////////////////////////////////////////
43 .\" //////////////////////////////////////////////////////////////////////////
46 .BR seccomp_rule_add (),
47 .BR seccomp_rule_add_array (),
48 .BR seccomp_rule_add_exact (),
50 .BR seccomp_rule_add_exact_array ()
51 functions all add a new filter rule to the current seccomp filter. The
52 .BR seccomp_rule_add ()
54 .BR seccomp_rule_add_array ()
55 functions will make a "best effort" to add the rule as specified, but may alter
56 the rule slightly due to architecture specifics, e.g. socket and ipc functions
58 .BR seccomp_rule_add_exact ()
60 .BR seccomp_rule_add_exact_array ()
61 functions will attempt to add the rule exactly as specified so it may behave
62 differently on different architectures. While it does not guarantee a exact
64 .BR seccomp_rule_add ()
66 .BR seccomp_rule_add_array ()
67 do guarantee the same behavior regardless of the architecture.
69 The newly added filter rule does not take effect until the entire filter is
70 loaded into the kernel using
77 macros generate a scmp_arg_cmp structure for use with the above functions. The
79 macro allows the caller to specify an arbitrary argument along with the
80 comparison operator, mask, and datum values where the
82 macros are specific to a certain argument. See the EXAMPLES section below.
84 While it is possible to specify the
86 value directly using the standard
88 values, in order to ensure proper operation across multiple architectures it
89 is highly recommended to use the
91 macro instead. See the EXAMPLES section below.
95 is the value returned by the call to
100 values are as follows:
103 The thread will be killed by the kernel when it calls a syscall that does not
104 match any of the configured seccomp filter rules.
107 The thread will throw a SIGSYS signal when it calls a syscall that does not
108 match any of the configured seccomp filter rules.
110 .B SCMP_ACT_ERRNO(uint16_t errno)
111 The thread will receive a return value of
113 when it calls a syscall that does not match any of the configured seccomp filter
116 .B SCMP_ACT_TRACE(uint16_t msg_num)
117 If the thread is being traced and the tracing process specified the
118 .B PTRACE_O_TRACESECCOMP
119 option in the call to
121 the tracing process will be notified, via
122 .B PTRACE_EVENT_SECCOMP
123 , and the value provided in
125 can be retrieved using the
126 .B PTRACE_GETEVENTMSG
130 The seccomp filter will have no effect on the thread calling the syscall if it
131 does not match any of the configured seccomp filter rules.
135 values are as follows:
138 Matches when the argument value is not equal to the datum value, example:
147 Matches when the argument value is less than the datum value, example:
156 Matches when the argument value is less than or equal to the datum value,
166 Matches when the argument value is equal to the datum value, example:
175 Matches when the argument value is greater than or equal to the datum value,
185 Matches when the argument value is greater than the datum value, example:
193 .B SCMP_CMP_MASKED_EQ
194 Matches when the masked argument value is equal to the masked datum value,
199 , SCMP_CMP_MASKED_EQ ,
204 .\" //////////////////////////////////////////////////////////////////////////
206 .\" //////////////////////////////////////////////////////////////////////////
208 .BR seccomp_rule_add (),
209 .BR seccomp_rule_add_array (),
210 .BR seccomp_rule_add_exact (),
212 .BR seccomp_rule_add_exact_array ()
213 functions return zero on success, negative errno values on failure.
214 .\" //////////////////////////////////////////////////////////////////////////
216 .\" //////////////////////////////////////////////////////////////////////////
220 #include <sys/stat.h>
221 #include <sys/types.h>
225 int main(int argc, char *argv[])
229 struct scmp_arg_cmp arg_cmp[] = { SCMP_A0(SCMP_CMP_EQ, 2) };
231 unsigned char buf[BUF_SIZE];
233 ctx = seccomp_init(SCMP_ACT_KILL);
239 fd = open("file.txt", 0);
243 rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0);
247 rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(read), 3,
248 SCMP_A0(SCMP_CMP_EQ, fd),
249 SCMP_A1(SCMP_CMP_EQ, (scmp_datum_t)buf),
250 SCMP_A2(SCMP_CMP_LE, BUF_SIZE));
254 rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
255 SCMP_CMP(0, SCMP_CMP_EQ, fd));
259 rc = seccomp_rule_add_array(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
264 rc = seccomp_load(ctx);
271 seccomp_release(ctx);
275 .\" //////////////////////////////////////////////////////////////////////////
277 .\" //////////////////////////////////////////////////////////////////////////
279 While the seccomp filter can be generated independent of the kernel, kernel
280 support is required to load and enforce the seccomp filter generated by
283 The libseccomp project site, with more information and the source code
284 repository, can be found at https://github.com/seccomp/libseccomp. This tool,
285 as well as the libseccomp library, is currently under development, please
286 report any bugs at the project site or directly to the author.
287 .\" //////////////////////////////////////////////////////////////////////////
289 .\" //////////////////////////////////////////////////////////////////////////
290 Paul Moore <paul@paul-moore.com>
291 .\" //////////////////////////////////////////////////////////////////////////
293 .\" //////////////////////////////////////////////////////////////////////////
294 .BR seccomp_syscall_priority (3),