Security Compliance Management (formerly Comply)

Puppet Security Compliance Management (SCM) is a tool that assesses the infrastructure you manage with Puppet Enterprise against CIS Benchmarks — the best practices for securely configuring systems from the Center for Internet Security (CIS).

Installing

This Module is required by the SCM product and should only be used as per the complete install instructions

Configuration

By default, SCM will install various dependencies required in order for the module and the CIS Assessor to function. Should you wish to configure what SCM manages, see the reference for more details.

Obtaining the Product

Please get in touch with a Puppet Representative

Running Acceptance Tests

bundle exec rake litmus:tear_down;
bundle exec rake litmus:provision_list[release_checks]; #reduce hosts in provision.yaml if required
bundle exec rake litmus:install_agent[puppet7];
bundle exec rake litmus:install_module;
bundle exec rake litmus:acceptance:parallel; #bundle exec rake litmus:acceptance:rid-fraternity.delivery.puppetlabs.net

Reference

Table of Contents

Classes

• comply: Installs the CIS Assessor.
• comply::scanners::ciscat: Installs the CIS Assessor along with required dependencies.

Functions

• module_version: Gets Comply module version
• random_string: Generates a random hex string
• random_uuid: Generates a random uuid
• report_errors: Returns error details

Returns error details

Data types

• Comply::Url: Comply url

Comply url

Tasks

• backup_assessor: Backup operations for the assessor, used for upgrades.
• ciscat_scan: Run a ciscat scan and upload to comply server.
• remove_assessor: Removes old assessor versions from assessors directory, based on number_to_keep parameter. Keeps latest versions

Classes

comply

Installs the CIS Assessor.

Examples

Use defaults

include comply

Basic example

class { 'comply':
  allow_insecure => false
}

Parameters

The following parameters are available in the comply class:

• allow_insecure
• manage_chocolatey
• linux_manage_unzip
• win_manage_7zip
• manage_java
• scanner_source
• scanner_source_linux
• scanner_source_mac
• scanner_source_windows
• scanner_checksum_linux
• scanner_checksum_mac
• scanner_checksum_windows
• scanner_version
• use_mtls
• windows_manage_wget
• assessor_download_token
• limits
• ignore_platform_mismatch

allow_insecure

Data type: Boolean

Enables skipping of certificate validation when the scanner_source parameter is specified.

Default value: false

manage_chocolatey

Data type: Boolean

Manage chocolatey in this module for installing packages and allows for 7zip to install with archive, requires chocolatey as the package provider

Default value: true

linux_manage_unzip

Data type: Boolean

Determines if this module should manage the installation of unzip on Linux

Default value: true

win_manage_7zip

Data type: Boolean

Determines if this module should manage the installation of 7zip on windows, requires chocolatey as the package provider.

Default value: false

manage_java

Data type: Boolean

Determines if this module should manage the installation of java Note: This param is DEPRECATED and will be removed in a subsequent version.

Default value: true

scanner_source

Data type: Optional[Stdlib::Filesource]

The URL to the location of a specific Assessor distribution within comply This may be specified as a source attribute of a file resource

In the Puppet Comply application config, if you specified "We want to access the assessor through our ingress controller", then set this value to https://PE TLS FQDN/assessor, otherwise set this value to https://Comply Hostname:30303/assessor

Default value: undef

scanner_source_linux

Data type: Optional[Stdlib::Filesource]

The URL to the location of a specific linux bundle should the user wish to host outside of comply.

Default value: "${scanner_source}/linux"

scanner_source_mac

Data type: Optional[Stdlib::Filesource]

The URL to the location of a specific mac bundle should the user wish to host outside of comply.

Default value: "${scanner_source}/mac"

scanner_source_windows

Data type: Optional[Stdlib::Filesource]

The URL to the location of a specific windows bundle should the user wish to host outside of comply.

Default value: "${scanner_source}/windows"

scanner_checksum_linux

Data type: Optional[String]

Specify the sha256 checksum of the Linux Assessor archive provided in scanner_source. Defaults to the checksum of the respective version of the scanner as part of Comply deployed in Puppet Application manager.

Default value: '5b0773a5b27759d55d6f01b45051f09f41b8550be91239c1faecda2a49c6629e'

scanner_checksum_mac

Data type: Optional[String]

Specify the sha256 checksum of the Mac Assessor archive provided in scanner_source. Defaults to the checksum of the respective version of the scanner as part of Comply deployed in Puppet Application manager.

Default value: 'd7ebcd072f371798dded1f1448dff4bd628dcc1c4cc6b99d1464f4d1b34aec40'

scanner_checksum_windows

Data type: Optional[String]

Specify the sha256 checksum of the Windows Assessor archive provided in scanner_source. Defaults to the checksum of the respective version of the scanner as part of Comply deployed in Puppet Application manager.

Default value: 'e055ec6183e75181e0822abcec5ce0535c4d37b9e4e9c5276b2a3a6fe38f5aa7'

scanner_version

Data type: Optional[Pattern[/\d+\.\d+\.\d+/]]

Specify the version of the Assessor archive provided in scanner_source. Defaults to the respective version of the scanner as part of Comply deployed in Puppet Application manager.

Default value: '4.52.0'

use_mtls

Data type: Boolean

Use mutual TLS authentication. Comply is configured to only accept requests from nodes with valid certificates issued with the same CA cert. Ensure you have configured Comply properly using certs generated on your PE instance.

Default value: true

windows_manage_wget

Data type: Boolean

Allow Comply to manage the wget package. Required for fetching the Assessor, requires chocolatey as the package provider.

Default value: true

assessor_download_token

Data type: Optional[String]

A bearer token to be used when downloading the Assessor.

Default value: ''

limits

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

Apply limits to the Assessor process, for example limit CPU usage. The limits parameter is a hash with the following structure: { "systemd-run" => { # Linux only if /usr/bin/systemd-run is available "CPUQuota" => 50 # Percentage of a single CPU core that the Assessor process is allowed to use, can be >100 for multiple cores. }, "nice" => { # Linux and Mac only "increment" => 10 # Increment the nice value of the Assessor process, can be negative. } }

Default value: undef

ignore_platform_mismatch

Data type: Boolean

Set to true to ignore platform mismatches, false otherwise.

Default value: false

comply::scanners::ciscat

CIS CAT Pro scanner requires a JRE as a prerequisite.

Examples

Manage packages elsewhere on Linux

class { 'comply::scanners::ciscat':
  scanner_source     => 'https://comply.10.10.10.10.nip.io/assessor',
  linux_manage_unzip => false,
}

Install the CIS Assessor when Comply is configured to access the assessor through an alternative ingress

class { 'comply::scanners::ciscat':
  scanner_source     => 'https://pe-tls-fqdn.10.10.10.10.nip.io/assessor',
  linux_manage_unzip => false,
}

Install the CIS Assessor when Comply is configured to access the assessor through default Port

class { 'comply::scanners::ciscat':
  scanner_source     => 'https://comply.10.10.10.10.nip.io:30303/assessor',
  linux_manage_unzip => false,
}

Install the CIS Assessor when hosting at a user provided location

class { 'comply::scanners::ciscat':
  scanner_source_linux     => https://server.puppet.com/Assessor-CLI-windows-v4.26.0.zip',
  scanner_source_windows   => https://server.puppet.com/Assessor-CLI-linux-v4.26.0.zip',
}

Limit the Assessor process to 50% of a single CPU core on Linux.

class { 'comply::scanners::ciscat':
  scanner_source => 'https://comply.10.10.10.10.nip.io/assessor',
  limits         => {"systemd-run" => {"CPUQuota" => 50}},
}

Increment the nice value of the Assessor process on Linux or macOS.

class { 'comply::scanners::ciscat':
  scanner_source => 'https://comply.10.10.10.10.nip.io/assessor',
  limits         => {"nice" => {"increment" => 10}},
}

Parameters

The following parameters are available in the comply::scanners::ciscat class:

• allow_insecure
• linux_manage_unzip
• manage_java
• scanner_source
• scanner_source_linux
• scanner_source_mac
• scanner_source_windows
• scanner_checksum_linux
• scanner_checksum_mac
• scanner_checksum_windows
• scanner_version
• use_mtls
• windows_manage_wget
• assessor_download_token
• limits
• ignore_platform_mismatch
• win_manage_7zip
• manage_chocolatey

allow_insecure

Data type: Boolean

Enables skipping of certificate validation when the scanner_source parameter is specified.

This parameter should be used only with the scanner_source parameter.

Default value: $comply::allow_insecure

linux_manage_unzip

Data type: Boolean

Determines if this module should manage the installation of unzip on Linux

Default value: $comply::linux_manage_unzip

manage_java

Data type: Boolean

Determines if this module should manage the installation of java Note: This param is DEPRECATED and will be removed in a subsequent version.

Default value: $comply::manage_java

scanner_source

Data type: Optional[Stdlib::Filesource]

The URL to the location of a specific Assessor distribution within comply This may be specified as a source attribute of a file resource

In the Puppet Comply application config within 2.X, if you specified "We want to access the assessor through our ingress controller", then set this value to https://PE TLS FQDN/assessor, otherwise set this value to https://Comply Hostname:30303/assessor

Default value: $comply::scanner_source

scanner_source_linux

Data type: Optional[Stdlib::Filesource]

The URL to the location of a specific linux bundle should the user wish to host outside of comply.

Default value: $comply::scanner_source_linux

scanner_source_mac

Data type: Optional[Stdlib::Filesource]

The URL to the location of a specific mac bundle should the user wish to host outside of comply.

Default value: $comply::scanner_source_mac

scanner_source_windows

Data type: Optional[Stdlib::Filesource]

The URL to the location of a specific windows bundle should the user wish to host outside of comply.

Default value: $comply::scanner_source_windows

scanner_checksum_linux

Data type: Optional[String]

Specify the sha256 checksum of the Linux Assessor archive provided in scanner_source. Defaults to the checksum of the respective version of the scanner deployed as part of the Application.

Default value: $comply::scanner_checksum_linux

scanner_checksum_mac

Data type: Optional[String]

Specify the sha256 checksum of the Mac Assessor archive provided in scanner_source. Defaults to the checksum of the respective version of the scanner deployed as part of the Application

Default value: $comply::scanner_checksum_mac

scanner_checksum_windows

Data type: Optional[String]

Specify the sha256 checksum of the Windows Assessor archive provided in scanner_source. Defaults to the checksum of the respective version of the scanner deployed as part of the Application

Default value: $comply::scanner_checksum_windows

scanner_version

Data type: Optional[Pattern[/\d+\.\d+\.\d+/]]

Specify the version of the Assessor archive provided in scanner_source. Defaults to the checksum of the respective version of the scanner deployed as part of the Application

Default value: $comply::scanner_version

use_mtls

Data type: Boolean

Use mutual TLS authentication. Comply is configured to only accept requests from nodes with valid certificates issued with the same configured CA cert. Ensure you have configured Comply properly using certs generated on your PE instance.

Default value: $comply::use_mtls

windows_manage_wget

Data type: Boolean

Allow Comply to manage the wget package. Required for fetching the Assessor.

Default value: $comply::windows_manage_wget

assessor_download_token

Data type: Optional[String]

A bearer token to be used when downloading the Assessor.

Default value: $comply::assessor_download_token

limits

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

Apply limits to the Assessor process, for example limit CPU usage. The limits parameter is a hash with the following structure: { "systemd-run" => { # Linux only if /usr/bin/systemd-run is available "CPUQuota" => 50 # Percentage of a single CPU core that the Assessor process is allowed to use, can be >100 for multiple cores. }, "nice" => { # Linux and Mac only "increment" => 10 # Increment the nice value of the Assessor process, can be negative. } }

Default value: $comply::limits

ignore_platform_mismatch

Data type: Boolean

Set to true to ignore platform mismatches, false otherwise.

Default value: $comply::ignore_platform_mismatch

win_manage_7zip

Data type: Boolean

Default value: $comply::win_manage_7zip

manage_chocolatey

Data type: Boolean

Default value: $comply::manage_chocolatey

Functions

module_version

Type: Ruby 4.x API

Gets Comply module version

module_version()

The module_version function.

Returns: String Comply module version

random_string

Type: Ruby 4.x API

Generates a random hex string

random_string()

The random_string function.

Returns: String Random hex string

random_uuid

Type: Ruby 4.x API

Generates a random uuid

random_uuid()

The random_uuid function.

Returns: String Random uuid

report_errors

Type: Ruby 4.x API

Returns error details

Returns error details

Examples

report_erros('[a, hash, of, errors]', true)

report_errors(ResultSet $error_hash, Optional[Boolean] $allow_exit_code2)

The report_errors function.

Returns: String Returns error string

Examples

report_erros('[a, hash, of, errors]', true)

error_hash

Data type: ResultSet

allow_exit_code2

Data type: Optional[Boolean]

Data types

Comply::Url

Comply url

Comply url

Alias of Variant[Array[Stdlib::HTTPUrl], Stdlib::HTTPUrl]

Tasks

backup_assessor

Backup operations for the assessor, used for upgrades.

Supports noop? false

Parameters

operation

Data type: Enum[create,delete,restore]

Allows create / delete / restore backups of the assessor.

ciscat_scan

Run a ciscat scan and upload to comply server.

Supports noop? false

Parameters

benchmark

Data type: Optional[String[1]]

Name of the benchmark file to run with the scan. Mutually exclusive with scan_hash.

comply_server

Data type: String[1]

Name of the FQDB comply server to upload to. NB passing 'nil' will prevent the upload

comply_port

Data type: String[1]

Port used from comply server.

custom_profile_id

Data type: Optional[Integer[1]]

A given custom_profile_id to be used for scans to have a custom profile applied.

debug

Data type: Optional[Boolean]

Runs the scan with debug options turned on.

profile

Data type: Optional[String[1]]

Name of the profile to run with the scan. This will use the default profile for that benchmark, if not specified.

scan_hash

Data type: Optional[String[1]]

JSON struct in string format of benchmarks/profiles and their machine names. Mutually exclusive with scan_hash.

scan_type

Data type: Optional[Enum['ad hoc','scheduled']]

The type of scan to be performed, ad hoc or scheduled.

ssl_verify_mode

Data type: Optional[Enum['none','peer']]

The SSL verify mode to use

scan_id

Data type: Optional[String[1]]

An id given to the scan that is about to be run

auth_token

Data type: Optional[String[1]]

A bearer token to be used when uploading scan reports (currently only used in SaaS deployment)

scan_report_upload_path

Data type: Optional[String[1]]

The path to which scan reports will be uploaded

remove_assessor

Removes old assessor versions from assessors directory, based on number_to_keep parameter. Keeps latest versions

Supports noop? false

Parameters

number_to_keep

Data type: Optional[Integer[1]]

The number of assessor versions to keep in the assessors directory

See https://www.puppet.com/docs/comply/3.x/comply-release-notes#release-notes