Puppet Class: auditd

Defined in:
manifests/init.pp

Summary

Configure the audit daemon for use with a specified audit profile.

Overview

Any variable that is not described here can be found in auditd.conf(5) and auditctl(8).

Parameters:

  • enable (Boolean) (defaults to: true)

    If true, enable auditing.

  • default_audit_profile (Optional[Variant[Enum['simp'],Boolean]]) (defaults to: undef)

    Deprecated by ‘$default_audit_profiles`

  • default_audit_profiles (Array[Auditd::AuditProfile]) (defaults to: [ 'simp' ])

    The built-in audit profile(s) to use to provide global audit rule configuration (error handling, buffer size, etc.) and a base set of audit rules.

    • When more than one profile is specified, the profile rules are effectively concatenated in the order the profiles are listed.

    • To add rules to the base set, use ‘auditd::rule`.

    • To manage the audit rules, yourself, set this parameter to ‘[]`.

    • @see ‘auditd::config::audit_profiles` for more details about this configuration.

  • audit_auditd_config (Boolean) (defaults to: true)

    Set up an audit rule to audit the ‘auditd` configuration files.

  • lname (String) (defaults to: $facts['networking']['fqdn'])

    An alias for the “name“ variable in the configuration file. This is used since “$name“ is a reserved keyword in Puppet.

  • ignore_anonymous (Boolean) (defaults to: true)

    For built-in audit profiles, whether to drop anonymous and daemon events, i.e., events for which “auid“ is ‘-1’ (aka ‘unset’). Audit records from these events are prolific but not useful.

  • ignore_crond (Boolean) (defaults to: true)

    For built-in audit profiles, whether to drop events related to cron jobs. ‘cron` creates a lot of audit events that are not usually useful.

  • ignore_time_daemons (Boolean) (defaults to: true)

    Ignore time modifications by time daemons that are running on the system since this is valid activity.

  • ignore_crypto_key_user (Boolean) (defaults to: true)

    Ignore CRYPTO_KEY_USER logs since these are generally noise.

  • ignore_errors (Boolean) (defaults to: true)

    Whether to set the ‘auditctl` ’-i’ option

  • ignore_failures (Boolean) (defaults to: true)

    Whether to set the ‘auditctl` ’-c’ option

  • ignore_system_services (Boolean) (defaults to: true)

    For built-in audit profiles, whether to ignore system service events, i.e., events for which the “auid“ is set but is less than the minimum UID for human users on the system. In most security guides, this filter is attached to every system call rule. So, by implementing the filter in an upfront drop rule, this feature provides optimization of that filtering.

  • action_mail_acct (String[1]) (defaults to: 'root')
  • admin_space_left (Variant[Integer[0],Pattern['^\d+%$']]) (defaults to: 50)
  • admin_space_left_action (Auditd::SpaceLeftAction) (defaults to: 'rotate')
  • at_boot (Boolean) (defaults to: true)

    If true, modify the Grub settings to enable auditing at boot time.

  • buffer_size (Integer[0]) (defaults to: 16384)

    Value of the ‘auditctl` ’-b’ option

  • backlog_wait_time (Optional[Integer[1,600000]]) (defaults to: undef)
  • disk_error_action (Auditd::DiskErrorAction) (defaults to: 'syslog')
  • disk_full_action (Auditd::DiskFullAction) (defaults to: 'rotate')
  • disp_qos (Enum['lossy','lossless']) (defaults to: 'lossy')

    ‘auditd` version 2 only

  • dispatcher (Stdlib::Absolutepath) (defaults to: '/sbin/audispd')

    ‘auditd` version 2 only

  • failure_mode (Integer[0]) (defaults to: 1)

    Value of the ‘auditctl` ’-f’ option

  • flush (Auditd::Flush) (defaults to: 'incremental')
  • freq (Integer[0]) (defaults to: 20)
  • immutable (Boolean) (defaults to: false)

    Whether or not to make the configuration immutable when using built-in audit profiles. Be aware that, should you choose to make the configuration immutable, you will not be able to change your audit rules without a reboot.

  • log_file (Stdlib::Absolutepath) (defaults to: '/var/log/audit/audit.log')
  • local_events (Optional[Boolean]) (defaults to: undef)

    ‘auditd` version 3 only

  • log_format (Auditd::LogFormat) (defaults to: 'raw')

    The output log format

    • ‘NOLOG’ is deprecated as of auditd 2.5.2

    • ‘ENRICHED’ is only available in auditd >= 2.6.0

  • log_group (String) (defaults to: 'root')
  • loginuid_immutable (Boolean) (defaults to: true)

    Sets the –loginuid-immutable option

    • This has been noted to potentially cause issues with some types of containers but a concrete explanation of what types has not yet been found.

  • max_log_file (Integer[0]) (defaults to: 24)
  • max_log_file_action (Auditd::MaxLogFileAction) (defaults to: 'rotate')
  • max_restarts (Optional[Integer[1]]) (defaults to: undef)

    sets the number of times a plugin will be restart.

  • name_format (Auditd::NameFormat) (defaults to: 'user')
  • num_logs (Integer[0]) (defaults to: 5)
  • overflow_action (Optional[Auditd::Overflowaction]) (defaults to: undef)

    sets the overflow action.

  • package_name (String[1]) (defaults to: 'audit')

    The name of the auditd package.

  • package_ensure (Simplib::PackageEnsure) (defaults to: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' }))
  • plugin_dir (Stdlib::Absolutepath)

    sets the directory for the plugin configuration files.

  • priority_boost (Integer[0]) (defaults to: 3)
  • q_depth (Integer[0]) (defaults to: 400)

    how big to make the internal queue of the audit event dispatcher

  • rate (Integer[0]) (defaults to: 0)

    Value of the ‘auditctl` ’-r’ option

  • root_audit_level (Auditd::RootAuditLevel) (defaults to: 'basic')

    What level of auditing should be used for su-root activity in built-in audit profiles that provide su-root rules. Be aware that setting this to anything besides ‘basic’ may overwhelm your system and/or log server. Options can be, ‘basic’, ‘aggressive’, ‘insane’. For the ‘simp’ audit profile, these options are as follows:

    - Basic: Safe syscall rules, should not follow program execution outside
      of the base app
    - Aggressive: Adds syscall rules for execve, rmdir and variants of rename
      and unlink
    - Insane: Adds syscall rules for write, creat and variants of chown,
      fork, link and mkdir
    
  • service_name (String[1]) (defaults to: 'auditd')

    The name of the auditd service.

  • space_left (Variant[Integer[0],Pattern['^\d+%$']]) (defaults to: auditd::calculate_space_left($admin_space_left))

    Must be larger than ‘$admin_space_left`.

    • If ‘$admin_space_left` is an `Integer`, will be set to `30 + $admin_space_left`

    • If ‘$admin_space_left` is a percentage (auditd >= 2.8.5), will be set to `1% + $admin_space_left`

  • space_left_action (Auditd::SpaceLeftAction) (defaults to: 'syslog')
  • syslog (Boolean) (defaults to: simplib::lookup('simp_options::syslog', {'default_value' => false }))

    If true, manage the settings for the syslog plugin It was left defaulted to simp_options::syslog value for backwards compatability. This does not activate/deactivate the plugin. That setting is in the auditd::config::audisp::syslog::enable setting. If syslog is set to true, by default it will enable the syslog plugin in order to be backwards compatable. If you want to ensure the plugin is disabled, set auditd::config::audisp::syslog::enable to false. If this is set to false the plugin settings are not managed by puppet.

  • target_selinux_types (Optional[Array[Pattern['^.*_t$']]]) (defaults to: undef)

    A list of SELinux types to target, all others will be dropped

    For systems that require all users and processes to be in a confined namespace, you may find that only auditing unconfined types will be sufficient since all other invalid system actions are already audited.

  • uid_min (Integer[0]) (defaults to: Integer(pick(fact('uid_min'), 1000)))

    The minimum UID for human users on the system. For built-in audit profiles when ‘$ignore_system_services` is true, any audit events generated by users below this number will be ignored, unless a corresponding rule is inserted before the UID-limiting rule in the rules list. When using `auditd::rule`, you can create such a rule by setting the `absolute` parameter to be ’first’.

  • verify_email (Optional[Boolean]) (defaults to: undef)

    auditd version 3 only

  • write_logs (Boolean) (defaults to: $log_format ? { /^(?i:nolog)$/ => false, default => true)

    Whether or not to write logs to disk.

    • The ‘NOLOG` option on `log_format` has been deprecated in newer versions of `auditd` so this attempts to do “the right thing” when `log_format` is set to `NOLOG` for legacy support.

  • purge_auditd_rules (Boolean) (defaults to: true)

    Whether or not to purge existing auditd rules under /etc/audit/rules.d

See Also:

  • puppet_classes::auditdauditd.conf(5)
  • auditctl(8)

Author:



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
# File 'manifests/init.pp', line 206

class auditd (
  # Control Parameters
  Boolean                                 $enable                   = true,
  Optional[Variant[Enum['simp'],Boolean]] $default_audit_profile    = undef,
  Array[Auditd::AuditProfile]             $default_audit_profiles   = [ 'simp' ],
  Boolean                                 $audit_auditd_config      = true,
  String                                  $lname                    = $facts['networking']['fqdn'],

  # Rule Tweaks
  Boolean                                 $ignore_anonymous         = true,
  Boolean                                 $ignore_crond             = true,
  Boolean                                 $ignore_time_daemons      = true,
  Boolean                                 $ignore_crypto_key_user   = true,
  Boolean                                 $ignore_errors            = true,
  Boolean                                 $ignore_failures          = true,
  Boolean                                 $ignore_system_services   = true,

  # Configuration Parameters
  String[1]                               $action_mail_acct         = 'root',
  Variant[Integer[0],Pattern['^\d+%$']]   $admin_space_left         = 50,
  Auditd::SpaceLeftAction                 $admin_space_left_action  = 'rotate',
  Boolean                                 $at_boot                  = true,
  Integer[0]                              $buffer_size              = 16384,
  Optional[Integer[1,600000]]             $backlog_wait_time        = undef,
  Auditd::DiskErrorAction                 $disk_error_action        = 'syslog',
  Auditd::DiskFullAction                  $disk_full_action         = 'rotate',
  Enum['lossy','lossless']                $disp_qos                 = 'lossy',
  Stdlib::Absolutepath                    $dispatcher               = '/sbin/audispd',
  Integer[0]                              $failure_mode             = 1,
  Auditd::Flush                           $flush                    = 'incremental',
  Integer[0]                              $freq                     = 20,
  Boolean                                 $immutable                = false,
  Optional[Boolean]                       $local_events             = undef,
  Stdlib::Absolutepath                    $log_file                 = '/var/log/audit/audit.log',
  Auditd::LogFormat                       $log_format               = 'raw',
  String                                  $log_group                = 'root',
  Boolean                                 $loginuid_immutable       = true,
  Integer[0]                              $max_log_file             = 24,
  Auditd::MaxLogFileAction                $max_log_file_action      = 'rotate',
  Optional[Integer[1]]                    $max_restarts             = undef, #data in module, #auditd version 3.0 and later
  Auditd::NameFormat                      $name_format              = 'user',
  Integer[0]                              $num_logs                 = 5,
  Optional[Auditd::Overflowaction]        $overflow_action          = undef, # data in module
  String[1]                               $package_name             = 'audit',
  Simplib::PackageEnsure                  $package_ensure           = simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' }),
  Stdlib::Absolutepath                    $plugin_dir,              # data in module
  Integer[0]                              $priority_boost           = 3,
  Integer[0]                              $q_depth                  = 400,
  Integer[0]                              $rate                     = 0,
  Auditd::RootAuditLevel                  $root_audit_level         = 'basic',
  String[1]                               $service_name             = 'auditd',
  Variant[Integer[0],Pattern['^\d+%$']]   $space_left               = auditd::calculate_space_left($admin_space_left),
  Auditd::SpaceLeftAction                 $space_left_action        = 'syslog',
  Boolean                                 $syslog                   = simplib::lookup('simp_options::syslog', {'default_value' => false }),   # CCE-26933-2
  Optional[Array[Pattern['^.*_t$']]]      $target_selinux_types     = undef,
  Integer[0]                              $uid_min                  = Integer(pick(fact('uid_min'), 1000)),
  Optional[Boolean]                       $verify_email             = undef,
  Boolean                                 $write_logs               = $log_format ? { /^(?i:nolog)$/ => false, default => true },
  Boolean                                 $purge_auditd_rules       = true,
) {

  include 'auditd::service'

  if $enable {
    simplib::assert_metadata($module_name)

    auditd::validate_init_params()

    if $facts['auditd_version'] and ( versioncmp($facts['auditd_version'], '2.6.0') < 0 ) {
      if ( versioncmp($facts['auditd_version'], '2.5.2') < 0 ) {
        unless $write_logs {
          $_log_format = 'NOLOG'
        }
      }
      else {
        # Versions > 2.5.2 do not handle NOLOG
        if $log_format == 'NOLOG' {
          $_log_format = 'raw'
        }

        $_write_logs = $write_logs
      }

      unless defined('$_log_format') {
        # ENRICHED was not added until 2.6.0
        if $log_format == 'ENRICHED' {
          $_log_format = 'raw'
        }
        else {
          $_log_format = $log_format
        }
      }
    }
    else {
      # Versions >= 2.6.0 do not support NOLOG
      if $log_format == 'NOLOG' {
        $_log_format = 'raw'
      }
      else {
        $_log_format = $log_format
      }

      $_write_logs = $write_logs
    }

    # This is done here so that the kernel option can be properly removed if
    # auditing is to be disabled on the system.
    if $at_boot {
      $_grub_enable = true
    }
    else {
      $_grub_enable = false
    }

    include 'auditd::install'
    include 'auditd::config'

    Class['auditd::install']
    -> Class['auditd::config']
    ~> Class['auditd::service']
    -> Class['auditd']

    if fact('grub_version') {
      Class['auditd::install'] -> Class['::auditd::config::grub']
    }

  }
  else {
    $_grub_enable = false
  }

  # This is done deliberately so that you cannot conflict a direct call to
  # auditd::config::grub with an include somewhere else. auditd::config::grub
  # would normally be a private class but may be used independently if
  # necessary.
  if fact('grub_version') {
    class { 'auditd::config::grub': enable => $_grub_enable }
  }
}