Skip to content

Latest commit

 

History

History
377 lines (281 loc) · 13 KB

README.md

File metadata and controls

377 lines (281 loc) · 13 KB
Raw

License CII Best Practices Puppet Forge Puppet Forge Downloads Build Status

Table of Contents

Overview

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

This is a SIMP module

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.

Module Description

You can use this module for the management of all components of auditd including configuration, service management, kernel parameters, and custom rule sets.

By default, a rule set is provided that should meet a reasonable set of operational goals for most environments.

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

Setup

Setup Requirements

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

What Auditd Affects

  • The audit kernel parameter
    • NOTE: This will be applied to all kernels in your standard grub configuration
  • The auditd service
  • The audid configuration in /etc/auditd.conf
  • The auditd rules in /etc/audit/rules.d
  • The audispd configuration in /etc/audisp/audispd.conf
  • The audispd syslog configuration if manage_syslog_plugin is enabled. audit version 2 : /etc/audisp/plugins.d/syslog.conf audit version 3 : /etc/auditd/plugins.d/syslog.conf

Usage

Basic Usage

# Set up auditd with the default settings and SIMP default ruleset
# A message will be printed indicating that you need to reboot for this option
# to take full effect at each Puppet run until you reboot your system.

include 'auditd'

Disabling Auditd

To disable auditd at boot, set the following in hieradata:

auditd::at_boot: false

Enable/Disable sending audit event to syslog:

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.

The setting auditd::syslog, defaults to false or syslog_options::syslog if you include simp_options. If you set auditd::syslog: false, it will not necessarily disable auditd logging to syslog, puppet will just no longer manage the syslog.conf plugin file.

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

Changing Key Values

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'

Understanding Auditd Profiles

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.

Stacking Profiles

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'

The Custom Profile

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:

Override All Other Profiles
auditd::default_audit_profiles:
  - 'custom'
Prepend Before the SIMP Profile
auditd::default_audit_profiles:
  - 'custom'
  - 'simp'
Append After the SIMP and STIG Profiles
auditd::default_audit_profiles:
  - 'simp'
  - 'stig'
  - 'custom'

The Built-in Profile

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.

Disabling All SIMP-provided Profiles

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'
Enabling Sample Rulesets with Built-in Profile

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

Configuring Complete Rulesets with Built-in Profile

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.

Adding One-Off Rules

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.

Adding Regular Filter Rules

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'
  ]
}

Prepend and Drop Everything From a User

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
}

Development

Please read our Contribution Guide

Acceptance tests

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.