huschi.net

AUDITD-PLUGINS(5)       System Administration Utilities      AUDITD-PLUGINS(5)
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. Gener-
              ally 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  com-
              pletely 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 capabili-
       ties, 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 han-
       dle 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 sig-
       nificant 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
Red Hat                            Apr 2023                  AUDITD-PLUGINS(5)