NAME¶
seccomp_rule_add, seccomp_rule_add_exact - Add a seccomp filter rule
SYNOPSIS¶
#include <seccomp.h>
typedef void * scmp_filter_ctx;
int SCMP_SYS(syscall_name);
struct scmp_arg_cmp SCMP_CMP(unsigned int arg,
enum scmp_compare op, ...);
struct scmp_arg_cmp SCMP_A0(enum scmp_compare op, ...);
struct scmp_arg_cmp SCMP_A1(enum scmp_compare op, ...);
struct scmp_arg_cmp SCMP_A2(enum scmp_compare op, ...);
struct scmp_arg_cmp SCMP_A3(enum scmp_compare op, ...);
struct scmp_arg_cmp SCMP_A4(enum scmp_compare op, ...);
struct scmp_arg_cmp SCMP_A5(enum scmp_compare op, ...);
int seccomp_rule_add(scmp_filter_ctx ctx, uint32_t action,
int syscall, unsigned int arg_cnt, ...);
int seccomp_rule_add_exact(scmp_filter_ctx ctx, uint32_t action,
int syscall, unsigned int arg_cnt, ...);
int seccomp_rule_add_array(scmp_filter_ctx ctx,
uint32_t action, int syscall,
unsigned int arg_cnt,
const struct scmp_arg_cmp *arg_array);
int seccomp_rule_add_exact_array(scmp_filter_ctx ctx,
uint32_t action, int syscall,
unsigned int arg_cnt,
const struct scmp_arg_cmp *arg_array);
Link with -lseccomp.
DESCRIPTION¶
The
seccomp_rule_add(),
seccomp_rule_add_array(),
seccomp_rule_add_exact(), and
seccomp_rule_add_exact_array()
functions all add a new filter rule to the current seccomp filter. The
seccomp_rule_add() and
seccomp_rule_add_array() functions will
make a "best effort" to add the rule as specified, but may alter the
rule slightly due to architecture specifics, e.g. socket and ipc functions on
x86. The
seccomp_rule_add_exact() and
seccomp_rule_add_exact_array() functions will attempt to add the rule
exactly as specified so it may behave differently on different architectures.
While it does not guarantee a exact filter ruleset,
seccomp_rule_add()
and
seccomp_rule_add_array() do guarantee the same behavior regardless
of the architecture.
The newly added filter rule does not take effect until the entire filter is
loaded into the kernel using
seccomp_load(3).
The
SCMP_CMP() and
SCMP_A{0-5}() macros generate a scmp_arg_cmp
structure for use with the above functions. The
SCMP_CMP() macro allows
the caller to specify an arbitrary argument along with the comparison
operator, mask, and datum values where the
SCMP_A{0-5}() macros are
specific to a certain argument. See the EXAMPLES section below.
While it is possible to specify the
syscall value directly using the
standard
__NR_syscall values, in order to ensure proper operation
across multiple architectures it is highly recommended to use the
SCMP_SYS() macro instead. See the EXAMPLES section below.
The filter context
ctx is the value returned by the call to
seccomp_init(3).
Valid
action values are as follows:
- SCMP_ACT_KILL
- The process will be killed by the kernel when it calls a syscall that does
not match any of the configured seccomp filter rules.
- SCMP_ACT_TRAP
- The process will throw a SIGSYS signal when it calls a syscall that does
not match any of the configured seccomp filter rules.
- SCMP_ACT_ERRNO(uint16_t errno)
- The process will receive a return value of errno when it calls a
syscall that does not match any of the configured seccomp filter
rules.
- SCMP_ACT_TRACE(uint16_t msg_num)
- If the process is being traced and the tracing process specified the
PTRACE_O_TRACESECCOMP option in the call to ptrace(2), the
tracing process will be notified, via PTRACE_EVENT_SECCOMP , and
the value provided in msg_num can be retrieved using the
PTRACE_GETEVENTMSG option.
- SCMP_ACT_ALLOW
- The seccomp filter will have no effect on the process calling the syscall
if it does not match any of the configured seccomp filter rules.
Valid comparison
op values are as follows:
- SCMP_CMP_NE
- Matches when the argument value is not equal to the datum value, example:
SCMP_CMP( arg , SCMP_CMP_NE , datum )
- SCMP_CMP_LT
- Matches when the argument value is less than the datum value, example:
SCMP_CMP( arg , SCMP_CMP_LT , datum )
- SCMP_CMP_LE
- Matches when the argument value is less than or equal to the datum value,
example:
SCMP_CMP( arg , SCMP_CMP_LE , datum )
- SCMP_CMP_EQ
- Matches when the argument value is equal to the datum value, example:
SCMP_CMP( arg , SCMP_CMP_EQ , datum )
- SCMP_CMP_GE
- Matches when the argument value is greater than or equal to the datum
value, example:
SCMP_CMP( arg , SCMP_CMP_GE , datum )
- SCMP_CMP_GT
- Matches when the argument value is greater than the datum value, example:
SCMP_CMP( arg , SCMP_CMP_GT , datum )
- SCMP_CMP_MASKED_EQ
- Matches when the masked argument value is equal to the masked datum value,
example:
SCMP_CMP( arg , SCMP_CMP_MASKED_EQ , mask , datum
)
RETURN VALUE¶
The
seccomp_rule_add(),
seccomp_rule_add_array(),
seccomp_rule_add_exact(), and
seccomp_rule_add_exact_array()
functions return zero on success, negative errno values on failure.
EXAMPLES¶
#include <fcntl.h>
#include <seccomp.h>
#include <sys/stat.h>
#include <sys/types.h>
#define BUF_SIZE 256
int main(int argc, char *argv[])
{
int rc = -1;
scmp_filter_ctx ctx;
struct scmp_arg_cmp arg_cmp[] = { SCMP_A0(SCMP_CMP_EQ, 2) };
int fd;
unsigned char buf[BUF_SIZE];
ctx = seccomp_init(SCMP_ACT_KILL);
if (ctx == NULL)
goto out;
/* ... */
fd = open("file.txt", 0);
/* ... */
rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0);
if (rc < 0)
goto out;
rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(read), 3,
SCMP_A0(SCMP_CMP_EQ, fd),
SCMP_A1(SCMP_CMP_EQ, (scmp_datum_t)buf),
SCMP_A2(SCMP_CMP_LE, BUF_SIZE));
if (rc < 0)
goto out;
rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
SCMP_CMP(0, SCMP_CMP_EQ, fd));
if (rc < 0)
goto out;
rc = seccomp_rule_add_array(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
arg_cmp);
if (rc < 0)
goto out;
rc = seccomp_load(ctx);
if (rc < 0)
goto out;
/* ... */
out:
seccomp_release(ctx);
return -rc;
}
NOTES¶
While the seccomp filter can be generated independent of the kernel, kernel
support is required to load and enforce the seccomp filter generated by
libseccomp.
The libseccomp project site, with more information and the source code
repository, can be found at
http://libseccomp.sf.net. This library is
currently under development, please report any bugs at the project site or
directly to the author.
AUTHOR¶
Paul Moore <paul@paul-moore.com>
SEE ALSO¶
seccomp_syscall_priority(3),
seccomp_load(3)