boris 1.0.1 → 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5f54a0bce9420195098ba5d362bc8ba592de3b2e
+  data.tar.gz: 6e798f3e9814cd293b3f9a3ea5bceb606be21ffa
+SHA512:
+  metadata.gz: 4bbc75ecf7d833216e5dc6d8a1501ff243f489c50905a3c3f45493f49da1c1f27d20dcf9bfb122e2304aaf4d10eb72ab13f1438413dfbb38d6966a07a922758b
+  data.tar.gz: d06c12bf5cfa6b2be0d17ecfae0957d78305f05b01bed97759edb208ba39f37a8b3fe1f8eba72bb2d2f01e4b000513e1ce65c7b3504491a005d05ad52ad93803

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+# 1.0.2
+* Fix for devices asking for password when connecting via SSH
+* Fixed return value for Target#connect
+* Added #failure_message to connectors
+* Added registry subkey and value caching for WMI connections
+* Added constants for connection failures, changed logging messages for connectors
+* Changed all eval calls to Object.send
+* Various bug fixes
+
 # 1.0.1
 * Renamed Profiles to Profilers
 * Moved networking helper methods to newly created Network module

data/README.md

@@ -19,36 +19,35 @@ Out of the box, Boris has server support for Red Hat, Solaris,and Windows (with
 ## Installation
     gem install boris
 
+Or if using Bundler, add to your Gemfile
+
+    gem 'boris'
+
 ## Example
 Let's pull some information from a RedHat Enterprise Linux server on our network:
 
 ```ruby
 require 'boris'
 
-# Boris has different levels of logging.  We can optionally set our logging level, which will apply
-# to all Targets created during this session.  If not set, the log level defaults to :fatal.
 Boris.log_level = :debug
 
 hostname = 'redhatserver01.mydomain.com'
 
-# let's use a helper to suggest how we should connect to it (which is useful if we're not sure what
-# kind of device this is)
+# let's use a helper to suggest how we should connect to it (if we're not sure what kind of device this is)
 puts Boris::Network.suggested_connection_method(hostname)
 
-# you can also add the logic to make the decision yourself by checking if certain TCP ports are responsive
+# you can also add the logic to make the decision yourself
 puts Boris::Network.tcp_port_responding?(hostname, 22)
 
-# create our target
 target = Boris::Target.new(hostname)
 
-# add credentials to try against this target
 target.options.add_credential(:user=>'myusername', :password=>'mypassword', :connection_types=>[:ssh])
 
-# if this is a host using SSH, we can also pass in Net::SSH options (such as a private key for authentication).
-# SSH options passed to Boris will automatically be pushed to Net:SSH.
+# if this is a host using SSH, we can also pass in Net::SSH options (such as a private key for
+# authentication). SSH options passed to Boris will automatically be passed to Net:SSH. Likewise for
+# Net::SNMP--options passed to :snmp_options will be passed to the Net::SNMP library.
 target.options[:ssh_options] = {:keys=>['/path/to/my/private/key']}
 
-# attempt to connect to this target using the credentials we supplied above
 target.connect
 
 if target.connected?
@@ -60,9 +59,7 @@ if target.connected?
 
   # we can call individual methods to grab specific information we may be interested in
   target.get(:hardware)
-
-  # or maybe get some network interface info
-  puts target.get(:network_interfaces)
+  target.get(:network_interfaces)
 
   # retrieved items can be referenced two ways:
   puts target[:network_interfaces].inspect
@@ -73,10 +70,12 @@ if target.connected?
   target.retrieve_all
 
   # if there is more information we want to collect but is not collected by default, we can specify
-  # our own commands to run against the target via two methods: #get_values returns an Array (each
-  # line is an element of the array), or #get_value, which returns a String (the first line returned
-  # from the command)
+  # our own commands to run against the target via two methods:
+  
+  # #get_values returns an Array (each line is an element of the array)
   puts target.connector.values_at('cat /etc/redhat-release')
+
+  # #get_value, which returns a String (the first line returned from the command)
   puts target.connector.value_at('uname -a')
   
   # NOTE: if this were a Windows server, you would send WMI queries instead of shell commands, ie:
@@ -84,14 +83,81 @@ if target.connected?
   # target.connector.values_at('SELECT * FROM Win32_ComputerSystem')
   #
 
-  # finally, we can package up all of the data into json format for portability (the true argument
-  # tells the #to_json method to output the json with tabbed formatting)
   puts target.to_json(:pretty_print)
 
   target.disconnect
 end
 ```
 
+## Sample Output
+```ruby
+target.get(:hardware)
+target.get(:operating_system)
+
+target.scrub_data!
+
+puts target[:hardware]
+  #=>{
+  #    :cpu_architecture=>64,
+  #    :cpu_core_count=>2,
+  #    :cpu_model=>'AMD Opteron Processor 6174',
+  #    :cpu_physical_count=>1,
+  #    :cpu_speed_mhz=>2200,
+  #    :cpu_vendor=>'AMD, Inc.',
+  #    :firmware_version=>'6.0',
+  #    :model=>'VMware Virtual Platform',
+  #    :memory_installed_mb=>1024,
+  #    :serial=>'VMware-1234',
+  #    :vendor=>'VMware, Inc.'
+  #  }
+
+puts target[:operating_system]
+  #=>{
+  #    :date_installed=>#<DateTime: 2013-02-04T19:08:49-05:00 ((2456329j,529s,891979000n),-18000s,2299161j)>,
+  #    :features=>[],
+  #    :kernel=>'5.2.3790',
+  #    :license_key=>'BBBBB-BBBBB-BBBBB-BBBBB-BBBBB',
+  #    :name=>'Microsoft Windows',
+  #    :roles=>['TerminalServer', 'TimeServer'],
+  #    :service_pack=>'Service Pack 2',
+  #    :version=>'Server 2003 R2 Standard'
+  #  }
+```
+
+## Data
+Through a number of queries and algorithms, Boris efficiently polls devices on the network for information including, but not limited to, network configuration, hardware capabilities, installed software and services, applied hotfixes/patches, and more.
+
+**Available methods for use on most platforms include:**
+
+* **file systems** - file system, mount point, capacity and utilization
+* **hardware** - make/model, cpu information, firmware/bios version, serial number
+* **hosted shares** - folders shared by the target
+* **installed applications** - installed applications and the dates of their installation
+* **installed patches** - installed patches/hotfixes and the dates of their installation
+* **installed services/daemons** - background services and their startup modes
+* **local users and groups** - local groups and the users within each
+* **network ID** - hostname and domain
+* **network interfaces** - ethernet and fibre channel interfaces, including IPs, MAC addresses, connection status
+* **operating system** - name, version, kernel, date installed
+
+See [Boris::Profilers::Structure](http://www.rubydoc.info/github/alkalinecoffee/boris/Boris/Profilers/Structure) for more details on the data structure.
+
+Because the commands that might work correctly on one type of platform most likely won't work on another, Boris handles this by the use of...
+
+## Profilers
+Profilers contain the instructions that allow us to run commands against our target and then parse and make sense of the data.  Boris comes with the capability to communicate with targets over SNMP, SSH, or WMI.  Each profiler is written to use one of these methods of communication (internally called 'connectors'), which serve as a vehicle for running commands against a server.  Boris comes with a few profilers built-in for some popular platforms, but can be easily extended to include other devices.
+
+**Available profilers:**
+
+* **[Linux Core](http://rubydoc.info/github/alkalinecoffee/boris/master/Boris/Profilers/Linux)**
+  * [Red Hat Linux](http://rubydoc.info/github/alkalinecoffee/boris/master/Boris/Profilers/RedHat)
+* **[UNIX Core](http://rubydoc.info/github/alkalinecoffee/boris/master/Boris/Profilers/UNIX)**
+  * [Oracle Solaris](http://rubydoc.info/github/alkalinecoffee/boris/master/Boris/Profilers/Solaris)
+* **[Windows Core](http://rubydoc.info/github/alkalinecoffee/boris/master/Boris/Profilers/Windows)**
+  * [Windows 2003 Server](http://rubydoc.info/github/alkalinecoffee/boris/master/Boris/Profilers/Windows2003)
+  * [Windows 2008 Server](http://rubydoc.info/github/alkalinecoffee/boris/master/Boris/Profilers/Windows2008)
+  * [Windows 2012 Server](http://rubydoc.info/github/alkalinecoffee/boris/master/Boris/Profilers/Windows2012)
+
 ## Extending Boris
 You can also run your own commands to grab information off of systems.  For example, on a Linux device, to run your own script that is already on the target and retrieve its output:
 
@@ -104,7 +170,7 @@ multiple_lines_of_data = target.connector.values_at('/path/to/some/script')
 single_line_of_data = target.connector.value_at('/path/to/some/script')
 ```
 
-Running commands in this fashion utilizes the #exec function from Net::SSH.
+Running commands in this fashion utilizes the #exec method from the Net::SSH library.
 
 For a Windows host, which uses WMI vice SSH, you can send WMI queries or registry keys to the connector to get information:
 
@@ -112,53 +178,22 @@ For a Windows host, which uses WMI vice SSH, you can send WMI queries or registr
 # this will pull rows from a class in the standard root\CIMV2 namespace, returning an array of hashes
 multiple_rows_of_data = target.connector.values_at('SELECT * FROM Win32_NetworkAdapter')
 
-# this will pull rows from a class in the lower-level root\WMI namespace (note the second argument we're passing to #values_at):
+# this will pull rows from a class in the lower-level root\WMI namespace (note the second argument we're
+# passing to #values_at):
 multiple_rows_of_data = target.connector.values_at('SELECT * FROM MSNdis_EnumerateAdapter', :root_wmi)
 
-# you can also poll for registry keys under HKEY_LOCAL_MACHINE by providing a base key path, which returns an array of keys:
+# you can also poll for registry keys under HKEY_LOCAL_MACHINE by providing a base key path, which returns
+# an array of keys:
 registry_keys = target.connector.registry_subkeys_at('SOFTWARE\Microsoft\Windows')
 
-# and then grab values found at some key via #registry_values_at, which returns value/data elements in a Hash:
+# and then grab values found at some key via #registry_values_at, which returns value/data elements in a
+# Hash:
 registry_values = target.connector.registry_values_at('SOFTWARE\Microsoft\Windows\CurrentVersion')
 ```
 
 **Coming soon--a write-up for SNMP devices**
 
-Boris also comes with the ability to add your own complete modules for using the framework by writing your own data collection algorithms.  This will also be written up in the near future.
-
-## Data
-Through a number of queries and algorithms, Boris efficiently polls devices on the network for information including, but not limited to, network configuration, hardware capabilities, installed software and services, applied hotfixes/patches, and more.
-
-**Available methods for use on most platforms include:**
-
-* **file systems** - file system, mount point, capacity and utilization
-* **hardware** - make/model, cpu information, firmware/bios version, serial number
-* **hosted shares** - folders shared by the target
-* **installed applications** - installed applications and the dates of their installation
-* **installed patches** - installed patches/hotfixes and the dates of their installation
-* **installed services/daemons** - background services and their startup modes
-* **local users and groups** - local groups and the member users within each
-* **network ID** - hostname and domain
-* **network interfaces** - ethernet and fibre channel interfaces, including IPs, MAC addresses, connection status
-* **operating system** - name, version, kernel, date installed
-
-See {http://www.rubydoc.info/github/alkalinecoffee/boris/Boris/Profilers/Structure Boris::Profilers::Structure} for more details on the data structure.
-
-Because the commands that might work correctly on one type of platform most likely won't work on another, Boris handles this by the use of...
-
-## Profilers
-Profilers contain the instructions that allow us to run commands against our target and then parse and make sense of the data.  Boris comes with the capability to communicate with targets over SNMP, SSH, or WMI.  Each profiler is written to use one of these methods of communication (internally called 'connectors'), which serve as a vehicle for running commands against a server.  Boris comes with a few profilers built-in for some popular platforms, but can be easily extended to include other devices.
-
-**Available profilers:**
-
-* **Linux Core**
-  * Red Hat Linux
-* **UNIX Core**
-  * Oracle Solaris
-* **Windows Core**
-  * Windows 2003 Server
-  * Windows 2008 Server
-  * Windows 2012 Server
+Boris also comes with the ability to add your own complete modules for using the framework by writing your own data collection algorithms.  I will also write-up a howto in the near future.
 
 ## User Account Requirements
 While Boris does its best to gather data from devices without any special privileges, sometimes it just can't be helped.  One example of this is the RedHat profiler, which requires `sudo` access for the `dmidecode` command, as there isn't a well known, reliable way to grab this info without `dmidecode`.  If Boris attempts to run a command that requires special access and is denied, it will throw a message to the logger and move on.

data/lib/boris.rb

@@ -13,5 +13,6 @@ require 'socket'
 require 'thread'
 require 'win32ole' if PLATFORM == :win32
 
+require 'boris/helpers'
 require 'boris/lumberjack'
 require 'boris/target'

data/lib/boris/connectors.rb

@@ -12,6 +12,8 @@ module Boris
     attr_reader :host
     attr_reader :options
     attr_reader :reconnectable
+    attr_reader :failure_message
+    attr_reader :user
 
     def initialize(host, cred={})
       @logger = Boris.logger

data/lib/boris/connectors/snmp.rb

@@ -11,7 +11,7 @@ module Boris
     # @param [Hash] cred credential we wish to use
     # @param [Hash] options an optional list of options. See {Boris::Options} for a list of all
     #   possible options.  The relevant option set here would be :snmp_options.
-    def initialize(host, cred, options={})
+    def initialize(host, cred, options=Options.new)
       super(host, cred)
       @snmp_options = options[:snmp_options].merge(:host=>@host, :version=>:SNMPv1, :community=>@user)
 

data/lib/boris/connectors/ssh.rb

@@ -11,10 +11,15 @@ module Boris
     # @param [Hash] cred credential we wish to use
     # @param [Hash] options an optional list of options. See {Boris::Options} for a list of all
     #   possible options.  The relevant option set here would be :ssh_options.
-    def initialize(host, cred, options={})
+    def initialize(host, cred, options=Options.new)
       @ssh_options = options[:ssh_options]
-      @ssh_options[:password] = @password if @password
-
+      
+      @ssh_options[:auth_methods] = ['publickey']
+      if @password
+        @ssh_options[:auth_methods] << 'password'
+        @ssh_options[:password] = @password
+      end
+      
       if @ssh_options
         invalid_ssh_options = @ssh_options.keys - Net::SSH::VALID_OPTIONS
         raise ArgumentError, "invalid ssh option(s): #{invalid_ssh_options.join(', ')}" if invalid_ssh_options.any?
@@ -41,12 +46,20 @@ module Boris
         @connected = @reconnectable = true
       rescue Net::SSH::AuthenticationFailed
         warn "connection failed (connection made but credentials not accepted with user #{@user})"
+        @failure_message = CONN_FAILURE_AUTH_FAILED
         @reconnectable = true
       rescue Net::SSH::HostKeyMismatch
-        warn 'connection failed (host key mismatch)'
+        warn CONN_FAILURE_HOST_KEY_MISMATCH
+        @failure_message = CONN_FAILURE_HOST_KEY_MISMATCH
+        @reconnectable = false
+      rescue SocketError, Errno::ETIMEDOUT
+        warn CONN_FAILURE_NO_HOST
+        @failure_message = CONN_FAILURE_NO_HOST
         @reconnectable = false
       rescue => error
-        warn "connection failed (#{error.message})"
+        message = "connection failed (#{error.message})"
+        warn message
+        @failure_message = message
         @reconnectable = true
       end
 
@@ -102,7 +115,7 @@ module Boris
           elsif data =~ /sorry, try again/i
             ch.close
             return_data = []
-            info "channel closed (we have a password to supply but system its not accepted)"
+            info 'channel closed (we have a password to supply but it is not accepted)'
           elsif data =~ /permission denied/i
             warn "permission denied for this request (#{data.gsub(/\n|\s+/, ', ')})"
           else
@@ -112,6 +125,11 @@ module Boris
         
         # called when something is written to stderr
         chan.on_extended_data do |ch, type, data|
+          if data =~ /password has expired/i
+            @failure_message = CONN_FAILURE_PASSWORD_EXPIRED
+            ch.close
+            disconnect
+          end
           error_messages.concat(data.split(/\n/))
         end
 

data/lib/boris/connectors/wmi.rb

@@ -3,6 +3,7 @@ require 'boris/connectors'
 module Boris
   class WMIConnector < Connector
     attr_accessor :wmi, :root_wmi, :registry
+    attr_reader :registry_cache
 
     HKEY_LOCAL_MACHINE = 0x80000002
     KEY_QUERY_VALUE = 1
@@ -16,6 +17,8 @@ module Boris
     # @param [Hash] cred credential we wish to use
     def initialize(host, cred)
       super(host, cred)
+
+      @registry_cache = []
     end
 
     # Disconnect from the host.
@@ -56,17 +59,31 @@ module Boris
         @connected = false
         if error.message =~ /access is denied/i
           warn "connection failed (connection made but credentials not accepted with user #{@user})"
+          @failure_message = CONN_FAILURE_AUTH_FAILED
           @reconnectable = true
+        elsif error.message =~ /call was canceled by the message filter/i
+          warn CONN_FAILURE_RPC_FILTERED
+          @failure_message = CONN_FAILURE_RPC_FILTERED
+          @reconnectable = false
         elsif error.message =~ /rpc server is unavailable/i
-          warn 'connection failed (rpc server not available)'
+          warn CONN_FAILURE_RPC_UNAVAILABLE
+          @failure_message = CONN_FAILURE_RPC_UNAVAILABLE
           @reconnectable = false
+        elsif error.message =~ /user credentials cannot be used for local connections/i
+          # clear the credentials then try to connect again
+          warn CONN_FAILURE_LOCAL_CREDENTIALS
+          @user = nil
+          @password = nil
+          establish_connection
         else
-          warn "connection failed (#{error.message.gsub(/\n\s*/, '. ')})"
+          message = "connection failed (#{error.message.gsub(/\n\s*/, '. ')})"
+          warn message
+          @failure_message = message
           @reconnectable = true
         end
       end
 
-      if @reconnectable == true
+      if @connected == false && @reconnectable == true
         info 'connection available for retry'
       elsif @reconnectable == false
         info 'connection does not seem to be available (so we will not retry)'
@@ -95,7 +112,20 @@ module Boris
       access_params.sSubKeyName = key_path
       access_params.uRequired = permission_to_check
 
-      @registry.ExecMethod_('CheckAccess', access_params).bGranted
+      has_access = false
+
+      begin
+        @registry.ExecMethod_('CheckAccess', access_params).bGranted
+        has_access = true
+      rescue => error
+        if error.message =~ /access is denied/i
+          info "access denied on checking access on #{key_path}"
+        else
+          info "error while checking access on #{key_path}"
+        end
+      end
+
+      has_access
     end
 
 
@@ -110,18 +140,26 @@ module Boris
     def registry_subkeys_at(key_path)
       subkeys = []
 
-      debug "reading registry subkeys at path #{key_path}"
+      debug "reading registry subkeys at #{key_path}"
+
+      found_key = @registry_cache.select{|item| item[:key_path] == key_path}.first
 
-      if has_access_for(key_path, KEY_ENUMERATE_SUB_KEYS)
+      if found_key && found_key[:subkeys]
+        debug "subkeys found in cache at #{key_path}"
+        subkeys = found_key[:subkeys]
+      elsif has_access_for(key_path, KEY_ENUMERATE_SUB_KEYS)
         in_params = @registry.Methods_('EnumKey').inParameters.SpawnInstance_
         in_params.hDefKey = HKEY_LOCAL_MACHINE
         in_params.sSubKeyName = key_path
 
-        @registry.ExecMethod_('EnumKey', in_params).sNames.each do |key|
-          subkeys << key_path + '\\' + key
-        end
+        keys_names = @registry.ExecMethod_('EnumKey', in_params).sNames
+        keys_names ? keys_names.each {|key| subkeys << key_path + '\\' + key} : subkeys = []
+
+        @registry_cache << {:key_path=>key_path, :subkeys=>subkeys}
       else
-        info "no access for enumerating keys at (#{key_path})"
+        info "no access for enumerating keys at #{key_path}"
+
+        @registry_cache << {:key_path=>key_path, :subkeys=>subkeys}
       end
 
       subkeys
@@ -140,7 +178,12 @@ module Boris
 
       debug "reading registry values at path #{key_path}"
 
-      if has_access_for(key_path, KEY_QUERY_VALUE)
+      found_key = @registry_cache.select{|item| item[:key_path] == key_path}.first
+
+      if found_key && found_key[:values]
+        debug "values found in cache (#{key_path})"
+        values = found_key[:values]
+      elsif has_access_for(key_path, KEY_QUERY_VALUE)
         in_params = @registry.Methods_('EnumValues').inParameters.SpawnInstance_
         in_params.hDefKey = HKEY_LOCAL_MACHINE
         in_params.sSubKeyName = key_path
@@ -152,27 +195,31 @@ module Boris
         subkey_values ||= []
 
         subkey_values.each do |value|
-          if value.length > 0
-            str_params.sValueName = value
-
-            begin
-              x = @registry.ExecMethod_('GetStringValue', str_params).sValue
-              x = @registry.ExecMethod_('GetBinaryValue', str_params).uValue unless x
-              x = @registry.ExecMethod_('GetDWORDValue', str_params).uValue unless x
-              x = @registry.ExecMethod_('GetExpandedStringValue', str_params).sValue unless x
-              x = @registry.ExecMethod_('GetMultiStringValue', str_params).sValue unless x
-              x = @registry.ExecMethod_('GetQWORDValue', str_params).uValue unless x
-
-              values[value.downcase.to_sym] = x
-            rescue
-              if $!.message =~ /invalid method/i
-                warn "unreadable registry value (#{key_path}\\#{value})"
-              end
+          break if value.length == 0
+
+          str_params.sValueName = value
+
+          begin
+            x = @registry.ExecMethod_('GetStringValue', str_params).sValue
+            x = @registry.ExecMethod_('GetBinaryValue', str_params).uValue unless x
+            x = @registry.ExecMethod_('GetDWORDValue', str_params).uValue unless x
+            x = @registry.ExecMethod_('GetExpandedStringValue', str_params).sValue unless x
+            x = @registry.ExecMethod_('GetMultiStringValue', str_params).sValue unless x
+            x = @registry.ExecMethod_('GetQWORDValue', str_params).uValue unless x
+
+            values[value.downcase.to_sym] = x
+          rescue
+            if $!.message =~ /invalid method/i
+              warn "unreadable registry value (#{key_path}\\#{value})"
             end
           end
         end
+
+        @registry_cache << {:key_path=>key_path, :values=>values}
       else
         info "no access for enumerating values at (#{key_path})"
+
+        @registry_cache << {:key_path=>key_path, :values=>values}
       end
 
       values