NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLES | NOTES | AUTHOR | SEE ALSO | COLOPHON

seccomp_rule_add(3)       libseccomp Documentation       seccomp_rule_add(3)

NAME         top

       seccomp_rule_add, seccomp_rule_add_exact - Add a seccomp filter rule

SYNOPSIS         top

       #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         top

       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. internal rewriting
       of multiplexed syscalls, like 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.

       Starting with Linux v4.8, there may be a need to create a rule with a
       syscall value of -1 to allow tracing programs to skip a syscall
       invocation; in order to create a rule with a -1 syscall value it is
       necessary to first set the SCMP_FLTATR_API_TSKIP attribute.  See
       seccomp_attr_set(3) for more information.

       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 thread will be killed by the kernel when it calls a
              syscall that matches the filter rule.

       SCMP_ACT_TRAP
              The thread will throw a SIGSYS signal when it calls a syscall
              that matches the filter rule.

       SCMP_ACT_ERRNO(uint16_t errno)
              The thread will receive a return value of errno when it calls
              a syscall that matches the filter rule.

       SCMP_ACT_TRACE(uint16_t msg_num)
              If the thread 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 thread calling
              the syscall if it matches the filter rule.

       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         top

       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         top

       #include <fcntl.h>
       #include <seccomp.h>
       #include <sys/stat.h>
       #include <sys/types.h>
       #include <stddef.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(exit_group), 0);
            if (rc < 0)
                 goto out;

            rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(exit), 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         top

       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
       https://github.com/seccomp/libseccomp.  This tool, as well as the
       libseccomp library, is currently under development, please report any
       bugs at the project site or directly to the author.

AUTHOR         top

       Paul Moore <paul@paul-moore.com>

SEE ALSO         top

       seccomp_syscall_resolve_name_rewrite(3), seccomp_syscall_priority(3),
       seccomp_load(3), seccomp_attr_set(3)

COLOPHON         top

       This page is part of the libseccomp (high-level API to the Linux
       Kernel's seccomp filter) project.  Information about the project can
       be found at ⟨https://github.com/seccomp/libseccomp⟩.  If you have a
       bug report for this manual page, see 
       ⟨https://groups.google.com/d/forum/libseccomp⟩.  This page was
       obtained from the project's upstream Git repository 
       ⟨https://github.com/seccomp/libseccomp⟩ on 2017-05-03.  If you dis‐
       cover any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

paul@paul-moore.com             25 July 2012             seccomp_rule_add(3)

Pages that refer to this page: seccomp(2)seccomp_load(3)seccomp_syscall_priority(3)seccomp_syscall_resolve_name(3)