Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Managing patches Grey arrow pointing right Advanced Patching Grey arrow pointing right

Advanced Patching

Sections

If you have a Puppet Enterprise Advanced license you can enable Advanced Patching with vulnerability remediation capabilities from the PE console. From the PE console navigation bar, select Overview and click Get started with Advanced Patching now.

Before you begin
  • The service requires an extra 1GB of RAM, to operate by default. CPU usage varies based on how many systems are being patched and how often, but is an incremental amount of usage. The service also requires incremental additional disk storage for the vulnerabilities database, with usage varying based on the number of nodes being managed.
  • To enable Advanced Patching, you must acquire a Puppet Enterprise Advanced license. Contact your Puppet Enterprise administrator or Contact our sales team to acquire a license and enable this feature.
  • Ensure there are no classification issues on the primary server and that a Puppet run can complete successfully before you enable Advanced Patching.
  • The Advanced Patching feature is not enabled by default, and requires a user with permissions to run all plans in order to enable the feature. Once enabled, the feature cannot currently be disabled.
  • The Advanced Patching feature assumes ownership of the PE Patch Management node group tree. Any patch groups declared under that group are modified or deleted by the Advanced Patching service. It is important that no additional classification is applied beyond use of the pe_patch class to the PE Patch Management group, or any groups underneath it otherwise Advanced Patching will not enable successfully.
  • Once enabled, the PE Advanced Patching feature enforces the state of the PE Patch Management node group tree, so any manual changes made to it are replaced.
  • RBAC: A default role is available for patching in PE. That role can be assigned to a user to do patching. The Administrator by default has all permissions. The permission needed for onboarding customers must have permissions to run a plan on the primary server. For more information about Advanced Patching user permissions and roles see User permissions and user roles.

Create a blackout window

To add a blackout window:

  1. In the PE console navigation bar, select Blackout Windows.
  2. Click Add blackout window.
  3. In the Information section, add a name for your blackout window.
  4. From the drop-down menu in the Availability section, select how often you would like the blackout window to run.
  5. In the Schedule section, designate a valid period of time for your blackout window.
  6. Click Add blackout window.

Create a maintenance window

To add a maintenance window:

  1. In the PE console navigation bar, select Maintenance Windows.
  2. Click Add maintenance window.
  3. In the Information section, add a name for your maintenance window.
  4. From the drop-down menu in the Availability section, select how often you would like the maintenance window to run.
    Note: You can select Custom from the drop-down menu to specify a more complex scheduling using a cron string to define your maintenance window. For more information see cron strings.
  5. In the Schedule section, designate a valid period of time for your maintenance window.
  6. Click Add maintenance window.

Create a patch group

To create a patch group:

  1. From the PE console navigation bar, select Patch Groups.
  2. Click Add patch group.
  3. In the Information section, add a name and description (optional) for your patch group.
  4. Select Next: Select nodes.
  5. From the drop-down menu, select one of the four available methods to pin nodes to a patch group:
    • Classification node group
    • Fact match
    • Node list
    • PQL query
  6. Select Next: Assign maintenance window.
  7. Filter maintenance windows by name and select Apply.
  8. Check the maintenance window(s) and click Add selected windows.
  9. Select Next: Assign blackout window.
  10. Filter blackout windows by name and select Apply.
  11. Check the blackout window(s) and click Add selected windows.
  12. Select Add patch group.
  13. From the PE console navigation bar, select Overview to:
    • View what patch groups need patched.
    • Apply patches for nodes that have been configured for patching.
      Note: When you select a group that needs patching from the Overview page, you can apply a patch job for that group by clicking Apply patch job in the upper-right corner.

Vulnerability remediation

Advanced Patching service includes vulnerability remediation capabilities, enabling you to identify vulnerabilities in your infrastructure and apply required updates to affected nodes.

Note:
  • To use Advanced Patching, you must acquire a Puppet Enterprise Advanced License and enable the Advanced Patching service.
  • To use vulnerability remediation capabilities, vulnerability data from your security scanner must be integrated into PE using a transformer to parse the scan data.
  • Nodes you want to patch must be added to patch groups.

Get an overview of detected vulnerabilities

In the PE console navigation bar, select Vulnerabilities to view a list of the vulnerabilities detected on your managed infrastructure, with summary information and an indication of how many nodes are affected.
Important: The vulnerability list reflects the most recent import of scan data into Puppet Enterprise. The Last scan data import information indicates when this data was last ingested. To view the date and time when the original scan was performed by your scanner, click the question mark symbol next to the Last scan data import information.

You can filter and sort the list to assess and prioritize the vulnerabilities for remediation. You can use a full or partial text search to locate specific vulnerabilities. To begin the remediation process for a vulnerability, locate and click the vulnerability in the list.

View vulnerabilities on an individual node

In the PE console navigation bar, navigate to the Node details page for a specific node, and click the Vulnerabilities tab to show a list of the vulnerabilities on the node.

Remediate a vulnerability

To select and remediate a vulnerability:
  1. In the PE console navigation bar, select Vulnerabilities.
  2. In the list of vulnerabilities, locate and click the vulnerability you want to remediate, to display details and access remediation capabilities.

View details and required remediation

On the Vulnerability details page, you can view summary and detailed information about the vulnerability, evaluate its impact on your infrastructure, and begin the remediation process.
  1. See the Key details for an overview of the vulnerability. To view the full description imported from your scanner via the transformer, see the Analysis.
  2. View the required Remediation, including the packages that must be updated. This information comes from your scanner via the transformer. Remediation is available when the relevant packages are present on the host.
    Note: Where a package recommended for update has a dependency on other packages, those packages are also updated in the remediation process. 
  3. Assess the impact on your infrastructure. Under Nodes with the vulnerability, use the Patch Group affected tab to see how many nodes are affected, check patch availability, and determine whether a patch job is scheduled. Use the Nodes Affected tab to identify the vulnerable nodes.

Next steps: Remediate the vulnerability.

Remediation

If a patch with the required package updates is available, you can create a patch job to remediate a vulnerability on affected nodes within a patch group.

In the Vulnerability details page for the vulnerability:
  1. Select the nodes for remediation.
    • Under Nodes with the vulnerability, go to the Nodes Affected tab and choose a patch group to list the nodes in that group. For the listed nodes, you can view whether a patch is available and whether a patch job has already been scheduled.
    • Select the nodes to remediate.
  2. Click Remediate Vulnerability to open the Create patch job wizard.
  3. If required, configure the patch job to reboot the nodes after patching, and set any advanced parameters required by the package manager.
  4. Choose when the patch job runs. You can run it immediately, or schedule for a later time. You can opt to override blackout and maintenance policies: for example, to apply critical patches outside of defined windows.
  5. Review the patch job settings.
  6. Run the patch job or activate the schedule.
    Note: Some Windows vulnerabilities may require registry updates after patching to fully remediate. These updates can be configured manually or by using Puppet tasks.
    Note: If remediation for a vulnerability involves a package managed by Puppet Enterprise, PE may revert updates made by the vulnerability remediation tool. This can result in a loop situation if PE then reapplies its desired state to the package.

Verification

You can track the progress of remediation in the Patch Jobs page, and see more detailed information in the Tasks page.
Note: Remediated vulnerabilities are still listed on the Vulnerability Details page until your security scanner has run a new scan and the new scan data has been ingested by running the transformer. To update the vulnerabilities list outside of a scheduled transformer run, you can run the transformer task ad hoc on the transformer node. See Update the vulnerability data. A history of the remediation actions on a specific node is included in the Activity tab of the Node details page.

View vulnerabilities in a patch group

In the console, navigate to the Patch Groups page to see the total number of security updates that are available for each patch group.

Integrate vulnerability data from a security scanner

To integrate information about vulnerabilities detected by your third-party scanning software, a vulnerability data transformer must be installed, configured and registered on a designated transformer node.

The transformer parses scan reports from your scanner and sends vulnerability information to Puppet Enterprise. This enables you to view the vulnerabilities in the PE console, see which Puppet-managed nodes are affected, and run vulnerability remediation patch jobs.
Figure 1. Vulnerability data flow

A reference vulnerability data transformer is available for download from the Puppet Forge. This implementation is designed to integrate vulnerability data generated by the Tenable Nessus™ security scanner. To connect to other types of scanning tools, you can design your own transformer scripts to attach to the transformer node.

Steps to integrate vulnerability data:

Install the transformer

For information about installing the reference transformer tool provided by Perforce, refer to the module’s installation instructions on Puppet Forge. Installation for other implementations is specific to the transformer. Classify a node in Puppet Enterprise to act as the transformer. When the Puppet agent runs on this node, it installs the transformer.
Note: Currently, only Linux nodes are supported as the transformer node.

Configure the transformer

The transformer must be configured with the services that allow it to contact your security scanner, ingest scan data, and transform that data into a format that PE can read and display. Configuration is specific to the transformer you are using, and may relate to functions such as the reading and processing of scan data, API querying, etc, For an example of transformer configuration, see the Parameters information in the Example implementation: Nessus transformer section.

Run the transformer task

Transformer operation is via a Puppet Enterprise task that runs on the transformer node. The task can run ad hoc or according to a schedule. A task for the example transformer tool provided by Perforce is included in the reference module. The task may be configured with a name such as run_<scannername>_transformer.
  1. In the PE console navigation bar, select Tasks and choose Run a task.
  2. In the Task section, enter the name of the transformer task.
  3. Select the transformer node and run the task.

Register and connect the transformer

When the transformer runs for the first time, it creates a registration request with PE. A registration request is also sent to reconnect a transformer that has been disconnected.

To register the transformer:
  1. Run the transformer task on the designated transformer node.
  2. The transformer sends a connection request.
  3. In the console, navigate to Vulnerabilities and click Accept for the registration request.

After the registration request has been accepted, data is ingested on the next transformer run.

Ingest vulnerability data

Vulnerability data from your security scanner is ingested when the transformer task runs on the transformer node. See Run the transformer task for details.
Note: Ingesting new scan data is dependent on a new scan having been completed in the scanner prior to running the transformer.

Update the vulnerability data

To load new vulnerability scan data outside of a scheduled transformer run (for example, to verify that a remediated vulnerability is no longer present), run an ad-hoc transformer task.
Note: Ingesting new scan data is dependent on a new scan having been completed by the scanner prior to running the transformer.

Disconnecting and reconnecting a transformer

To disconnect from a transformer, click Manage data integration in the Vulnerabilitiespage, choose Disconnect this transformer, and confirm when prompted.
Note: When you disconnect, scan data is no longer ingested and the vulnerability list may no longer be up to date.

To re-enable data imports, run the transformer task and accept the connection request in the Vulnerabilities screen. See Register and connect the transformer for more information.

Developing a custom transformer

This section provides reference information that is useful for developers who want to create and deploy a custom vulnerability data transformer to integrate data from a third-party scanning tool. Once the custom transformer is deployed, PE reports vulnerabilities detected on Puppet-managed nodes, allowing you to apply relevant patches for vulnerability remediation.

See below for an overview of the functions of a transformer, and information about the Puppet module that provides a reference implementation of the integration.

For an overview of vulnerability remediation capabilities in PE, see Vulnerability remediation.

For an overview of data integration requirements, see Integrate vulnerability data from a security scanner.

Essential functions of a transformer

  • A trusted interface between the transformer and the third-party scanner, allowing the transformer to ingest data from the scanner. Possible implementations include passing scan report export files to the transformer or querying the scanner via an API endpoint. 
  • A system for mapping specific elements of the scanner data to their corresponding elements within PE.
  • Accurate integration with the PE environment: for example, so that PE managed nodes identified by the scanner are correctly identified in PE.
  • A trusted interface between the transformer and PE, enabling the transformer to parse scanner data, transform it into a standard format that the PE vulnerability remediation service can read, and push the data into PE.
Note: Testing and logging should be consistent with your organization’s requirements.

Example implementation: Nessus transformer

The nessus_transformer is a Puppet Enterprise module that can be installed and configured to integrate vulnerability data from Tenable Nessus™ scan reports. Alternatively, it can serve as a reference for PE customers who want to create custom vulnerability data transformers to integrate data from other security scanners. The module is available for download from the Puppet Forge and can be deployed in PE by customers who have enabled the Advanced Patching feature. Information about the Nessus security scanner is provided by Tenable at Tenable Nessus Documentation | Tenable™ .

Methods of accessing scan export files

You can configure the transformer to access scan data using either of the following methods:

  • Reading from a directory: The transformer accesses the latest scan export file downloaded to a specified directory.
  • Querying the Nessus API: The transformer reads the latest scan export file provided directly by the Nessus API.
Modes of operation

The transformer can operate in two modes: 

  • On-demand data ingestion: Manually initiate the transformer by running a task in PE. 

  • Scheduled data ingestion: Automatically initiate data ingestion by configuring the transformer to run on a predefined schedule.

Depending on the chosen method of access, the transformer either queries the Nessus API or reads the latest export file from a directory.

Requirements

  • Python

  • SystemD Service and Timer for scheduling capabilities

Installation and registration

Refer to the module’s installation instructions on Puppet Forge for information on access and other requirements.

To use the transformer in Puppet Enterprise, classify a node in PE to act as the transformer. When the Puppet agent runs on this node, it installs the transformer.

When the transformer first runs on the node, either as a task or according to a schedule, it creates a registration request with PE. This must be accepted in the PE UI to allow data ingestion.

After the registration request has been accepted, data is ingested on the next transformer run.

Security

Endpoints are secured via RBAC and https.

The connection between the transformer node and the PE node must remain active for long enough to complete the ingestion of data. The time required depends on transformer speed and the volume of data being transferred.

To help prevent Denial of Service (DoS) attacks and similar threats, data is ingested from only one scan export file at a time, and the same scan results cannot be ingested multiple times.

Parameters

The transformer is configured with parameters that determine how it handles functions such as file reading (directory location, file processing criteria, etc.) and API querying (polling frequency, credentials etc.).
Note: Encrypt string values for sensitive parameters via hiera-eyaml. Create hiera-eyaml keys if not already generated on your PE Instance.

Node encrypt may be used as an optional extra layer of security. If you want to use node encrypt and the node_encrypt module is not already available, install puppetlabs-node_encrypt to be used on your CA or any compile server.

Parameters Description
pe_token

Sensitive 

Required

The PE RBAC authentication token with permission to push data to the Vulnerability Remediation Service.

The transformer uses the RBAC token to register itself using the registration API. A backoff mechanism is included.

A PE Token can be generated via your puppet enterprise console.

scan_reports_source_access_key

Sensitive 

Required when configuring the transformer to query the Nessus API to download the latest scan data.

Authentication access key for the scanner endpoint.

If required, the key can be generated on your Tenable Nessus Instance. 

scan_reports_source_secret_key

Sensitive 

Required when configuring the transformer to query the Nessus API to download the latest scan data.

Authentication secret key for the scanner endpoint.

If required, the key can be generated on your Tenable Nessus instance. 

scan_reports_source_ca_certificate

Sensitive 

The Nessus CA certificate.

May be optionally provided when configuring the transformer to query the Nessus API to download the latest scan data.

scan_reports_source_address The FQDN/IP address used by Nessus.
scan_reports_source_filepath

Required when configuring the transformer to read scan data from a manually downloaded export file.

The path to the scanner report export directory to which the Nessus scan data has been downloaded.
manage_python Determines if the module manages the installation of Python. When set to No, the existing Python setup is used.
run_in_venv Run the transformer within a Python virtual environment.
sync_schedule Schedule string in SystemD Timer format. Configures the transformer to run to a specific schedule.
python_version The version of python to be installed. If not specified, the transformer uses latest version available on the machine through the default package managers.
scan_reports_source_port Port Number used by Nessus.
scan_reports_destination_endpoint URL to the Vulnerability Remediation Service ingestion endpoint
scan_name The name of the specific scan for which data is to be processed by the transformer. A list of all named scans is provided in the Nessus UI.
Note: The scan_reports_source_filepath cannot be specified at the same time as scan_reports_source_address, scan_reports_source_access_key and scan_reports_source_secret_key, as they relate to different modes of operation.
Was this page helpful?