Version information
This version is compatible with:
- Puppet Enterprise 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.21.0 < 9.0.0
- , , , , , , , , ,
Start using this module
Add this module to your Puppetfile:
mod 'enterprisemodules-vulnerability', '1.4.0'
Learn more about managing modules with a PuppetfileDocumentation
Table of Contents
- Overview
- License
- Description
- Setup
- Scanning for vulnerabilities
- Guarding the number of vulnerabilities
- Customisations
- Reference
- Limitations
Overview
The recent vulnerability in log4j has once again shown us that detecting and resolving vulnerabilities in your IT infrastructure can be a daunting and very time-consuming task. The best way to ensure that you can easily detect and fix these issues is to integrate them into your current way of working and your current set of tools.
This module allows you to integrate your general vulnerability management into your Puppet workflow. After you include this module in your Puppet code base, Puppet will start to check your systems for vulnerabilities.
License
This is a commercially licensed module. But you can use the module on VirtualBox-based development systems for FREE. You can request a FREE trial license here
Check the License for details.
Description
All of the vulnerabilities are available as facts. When you use a Puppet server (Puppet Enterprise or non-PE), these facts are sent to your PuppetDB. This means that you have one location where you can see all of your systems' vulnerabilities.
The module contains the functionality to assess the vulnerabilities on your systems and allows you to use Puppet to execute mitigating actions automatically.
Using this module in combination with the Open Source resolve
module lets Puppet automatically resolve some of the vulnerabilities it detects.
Under the hood, this module used the powerful and fast vulnerability scanner grype
Setup
Requirements
The vulnerability
module requires:
- Puppet module
enterprisemodules-easy_type
installed. - Puppet version 4.0 or higher. Can be Puppet Enterprise or Puppet Open Source
- A valid Enterprise Modules license for usage
- Runs on most Linux and Windows systems
Installing the vulnerability module
To install these modules, you can use a Puppetfile
mod 'enterprisemodules/vulnerability', '0.1.0'
Then use the librarian-puppet
or r10K
to install the software.
You can also install the software using the puppet module
command:
puppet module install enterprisemodules-vulnerability
Scanning for vulnerabilities
The basic step is to include the class:
include vulnerability`
Adding this line of code to your Puppet code base, will start vulnerability scanning on all of your files.
Guarding the number of vulnerabilities
Ok, so now you have all the information about found vulnerabilities on your system. But how are you going to use it?
Failing when a vulnerability is found
The ::vulnerability::guard
class allows you to specify the number of specific vulnerabilities your allow on your system. When more vulnerabilities are found, Puppet will throw an error. You will need to monitor the status of the Puppet runs on your puppetserver and take appropriate action when Puppet fails because of a detected vulnerability.
Executing Puppet code when a vulnerability is found
The module contains some functions you can use in your Puppet code to determine if a certain CVE is detected and when it is, execute some remediation Puppet code for this.
Using the command line
The Vulnerability module contains a command-line utility. Using the utility, you can select the list of detected vulnerabilities and maybe rep[ort information to monitoring utilities.
Customisations
Because scanning all of your files is a very resource-intensive and time-consuming task, you might want to customize this scanning to your needs.
time between scans
By default, Puppet scans your system once every 24 hours. If you would like to change this time, you can add this to your hieradata:
vulnerability::setup::ttl_hours: 48
This will change the frequency to once every 48 hours. The longer you make this interval, the less up-to-date your list of vulnerabilities is, and the fewer resources and times it takes.
Directories to scan
By default Puppet will scan all of your files. This is probably a bit too much. You can control the directories that are scanned by adding them to your hiera data like this:
vulnerability::setup::directories:
- /bin
- /usr/bin
- /sbin
- /myapp
Files and directories to exclude
By default Puppet will scan all of the files and subdirectories you have specified in the previous step. You might, however, want to exclude specific files and/or directories. You can control this by adding this to your hiera data:
vulnerability::setup::excludes:
- ./software_kits
- ./user_files/**/*.tar
Reference
You can find some more information here regarding this Puppet module:
Limitations
This module runs on most Linux and Windows versions. It requires a puppet version higher than 4. Other configurations are not supported.
This module depends heavily on the caching capabilities of facter. These capabilities are added from facter version 4. Using Puppet with a lower version of facter, will still work, but it will determine the vulnerabilities on every Puppet run. This might not be what you need.
Reference
Table of Contents
Classes
vulnerability
: The top-level class of the vulnerability module.vulnerability::clear_facter_cache
: Clear thecve_list
facter cache.vulnerability::guard
: Guard the system for vulnerabilities.vulnerability::install
: This class ensures the installation ofgrype
in a correct way so that Puppet can start guarding the vulnerabilities on this system.vulnerability::install::linux
: This class takes care of installinggrype
on linux systems.vulnerability::install::windows
: This class takes care of installinggrype
on windows systems.vulnerability::setup
: Ensure the your vulnerability scanning is setup correctly.vulnerability::update
: Update thegrype
vulnerability database from the URL specified asvulnerability::setup::update_url
.
Resource types
vulnerability_status
: Manage the status of the vulnerabilities on your system. Using this type, you can start to manage the number of vulnerabilities you allow on
Functions
vulnerability::affected_files
: get the list of files that are affected by a specified vulnerabilityvulnerability::detected
: Determine if a specified vulnerability is found on this systemvulnerability::severity
: Return an array of vulnerability id's of a specified level on this systemvulnerability::validate
: Validate that your system doesn't have vulnerabilities above a specified level. When your system does contain the vulnerabilities, signal
Data types
Vulnerability::Fix_state
: The fix state of the CVE.Vulnerability::Level
: The severity level of the CVE
Classes
vulnerability
vulnerability::vulnerability
This class ensures that the correct version of grype
is installed and configured and that on the specified interval your systems are scanned for vulnerabilities.
See the file "LICENSE" for the full license governing this code.
Parameters
The following parameters are available in the vulnerability
class:
update
Data type: Boolean
Update the vulnerability database on every Puppet run.
When you set this value to true
, Puppet will check the vulnerability database on every run and update it when it detects a new version.
Although setting it to true is the best setting security-wise, it can introduce dynamic changes to your Puppet run's that you don't want. When you want more controlled updates, set this value to false and make sure that the vulnerability::update
class is scheduled in some other way.
Even when you set this value to false
, Puppet will do an update on the initial run where grype
is installed. This is required to at least have an initial vulnerability database.
guard
Data type: Boolean
When you set this value to true
, Puppet start's to guard the number of vulnerabilities on your system.
Check the ::vulnerability::guard
class for details.
The default value is false
meaning no automatic checks on the vulnerability status.
vulnerability::clear_facter_cache
vulnerability::clear_facter_cache
This measn that on the next Puppet run, the fact will be determined again.
See the file "LICENSE" for the full license governing this code.
vulnerability::guard
vulnerability::guard
When you include this class into your catalog, Puppet starts to guard your system. Meaning it will check on every Puppet run's if the number of found vulnerabilities is lower than the maximum number you have specified.
When Puppet detects that more vulnerabilities are found on your system than you specified, Puppet will fail.
You will need to monitor the status of Puppet runs on the Puppet server and take appropriate actions.
Sometimes you know about a set of vulnerabilities, and you don't want Puppet to report on this. If this is the case, add the vulnerability ID to the allow_list
. Puppet will then allow this specific CVE on your system without reporting and/or failing on it.
See the file "LICENSE" for the full license governing this code.
Parameters
The following parameters are available in the vulnerability::guard
class:
allow_list
Data type: Array[String[1]]
The list of vulnerability id's you want to allow on your system. When a found vulnerability is on your allow list, it will not count in the number of identified vulnerabilities on the system.
critical
Data type: Optional[Integer]
The number of critical vulnerabilities you allow on your system before Puppet throws an error.
The default is 0
.
high
Data type: Optional[Integer]
The number of high vulnerabilities you allow on your system before Puppet throws an error.
The default is Undef
. Meaning Puppet doesn't guard this.
low
Data type: Optional[Integer]
The number of low vulnerabilities you allow on your system before Puppet throws an error.
The default is Undef
. Meaning Puppet doesn't guard this.
medium
Data type: Optional[Integer]
The number of low vulnerabilities you allow on your system before Puppet throws an error.
The default is Undef
. Meaning Puppet doesn't guard this.
negligible
Data type: Optional[Integer]
The number of negligible vulnerabilities you allow on your system before Puppet throws an error.
The default is Undef
. Meaning Puppet doesn't guard this.
unknown
Data type: Optional[Integer]
The number of unkown vulnerabilities you allow on your system before Puppet throws an error.
The default is Undef
. Meaning Puppet doesn't guard this.
vulnerability::install
vulnerability::install
See the file "LICENSE" for the full license governing this code.
Parameters
The following parameters are available in the vulnerability::install
class:
version
Data type: String[1]
The version of grype
to install.
base_url
Data type: String[1]
The base part of the URL where to download grype from.
The default is: https://github.com/anchore/grype/releases/download
, meaning we download directly from the original github source.
vulnerability::install::linux
vulnerability::install::linux
See the file "LICENSE" for the full license governing this code.
Parameters
The following parameters are available in the vulnerability::install::linux
class:
version
Data type: String[1]
The version of grype
to install.
temp_dir
Data type: String[1]
The temporary directory to use for the installation.
The default value for this is /tmp
.
root_dir
Data type: Stdlib::Absolutepath
The root directory where all grype files are stored. This is an internal variable. Please be cautious when changing this.
base_url
Data type: String[1]
The base part of the URL where to download grype from.
The default is: https://github.com/anchore/grype/releases/download
, meaning we download directly from the original github source.
vulnerability::install::windows
vulnerability::install::windows
See the file "LICENSE" for the full license governing this code.
Parameters
The following parameters are available in the vulnerability::install::windows
class:
version
Data type: String[1]
The version of grype
to install.
temp_dir
Data type: Stdlib::Absolutepath
The temporary directory to use for the installation.
The default value for this is /tmp
.
root_dir
Data type: Stdlib::Absolutepath
The root directory where all grype files are stored. This is an internal variable. Please be cautious when changing this.
base_url
Data type: String[1]
The base part of the URL where to download grype from.
The default is: https://github.com/anchore/grype/releases/download
, meaning we download directly from the original github source.
vulnerability::setup
vulnerability::setup
Key settings are:
- directories
- excludes
- ttl_hours
See the file "LICENSE" for the full license governing this code.
Parameters
The following parameters are available in the vulnerability::setup
class:
cache_dir
Data type: Stdlib::Absolutepath
The grype
cache directory.
The default values is fine most of the time.
This is an internal variable. Please be cautious when changing this.
config_dir
Data type: Stdlib::Absolutepath
The grype
config directory.
The default values is fine most of the time.
This is an internal variable. Please be cautious when changing this.
update_url
Data type: String[1]
The url used for fetching the database updates.
ttl_hours
Data type: Integer
This specifies the number of hours you want to keep between different vulnerability scans.
The vulnerability module uses facter to report the CVE's found on a system. Scanning a system, however, is a resource-intensive and time-consuming activity. Therefore we don't want Puppet to do this on every Puppet run.
This parameter specifies the number of hours between new scans. It is the amount of time the fact cve_list
is deemed valid.
The default value is 24
, meaning a new scan is done once a day.
When you change the setting or update the vulnerability database, the fact is automatically invalidated, so a new scan is done on the next puppet run.
directories
Data type: Array[Stdlib::Absolutepath]
This parameter contains an Array of strings containing the directories you want to scan for vulnerabilities.
The default value for this is ['/']
. This is safe but also slow. You can speed up the detection of the vulnerabilities by being more specific on the directories you want to scan.
excludes
Data type: Array[String[1]]
An array of exclude relative paths of directories and/or files you want to skip during vulnerability scanning. The default value for this setting is an empty array. This means no files and/or directories will be excludes fropm the scan.
level
Data type: Vulnerability::Level
The severity level of the vulnerabilities you want to report on the system. Valid values are in order of severity are:
- Critical
- High
- Medium
- Low
- Negligible
- Unknown
When you select a value, vulnerabilities of that level and higher will be reported on the system.
When you select one of the lower levels, potentially a lot of CVE's are reported on the CVE list. This might cause strain on your Puppetdb.
The default value is
Medium
vulnerability::update
vulnerability::update
When a new version is detected, it is downloaded and installed. Also, the cve_list
fact cache is invalidated, so a new vulnerability scan is executed on the next Puppet run.
See the file "LICENSE" for the full license governing this code.
Resource types
vulnerability_status
Manage the status of the vulnerabilities on your system.
Using this type, you can start to manage the number of vulnerabilities you allow on your system. Here is an example on how to use it:
vulnerability_status { 'master.example.com':
critical => 2,
high => 90,
allow_list => ['CVE-2018-11749'],
when_more => error,
}
In this example, you allow a maximum of 2 critical and 90 high vulnerabilities on your system. You#{' '} know that vulnerability CVE-2018-11749 is on your system and for now, you don't want it to allow this CVE and not include it in the count.
Parameters
The following parameters are available in the vulnerability_status
type.
provider
The specific backend to use for this vulnerability_status
resource. You will seldom need to specify this --- Puppet
will usually discover the appropriate provider for your platform.
Functions
vulnerability::affected_files
Type: Ruby 4.x API
get the list of files that are affected by a specified vulnerability
vulnerability::affected_files()
get the list of files that are affected by a specified vulnerability
vulnerability::detected
Type: Ruby 4.x API
Determine if a specified vulnerability is found on this system
vulnerability::detected()
Determine if a specified vulnerability is found on this system
vulnerability::severity
Type: Ruby 4.x API
Return an array of vulnerability id's of a specified level on this system
vulnerability::severity()
Return an array of vulnerability id's of a specified level on this system
vulnerability::validate
Type: Ruby 4.x API
Validate that your system doesn't have vulnerabilities above a specified level. When your system does contain the vulnerabilities, signal this to the puppet server
vulnerability::validate()
Validate that your system doesn't have vulnerabilities above a specified level. When your system does contain the vulnerabilities, signal this to the puppet server
Data types
Vulnerability::Fix_state
The fix state of the CVE.
Alias of
Enum['fixed', 'not-fixed', 'wont-fix', 'unknown']
Vulnerability::Level
The severity level of the CVE
Alias of
Enum['Critical', 'High', 'Medium', 'Low', 'Negligible', 'Unknown']
Version updates
1.4.0
- [core] Update to grype 0.79.4
1.3.0
- [core] Update to grype 0.77.4
1.2.0
- [task/fetch_vulnerabilities] Initial implementation
- [cve_list] Fix issue when no vulnerabilities where found on a specific dir
- [core] Remove the automatic fetching of licenses.
1.1.0
- [core] Update to grype 0.75.0
1.0.0
- [release] Update versions of required modules
- [core] Update to grype 0.62.3
- [quality] Fix acceptance test on Puppet 8
0.8.0
- [core] Upda to grype 0.61.1
- [core] Add support for Puppet 8
- [core] Fix way of loading EM entitlements
- [grype_version] Fix missing require
- [core] Fix reading found vulnerabilies with special characters
- [remediate] Add initial implementation for remediation
- [data] Set Linux defaults for directories to scan
- [facts] Set the facter timeout to 2 hours
0.7.0
- [core] Upda to grype 0.54.0
0.6.0
- [core] Upda to grype 0.52.0
- [core] Add support for EL9
0.5.3
- [core] Update grype to 0.48.0
0.5.2
- [core] Update to grype 0.41.0
0.5.1
- [core] Update to grype 0.35.0
0.5.0
- [release] Add support for AlmaLinux and Rocky
- [core] Update to grype 0.34.3
0.4.6
- [linux] Fix onwership of grype exec
- [release] Fix metadata dependencies
- [core] Start using cleanup resource
- [core] Update to grype 0.33.1
0.4.5
- [core] Fix default scan dir for windows
- [core] Enforce the ordering by further containment
- [vulnerability_status] Improve the understandibility of the messages
0.4.4
- [vulnerability] fail in guard should not hinder other classes
- [vulnerability_status] Add confinement to ensure running after install
0.4.3
- [vulnerability_status] Fix error when fact not (yet) defined
0.4.2
- [core] Add containment to remediate ordering issues
0.4.1
- [core] Update to V0.31.1 of grype
0.4.0
- [core] Add support for windows
- [setup] Remove unused parameter facter_conf
0.3.1
- [core] Use facter types intstead of exec and hocon
- [cve_list] Fix reading of config
- [core] Automatically fetch license files
0.3.0
- [docs] Extend the documentation
- [guard] Add initial implementation
- [vulnerability_status] Initial implementation
0.2.0
- [functions/validate] Hard failure when not valid
- [commands] Add summary display
- [commands] Handle nil cve_list with good error
- [setup] Add support for specifying level
- [commands] Add command line interface to vulnerability fact
- [core] Let functions handle empty cve_list fact
0.1.1
-[docs] Remove markdown reference is titles
0.1.0
- Initial release
Dependencies
- enterprisemodules-easy_type (>= 2.37.2 < 3.0.0)
- puppetlabs-stdlib (>= 6.0.0 < 10.0.0)
- puppet-archive (>= 5.0.0 < 8.0.0)
Enterprise Modules License d.d. January 2018 This license ("License") governs the terms and conditions under which ora_install module ("the Software") is licensed by Enterprise Modules B.V, a limited liability company in the Netherlands, registered in the Dutch Chamber of Commerce: 63689537 ("Licensor"), to the user of the Software ("Licensee"). Article 1. Grant of license 1.1 Licensor hereby grants to Licensee the right to use the Software for its internal business purposes. 1.2 The license granted in the previous paragraph is limited to the use on VirtualBox Virtual machines. For further use a commercial license must be directly obtained from Licensor. Article 2. License limitations 2.1 All right, title and interest to the Software, the accompanying documentation and all modifications and extensions thereto rest and remain with Licensor. Licensee only has the rights and permissions explicitly granted by this License or granted in writing otherwise. Licensee shall not use, copy, modify, distribute or publish the Software in any other manner. Nothing in this License is intended to, and shall not be construed to, transfer to Licensee any rights in intellectual property developed by Licensor. 2.2 In particular, Licensee shall not: a) provide copies of the Software to third parties, including to entities controlling, controlled by or under common control with Licensee; b) sublicense the Software or otherwise make available the Software to such third parties, including by rental, Software-as-a-Service models or otherwise; c) remove indications of Licensor as copyright holder of the Software or to remove or render illegible any part thereof. 2.3 The Software comprises third-party open source software. The respective third-party rights holders grant Licensee the rights indicated in the applicable open source licenses. These licenses can be found in the documentation. The License does not apply to this open source software, and nothing in this License shall be construed as a limitation of any right granted under an open source license. Article 3. Trademark 3.1 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 Software. Article 4. Limitation of Liability 4.1 Licensor provides the Software on an "AS IS" basis, and expressly disclaims all conditions, representations or warranties, express or implied, including without limitation any implied warranties of merchantability, fitness for a particular purpose, and non-infringement of third party rights regarding the Software. Licensor is solely responsible for determining the appropriateness of using the Software and assume any risks associated arising out of or in connection with the Software and this License. 4.2 Licensor shall not be liable for any damages, including consequential, special, punitive and/or incidental damages or fines imposed by regulatory bodies, arising out of or in connection with the Software and this License. 4.3 Licensee shall release, defend, indemnify and hold harmless Licensor from and against any and all claims, damages and liability arising in connection with the Software, including from claims, damages or liability from customers of Licensee. Article 5. Miscellaneous 5.1 Licensor reserves the right to change any or all parts of this License without prior notice. 5.2 The law of the Netherlands governs this License and the terms and conditions therein. 5.3 Any disputes arising between Licensor and Licensee in connection with the License will be settled by the competent courts in the Netherlands for the principal place of business of the Licensor.