nexpose_cyberark 0.0.5-java → 0.0.7-java

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    MDIzMGQ4MWQxMmJhYTEwYWUyNjI2OGNjMWE5ZDllMmViZjhhMTg1Yg==
-  data.tar.gz: !binary |-
-    ZDBiNTUzMWNkOGI4OTIyOWQ4Njk2YzRmZGVjOWVkMThhNGQzNzUzNg==
+SHA1:
+  metadata.gz: 68e0232ec62a2c5b8577a31de453c00a2de0b16d
+  data.tar.gz: 20c1ac8801f2d86785cc06be593ca95c35430c0e
 SHA512:
-  metadata.gz: !binary |-
-    NTlkNTI2MTdlOWUyZDdmZjg3NWE3YjQ2OThhZDVlZjA0M2ViMDNiMmVhODQz
-    M2ZkYWU3NWI2M2JiMmZmNmQ4YzFjNDc1ZDQyNDkyYjM4N2Y3M2I0YTZlOGUz
-    M2ExYmFiZDJlMTQ0YTQ4MjAzMzViZjEzNmNmYzE3NzU3OGM1YmY=
-  data.tar.gz: !binary |-
-    ZTA1NmVmOTc4Y2RhZWVlZTcxODQ1MzA3ODE3MDBjNjc4NzUwODM0N2Q5ZmY1
-    NjhjOWEyMjA5ODBmZWU4ZjM2ZDMxMmE1ZjdiY2VkNWE3NzZjNDllZmU1NjVl
-    MDY2NDczZDYxNjYxNDM2MTljYjk4MDM2ZDczOTQwYzU1YjU3ZDA=
+  metadata.gz: 68a621af64dc0b8e4e8ff251c920ff10c26345a5c19e4632fd745a4ee21b32cfd0dd7a2e8c2613b77b8de77f5bb6d6950dd4853b74418cc515ffc02edc7a955f
+  data.tar.gz: 73768b500ae65ac6c9d05dc3b314cc036201a1aeaba6b8595c81f92b040d741e75b6c30e5d97f281efdc10fa9e1f788d6835ae2ea464cb245079e7fd45624ee8

data/README.md

@@ -1,33 +1,93 @@
-# NexposeCyberark
+# Nexpose Cyberark Integration
 
-The nexpose CyberArk integration allows the use of credentials stored in CyberArk Vault to be used in scanning jobs,
-allowing Nexpose to perform authenticated scans, increasing the confidence in fingerprinting and vulnerabilities found.
+This is the official gem package for the **JRuby Nexpose Cyberark Integration**
+
+For assistance with using the gem please email the Rapid7 integrations support team at <support@rapid7.com>
+
+## About
+
+Application Identity Manager is designed to randomize and store the passwords for accounts on target systems on a regular recurring basis. Because these passwords are stored and managed by the vault, they can be retrieved via an authorised partner provided Java SDK.  
+
+This integration is designed to import credentials for assets, stored in a password Vault in CyberArk, to enable the Nexpose Console to conduct authenticated scans. 
+
+The nexpose_cyberark integration contains functionality to start a scan automatically after loading credentials into Nexpose. This feature can be disabled from within the configuration file.
+
+Below is a brief description of the two options:  
+
+* 'Y' (Yes) - The integration will retrieve the credentials for the assets to be scanned. These credentials are stored in Nexpose and a scan is started, with these credentials being available. Once the scan is completed, the credentials are removed from Nexpose. 
+* 'N' (No) -­ The integration will retrieve the credentials for the assets to be scanned. These credentials are then stored as part of the site authentication information in Nexpose. The program will then exit. This mode does not delete credentials upon completion, but leaves the credentials in Nexpose for use during the next scan. These will need to be manually removed by the user, or will be removed automatically when the integration is used again.  
+This mode is useful for loading credentials into Nexpose for use in scheduled scans.
 
 ## Installation
 
-This is a JRuby Gem, it uses CyberArk's Java libraries to perform queries on CyberArk's vaults and Ruby libraries to
-communicate with Nexpose. As such, JRuby needs to be installed on the target system.
+This is a JRuby Gem, it uses CyberArk's Java libraries to perform queries on CyberArk's vaults and Ruby libraries to communicate with Nexpose. As such, JRuby needs to be installed on the target system.
+
+The following link shows the different options for installing JRuby on several platforms:  
+
+<http://jruby.org/>
+
+RubyGems is the other prerequisite for using nexpose_cyberark. After successfully installing the JRuby interpreter, install RubyGems. 
+The following link shows the different options for installing RubyGems in several platforms: 
+ 
+<http://rubygems.org/>
+
+#### BEFORE INSTALLATION:
+
+* Install CyberArk's provided Password SDK Client on the system. Please refer to Cyberark documentation for installation and configuration of the Password SDK
+* Once installed and configured we must go to out Vault and make sure the assets have the following characteristics: 
+	1. Naming in CyberArk 
+   For credentials to be imported successfully into Nexpose from CyberArk, they must be commonly named so they can be resolved to a unique asset. 
+   The nexpose_cyberark integration currently supports the following naming conventions in both Nexpose and CyberArk:
+   
+   		* The full-­qualified domain name of the asset.  
+   		* The IP address of the asset.  
+   		
+   		The integration is able to resolve a domain name from an IP address, and vice versa, allowing flexibility when creating and naming objects in the CyberArk vault. This will also allow flexibility when adding assets to a site and storing credentials within the vault. 
+   IP ranges are also supported when scanning a site -­ the integration will correctly resolve and load credentials for the assets in the range.  
+   _Note_: please ensure the host system of the integration has correctly configured DNS settings to allow the resolution of IP/FQDNs. 
+	2. The policy ID of the Object needs to be entered into the configuration file of the integration (see below). Policy IDs must uniquely point to either the 'Unix' OS or 'Windows' OS which tie to the authentication method Nexpose uses to conduct an authenticated scan (SSH or SMB/CIFS) 
+   The APP ID, Safe and Folder names are required to fully configure the integration. Please refer to CyberArk documentation for more information and make a note of these. 
+
+After installing Ruby and RubyGems, install nexpose_cyberark by opening a command prompt or terminal window with JRuby and RubyGems added to the PATH and run the following command: 
+
+```ruby 
+gem install nexpose_cyberark 
+```
+
+This command will install the CyberArk Integration Gem and all necessary prerequisites.
+
+#### Configuring the CyberArk Gem
+
+Once all dependencies have been installed, the configuration files need to be edited with the details of the target CyberArk Instance. To insert the details, open the configuration file under the config folder found in the Gem installation:  
+
+* Windows: C:\JRuby\<version\>\lib\ruby\gems\shared\gems\nexpose_cyberark-­\<version\>-java\lib\nexpose_cyberark\config  
+* Linux: /var/lib/gems/\<version\>/gems/nexpose_cyberark-­\<version\>-­java/lib/nexpose_cyberark/config  
+
+Your installation folder may differ; please refer to the Ruby documentation for the specific location.
+
+To finish configuration, the following environment variables must be setup on the host:
+
+| ENV_VAR          | Description   			            | Sample Value|
+| ---------------- |:----------------------------------:| -----------:|
+| NEXPOSE_URL      | Address of Nexpose Server          | 127.0.0.1   |
+| NEXPOSE_USERNAME | User with site and scan credentials| JBloggs     |
+| NEXPOSE_PASSWORD | Password for user                  | Password    |
+| NEXPOSE_PORT     | Nexpose port                       | 3780        |
 
-BEFORE INSTALLATION:
-* Install CyberArk's provided Password SDK Client on the system
-* Configure CyberArk vault Objects to match Nexpose scan targets:
-    For example if a Nexpose hostname is in the form of 'systemv6.mydomain.com' your Object must be 'systemv6.mydomain.com'
-    If the scan target is an IP address, the object name must be the IP address.
-* Make sure the Policy ID of your objects include the description of the OS: 'unix' or 'windows'
+Please ensure the environment variables are named **_exactly_** as above
 
 ## Usage
 
- 	Configure Vault settings:
-o	APP ID, Safe, Folder properties from CyberArk. Please refer to CyberArk documentation.
- 	Configure Nexpose settings:
-o	A valid nexpose user, password, ip address and sites to manage.
-o	The start scan variable. If set to true, once updated the gem will trigger a scan of the site, wait until it’s finished and deletes the credentials stored. If set to false, it’ll not kick a scan and will run on scheduled.
- 	Run the script for the first time.
-o	The script can be run using the command from the command line:
-             jruby nx_cyberark.rb
-o	The script will run and perform the queries, if the start scan variable is set to false, the script will exit silently; otherwise the script will output the status of each scan
+Assuming the Nexpose and CyberArk parameters are correctly configured, issue the command: 
 
+```ruby 
+jruby nx_cyberark.rb 
+```
 
-## Help
+from a command / bash shell within the "bin" folder of the Gem. Every time this command is executed, the service will query the site on Nexpose to retrieve the assets to be scanned, query CyberArk for the correct credentials for the assets and return them to Nexpose to validate the scan.  
+The script will run and perform the queries: if the start_scans variable is set to false, the script will exit silently, leaving the 
+credentials in Nexpose for use in the next scan; otherwise the script will output the status of each scan performed and 
+remove the credentials from Nexpose upon completion. 
 
-* Email us to integrations_support@rapid7.com
+Note: Passwords stored in CyberArk can be rotated before a scan is initiated. Make sure to properly synchronise the 
+scanning window with your password rotations.

data/lib/nexpose_cyberark.rb

@@ -3,7 +3,7 @@ require 'nexpose_cyberark/password_ops'
 require 'nexpose_cyberark/nexpose_ops'
 require 'nexpose_cyberark/version'
 require 'waitutil'
-require 'Resolv'
+require 'resolv'
 
 module NexposeCyberark
   module Vault
@@ -11,8 +11,12 @@ module NexposeCyberark
     def self.update_credentials(vault_options, nexpose_options = nil)
       #Setup logger
       @log = NexposeCyberark::NxLogger.instance
-      @log.setup_logging(nexpose_options[:logging] || true, nexpose_options[:log_level] || 'info')
-      @log.setup_statistics_collection(NexposeCyberark::VENDOR, NexposeCyberark::PRODUCT_NAME, NexposeCyberark::VERSION)
+
+      log_enabled = nexpose_options[:logging].downcase.start_with? 'y'
+      @log.setup_statistics_collection(NexposeCyberark::VENDOR, 
+                                       NexposeCyberark::PRODUCT_NAME, 
+                                       NexposeCyberark::VERSION)
+      @log.setup_logging(log_enabled, nexpose_options[:log_level] || 'info')
 
       @nx = Ops::Nexpose.new(nexpose_options[:nxip], nexpose_options[:nxport], nexpose_options[:nxuser], nexpose_options[:nxpassword])
       @log.log_message('Connection to the Nexpose console complete!')

data/lib/nexpose_cyberark/nexpose_ops.rb

@@ -7,7 +7,7 @@ module Ops
     def initialize(nxip, nxport, nxuser, nxpasword)
       @log = NexposeCyberark::NxLogger.instance
       @log.log_message('Connecting to the Nexpose console..')
-      @nsc = Connection.new(nxip, nxuser, nxpasword)
+      @nsc = Connection.new(nxip, nxuser, nxpasword, nxport)
       @nsc.login
       @log.on_connect(nxip, nxport, @nsc.session_id, '{}')
     end
@@ -97,4 +97,4 @@ module Ops
       status
     end
   end
-end
+end

data/lib/nexpose_cyberark/nx_logger.rb

@@ -6,27 +6,23 @@ require 'singleton'
 module NexposeCyberark
   class NxLogger
     include Singleton
-    attr_accessor :options, :statistic_key, :product, :logger_file
     LOG_PATH = "./logs/rapid7_%s.log"
     KEY_FORMAT = "external.integration.%s"
     PRODUCT_FORMAT = "%s_%s"
 
     DEFAULT_LOG = 'integration'
-    PRODUCT_RANGE = 3..30
+    PRODUCT_RANGE = 4..30
     KEY_RANGE = 3..15
 
     ENDPOINT = '/data/external/statistic/'
 
     def initialize()
-      @logger_file = get_log_path product
+      create_calls
+      @logger_file = get_log_path @product
       setup_logging(true, 'info')
     end
 
     def setup_statistics_collection(vendor, product_name, gem_version)
-      #Remove illegal characters
-      vendor.to_s.gsub!('-', '_')
-      product_name.to_s.gsub!('-', '_')
-
       begin
         @statistic_key = get_statistic_key vendor
         @product = get_product product_name, gem_version
@@ -35,47 +31,43 @@ module NexposeCyberark
       end
     end
 
-    def setup_logging(enabled, log_level = nil)
-      unless enabled || @log.nil?
-        log_message('Logging disabled.')
-        return
-      end
+    def setup_logging(enabled, log_level = 'info', stdout=false)
+      @stdout = stdout
 
-      @logger_file = get_log_path product
+      log_message('Logging disabled.') unless enabled || @log.nil?
+      @enabled = enabled
+      return unless @enabled
+
+      @logger_file = get_log_path @product
 
       require 'logger'
       directory = File.dirname(@logger_file)
       FileUtils.mkdir_p(directory) unless File.directory?(directory)
-      io = IO.for_fd(IO.sysopen(@logger_file, 'a'))
+      io = IO.for_fd(IO.sysopen(@logger_file, 'a'), 'a')
       io.autoclose = false
       io.sync = true
       @log = Logger.new(io, 'weekly')
-      @log.level = if log_level.casecmp('info') == 0
-                     Logger::INFO
+      @log.level = if log_level.to_s.casecmp('info') == 0 
+                     Logger::INFO 
                    else
                      Logger::DEBUG
                    end
       log_message("Logging enabled at level <#{log_level}>")
     end
 
-    # Logs an info message
-    def log_message(message)
-      @log.info(message) unless @log.nil?
-    end
-
-    # Logs a debug message
-    def log_debug_message(message)
-      @log.debug(message) unless @log.nil?
-    end
-
-    # Logs an error message
-    def log_error_message(message)
-      @log.error(message) unless @log.nil?
+    def create_calls
+      levels = [:info, :debug, :error, :warn]
+      levels.each do |level|
+        method_name = 
+        define_singleton_method("log_#{level.to_s}_message") do |message|
+          puts message if @stdout
+          @log.send(level, message) unless !@enabled || @log.nil?
+        end
+      end
     end
 
-    # Logs a warn message
-    def log_warn_message(message)
-      @log.warn(message) unless @log.nil?
+    def log_message(message)
+      log_info_message message
     end
 
     def log_stat_message(message)
@@ -92,13 +84,28 @@ module NexposeCyberark
         return nil
       end
 
+      vendor.gsub!('-', '_')
+      vendor.slice! vendor.rindex('_') until vendor.count('_') <= 1
+
+      vendor.delete! "^A-Za-z0-9\_"
+
       KEY_FORMAT % vendor[0...KEY_RANGE.max].downcase
     end
 
     def get_product(product, version)
-      return nil if (product.nil? || version.nil?)
+      return nil if ((product.nil? || product.empty?) || 
+                     (version.nil? || version.empty?))
+
+      product.gsub!('-', '_')
+      product.slice! product.rindex('_') until product.count('_') <= 1
+
+      product.delete! "^A-Za-z0-9\_"
+      version.delete! "^A-Za-z0-9\.\-"
+
       product = (PRODUCT_FORMAT % [product, version])[0...PRODUCT_RANGE.max]
 
+      product.slice! product.rindex(/[A-Z0-9]/i)+1..-1
+
       if product.length < PRODUCT_RANGE.min
         log_stat_message("Product length below minimum <#{PRODUCT_RANGE.min}>.")
         return nil
@@ -107,9 +114,12 @@ module NexposeCyberark
     end
 
     def generate_payload(statistic_value='')
-      payload = {'statistic-key' => @statistic_key,
-                 'statistic-value' => statistic_value,
-                 'product' => @product}
+      product_name, separator, version = @product.to_s.rpartition('_')
+      payload_value = {'version' => version}.to_json
+
+      payload = {'statistic-key' => @statistic_key.to_s,
+                 'statistic-value' => payload_value,
+                 'product' => product_name}
       JSON.generate(payload)
     end
 
@@ -126,6 +136,7 @@ module NexposeCyberark
       log_stat_message "Received code #{response.code} from Nexpose console."
       log_stat_message "Received message #{response.msg} from Nexpose console."
       log_stat_message 'Finished sending statistics data to Nexpose.'
+
       response.code
     end
 
@@ -137,7 +148,7 @@ module NexposeCyberark
         log_stat_message('Statistics collection not enabled.')
         return
       end
-
+      
       begin
         payload = generate_payload value
         send(nexpose_address, nexpose_port, session_id, payload)
@@ -146,5 +157,10 @@ module NexposeCyberark
       end
     end
 
+    #Used by net library for debugging 
+    def <<(value)
+      log_debug_message(value)
+    end
+
   end
 end

data/lib/nexpose_cyberark/version.rb

@@ -1,5 +1,5 @@
 module NexposeCyberark
-  VERSION = "0.0.5"
+  VERSION = "0.0.7"
   VENDOR = "Cyberark"
   PRODUCT_NAME = "nexpose_cyberark"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexpose_cyberark
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: java
 authors:
 - Damian Finol
@@ -9,82 +9,82 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-11 00:00:00.000000000 Z
+date: 2016-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.4'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
 - !ruby/object:Gem::Dependency
   name: nexpose
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
 - !ruby/object:Gem::Dependency
   name: waitutil
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
 description: Nexpose Cyberark integration provides credentials for authenticated scans
   in Nexpose.
 email:
-- integrations_support@rapid7.com
+- support@rapid7.com
 executables:
 - nx_cyberark.rb
 extensions: []
@@ -112,18 +112,19 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.3
 signing_key: 
 specification_version: 4
 summary: Nexpose Cyberark integration.
 test_files: []
+has_rdoc: