Table of Contents

• Description
  • This is a SIMP module
• Usage
  • Example: Managing Packages
  • Example: Managing Packages but silencing messages
• Reference
• Limitations
• Development
  • Acceptance tests

Description

This module provides capabilities to add resources to the puppet catalog after the initial compilation has been compiled.

WARNING:

This module is not recommended for use outside of the SIMP framework. It was developed for specific policy requirements from the DISA STIG, CIS Benchmark, etc... that require resources to either be installed or removed. In order to not interfere with other manifests that might have legitimately added resources, it first checks if each resource has already been included in the catalog and then adds the appropriate resource to add or remove that resource, as necessary.

WARNING:

See REFERENCE.md for full API details.

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 may be submitted to our bug tracker.

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 are disabled by default and must be explicitly opted into by administrators. Please review the parameters in simp/simp_options for details.

Usage

This module provides classes that help users properly use the underlying native type for processing deferred resources.

Example: Managing Packages

  class { 'deferred_resources::packages':
    'remove'  => ['pkg1', 'pkg2'],
    'install' => ['pkg3', 'pkg4'],
    'mode'    => 'enforcing'
  }

Example: Managing Packages but silencing messages

  class { 'deferred_resources::packages':
    'remove'    => ['pkg1', 'pkg2'],
    'install'   => ['pkg3', 'pkg4'],
    'mode'      => 'enforcing',
    'log_level' => 'debug'
  }

Reference

Please refer to the inline documentation within each source file, or to the module's generated YARD documentation for reference material.

Limitations

SIMP Puppet modules are generally intended for use on Red Hat Enterprise Linux and compatible distributions, such as CentOS. Please see the metadata.json file for the most up-to-date list of supported operating systems, Puppet versions, and module dependencies.

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 install
bundle exec rake beaker:suites

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

Reference

Table of Contents

Classes

• deferred_resources
• deferred_resources::files: This class takes an Array of file resources to remove, and a Hash of file resources to install. After the entire puppet catalog has been com
• deferred_resources::groups: This class takes an Array of group resources to remove, and a Hash of group resources to install. After the entire puppet catalog has been c
• deferred_resources::packages: This class takes two Hashes of packages, one to remove and one to install. After the entire puppet catalog has been compiled, it will proc
• deferred_resources::users: This class takes an Array of user resources to remove, and a Hash of user resources to install. After the entire puppet catalog has been com

Resource types

• deferred_resources: DANGER THIS RESOURCE TYPE DOES THINGS THAT MAY BE CONFUSING MAKE SURE YOU FULLY UNDERSTAND HOW IT WORKS PRIOR TO USING IT *** DANGE

Classes

deferred_resources

The deferred_resources class.

Parameters

The following parameters are available in the deferred_resources class:

• mode
• log_level
• auto_include

mode

Data type: Enum['warning','enforcing']

If set to enforcing then the management classses will take action on the system. If set to 'warning' a message will be printed noting what would have taken place on the system but the catalog will not be updated.

Default value: 'warning'

log_level

Data type: Simplib::PuppetLogLevel

Set the log level for warning messages

Default value: 'info'

auto_include

Data type: Boolean

Default value: true

deferred_resources::files

This class takes an Array of file resources to remove, and a Hash of file resources to install.

After the entire puppet catalog has been compiled, it will process both lists and, for any resource that is not already defined in the catalog, it will take the appropriate action.

An exception will be raised if you list the same file in both lists.

Parameters

The following parameters are available in the deferred_resources::files class:

• remove
• install
• update_existing_resources
• mode
• log_level

remove

Data type: Array[Stdlib::Absolutepath]

A list of files to remove.

Default value: []

install

Data type: Hash[Stdlib::Absolutepath, Hash]

A Hash of files to install.

Default value: {}

update_existing_resources

Data type: Boolean

DANGEROUS - READ CAREFULLY

Update the following attributes of resources that already exist in the catalog if set in the install Hash:

• user
• group
• content
  • Will unset source

If you wish to affect additional parameters on an existing resource in the catalog, you should not use this class and should instead use a Resource Collector.

@see https://puppet.com/docs/puppet/5.3/lang_resources_advanced.html#amending-attributes-with-a-collector

Default value: false

mode

Data type: Enum['warning','enforcing']

@see deferred_resources::mode

Default value: $deferred_resources::mode

log_level

Data type: Simplib::PuppetLogLevel

@see deferred_resources::log_level

Default value: $deferred_resources::log_level

deferred_resources::groups

This class takes an Array of group resources to remove, and a Hash of group resources to install.

After the entire puppet catalog has been compiled, it will process both lists and, for any resource that is not already defined in the catalog, it will take the appropriate action.

An exception will be raised if you list the same group in both lists.

Parameters

The following parameters are available in the deferred_resources::groups class:

• remove
• install
• mode
• log_level

remove

Data type: Array[String[1]]

A list of groups to remove.

Default value: []

install

Data type: Variant[Hash, Array[String[1]]]

A list of groups to install.

• A Hash can be used to add extra attributes for the group, but the ensure attribute will always be set to absent for removal and present for creation.

Default value: {}

mode

Data type: Enum['warning','enforcing']

@see deferred_resources::mode

Default value: $deferred_resources::mode

log_level

Data type: Simplib::PuppetLogLevel

@see deferred_resources::log_level

Default value: $deferred_resources::log_level

deferred_resources::packages

This class takes two Hashes of packages, one to remove and one to install.

After the entire puppet catalog has been compiled, it will process both lists and, for any resource that is not already defined in the catalog, it will take the appropriate action.

An exception will be raised if you list the same package in both lists.

Parameters

The following parameters are available in the deferred_resources::packages class:

• remove
• remove_ensure
• install
• install_ensure
• default_options
• mode
• log_level

remove

Data type: Variant[Hash, Array]

A list of packages to remove.

• A Hash can be used to add extra attributes for the package, but the ensure attribute will be overwritten if it is included.

Default value: {}

remove_ensure

Data type: Enum['absent','purged']

If removing, then this is the state that the packages should have.

• This will be overridden by anything set in options applied to an entry in the $remove Hash.

Default value: 'absent'

install

Data type: Variant[Hash, Array]

A list of packages to install.

• A Hash can be used to add extra attributes for the package, but the ensure attribute will always be set to $package_ensure.

Default value: {}

install_ensure

Data type: Enum['latest','present','installed']

If installing, then this is the state that the packages should have.

• This will be overridden by anything set in options applied to an entry in the $install Hash.

Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' })

default_options

Data type: Hash

A Hash of options to apply to all packages (both remove and install. If ensure is entered in these options it will be overwritten.

• These options may be anything that a Puppet Package resource can normally accept.

Default value: {}

mode

Data type: Enum['warning','enforcing']

@see deferred_resources::mode

Default value: $deferred_resources::mode

log_level

Data type: Simplib::PuppetLogLevel

@see deferred_resources::log_level

Default value: $deferred_resources::log_level

deferred_resources::users

This class takes an Array of user resources to remove, and a Hash of user resources to install.

After the entire puppet catalog has been compiled, it will process both lists and, for any resource that is not already defined in the catalog, it will take the appropriate action.

An exception will be raised if you list the same user in both lists.

Parameters

The following parameters are available in the deferred_resources::users class:

• remove
• install
• mode
• log_level

remove

Data type: Array[String[1]]

A list of users to remove.

Default value: []

install

Data type: Variant[Hash, Array[String[1]]]

A list of users to install.

• A Hash can be used to add extra attributes for the user, but the ensure attribute will always be set to absent for removal and present for creation.

Default value: {}

mode

Data type: Enum['warning','enforcing']

@see deferred_resources::mode

Default value: $deferred_resources::mode

log_level

Data type: Simplib::PuppetLogLevel

@see deferred_resources::log_level

Default value: $deferred_resources::log_level

Resource types

deferred_resources

DANGER

THIS RESOURCE TYPE DOES THINGS THAT MAY BE CONFUSING MAKE SURE YOU FULLY UNDERSTAND HOW IT WORKS PRIOR TO USING IT

DANGER

WARNING: This type is NOT meant to be called directly. Please use the helper classes in the module.

This type will process after the catalog has been compiled but before it is applied. It takes a list of resources and checks for the existence of that resource in the compiled catalog. If the resource has already been defined in the catalog, it prints out a message that an action will not be performed.

If mode is set to warning, instead of adding resources to the catalog, it prints out a list of resources that would have been added.

Parameters

The following parameters are available in the deferred_resources type.

• default_options
• log_level
• mode
• name
• override_existing_attributes
• resource_type
• resources

default_options

A Hash of options to be used for all resources.

Default value: Hash.new

log_level

Valid values: alert, crit, debug, notice, emerg, err, info, warning

Set the message log level for notifications.

Default value: warning

mode

Valid values: enforcing, warning

enforcing => Actually add the resource to the catalog post-compilation warning => Tell the user what would be done but do not actually alter the catalog.

Default value: warning

name

namevar

Unique name for this resource.

override_existing_attributes

A Hash or Array of items that should be updated on existing attributes if they exist.

This is basically a controlled resource collector and absolutely must not be taken lightly when used since it will affect existing resources in your catalog.

If you want to be explicit, use a Resource Collector and do not set this.

If a Hash is passed, each key is the attribute that can be overridden and an optional hash of options can be passed with the following meanings.

• 'invalidates':
  • An Array of entries that this particular parameter invalidates. This means that the items in the list will be set to nil in the overridden resource.

resource_type

Valid values: /.+/

The type of Puppet resource that will be passed in :resources

resources

A Hash or Array of resources to add to the catalog.

• Mon Oct 23 2023 Steven Pritchard steve@sicura.us - 0.8.0

• [puppetsync] Add EL9 support

• Wed Oct 11 2023 Steven Pritchard steve@sicura.us - 0.7.0

• [puppetsync] Updates for Puppet 8
  • These updates may include the following:
    • Update Gemfile
    • Add support for Puppet 8
    • Drop support for Puppet 6
    • Update module dependencies

• Wed Aug 23 2023 Steven Pritchard steve@sicura.us - 0.6.0

• Add AlmaLinux 8 support

• Mon Jun 12 2023 Chris Tessmer chris.tessmer@onyxpoint.com - 0.5.0

• Add RockyLinux 8 support

• Sun Feb 13 2022 Trevor Vaughan trevor@sicura.us - 0.4.1

• Support Amazon Linux 2

• Tue Jun 15 2021 Chris Tessmer chris.tessmer@onyxpoint.com - 0.4.0

• Removed support for Puppet 5
• Ensured support for Puppet 7 in requirements and stdlib

• Thu Dec 17 2020 Chris Tessmer chris.tessmer@onyxpoint.com - 0.3.1

• Removed EL6 support

• Wed Dec 11 2019 Trevor Vaughan tvaughan@onyxpoint.com - 0.3.0

• Add EL8 support

• Thu Oct 31 2019 Liz Nemsick lnemsick.simp@gmail.com - 0.2.3

• Remove 'ftp' and 'games' users and groups when enforcing STIG compliance.
• Support simp/simplib 5.x.

• Fri Aug 02 2019 Robert Vincent pillarsdotnet@gmail.com - 0.2.3

• Support puppetlabs/stdlib 6.x.

• Thu Jul 25 2019 Trevor Vaughan tvaughan@onyxpoint.com - 0.2.2

• Allow users to set 'absent' or 'purged' when removing packages.

• Tue Jul 23 2019 Liz Nemsick lnemsick.simp@gmail.com - 0.2.2

• Remove unnecessary data_provider key in the metadata.json file.

• Mon Jun 17 2019 Trevor Vaughan tvaughan@onyxpoint.com - 0.2.1

• Define deep merge strategies for the Hash and Array class arguments.

• Mon Apr 01 2019 Trevor Vaughan tvaughan@onyxpoint.com - 0.2.0

• Add deferred_resources::users
• Add deferred_resources::groups
• Add deferred_resources::files
• Add 'override_existing_attributes' capability to the 'deferred_resources' native type
• Drop Puppet 4 support
• Add Puppet 6 support

• Thu Mar 07 2019 Liz Nemsick lnemsick.simp@gmail.com - 0.1.1

• Update the upper bound of stdlib to < 6.0.0
• Update a URL in the README.md

• Thu Jul 05 2018 Jeanne Greulich jeannegreulich@onyxpoint.com - 0.1.0

• This module supports adding lists of packages to the catalog after the all the manifests have been compiled. Its purpose is to support policy enforcement for the SIMP project and is not meant for general purpose use.