| 1 | .TH "seccomp_rule_add" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation" |
| 2 | .\" ////////////////////////////////////////////////////////////////////////// |
| 3 | .SH NAME |
| 4 | .\" ////////////////////////////////////////////////////////////////////////// |
| 5 | seccomp_rule_add, seccomp_rule_add_exact \- Add a seccomp filter rule |
| 6 | .\" ////////////////////////////////////////////////////////////////////////// |
| 7 | .SH SYNOPSIS |
| 8 | .\" ////////////////////////////////////////////////////////////////////////// |
| 9 | .nf |
| 10 | .B #include <seccomp.h> |
| 11 | .sp |
| 12 | .B typedef void * scmp_filter_ctx; |
| 13 | .sp |
| 14 | .BI "int SCMP_SYS(" syscall_name ");" |
| 15 | .sp |
| 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 ", " ... ");" |
| 24 | .sp |
| 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 ", " ... ");" |
| 29 | .sp |
| 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 ");" |
| 38 | .sp |
| 39 | Link with \fI\-lseccomp\fP. |
| 40 | .fi |
| 41 | .\" ////////////////////////////////////////////////////////////////////////// |
| 42 | .SH DESCRIPTION |
| 43 | .\" ////////////////////////////////////////////////////////////////////////// |
| 44 | .P |
| 45 | The |
| 46 | .BR seccomp_rule_add (), |
| 47 | .BR seccomp_rule_add_array (), |
| 48 | .BR seccomp_rule_add_exact (), |
| 49 | and |
| 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 () |
| 53 | and |
| 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 |
| 57 | on x86. The |
| 58 | .BR seccomp_rule_add_exact () |
| 59 | and |
| 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 |
| 63 | filter ruleset, |
| 64 | .BR seccomp_rule_add () |
| 65 | and |
| 66 | .BR seccomp_rule_add_array () |
| 67 | do guarantee the same behavior regardless of the architecture. |
| 68 | .P |
| 69 | The newly added filter rule does not take effect until the entire filter is |
| 70 | loaded into the kernel using |
| 71 | .BR seccomp_load (3). |
| 72 | .P |
| 73 | The |
| 74 | .BR SCMP_CMP () |
| 75 | and |
| 76 | .BR SCMP_A{0-5} () |
| 77 | macros generate a scmp_arg_cmp structure for use with the above functions. The |
| 78 | .BR SCMP_CMP () |
| 79 | macro allows the caller to specify an arbitrary argument along with the |
| 80 | comparison operator, mask, and datum values where the |
| 81 | .BR SCMP_A{0-5} () |
| 82 | macros are specific to a certain argument. See the EXAMPLES section below. |
| 83 | .P |
| 84 | While it is possible to specify the |
| 85 | .I syscall |
| 86 | value directly using the standard |
| 87 | .B __NR_syscall |
| 88 | values, in order to ensure proper operation across multiple architectures it |
| 89 | is highly recommended to use the |
| 90 | .BR SCMP_SYS () |
| 91 | macro instead. See the EXAMPLES section below. |
| 92 | .P |
| 93 | The filter context |
| 94 | .I ctx |
| 95 | is the value returned by the call to |
| 96 | .BR seccomp_init (3). |
| 97 | .P |
| 98 | Valid |
| 99 | .I action |
| 100 | values are as follows: |
| 101 | .TP |
| 102 | .B SCMP_ACT_KILL |
| 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. |
| 105 | .TP |
| 106 | .B SCMP_ACT_TRAP |
| 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. |
| 109 | .TP |
| 110 | .B SCMP_ACT_ERRNO(uint16_t errno) |
| 111 | The thread will receive a return value of |
| 112 | .I errno |
| 113 | when it calls a syscall that does not match any of the configured seccomp filter |
| 114 | rules. |
| 115 | .TP |
| 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 |
| 120 | .BR ptrace (2), |
| 121 | the tracing process will be notified, via |
| 122 | .B PTRACE_EVENT_SECCOMP |
| 123 | , and the value provided in |
| 124 | .I msg_num |
| 125 | can be retrieved using the |
| 126 | .B PTRACE_GETEVENTMSG |
| 127 | option. |
| 128 | .TP |
| 129 | .B SCMP_ACT_ALLOW |
| 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. |
| 132 | .P |
| 133 | Valid comparison |
| 134 | .I op |
| 135 | values are as follows: |
| 136 | .TP |
| 137 | .B SCMP_CMP_NE |
| 138 | Matches when the argument value is not equal to the datum value, example: |
| 139 | .sp |
| 140 | SCMP_CMP( |
| 141 | .I arg |
| 142 | , SCMP_CMP_NE , |
| 143 | .I datum |
| 144 | ) |
| 145 | .TP |
| 146 | .B SCMP_CMP_LT |
| 147 | Matches when the argument value is less than the datum value, example: |
| 148 | .sp |
| 149 | SCMP_CMP( |
| 150 | .I arg |
| 151 | , SCMP_CMP_LT , |
| 152 | .I datum |
| 153 | ) |
| 154 | .TP |
| 155 | .B SCMP_CMP_LE |
| 156 | Matches when the argument value is less than or equal to the datum value, |
| 157 | example: |
| 158 | .sp |
| 159 | SCMP_CMP( |
| 160 | .I arg |
| 161 | , SCMP_CMP_LE , |
| 162 | .I datum |
| 163 | ) |
| 164 | .TP |
| 165 | .B SCMP_CMP_EQ |
| 166 | Matches when the argument value is equal to the datum value, example: |
| 167 | .sp |
| 168 | SCMP_CMP( |
| 169 | .I arg |
| 170 | , SCMP_CMP_EQ , |
| 171 | .I datum |
| 172 | ) |
| 173 | .TP |
| 174 | .B SCMP_CMP_GE |
| 175 | Matches when the argument value is greater than or equal to the datum value, |
| 176 | example: |
| 177 | .sp |
| 178 | SCMP_CMP( |
| 179 | .I arg |
| 180 | , SCMP_CMP_GE , |
| 181 | .I datum |
| 182 | ) |
| 183 | .TP |
| 184 | .B SCMP_CMP_GT |
| 185 | Matches when the argument value is greater than the datum value, example: |
| 186 | .sp |
| 187 | SCMP_CMP( |
| 188 | .I arg |
| 189 | , SCMP_CMP_GT , |
| 190 | .I datum |
| 191 | ) |
| 192 | .TP |
| 193 | .B SCMP_CMP_MASKED_EQ |
| 194 | Matches when the masked argument value is equal to the masked datum value, |
| 195 | example: |
| 196 | .sp |
| 197 | SCMP_CMP( |
| 198 | .I arg |
| 199 | , SCMP_CMP_MASKED_EQ , |
| 200 | .I mask |
| 201 | , |
| 202 | .I datum |
| 203 | ) |
| 204 | .\" ////////////////////////////////////////////////////////////////////////// |
| 205 | .SH RETURN VALUE |
| 206 | .\" ////////////////////////////////////////////////////////////////////////// |
| 207 | The |
| 208 | .BR seccomp_rule_add (), |
| 209 | .BR seccomp_rule_add_array (), |
| 210 | .BR seccomp_rule_add_exact (), |
| 211 | and |
| 212 | .BR seccomp_rule_add_exact_array () |
| 213 | functions return zero on success, negative errno values on failure. |
| 214 | .\" ////////////////////////////////////////////////////////////////////////// |
| 215 | .SH EXAMPLES |
| 216 | .\" ////////////////////////////////////////////////////////////////////////// |
| 217 | .nf |
| 218 | #include <fcntl.h> |
| 219 | #include <seccomp.h> |
| 220 | #include <sys/stat.h> |
| 221 | #include <sys/types.h> |
| 222 | |
| 223 | #define BUF_SIZE 256 |
| 224 | |
| 225 | int main(int argc, char *argv[]) |
| 226 | { |
| 227 | int rc = \-1; |
| 228 | scmp_filter_ctx ctx; |
| 229 | struct scmp_arg_cmp arg_cmp[] = { SCMP_A0(SCMP_CMP_EQ, 2) }; |
| 230 | int fd; |
| 231 | unsigned char buf[BUF_SIZE]; |
| 232 | |
| 233 | ctx = seccomp_init(SCMP_ACT_KILL); |
| 234 | if (ctx == NULL) |
| 235 | goto out; |
| 236 | |
| 237 | /* ... */ |
| 238 | |
| 239 | fd = open("file.txt", 0); |
| 240 | |
| 241 | /* ... */ |
| 242 | |
| 243 | rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0); |
| 244 | if (rc < 0) |
| 245 | goto out; |
| 246 | |
| 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)); |
| 251 | if (rc < 0) |
| 252 | goto out; |
| 253 | |
| 254 | rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1, |
| 255 | SCMP_CMP(0, SCMP_CMP_EQ, fd)); |
| 256 | if (rc < 0) |
| 257 | goto out; |
| 258 | |
| 259 | rc = seccomp_rule_add_array(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1, |
| 260 | arg_cmp); |
| 261 | if (rc < 0) |
| 262 | goto out; |
| 263 | |
| 264 | rc = seccomp_load(ctx); |
| 265 | if (rc < 0) |
| 266 | goto out; |
| 267 | |
| 268 | /* ... */ |
| 269 | |
| 270 | out: |
| 271 | seccomp_release(ctx); |
| 272 | return \-rc; |
| 273 | } |
| 274 | .fi |
| 275 | .\" ////////////////////////////////////////////////////////////////////////// |
| 276 | .SH NOTES |
| 277 | .\" ////////////////////////////////////////////////////////////////////////// |
| 278 | .P |
| 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 |
| 281 | libseccomp. |
| 282 | .P |
| 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 | .\" ////////////////////////////////////////////////////////////////////////// |
| 288 | .SH AUTHOR |
| 289 | .\" ////////////////////////////////////////////////////////////////////////// |
| 290 | Paul Moore <paul@paul-moore.com> |
| 291 | .\" ////////////////////////////////////////////////////////////////////////// |
| 292 | .SH SEE ALSO |
| 293 | .\" ////////////////////////////////////////////////////////////////////////// |
| 294 | .BR seccomp_syscall_priority (3), |
| 295 | .BR seccomp_load (3) |