nexpose_sccm 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 05d535cae6251874a19e668e8f19fead29309377
+  data.tar.gz: fd671a1b752549f983b6c3e85d47e8f57920a15f
+SHA512:
+  metadata.gz: d833ae2f1444db55e6daae56a5b4bccc10feeb2d93ced13a1e4d8a8a3de1ad67d1210f142257559555b63f0fbe9bf0958aac4cb838208fa152fe60a94074e382
+  data.tar.gz: 1bb2ee97958b404fbad16459389c966046cd241675c487e877e381e36b84ddb01f1ed3c1c88d80190bdfe8246c469fffd3476f83655a230968af191896f27eb1

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+gem 'winrm'
+
+group :nexpose, optional: true do
+  gem 'nexpose'
+end
+
+group :dwh, optional: true do
+  ## May need to install postgres drivers before the gem
+  gem 'pg'
+end
+
+# Specify your gem's dependencies in nexpose_servicenow.gemspec

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Adam Robinson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,212 @@
+# 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](https://rapid7support.force.com/customers/login)
+
+## 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: 
+
+```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:
+
+```bash
+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 
+```bash
+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:
+
+```bash
+bundle package
+```
+Then copy the directory to the offline system and install dependencies followed by bundle install:
+
+```bash
+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`
+
+### <Pending Windows Instructions>
+
+## 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
+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:
+
+```bash
+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](https://blogs.technet.microsoft.com)  
+
+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 support@rapid7.com
+
+## 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

data/bin/encrypt_settings.rb

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'openssl'
+require 'io/console'
+require 'base64'
+require 'fileutils'
+require 'yaml'
+require 'nexpose_sccm/utilities/utility_config'
+
+SETTINGS_LOCATIONS = [File.join(File.dirname(__FILE__), '../conf/'),
+                      File.join(File.dirname(__FILE__), '/'),
+                      '/opt/rapid7/nexpose/scripts/',
+                      'C:\\program files\\rapid7\\nexpose\\scripts\\']
+
+options = {}
+ops = OptionParser.new do |opts|
+  opts.banner = "Usage: #{$0} [options]\n"
+
+  opts.on('-s SETTINGS', '--settings SETTINGS', 'Path to settings directory with yml files') do |config|
+    options[:config_location] = config
+  end
+
+  opts.on('-h', '--help', 'Show this message') do
+    puts opts.help
+    exit
+  end
+end
+
+# Prompt function
+def prompt(pwd, default, *args)
+  begin
+    print(*args)
+    result = ""
+    if pwd
+      result = STDIN.noecho(&:gets).strip
+      print("\n")
+    else
+      result = gets.strip
+    end
+    if (result.empty? || result.nil?) && (default.nil? || default.empty?)
+      raise
+    end
+  rescue
+    retry
+  end
+  return result.empty? ? default : result
+end
+
+# Create directory function - careful as this will attempt to create
+# parent directories that do not exist as well.
+def create_dir(path, mode=nil)
+  FileUtils.mkdir_p(path) unless File.exist?(path)
+  FileUtils.chmod(mode, path) unless mode.nil?
+end
+
+begin
+  ops.parse! ARGV
+rescue OptionParser::InvalidOption => error
+  puts "Error encountered. Details: #{error}\n\n#{ops}"
+  exit 1
+end
+
+settings = UtilityConfig.load_config(SETTINGS_LOCATIONS,
+                                     options[:config_location])
+
+unless settings.key?(:secret)
+  puts "The secret.yml file in the chosen / default location must be populated."
+  exit 0
+end
+
+to_encrypt = {}
+
+# Read in settings.yml to identify what to encrypt; will begin with (enc)
+settings.each do |key, value|
+  to_encrypt[key] = {} # unless key.to_s.eql?('secret')
+  value.each do |k, v|
+    if v.to_s.start_with?('(enc)')
+      to_encrypt[key][k] = v.sub('(enc)', '')
+      settings[key][k] = 'secret'
+    elsif v.class == Hash
+      v.each do |k2, v2|
+        if v2.to_s.start_with?('(enc)')
+          to_encrypt[key][k] = {} if to_encrypt[key][k].nil?
+          settings[key][k] = {} if settings[key][k].nil?
+
+          to_encrypt[key][k][k2] = v2.sub('(enc)', '')
+          settings[key][k][k2] = 'secret'
+        end
+      end
+    end
+  end
+end
+
+if settings.key?(:secret)
+  if File.exist?(settings[:secret][:encrypt_key_dir]) && File.exist?(settings[:secret][:encrypt_cred_file])
+    priv_key = OpenSSL::PKey::RSA.new(File.read(File.join(settings[:secret][:encrypt_key_dir], 'rsa_key')))
+    dec_buf = priv_key.private_decrypt(Base64.decode64(File.read(settings[:secret][:encrypt_cred_file])))
+    current_settings = YAML::load(dec_buf)
+    current_settings.each do |k, v|
+      if to_encrypt.key?(k)
+        if to_encrypt[k].nil? || to_encrypt[k].empty?
+          to_encrypt[k] = v
+        end
+      end
+    end
+  end
+end
+
+# Assign directories.  Make sure nxkeys is 700 permissions
+# and the tree is owned by either root or the owner of the key file.
+priv_dir = prompt(false, settings[:secret][:encrypt_key_dir], "Keys directory (default - #{settings[:secret][:encrypt_key_dir]}): ")
+secret_file = prompt(false, settings[:secret][:encrypt_cred_file], "Encrypted settings file (default - #{settings[:secret][:encrypt_cred_file]}): ")
+
+create_dir(priv_dir, 0700)
+
+# Update and save settings.yml
+UtilityConfig.save_encrypt(SETTINGS_LOCATIONS, options[:config_location])
+
+# Protected private key file
+priv_file = File.join(priv_dir, 'rsa_key')
+
+# Generate private key and write to file.
+rsa_key = OpenSSL::PKey::RSA.new(4096)
+File.open(priv_file, 'w') {|file| file.write(rsa_key)}
+FileUtils.chmod(0600, priv_file)
+puts "Private key created."
+# Generate public key from private key used to encrypt the credential YAML.
+pub_key = rsa_key.public_key
+
+# Encrypt then encode necessary settings
+enc_creds = Base64.encode64(pub_key.public_encrypt(to_encrypt.to_yaml))
+File.open(secret_file, 'w') {|file| file.write(enc_creds)}
+FileUtils.chmod(0750, secret_file)
+puts "Created encrypted credentials at #{secret_file}"

data/bin/nexpose_sccm

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+require 'csv'
+require 'base64'
+require 'openssl'
+require 'optparse'
+require 'yaml'
+require 'nexpose_sccm'
+
+# module WinRM
+#   module HTTP
+#     # A generic HTTP transport that utilized HTTPClient to send messages back and forth.
+#     # This backend will maintain state for every WinRMWebService instance that is instantiated so it
+#     # is possible to use GSSAPI with Keep-Alive.
+#     class HttpTransport
+#       def verify_ssl_fingerprint(cert)
+#         return unless @ssl_peer_fingerprint
+#         conn_fingerprint = OpenSSL::Digest::SHA1.new(cert.to_der).to_s
+#         puts @ssl_peer_fingerprint
+#         puts conn_fingerprint
+#         return unless @ssl_peer_fingerprint.casecmp(conn_fingerprint) != 0
+#         raise "ssl fingerprint mismatch!!!!\n"
+#       end
+#     end
+#   end
+# end
+
+# Allow for override of options; -s leverage for settings directory location
+@options = {}
+
+ops = OptionParser.new do |opts|
+  opts.banner = 'Usage: nexpose_sccm [options]'
+  opts.on('-s SETTINGS', '--settings SETTINGS', 'Path to settings directory with yml files') do |config|
+    @options[:config_location] = config
+  end
+
+  opts.on('-i INPUT_FILE', '--input INPUT_FILE', 'Path to input file leveraged by query') do |config|
+    @options[:input_file_location] = config
+  end
+
+  opts.on("-h", "--help", "Show this message") do
+    puts opts
+    exit 0
+  end
+
+  opts.on_tail("--version", "Show version") do
+    puts "\nnexpose_sccm v#{NexposeSCCM::VERSION}"
+    exit
+  end
+end
+
+begin
+  ops.parse! ARGV
+rescue OptionParser::InvalidOption => error
+  puts "Error encountered. Details: #{error}\n\n#{ops}"
+  exit 1
+end
+
+SETTINGS_LOCATIONS = [File.join(File.dirname(__FILE__), '../conf/'),
+                      File.join(File.dirname(__FILE__), '/'),
+                      '/opt/rapid7/nexpose/scripts/',
+                      'C:\\program files\\rapid7\\nexpose\\scripts\\']
+
+# Load settings from -s option or parse known locations for configuration file
+settings = UtilityConfig.load_config(SETTINGS_LOCATIONS,
+                                     @options[:config_location])
+settings = UtilityConfig.load_encrypt(settings)
+
+NexposeSCCM.setup(settings)
+NexposeSCCM.generate_updates(settings, @options[:input_file_location])