Nexpose SCCM Integration

This is the offical gem package for the Ruby Nexpose SCCM integration.

For assistance with using the gem, please contact the Rapid7 Integrations support team using the Rapid7 Support Portal

About

The nexpose_sccm integration is designed to pull vulnerability and solution data from Nexpose scan results, to then generate SCCM Software Update Groups and Collections based upon the data. These groups can then be used to deploy software updates to assets, enabling partial automation of the process.

Example queries to retrieve data from Nexpose have been provided, with the option for the user to supply different variations instead.
The integration supports retrieving data from the Nexpose Console or via a separate DataWarehouse installation.

The integration provides options to create Deployment Packages on the SCCM server, as well as generate a CSV report of assets found in Nexpose, but currently unknown or not managed by SCCM.

NOTE: Requires SCCM 1702 or later for Deployment Package functionality. It is possible to gather the version of SCCM by running the following command in Powershell: 

Get-ItemProperty HKLM:\\SOFTWARE\\Microsoft\\SMS\\Setup

Ruby Version [>= 2.3.1, < 2.5.0]

For more information please refer to the integration documentation which can be requested from the Rapid7 support team.

Installation

RubyGems (preferred)

With the correct Ruby version available, run the following command from the command line:

gem install nexpose_sccm

This will also download and install the required dependencies.

Bundler

Using the Bundler gem, the integration can be installed or packaged to be installed on a system with no Internet access.

Choose between using the Nexpose Console or a Data Warehouse for data export.

Online
bundle install --with nexpose dwh
Offline

On a system with internet access and a similar setup to the final install location, run the following command from within the gem folder:

bundle package

Then copy the directory to the offline system and install dependencies followed by bundle install:

apt install ruby ruby-dev ruby-bundler libpq-dev build-essential
bundle install --local --with nexpose dwh

The required gems are located under nexpose_sccm/vendor/cache

Configuration

Configuration files for the nexpose_sccm integration can be found under nexpose_sccm/conf/

There are several files located here that need populated:

  • logging.yml This file contains logging settings for the integration
  • nexpose.yml This file contains the Nexpose connection settings
  • postgres.yml This file contains the Data Warehouse connection settings
  • queries.yml This file contains the queries used by the integration. Please see below for more information
  • sccm.yml This file contains settings for the operation of the integration, as well as the SCCM connection settings
  • secret.yml This file contains settings for the in-built encryption functionality (optional)

Windows and SCCM Permissions

The user account running the integration should preferably be a Windows Domain account.
It needs to be added to the Remote Management Users group on the SCCM server.
It also needs to be added as an "Administrative User" in the SCCM Console.
The Security role for this user should be a custom role based on the pre-existing "Read-Only Analyst", with the following additional permissions:

Permission Group Permissions
Collection Create, Delete Resource, Modify, Modify Resource, Read, Read Resource, Remote Control, View Collected File
Software Update Group Create, Modify, Read
Software Update Package Create, Modify, Read

This user may also need to log into the SCCM Console to activate the account.

For WinRM access from the host machine to the SCCM server, ports 5985 (HTTP) or 5986 (HTTPS) will need to be opened in the Firewall.
For HTTPS communication between the host machine and the SCCM server, a HTTPS listener will need to be created. The SSL Peer Fingerprint can then be retrieved by running the command in the sccm.yaml file.

Nexpose SCCM settings

These settings are found at the bottom of the sccm.yml file. A brief explanation of each can be found below:

Setting Description
create_deployment_package Set to true to create Deployment Packages based on the generated Software Update Groups. This leverages staging configuration for where software updates are downloaded
download_updates Set to true to have SCCM download updates for the deployment package in scope. This setting will not be used if create_deployment_package is false
integration_prefix The prefix used for all Software Update Groups, Collections and Deployment Package names
generate_unknown_device_report Set to true to generate a CSV report of devices found in Nexpose, but unknown to SCCM
report_location Absolute or relative location of directory where reports should be saved
scope The query to run from queries.yml - must match the name in the file
action Can be set to either update or create for generating objects in SCCM. Recommended to leave as update to avoid creating large numbers of objects
data_source Defines where vulnerability and solution data is pulled from - set nsc for the Nexpose Console, dwh for a Data Warehouse
software_update_group_key The name of the SQL query column used for grouping and generating Software Update Groups
collection_key The name of the SQL query column used for grouping and generating Collections

Nexpose Queries

The queries.yml file can be modified to include customised queries. These should be tested in the Reports section of the Nexpose Console or against the Data Warehouse before use.
The query should be named following the convention shown for existing queries. It should also be under :nsc: or :dwh: depending on which Data Source it is to run against, following the YAML indentation rules.

Values can be inserted into queries at runtime - either from a file or a user prompt. The asset_best_solution_by_site query shows an example of this for a single value, whereas the vuln_by_id query demonstrates this for two lists. See the vuln_ids.csv file for an example of passing values in by file.

Any column can be used in the query as the key for either Software Update Groups or Collections - they do not need to be the same column, nor marked with the "key" identifier.
Below is a list of required or recommended columns for creating a query:

Column Required Description
key Yes This column makes an easy identifier for creating Software Update Groups or Collections. It is the default value listed in the sccm.yml file. This can be any column the user wishes to group on e.g. when running the integration, you could group Collections by site_id, combining all assets in a site into the same Collection. However, they could then use a different column to group the Software Update Groups e.g. IP Address
ip_address Yes The IP address is used for finding matching SCCM managed devices by IP Address
host_name Yes The host name is used for finding matching SCCM managed devices by HostName
nexpose_id Yes The solution's nexpose_id is used for extracting the solution, for each vulnerability, per asset in scope. This is required for retrieving the software patches from SCCM

Encryption Settings

In order to asymmetrically encrypt sensitive data in the configuration files, perform the following:

  • Identify the values to be encrypted and prefix them with (enc) e.g. :user: '(enc)nxuser'
  • Ensure the :secret section is also defined in secret.yml with the location to store the encrypted key directory and encrypted settings file. It is important these values do not change as the integration will use them to identify how to decrypt the encrypted settings.

Once all fields expected to be encrypted have been updated, then the encrypt_settings.rb script can be used for the encryption process. Once run, the configuration files will be updated. This informs the integration to retrieve the credentials from the encrypted file:

ruby encrypt_settings.rb

It is important to remember to re-encrypt ALL configuration files if any encrypted values are updated.
To disable the use of encrypted settings, either remove or comment out the entire :secret section within secret.yml

Like the main integration, the configuration file location can be passed using the -s flag.

Usage

The executable used for initiating the integration can be found in the bin/ directory of the installed nexpose_sccm gem. With the gem installed, the integration can be called using the following command:

nexpose_sccm [options]

The following options can be used with the integration:

Option Description
--version Shows version information about the nexpose_sccm gem
-h Displays the information listed here
-s SETTINGS The path to the settings directory containing the necessary yml files. Only needed if files are stored in a chosen location
-i INPUT_FILE The path to the input file leveraged by the query. This should be in CSV format with a column for each set of input data and the headers should match the required field names. See vuln_ids.csv for an example

Validation

There are two ways to validate the successful completion of the integration.
First, verify the output of the log file or STDOUT if configured. During normal usage, the log level should be set to INFO which means only informational or error messages will be populated within the log. If any error messages are found, please review them to identify the reason for the error. A successful run should only contain INFO and/or DEBUG messages.
The log file can be found under <gem_install_location>/nexpose_sccm/lib/nexpose_sccm/logs/

In addition, once the integration has run it is possible to check the Software Update Groups, Collections, and Deployment Packages that are generated within SCCM. Once logged into the SCCM console, view each section to ensure everything is properly generated.
If download_updates is set to true then downloaded updates will also be found at the staging location set in the sccm.yml file.

Troubleshooting

Logs

Please check the log files located at <gem_install_location>/nexpose_sccm/lib/nexpose_sccm/logs/
These will output errors occurring during the normal run of the integration. Log messages will also appear here if there is an issue connecting to the SCCM server via WinRM.

Windows Issues

The integration uses WinRM and WMI to communicate with the SCCM Console, as well as to run WQL and Powershell commands. If an error occurs with this process it will be when doing the following:

  • Getting Device, Collection, Software Update Group, Software Update or Deployment Package information
  • Creating Collections, Software Update Groups or Deployment Packages

Please ensure your user has the correct permissions for these tasks.
Please ensure any local users have the correct permissions for running tasks on the SCCM console.

Information on these issues can be found on the Microsoft Technet Website

Useful logs can be found in the "Event Viewer" application on the SCCM server:

  • Windows Logs -> System
  • Application and Services -> Microsoft -> Windows Remote Management

Support

For further issues, please contact the Rapid7 support team at [email protected]

Contribution

Changelog

0.4.0

  • Adaptation from existing script into a Ruby gem
    • Restructuring file hierarcy
    • Implementing internal logger
    • Adding licensing
    • Adding a gemspec
    • Removing Bundler
    • Adding extra example queries
    • Updating README
  • Published to the RubyGems repository