NAME

       auditd-plugins - realtime event receivers

DESCRIPTION

       auditd  can multiplex audit events in realtime. It takes audit events and distributes them
       to child programs that want to analyze events in realtime. When the audit daemon  receives
       a  SIGTERM  or SIGHUP, it passes that signal to its child processes so that can reload the
       configuration or terminate.

       The child programs install a configuration file in a plugins directory which  defaults  to
       /etc/audit/plugins.d.  This can be controlled by a auditd.conf config option plugin_dir if
       the admin wished to locate plugins somewhere else. But auditd will install its plugins  in
       the default location.

       The  plugin  directory will be scanned and every plugin that is active will be started. If
       the plugin has a problem and exits, it will be started a maximum of max_restarts times  as
       found in auditd.conf.

       Config  file  names  are  not  allowed to have more than one '.' in the name or it will be
       treated as a backup copy and skipped. Config file options are given one per line  with  an
       equal sign between the keyword and its value. The available options are as follows:

       active The options for this are yes or no.

       direction
              The  option  is dictated by the plugin.  In or out are the only choices. You cannot
              make a plugin operate in a way it wasn't designed just  by  changing  this  option.
              This  option is to give a clue to the event dispatcher about which direction events
              flow. NOTE: inbound events are not supported yet.

       path   This is the absolute path to  the  plugin  executable.  In  the  case  of  internal
              plugins, it would be the name of the plugin.

       type   This  tells  the dispatcher how the plugin wants to be run. There is currently only
              one option, builtin , which is the default setting.

       args   This allows you to pass arguments to the child program. Generally  plugins  do  not
              take  arguments  and have their own config file that instructs them how they should
              be configured. At the moment, there is a limit of 2 args.

       format The valid options for this are binary and string.  Binary passes the  data  exactly
              as  the  audit  event  dispatcher  gets it from the audit daemon. The string option
              tells the dispatcher to completely change the event  into  a  string  suitable  for
              parsing with the audit parsing library. The default value is string.

NOTE

       auditd  has  an  internal  queue  to  hold events for plugins. (See the q_depth setting in
       auditd.conf.) Plugins have to watch for and dequeue events as fast as possible  and  queue
       them  internally  if  they  can't  be  immediately processed. If the plugin is not able to
       dequeue records, the auditd internal queue will get filled. At any time, as root, you  can
       run the following to check auditd's metrics:

       auditctl --signal cont ; sleep 1 ; cat /var/run/auditd.state

       If auditd's internal queue fills, it cannot dequeue any events from the kernel backlog. If
       the kernel's backlog fills, it looks at  the  value  of  backlog_wait_time  to  delay  all
       processes that generate an event to see if there is eventually room to add the event. This
       will likely be noticed as slowing down various processes  on  the  machine.  The  kernel's
       audit subsystem can be checked by running:

       auditctl -s

       When  tuning  the  audit  system's performance, you'd want to check both kernel and auditd
       metrics and adjust accordingly.

NOTES FOR DEVELOPERS

       When the audit daemon starts your plugin, you will be running as root. If you do not  need
       root privileges, you should change uid/gid to lower chances of being a target for exploit.
       If you need to retain capabilities, using libcap-ng is the simplest way.

       Your environment is not going to be clean. You are inheriting many attributes from  auditd
       itself.  You  will  need  to  adjust your signal mask, sigaction, umask, and environmental
       variables. Look at the auditd man page to see  which  signals  auditd  used.  Plugins  are
       expected  to  handle  SIGTERM  and  SIGHUP.  You  will also inherit the resource limits of
       auditd. Note that  some  of  these  resource  limits,  such  as  maximum  number  of  open
       descriptors,  are  controlled  by systemd. You also inherit auditd's nice value. You might
       want to adjust that to be sure to keep up with incoming audit events.

       Auditd will send events to the  plugin  on  it's  stdin.  The  plugin  has  to  keep  this
       descriptor  empty  so  that events don't back up. If you do significant processing of each
       event, you should add an internal queue to your design in order to  keep  events  flowing.
       The  auparse_feed  function  is  the  preferred way to examine whole events if you need to
       analyze the contents of the events.

FILES

       /etc/auditd/auditd.conf /etc/audit/plugins.d

SEE ALSO

       auditd.conf(5), auditd(8), execve(2), auparse_feed(3).

AUTHOR

       Steve Grubb