Index of /~abial/spy/

<pre>
SPY(4)                 FreeBSD Kernel Interfaces Manual                 SPY(4)

NAME
     spy - system call monitor

SYNOPSIS
     kldload spy

DESCRIPTION
     spy provides a means of monitoring and controlling the system-wide use of
     selected system calls.  While user applications like ktrace(1) and
     truss(1) are normally used for providing detailed information about the
     use of system calls by a particular process or proces group, spy can mon-
     itor and restrict the use of particular system calls by all processes.

     The information provided by spy is made available through syslogd(8) dae-
     mon.  spy logs information using LOG_SECURITY facility with LOG_INFO lev-
     el.


     In addition, the arguments to the system call are listed for the follow-
     ing:

           chdir(2),  chmod(2),  execve(2),  link(2),  mkdir(2),  mount(2),
           open(2),  rmdir(2),  setegid(2),  seteuid(2),  setgid(2),
           setpgid(2),  setregid(2),  setreuid(2),  setsid(2),  setuid(2),
           unlink(2) unmount(2)

     The operation of spy is controlled through the sysctl(3) interface.

     There are several options which control the way the syscall is monitored.
     The options can be divided in two categories.

     The first group of options describes what kind of user/group id's will be
     subject to monitoring. Available options are as follows:

     user   monitors syscalls generated by uid!=0 (that is, all processes
            owned by users except for root).

     root   monitors syscalls generated by uid==0 (that is, all processes with
            real uid of root)

     uid=n  monitors syscalls generated by uid==n (that is, all processes with
            real uid equal to n)

     gid=n  monitors syscalls generated by gid==n (that is, all processes with
            real gid equal to n)

     Second group defines how much detailed information will be logged:

     args   provides the information about arguments to a syscall. However,
            it's possible only for the few above mentioned syscalls.

     other  provides any other useful information, which relates to the
            syscall.

     If the syscall being monitored matches the uid/gid criteria, there will
     always be some information logged to the syslog, namely:

     +o   the name of the system call, e.g.: "execve".

     +o   the PID and PPID, together with the process names of each.  PID and
         PPID parts are separated by colon. Each part consists of numeric pro-

         cess ID and process name in paretheses. E.g. "4807(ping):4725(sh)"

     +o   the real and effective UID and GID of the calling process, separated
         by colon. E.g. "1001:20".

     +o   current effective UID and GID, separated by colon. E.g. "0:20".

     +o   an indication of whether the call failed because the system call has
         been disabled.

     WARNING: All possible options are combined using OR operation. Therefore,
     some combinations don't make much sense, like 'user,uid=20' - this one,
     in particular, will report syscalls for all users, which is probably not
     what was intended.

     The options are provided as a part of argument to most of the sysctl(3)
     controls listed below. In most cases they are prepended with the syscall
     name. The separator is a comma.

     The following sysctl variables are available to control the operation of
     the module:

     kern.spy.defopt  (read-write string) The default monitoring options for
                      system calls for which no other options were specifical-
                      ly defined.  Option values are combined with an OR oper-
                      ation to form a mask. The following options are set on
                      startup: user,root,args.

     kern.spy.list    (read-only string) The list of currently monitored sys-
                      tem calls. Each line consists of the syscall name, the
                      number of times it's been intercepted, and the options
                      used to trigger the monitor.

     kld.spy.dump     (read-only struct spy_ent, see <spy.h>) A raw view of
                      the information provided by the kern.spy.list variable.

     kern.spy.add     (write-only string) Add a system call to the list of
                      monitored system calls.  The newly added call will be
                      monitored by the generic handler, unless some other han-
                      dler has been implemented for it. It's possible to also
                      set monitoring options - see the examples below.

     kern.spy.del     (write-only string) Remove a system call from the list
                      of monitored system calls.

     kern.spy.disable
                      (write-only string) Disable the use of a system call by
                      all users matching the categories defined with options
                      (or with default options, if none specified).

                      WARNING: using this feature without understanding the
                      consequences may leave your system in totally unusable
                      state, requiring cold reboot.  Beware!

     kern.spy.enable  (write-only string) Enable the use of a previously dis-
                      abled system call. NOTE: the syscall is still monitored.
                      You have to use kern.spy.del in order to remove it from
                      the list.

EXAMPLES
     Start monitoring the mount(2) syscall, and report its usage for processes
     with real uid=65534 (possibly coming from buggy CGIs) and for root owned
     processes. Report the arguments used:

           sysctl -w kern.spy.add=mount,uid=65534,root,args


     Set default options so that syscalls without any specific options are re-
     ported: for anyone (user or root), with their arguments and with any oth-
     er available information, if possible:

           sysctl -w kern.spy.defopt=user,root,args,other

     Set new options for already monitored syscall:

           sysctl -w kern.spy.set=mount,user,root,args

     Disable the setuid(2) syscall for user 'nobody':

           sysctl -w kern.spy.disable=setuid,uid=65534,args

SEE ALSO
     sysctl(3),  kld(4),  kldload(8),  kldstat(8),  kldunload(8),  sysctl(8)

HISTORY
     The spy interface was first made available in FreeBSD 4.0.

AUTHORS
     spy was developed by Andrzej Bialecki <abial@FreeBSD.org>.

BUGS
     +o   spy fills up the system message buffer with log entries, eventually
         overwriting other useful information that could have been displayed
         by dmesg(1). Fortunately this doesn't apply anymore to 5.0-CURRENT.

     +o   the functionality of spy would be better implemented as ACLs.

     If you have any comments, or if this interface is of any use for you and
     you perhaps want to improve it, please contact the author.

FreeBSD                        February 14, 2000                             3
</pre>