SYSTRACE(1)             FreeBSD General Commands Manual            SYSTRACE(1)

NNAAMMEE
     ssyyssttrraaccee - generates and enforces system call policies

SSYYNNOOPPSSIISS
     ssyyssttrraaccee [--aaAAiittUU] [--gg _g_u_i] [--ff _f_i_l_e] [--pp _p_i_d] _c_o_m_m_a_n_d _._._.

DDEESSCCRRIIPPTTIIOONN
     The ssyyssttrraaccee utility enforces system call policies for applications by
     constraining the application's access to the system.  The policy is gen-
     erated interactively.  Operations not covered by the policy raise an
     alarm and allow an user to refine the currently configured policy.

     The options are as follows:

     --aa       Enables automatic enforcement of configured policies.  An opera-
              tion not covered by policy is denied and logged via syslog(3).

     --AA       Automatically generate a policy that allows every operation the
              application executes.  The created policy functions as a base
              that can be refined.

     --ii       Inherits the policy of the first executed binary to all chil-
              dren.

     --tt       Uses text mode to ask for interactive policy generation.

     --UU       Ignore user configured policies and use only global system poli-
              cies.

     --gg _g_u_i   Specifies an alternative location for the notification user
              interface.

     --ff _f_i_l_e  The policies specified in _f_i_l_e are added to the policies that
              ssyyssttrraaccee knows about.

     --pp _p_i_d   Specifies the pid of a process that ssyyssttrraaccee should attach to.
              The full path name of the corresponding binary has to be speci-
              fied as _c_o_m_m_a_n_d.

PPOOLLIICCYY
     The policy is specified via the following grammar:

        filter = expression "then" action errorcode
        expression = symbol | "not" expression | "(" expression ")" |
            expression "and" expression | expression "or" expression
        symbol = string typeoff "match" cmdstring |
            string typeoff "eq" cmdstring | string typeoff "neq" cmdstring |
            string typeoff "sub" cmdstring | string typeoff "nsub" cmdstring |
            string typeoff "inpath" cmdstring | "true"
        typeoff = /* empty */ | "[" number "]"
        action = "permit" | "deny"
        errorcode = /* empty */ | "[" string "]"

     The _c_m_d_s_t_r_i_n_g is an arbitrary string enclosed with quotation marks.  The
     _e_r_r_o_r_c_o_d_e is used to return an errno(2) value to the system call when
     using a _d_e_n_y action.  The value ``inherit'' has a special meaning when
     used with a _p_e_r_m_i_t rule for the _e_x_e_c_v_e system call.  In that case, the
     current policy is inherited for the new binary.

     The filter operations have the following meaning:

        match    Evaluates to true if file name globbing according to
                 fnmatch(3) succeeds.

        eq       Evaluates to true if the system call argument matches
                 _c_m_d_s_t_r_i_n_g exactly.

        neq      This is the logical negation of _e_q.

        sub      Performs a substring match on the system call argument.

        nsub     This is the logical negation of _s_u_b.

        inpath   Evaluates to true if the system call argument is a subpath of
                 _c_m_d_s_t_r_i_n_g.

     Policy entries may contain an appended predicate.  Predicates have the
     following format:

        ", if" {"user", "group"} {"=", "!="} string

     A rule is added to the configured policy only if its predicate evaluates
     to true.

EEXXAAMMPPLLEESS
     An excerpt from a sample ls(1) policy might look as follows:

        Policy: /bin/ls, Emulation: native
        [...]
                native-open: filename eq "$HOME" and oflags sub "ro" then permit
                native-fchdir: permit
        [...]
                native-open: filename eq "/tmp" and oflags sub "ro" then permit
                native-stat: permit
                native-open: filename match "$HOME/*" and oflags sub "ro" then permit
                native-open: filename eq "/etc/pwd.db" and oflags sub "ro" then permit
        [...]
                native-open: filename eq "/etc" then deny[eperm], if group != wheel

FFIILLEESS
     /dev/systrace    systrace device
     /etc/systrace    global systrace policies
     $HOME/.systrace  user specified policies

SSEEEE AALLSSOO
     systrace(4)

BBUUGGSS
     Applications that use clone()-like system calls to share the complete
     address space between processes may be able to replace system call argu-
     ments after they have been evaluated by ssyyssttrraaccee and escape policy
     enforcement.

AAUUTTHHOORRSS
     The ssyyssttrraaccee utility has been developed by Niels Provos.

FreeBSD 4.5                      June 3, 2002                      FreeBSD 4.5
