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
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:
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.
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.
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.
bundle install --with nexpose dwh
On a system with internet access and a similar setup to the final install location, run the following command from within the gem folder:
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
Configuration files for the nexpose_sccm integration can be found under
There are several files located here that need populated:
logging.ymlThis file contains logging settings for the integration
nexpose.ymlThis file contains the Nexpose connection settings
postgres.ymlThis file contains the Data Warehouse connection settings
queries.ymlThis file contains the queries used by the integration. Please see below for more information
sccm.ymlThis file contains settings for the operation of the integration, as well as the SCCM connection settings
secret.ymlThis 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:
|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
Nexpose SCCM settings
These settings are found at the bottom of the
sccm.yml file. A brief explanation of each can be found below:
|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
|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|
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
: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:
|key||Yes||This column makes an easy identifier for creating Software Update Groups or Collections. It is the default value listed in the
|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|
In order to asymmetrically encrypt sensitive data in the configuration files, perform the following:
- Identify the values to be encrypted and prefix them with
- Ensure the
:secretsection is also defined in
secret.ymlwith 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:
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
Like the main integration, the configuration file location can be passed using the
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:
The following options can be used with the integration:
|--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|
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
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.
download_updates is set to true then downloaded updates will also be found at the
staging location set in the
Please check the log files located at
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.
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
For further issues, please contact the Rapid7 support team at [email protected]
- 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