Version information
This version is compatible with:
- Puppet Enterprise 2025.3.x, 2025.2.x, 2025.1.x, 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x
- Puppet > 6.24 <= 9.0.0
- , , , , , , , , , ,
Tasks:
- backup_assessor
- ciscat_scan
- remove_assessor
This module is licensed for use with Puppet Enterprise. You may also evaluate this module for up to 90 days.Learn More
Start using this module
Add this module to your Puppetfile:
mod 'puppetlabs-comply', '3.4.0'Learn more about managing modules with a PuppetfileDocumentation
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 versionrandom_string: Generates a random hex stringrandom_uuid: Generates a random uuidreport_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_insecuremanage_chocolateylinux_manage_unzipwin_manage_7zipmanage_javascanner_sourcescanner_source_linuxscanner_source_macscanner_source_windowsscanner_checksum_linuxscanner_checksum_macscanner_checksum_windowsscanner_versionuse_mtlswindows_manage_wgetassessor_download_tokenlimitsignore_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_insecurelinux_manage_unzipmanage_javascanner_sourcescanner_source_linuxscanner_source_macscanner_source_windowsscanner_checksum_linuxscanner_checksum_macscanner_checksum_windowsscanner_versionuse_mtlswindows_manage_wgetassessor_download_tokenlimitsignore_platform_mismatchwin_manage_7zipmanage_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
What are tasks?
Modules can contain tasks that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
Tasks in this module release
Dependencies
- puppet/archive (>= 4.3.0 <= 7.1.0)
- puppetlabs/chocolatey (>= 5.0.0 <= 8.0.2)
- puppetlabs/inifile (>= 4.1.0 <= 6.2.0)
- puppetlabs/ruby_task_helper (>= 0.6.1 <= 1.0.0)
- puppetlabs/stdlib (>= 5.0.0 <= 9.7.0)
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.