Table of Contents

• Description
  • This is a SIMP module
• Setup
  • Setup Requirements
  • Beginning with hirs_provisioner
• Usage
• Reference
• Limitations
• Development
  • Acceptance tests

+---------------------------------------------------------------+
| WARNING: This is currently an **EXPERIMENTAL** module things  |
| may change drastically, and in breaking ways, without notice! |
+---------------------------------------------------------------+

Description

This module manages Host Integrity at Runtime and Start-up (HIRS) provisioning. It installs and configures the necessary packages and components to register the system with an Attestation Certificate Authority, which can ensure Trusted Computing Group based Supply Chain Validation of systems.

See REFERENCE.md for more 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.

Setup

Setup Requirements

In order to utilize the HIRS Provisioner module, the target system must have an enabled TPM device and an ACA must be configured and accessible for the the system to receive a certificate and register. If the ACA is hosted on a remote system, the fully qualified domain name of the ACA system should be specified in Hiera. The SIMP TPM or TPM2 modules can be used to setup and enable the TPM devices.

Beginning with hirs_provisioner

Simply include hirs_provisioner.

Usage

If the ACA is hosted on a remote system, it is necessary to specify the fully qualified domain name of that system in Hiera, by adding the following:

---
hirs_provisioner::config::aca_fqdn: fqdn.of.the.aca

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

Reference

Table of Contents

Classes

• hirs_provisioner: Installs HIRS_Provisioner RPM and configures and registers with HIRS ACA
• hirs_provisioner::config: Called from hirs_provisioner for service config
• hirs_provisioner::install: Called from hirs_provisioner for install

Classes

hirs_provisioner

Installs HIRS_Provisioner RPM and configures and registers with HIRS ACA

Parameters

The following parameters are available in the hirs_provisioner class:

• enable
• package_ensure
• tpm_1_2_packages
• tpm_2_0_packages

enable

Data type: Boolean

This module will install and mangage HIRS unless false

Default value: true

package_ensure

Data type: String[1]

The default ensure parameter for packages.

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

tpm_1_2_packages

Data type: Hash[String[1], Optional[Hash]]

A hash of packages needed for HIRS with TPM 1.2.

• NOTE: Setting this will override the default package list
• The ensure value can be set in the hash of each package, like the example below:

Example: Override packages

{ 'HIRS_Provisioner' => { 'ensure' => '3.14.3' } }

Default value: { 'HIRS_Provisioner_TPM_1_2' => {} }

tpm_2_0_packages

Data type: Hash[String[1], Optional[Hash]]

A hash of packages needed for HIRS with TPM 2.0.

Default value: { 'HIRS_Provisioner_TPM_2_0' => {} }

hirs_provisioner::config

Called from hirs_provisioner for service config

Parameters

The following parameters are available in the hirs_provisioner::config class:

• aca_fqdn
• aca_port
• broker_port
• portal_port

aca_fqdn

Data type: Simplib::Hostname

The fully qualified domain name of the Attestation Certificate Authority (ACA). This will also be used for the Broker and Portal FQDNs.

Default value: 'localhost'

aca_port

Data type: Simplib::Port

The configured listening port for the ACA.

Default value: 8443

broker_port

Data type: Simplib::Port

The configured broker listening port for the ACA.

Default value: 61616

portal_port

Data type: Simplib::Port

The configured portal listening port for the ACA.

Default value: 8443

hirs_provisioner::install

Called from hirs_provisioner for install

• Wed Oct 11 2023 Steven Pritchard steve@sicura.us - 0.4.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

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

• Add RockyLinux 8 support

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

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

• Tue Jun 08 2021 Trevor Vaughan tvaughan@onyxpoint.com - 0.1.5

• Disabled the TPM 1.2 tests due to upstream ACA issues
• Worked around a bug in the ACA for the tests
• Added java installation to the module since it is a required dependency
• Bumped the puppet and puppetlabs/stdlib supported versions

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

• Removed EL6 support

• Thu Jul 23 2020 Jeanne Greulich jeanne.greulich@onyxpoint.com - 0.1.4-0

• update the upper bound of simplib for SIMP 6.5 release

• Mon Mar 02 2020 Jeanne Greulichjeanne.greulich@onyxpoint.com - 0.1.3

• Updated tests to use tpm2 simulator package from download.simp-project.
• HIRS tpm provisioner software does not run on EL8 yet.

• Wed Jul 03 2019 Trevor Vaughan tvaughan@onyxpoint.com - 0.1.2

• Updated README.md
• Added REFERENCE.md

• Fri Jun 14 2019 Michael Morrone michael.morrone@onyxpoint.com - 0.1.1

• Removed the HIRS package dependency list that was in common.yaml, as the HIRS RPM now appropriately specifies its dependencies.
• Removed the softlink in the install manifest, because it is no longer needed with the newer HIRS package.
• Updated the upper bound of puppet and stdlib to < 7.0.0
• Updated RPMs for installation and testing
• Updated Travis and GitLab Test matrices

• Fri Mar 08 2019 Liz Nemsick lnemsick.simp@gmail.com - 0.1.0

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

• Fri Dec 21 2018 Michael Morrone michael.morrone@onyxpoint.com - 0.1.0

• Initial commit.
• Install HIRS Provisioner and check-in with Attestation Certificate Authority.