Provided by: libseccomp-dev_2.2.3-3ubuntu3_i386 bug

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  thread 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 thread 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  thread 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 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 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  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

       Paul Moore <paul@paul-moore.com>

SEE ALSO

       seccomp_syscall_priority(3), seccomp_load(3)