• Overview
• Breaking changes in 11.0.0
• This is a SIMP module
• Module Description
• Setup
  • Setup Requirements
  • What Auditd Affects
  • When changes take effect
• Usage
  • Basic Usage
  • Disabling Auditd
  • Changing Key Values
  • Understanding Auditd Profiles
    • Stacking Profiles
    • The Custom Profile
      • Override All Other Profiles
      • Prepend Before the SIMP Profile
      • Append After the SIMP and STIG Profiles
    • The Built-in Profile
      • Disabling All SIMP-provided Profiles
      • Enabling Sample Rulesets with Built-in Profile
      • Configuring Complete Rulesets with Built-in Profile
  • Adding One-Off Rules
    • Adding Regular Filter Rules
    • Prepend and Drop Everything From a User
• Development
  • Acceptance tests

This module manages the Audit daemon, kernel parameters, and related subsystems.

Including this class no longer configures anything. Before 11.0.0, include 'auditd' installed the package, replaced your kernel audit rules, purged /etc/audit/rules.d, rewrote auditd.conf, took ownership of /etc/audit and /var/log/audit, started and enabled the service, and added audit=1 to the kernel command line. It now installs the package and stops there. Every other resource is declared only when a parameter asks for it, and those parameters default to undef, false or [].

If you are a SIMP user, apply the simp:defaults compliance profile and you get the old behavior back. If you are not, set what you want explicitly.

• /etc/audit/audit-stop.rules and the audisp-*.conf files are no longer deleted. The recursive purge of /etc/audit is gone, so rpm -V audit comes back clean.
• /etc/audit keeps the mode the package ships (0750) rather than being tightened to 0700.
• auditd.conf is edited key by key instead of being rendered from a template, so package comments and the keys this module has no opinion about (use_libwrap, tcp_*, transport, krb5_principal, distribute_network, end_of_event_timeout) stay in the file at their packaged values. The effective daemon configuration is unchanged, because those packaged values match the compiled-in defaults the daemon used before. Keys keep their packaged position; a key missing from the file is appended. That matters for verify_email, which auditd only honours if it precedes action_mail_acct. Every supported package ships it in that position, so only a file it was removed from by hand is affected.
• The simp and stig base rules files (50_NN_<profile>_base.rules) are edited rule by rule instead of rendered whole. See How the base rules files are managed. On x86_64 the rules are unchanged. Elsewhere, the STIG audit_chmod rules follow the same arch gate as its other syscall rules, and audit_32bit_operations: true is ignored. A fresh file has no comments; an existing file keeps the ones it has.
• On auditd 3 and later, /etc/audit/plugins.d/syslog.conf is edited key by key instead of being rendered from a template. Only active and args are written, plus path and type when set explicitly; the rest keeps the packaged values, which match what the template wrote. auditd 2's audispd.conf is unchanged.

• A bare include 'auditd' installs the package. Service state, rules, GRUB, auditd.conf and the log directory are left exactly as the package left them.
• auditd::enable is deprecated. true prints a notice and does nothing else; false prints a notice and implies a stopped, disabled service with at_boot => false, but no longer stands the rest of the module down. auditd::default_audit_profile is likewise deprecated in favour of auditd::default_audit_profiles.
• The Array list parameters (auditd::target_selinux_types, stig::suid_sgid_cmds, simp::audit_auditd_cmds_list, the root syscall lists, ...) are deprecated in favour of *_entries Hashes that hold the defaults. The Arrays still apply, and a --entry knockout set in a single Hiera layer becomes absent. A knockout is lost when the Array is set in more than one layer, because the merge consumes it; use the Hash to remove an entry.
• Setting one auditd.conf parameter now changes exactly that one key. The exception is auditd::admin_space_left, which also writes the space_left derived from it unless auditd::space_left is set.
• auditd::space_left defaults to undef rather than auditd::calculate_space_left($admin_space_left). It is still derived from auditd::admin_space_left when that is set, so the two keys are written together; unset, neither is written.
• auditd::config_group no longer defaults to auditd::log_group. The two govern different things -- who may read the audit logs versus who may read the audit configuration -- and are set independently now. Unset, the configuration files fall back to group root.
• The Boolean rule toggles of the simp and stig profiles (audit_chown, audit_suid_sgid, ...) default to undef rather than true or false. undef writes nothing and leaves any existing rule alone, false removes the rule, and true writes it. simp:defaults sets the old values. With none of a profile's toggles set, its base rules file is not written at all, unless auditd::purge_auditd_rules is true; then the file is kept as it is.
• Changing auditd::default_audit_profiles from ['simp'] to ['stig'] without auditd::purge_auditd_rules: true leaves the old 50_00_simp_base.rules on disk. The purge used to remove it for you.
• auditd::buffer_size, auditd::failure_mode, auditd::rate, auditd::backlog_wait_time and auditd::loginuid_immutable are written to /etc/audit/rules.d/puppet_auditd.rules instead of 00_head.rules. For these, augenrules lets the last file read win, and that name sorts after the package's audit.rules, so a set value takes effect without the purge. A file of your own that sorts after puppet_auditd.rules still wins over it. The file is written only when one of these is set or the purge is on.
• 00_head.rules, 05_default_drop.rules, 99_tail.rules and puppet_auditd.rules are edited line by line instead of rendered whole. Each line follows its parameter: unset leaves whatever is in the file, false (or 'absent' for a number) removes it, and a value writes it. A partial compliance profile therefore never reverts what an earlier one applied. This covers the settings above, auditd::ignore_errors, auditd::ignore_failures, auditd::immutable, auditd::target_selinux_types and the auditd::ignore_* drops.
• auditd::immutable defaults to undef rather than false. simp:defaults sets false.
• auditd::target_selinux_types entries must be SELinux type names ([a-z0-9_]+_t).
• auditd::root_audit_level: aggressive or insane with a rule profile in auditd::default_audit_profiles writes -b even with auditd::buffer_size unset: an unset or smaller value is raised to 32788 or 65576. This is the one rule-settings line written without its own parameter. Set auditd::buffer_size: 'absent' to prevent it.
• With auditd::purge_auditd_rules: true and auditd::buffer_size unset, puppet_auditd.rules gets the packaged -b 8192, which the purge removes along with audit.rules. simp:defaults sets -b 16384.
• With auditd::ignore_failures unset, the simp and stig profiles write -c. They watch paths that may not exist, such as /etc/snmp/snmpd.conf, and without -c the kernel stops loading at the first rejected rule and silently drops every rule after it. Set auditd::ignore_failures: false to opt out.
• auditd::config::audisp::syslog::pkg_name is a required String[1] supplied by the module data. Setting it to ~ used to skip the audispd-plugins package; it now fails the catalogue.

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they can be submitted to our JIRA.

This module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:

• When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.
• If used independently, all SIMP-managed security subsystems will be disabled by default and must be explicitly opted into by administrators. Please review simp_options for details.

You can use this module for the management of all components of auditd including configuration, service management, kernel parameters, and custom rule sets. Each of those is opted into separately; see Breaking changes in 11.0.0.

A rule set meeting a reasonable set of operational goals for most environments is available as the simp audit profile, and is what the simp:defaults compliance profile selects. It is not applied unless you ask for it.

The audit kernel parameter may optionally be managed independently of the rest of the module using the ::auditd::config::grub class.

If auditd::syslog is true, you will need to install simp/rsyslog as a dependency.

Only the audit package is installed unconditionally. Everything below happens only when the parameter named beside it is set:

/etc/audit itself is no longer managed at all: the recursive purge that used to run over it is gone.

The rule files this module writes always get owner root, group auditd::config_group (root when unset) and a mode with no access for others. Other files in /etc/audit/rules.d, such as the package's audit.rules or rules an administrator added, are left as they are unless auditd::manage_rules_d_attributes is true. That gives them, and any subdirectories and their contents, the same owner, group and mode without deleting anything, which is what CIS 6.3.4.6 and 6.3.4.7 (EL8) and 6.2.4.6 and 6.2.4.7 (EL9) check. auditd::purge_auditd_rules: true does the same as part of the purge. A run that repairs an attribute refreshes the service like any other configuration change.

Rule files and auditd.conf keys are written to disk as soon as Puppet runs. Whether they reach the running system depends on who owns the service:

• The service is managed (auditd::service_ensure or auditd::service_enable): a change restarts auditd, which reloads auditd.conf and loads the rules.
• auditd::reload_on_change: true: without taking over the service, a change runs auditctl --signal reload (auditd re-reads auditd.conf) and augenrules --load (the kernel loads the rules). Both are skipped while auditd is stopped, so a daemon an administrator stopped stays stopped. A few auditd.conf keys, such as tcp_listen_port, still take effect only on a full restart; see auditd.conf(5).
• Neither: nothing touches the running system. The change takes effect the next time auditd starts. systemctl restart auditd is refused (the unit sets RefuseManualStop=yes); use service auditd restart, or load just the rules with augenrules --load.

If the running rule set is immutable (-e 2, from auditd::immutable), no rule change can load until the host reboots. With auditd::reload_on_change, the module reads that state from the kernel through the auditd_state fact and registers a reboot_notify instead of a load that would change nothing.

This matters for modules that call auditd::rule, such as simp/aide, simp/pki, simp/sssd and simp/pupmod. Their rules are loaded right away only when this module manages the service or auditd::reload_on_change is set. The simp:defaults profile manages the service.

# Installs the audit package. Nothing else: no rules, no service state, no
# auditd.conf edits, no kernel command line change.
include 'auditd'

To get the behavior releases before 11.0.0 gave you, apply the simp:defaults compliance profile, or set the pieces you want yourself:

auditd::default_audit_profiles:
  - simp
auditd::purge_auditd_rules: true
auditd::service_ensure: running
auditd::service_enable: true
auditd::at_boot: true
auditd::log_group: root

With auditd::at_boot: true, a message is printed at each Puppet run indicating that you need to reboot for the kernel parameter to take effect, until you do.

auditd::at_boot controls only the audit=1 kernel parameter. Setting it to false actively removes that parameter from the kernel command line, which is different from leaving it unset -- unset means this module does not touch your boot loader at all.

# Take audit=1 off the kernel command line
auditd::at_boot: false

# Stop and disable the service
auditd::service_ensure: stopped
auditd::service_enable: false

This capability is most useful for forwarding audit records to remote servers as syslog messages, since these records are already persisted locally in audit logs. For most sites, however, using this capability for all audit records can quickly overwhelm host and/or network resources, especially if the messages are forwarded to multiple remote syslog servers or persisted locally. Site-specific, rsyslog actions to implement filtering will likely be required to reduce this message traffic.

auditd::syslog defaults to false; simp:defaults sets true. Setting auditd::syslog: false does not necessarily disable auditd logging to syslog -- Puppet simply stops managing the syslog.conf plugin file.

The deprecated auditd::config::audisp::syslog::rsyslog, which hooks the dispatcher into the SIMP rsyslog module, also defaults to false; simp:defaults sets true.

The settings needed for enabling/disabling sending audit log messages to syslog are shown below.

To enable:

auditd::syslog: true
auditd::config::audisp::syslog::enable: true
auditd::config::audisp::syslog::drop_audit_logs: false
# The setting for drop_audit_logs enabled for backwards compatability
# but should be set to false if you want auditd to log to syslog.

To disable:

auditd::syslog: true
auditd::config::audisp::syslog::enable: false

To override the default values included in the module, you can either include new values for the keys at the time that the classes are declared, or set the values in hieradata:

class { 'auditd':
  ignore_failures => true,
  log_group       => 'root',
  flush           => 'INCREMENTAL'
}

auditd::ignore_failures: true
auditd::log_group: 'root'
auditd::flush: 'INCREMENTAL'

This module supports various configurations both independently and simultaneously to meet varying end user requirements.

NOTE: The default behavior of this module is to ignore any invalid rules and apply as much of the rule set as possible. This is done so that you end up with an effective level of auditing regardless of a simply typo or conflicting rule. Please test your final rule sets to ensure that your system is auditing as expected.

The auditd::default_audit_profiles parameter determines which profiles are included, and in what order the rules are added to the system.

The auditd::default_audit_profiles has a default setting of [ 'simp' ] which applies the optimized SIMP auditing profile which is suitable for meeting most generally available compliance requirements. It does not, however, generally appease the scanning utilities since it optimizes the rules for performance and most scanners cannot handle audit rule optimizations.

There are three other profiles available in the system by default:

• stig => Applies the rules as defined in the latest covered DISA STIG
• custom => Allows users to define their own rules easily via Hiera
• built_in => Allows usage of EL8+ included sample rulesets to configure system

There are a large number of parameters exposed for each profile that are meant to be set via Hiera and you should take a look at the REFERENCE.md file to understand the full capabilities of each profile.

The simp and stig profiles write their rules to /etc/audit/rules.d/50_NN_<profile>_base.rules one line at a time. Each rule is found by its body, the part before -k/-F key=, so:

• A changed key, auditd::uid_min, or root syscall list replaces the rule in place.
• A rule turned on later is appended to the end of the file. Order within the file does not change whether an event is logged, because neither profile writes a never or exclude rule. It can change the key an event is logged under, because the kernel records the key of the first rule that matches.
• A list is a *_entries Hash of entry to its options (such as stig::suid_sgid_cmds_entries or simp::audit_suspicious_apps_entries), merged deep into the module's defaults, so a Hiera layer lists only the entries it changes. { ensure => absent } removes an entry's rule. An entry deleted from the Hash is left in the file. Set the toggle to false to remove every rule it owns.
• A rule body two toggles both write (the STIG lists overlap) is found by body and key. Changing one of those keys adds a new line and leaves the old one.

To get a clean file in the original order, delete the base file and run Puppet again. It rebuilds every enabled rule in the profile's own order.

In some cases, you may want to combine profiles in different orders. This may either be done in order to pass a particular scanning engine or to ensure that items that are not caught by the first profile are caught by the second.

Profiles are included and ordered by passing an Array to the auditd::default_audit_profiles parameter and are added to auditd in the order in which they are defined in the Array.

For example, this (the default) would only add the simp profile:

auditd::default_audit_profiles:
  - 'simp'

Likewise, this would add the stig rules prior to the simp profile:

auditd::default_audit_profiles:
  - 'stig'
  - 'simp'

Users may wish to either completely override the default profiles or prepend/append their own rules to the stack for compliance purposes.

You can easily do this via Hiera as shown in the following example:

auditd::config::audit_profiles::custom::rules:
  - '-w /etc/passwd -wa -k passwd_files'
  - '-w /etc/shadow -wa -k passwd_files'

To activate the custom profile, you will need to set the auditd::default_audit_profiles parameter as shown in the following examples:

auditd::default_audit_profiles:
  - 'custom'

auditd::default_audit_profiles:
  - 'custom'
  - 'simp'

auditd::default_audit_profiles:
  - 'simp'
  - 'stig'
  - 'custom'

Starting with release 3.0.0-17 on EL8 hosts, the audit package includes a number of sample-rules under /usr/share/audit/sample-rules that can be used to configure a system fairly completely. Within these rules are sets for STIG, OSPP, etc. that can simply be moved to /etc/audit/rules.d and compiled with augenrules to configure a system.

Most likely, if using the sample rulesets from the built-in profile, you will want to disable included SIMP profiles (not necessary, but may include overlapping rules if not). To do this:

auditd::default_audit_profiles:
  - 'built_in'

To enable specific sample rulesets, simply include them in the built-in profile parameter:

auditd::config::audit_profiles::built_in::rulesets:
  - 'base-config'
  - 'stig'
  - 'finalize'

where the ruleset names are found via the custom fact auditd_sample_rulesets

If you are only planning to use the built_in profile and the included sample rulesets to configure the system, it will be worth noting that profile-specific sample files include configuration information within comments in the files as well.

As an example, the STIG rules sample file will note that it relies on base-config and finalize rulesets to be feature-complete. Other rulesets will contain similar information.

Rules are alphanumerically ordered based on file-system globbing. It is recommended that users use the auditd::rule defined type for adding rules.

Other options are available with auditd::rule but these are the most commonly used.

On its own, auditd::rule writes only the rule file. The preamble that augenrules loads ahead of the rules comes from the audit package's own rules.d/audit.rules. auditd::buffer_size, auditd::failure_mode, auditd::rate, auditd::backlog_wait_time and auditd::loginuid_immutable take effect on their own, from puppet_auditd.rules. auditd::ignore_errors, auditd::ignore_failures and auditd::immutable are managed only once this module is asked to manage the directory, with a profile or auditd::purge_auditd_rules: true; see the breaking changes above.

auditd::rule { 'failed_file_creation':
  content => '-a always,exit -F arch=b64 -S creat -F exit=-EACCES -k failed_file_creation'
}

auditd::rule { 'passwd_file_watches':
  content => [
    '-w /etc/passwd -wa -k passwd_files',
    '-w /etc/shadow -wa -k passwd_files'
  ]
}

This will make your rule land in the 00 set of rules.

auditd::rule { 'pre_drop_user_5000':
  content => '-a exit,never -F auid=5000',
  prepend => true
}

Please read our Contribution Guide

This module includes Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests use Vagrant with VirtualBox as a back-end; Vagrant and VirtualBox must both be installed to run these tests without modification. To execute the tests run the following:

bundle exec rake beaker:suites

Some environment variables may be useful:

BEAKER_debug=true
BEAKER_provision=no
BEAKER_destroy=no
BEAKER_use_fixtures_dir_for_modules=yes
BEAKER_fips=yes

• BEAKER_debug: show the commands being run on the STU and their output.
• BEAKER_destroy=no: prevent the machine destruction after the tests finish so you can inspect the state.
• BEAKER_provision=no: prevent the machine from being recreated. This can save a lot of time while you're writing the tests.
• BEAKER_use_fixtures_dir_for_modules=yes: cause all module dependencies to be loaded from the spec/fixtures/modules directory, based on the contents of .fixtures.yml. The contents of this directory are usually populated by bundle exec rake spec_prep. This can be used to run acceptance tests to run on isolated networks.
• BEAKER_fips=yes: enable FIPS-mode on the virtual instances. This can take a very long time, because it must enable FIPS in the kernel command-line, rebuild the initramfs, then reboot.

Please refer to the SIMP Beaker Helpers documentation for more information.