boris 1.0.0.beta.1 → 1.0.1

data/lib/boris/connectors/wmi.rb

@@ -8,10 +8,17 @@ module Boris
     KEY_QUERY_VALUE = 1
     KEY_ENUMERATE_SUB_KEYS = 8
 
-    def initialize(host, cred, options, logger=nil)
-      super(host, cred, options, logger)
+    # Create an instance of WMIConnector by passing in a mandatory hostname or IP address,
+    # credential to try, and optional Hash of {Boris::Options options}.  Under the hood, this
+    # class uses the WIN32OLE library.
+    #
+    # @param [String] host hostname or IP address
+    # @param [Hash] cred credential we wish to use
+    def initialize(host, cred)
+      super(host, cred)
     end
 
+    # Disconnect from the host.
     def disconnect
       super
       @wmi = nil
@@ -21,6 +28,9 @@ module Boris
       debug 'connections closed'
     end
     
+    # Establish our connection.  Three connection types are created: one to the WMI cimv2
+    # namespace, one to the WMI root namespace, and one to the registry.
+    # @return [WMIConnector] instance of WMIConnector
     def establish_connection
       super
 
@@ -62,55 +72,23 @@ module Boris
         info 'connection does not seem to be available (so we will not retry)'
       end unless @transport
 
-      return self
-    end
-
-    def value_at(request, conn=:wmi)
-      values_at(request, conn, limit=1)[0]
-    end
-
-    def values_at(request, conn=:wmi, limit=nil)
-      super(request, limit)
-      
-      rows = case conn
-      when :root_wmi
-        @root_wmi.ExecQuery(request, nil, 48)
-      when :wmi
-        @wmi.ExecQuery(request, nil, 48)
-      end
-
-      return_data = []
-
-      i = 0
-
-      rows.each do |row|
-        i += 1
-
-        return_hash = {}
-
-        row.Properties_.each do |property|
-          if property.Name =~ /^attributes/i && property.Value.kind_of?(WIN32OLE)
-            row.Attributes.Properties_.each do |property|
-              return_hash[property.Name.downcase.to_sym] = property.Value
-            end
-          else
-            return_hash[property.Name.downcase.to_sym] = property.Value
-          end
-        end
-
-        return_data << return_hash
-
-        break if (limit.nil? && i == limit)
-      end
-
-      info "#{return_data.size} row(s) returned"
-
-      return return_data
+      self
     end
 
+    # Check if we have access to perform an action on the specified key path. This
+    # adds a slight overhead in terms of registry read speed, as internally Boris
+    # will check for access to enumerate subkeys for each registry key it wants to
+    # read, but this does cut down on the number of access errors on the host.
+    #
+    #  # KEY_ENUMERATE_SUB_KEYS and KEY_QUERY_VALUE are constants specified in Boris.
+    #  # Check Microsoft docs for other possible values.
+    #  connector.has_access_for('SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall', KEY_ENUMERATE_SUB_KEYS)
+    #    #=> true
+    #
+    # @param [String] key_path the registry key we wish to check access for
+    # @param [Integer] permission_to_check the access we wish to test
+    # @return [Boolean] true if we have access to perform this action on specified key
     def has_access_for(key_path, permission_to_check=nil)
-      debug "checking for registry read access for #{key_path}"
-
       access_params = @registry.Methods_('CheckAccess').inParameters.SpawnInstance_
 
       access_params.hDefKey = HKEY_LOCAL_MACHINE
@@ -120,8 +98,17 @@ module Boris
       @registry.ExecMethod_('CheckAccess', access_params).bGranted
     end
 
+
+    # Returns an array of subkey names found at the specified key path under
+    # HKEY_LOCAL_MACHINE.
+    #
+    #  connector.registry_subkeys_at('SOFTWARE\Microsoft')
+    #   #=> ['SOFTWARE\Microsoft\Office', 'SOFTWARE\Microsoft\Windows'...]
+    #
+    # @param [String] key_path the registry key we wish to test
+    # @return [Array] array of subkeys found
     def registry_subkeys_at(key_path)
-      return_data = []
+      subkeys = []
 
       debug "reading registry subkeys at path #{key_path}"
 
@@ -131,15 +118,23 @@ module Boris
         in_params.sSubKeyName = key_path
 
         @registry.ExecMethod_('EnumKey', in_params).sNames.each do |key|
-          return_data << key_path + '\\' + key
+          subkeys << key_path + '\\' + key
         end
       else
         info "no access for enumerating keys at (#{key_path})"
       end
 
-      return return_data
+      subkeys
     end
 
+    # Returns an array of values found at the specified key path under
+    # HKEY_LOCAL_MACHINE.
+    #
+    #  connector.registry_values_at('SOFTWARE\Microsoft')
+    #   #=> {:valuename=>value, ...}
+    #
+    # @param [String] key_path the registry key we wish to test
+    # @return [Hash] hash of key/value pairs found at the specified key path
     def registry_values_at(key_path)
       values = Hash.new
 
@@ -157,7 +152,7 @@ module Boris
         subkey_values ||= []
 
         subkey_values.each do |value|
-          if !value.empty?
+          if value.length > 0
             str_params.sValueName = value
 
             begin
@@ -170,7 +165,7 @@ module Boris
 
               values[value.downcase.to_sym] = x
             rescue
-              if $!.message =~ /#{invalid method}/i
+              if $!.message =~ /invalid method/i
                 warn "unreadable registry value (#{key_path}\\#{value})"
               end
             end
@@ -180,7 +175,67 @@ module Boris
         info "no access for enumerating values at (#{key_path})"
       end
 
-      return values
+      values
     end
+
+    # Return a single value from our request.
+    #
+    # @param [String] request the command we wish to execute over this connection
+    # @param [Symbol] conn the channel we should use for our request
+    #  Options: +:root_wmi+, +:cimv2+ (default)
+    # @return [String] the first row/line returned by the host
+    def value_at(request, conn=:cimv2)
+      values_at(request, conn, limit=1)[0]
+    end
+
+    # Return multiple values from our request, up to the limit specified (or no
+    # limit if no limit parameter is specified.
+    #
+    # @param [String] request the command we wish to execute over this connection
+    # @param [Symbol] conn the channel we should use for our request
+    #  Options: +:root_wmi+, +:wmi+ (default)
+    # @param [Integer] limit the optional maximum number of results we wish to return
+    # @return [Array] an array of rows returned by the query
+    def values_at(request, conn=:cimv2, limit=nil)
+      super(request, limit)
+      
+      rows = case conn
+      when :root_wmi
+        @root_wmi.ExecQuery(request, nil, 48)
+      when :cimv2
+        @wmi.ExecQuery(request, nil, 48)
+      end
+
+      return_data = []
+
+      i = 0
+
+      rows.each do |row|
+        i += 1
+
+        return_hash = {}
+
+        row.Properties_.each do |property|
+          if property.Name =~ /^attributes/i && property.Value.kind_of?(WIN32OLE)
+            row.Attributes.Properties_.each do |property|
+              return_hash[property.Name.downcase.to_sym] = property.Value
+            end
+          else
+            return_hash[property.Name.downcase.to_sym] = property.Value
+          end
+        end
+
+        return_data << return_hash
+
+        break if (limit.nil? && i == limit)
+      end
+
+      debug "#{return_data.size} row(s) returned"
+
+      return return_data
+    end
+
+
+
   end
 end

data/lib/boris/errors.rb

@@ -7,7 +7,7 @@ module Boris
 
   class NoActiveConnection < StandardError; end
 
-  class NoProfileDetected < StandardError; end
+  class NoProfilerDetected < StandardError; end
 
   class InvalidOption < StandardError; end
 

data/lib/boris/helpers/array.rb

@@ -1,63 +1,63 @@
-class Array
-  def strip_string_values_in_array
-    self.map! do |val|
-      val.strip_string_values_in_array if val.is_a?(Array)
-      val.strip_string_values_in_hash if val.is_a?(Hash)
-      val.is_a?(String) ? val.strip : val
-    end
-  end
-  
-  def to_ms_product_key
-    valid_chars = 'BCDFGHJKMPQRTVWXY2346789'.scan(/./)
-
-    product_key = nil
-    
-    raw_product_key = []
-
-    52.upto(66) do |idx|
-      raw_product_key << self[idx]
-    end
-
-    24.downto(0) do |a|
-      b = 0
-
-      14.downto(0) do |c|
-        b = b * 256 ^ raw_product_key[c]
-        raw_product_key[c] = (b / 24).to_i
-        b = b.remainder(24)
-      end
-
-      product_key = "#{valid_chars[b]}#{product_key}"
-
-      if a.remainder(5) == 0 && a != 0
-        product_key = "-#{product_key}"
-      end
-    end
-
-    return product_key.upcase
-  end
-
-  def to_nil_hash
-    h = Hash.new
-    self.each do |item|
-      if item.kind_of?(Hash)
-        h.merge!(item)
-      else
-        h[item.to_sym] = nil
-      end
-    end
-    return h
-  end
-
-  def to_wwn
-    wwn = []
-
-    0.upto(7) do |i|
-      hex = self[i].to_s(16)
-      hex = "0#{hex}" if self[i] < 16
-      wwn << hex
-    end
-    
-    return wwn.join
-  end
+class Array
+  def strip_string_values_in_array
+    self.map! do |val|
+      val.strip_string_values_in_array if val.is_a?(Array)
+      val.strip_string_values_in_hash if val.is_a?(Hash)
+      val.is_a?(String) ? val.strip : val
+    end
+  end
+  
+  def to_ms_product_key
+    valid_chars = 'BCDFGHJKMPQRTVWXY2346789'.scan(/./)
+
+    product_key = nil
+    
+    raw_product_key = []
+
+    52.upto(66) do |idx|
+      raw_product_key << self[idx]
+    end
+
+    24.downto(0) do |a|
+      b = 0
+
+      14.downto(0) do |c|
+        b = b * 256 ^ raw_product_key[c]
+        raw_product_key[c] = (b / 24).to_i
+        b = b.remainder(24)
+      end
+
+      product_key = "#{valid_chars[b]}#{product_key}"
+
+      if a.remainder(5) == 0 && a != 0
+        product_key = "-#{product_key}"
+      end
+    end
+
+    return product_key.upcase
+  end
+
+  def to_nil_hash
+    h = Hash.new
+    self.each do |item|
+      if item.kind_of?(Hash)
+        h.merge!(item)
+      else
+        h[item.to_sym] = nil
+      end
+    end
+    return h
+  end
+
+  def to_wwn
+    wwn = []
+
+    0.upto(7) do |i|
+      hex = self[i].to_s(16)
+      hex = "0#{hex}" if self[i] < 16
+      wwn << hex
+    end
+    
+    return wwn.join
+  end
 end

data/lib/boris/helpers/constants.rb

@@ -1,20 +1,23 @@
-module Boris
-  VENDOR_ADOBE      = 'Adobe Systems, Inc.'
-  VENDOR_AMD        = 'AMD, Inc.'
-  VENDOR_APC        = 'APC Corp.'
-  VENDOR_BROCADE    = 'Brocade Communications Corp.'
-  VENDOR_CISCO      = 'Cisco Systems, Inc.'
-  VENDOR_CITRIX     = 'Citrix Systems, Inc.'
-  VENDOR_DELL       = 'Dell Inc.'
-  VENDOR_EMULEX     = 'Emulex Corp.'
-  VENDOR_F5         = 'F5 Networks, Inc.'
-  VENDOR_HP         = 'Hewlett Packard, Inc.'
-  VENDOR_IBM        = 'IBM Corp.'
-  VENDOR_INTEL      = 'Intel Corp.'
-  VENDOR_MICROSOFT  = 'Microsoft Corp.'
-  VENDOR_ORACLE     = 'Oracle Corp.'
-  VENDOR_QLOGIC     = 'QLogic Corp.'
-  VENDOR_REDHAT     = 'Red Hat Inc.'
-  VENDOR_SUSE       = 'SUSE Linux GmbH'
-  VENDOR_VMWARE     = 'VMware, Inc.'
+module Boris
+  VENDOR_ADOBE      = 'Adobe Systems, Inc.'
+  VENDOR_AMD        = 'AMD, Inc.'
+  VENDOR_APC        = 'APC Corp.'
+  VENDOR_BROCADE    = 'Brocade Communications Corp.'
+  VENDOR_CISCO      = 'Cisco Systems, Inc.'
+  VENDOR_CITRIX     = 'Citrix Systems, Inc.'
+  VENDOR_DELL       = 'Dell Inc.'
+  VENDOR_EMULEX     = 'Emulex Corp.'
+  VENDOR_F5         = 'F5 Networks, Inc.'
+  VENDOR_HP         = 'Hewlett Packard, Inc.'
+  VENDOR_IBM        = 'IBM Corp.'
+  VENDOR_INTEL      = 'Intel Corp.'
+  VENDOR_MICROSOFT  = 'Microsoft Corp.'
+  VENDOR_ORACLE     = 'Oracle Corp.'
+  VENDOR_QLOGIC     = 'QLogic Corp.'
+  VENDOR_REDHAT     = 'Red Hat Inc.'
+  VENDOR_SUSE       = 'SUSE Linux GmbH'
+  VENDOR_VMWARE     = 'VMware, Inc.'
+
+  PORT_DEFAULTS = {:ssh=>22, :wmi=>135}
+  VALID_CONNECTION_TYPES = [:snmp, :ssh, :wmi]
 end

data/lib/boris/helpers/hash.rb

@@ -1,8 +1,8 @@
-class Hash
-  def strip_string_values_in_hash
-    self.each_pair do |key, val|
-      val.strip_string_values_in_array if val.is_a?(Array)
-      self[key] = val.strip if val.is_a?(String)
-    end
-  end
+class Hash
+  def strip_string_values_in_hash
+    self.each_pair do |key, val|
+      val.strip_string_values_in_array if val.is_a?(Array)
+      self[key] = val.strip if val.is_a?(String)
+    end
+  end
 end

data/lib/boris/helpers/network.rb

@@ -0,0 +1,68 @@
+require 'boris/lumberjack'
+
+module Boris
+  module Network
+    extend Lumberjack
+
+    # Attempts to suggest a connection method based on whether certain TCP ports
+    # on the target are responding (22 for SSH, 135 for WMI by default).  Can be
+    # used to speed up the process of determining whether we should try to
+    # connect to our host using different methods, or bypass certain attempts
+    # entirely.
+    #
+    #  Boris::Network.suggested_connection_method('linuxserver01') #=> :ssh
+    #
+    # @param target name we wish to test against
+    # @return [Symbol] returns :wmi, :ssh, or nil
+    # @see tcp_port_responding?
+    def self.suggested_connection_method(target)
+      connection_method = nil
+      
+      PORT_DEFAULTS.each_pair do |key, val|
+        break if connection_method
+        
+        debug "detecting if #{key.to_s} is available"
+
+        if tcp_port_responding?(target, val)
+          debug "#{key.to_s} seems to be available"
+          connection_method = key
+        else
+          info 'wmi does not appear to be responding'
+        end
+      end
+
+      info 'failed to detect connection method' if connection_method.nil?
+      connection_method
+    end
+
+    # Checks if the supplied TCP port is responding on the target.  Useful for
+    # determining which connection type we should use instead of taking more
+    # time connecting to the target using different methods just to check if
+    # they succeed or not.
+    #
+    #  Boris::Network.tcp_port_responding?('windowsserver01', 22)   #=> false
+    #  Boris::Network.tcp_port_responding?('windowsserver01', 135)  #=> true
+    #
+    # @param target name we wish to test against
+    # @param port the TCP port number we wish to test
+    # @return [Boolean] returns true of the supplied port is responding
+    def self.tcp_port_responding?(target, port)
+      status = false
+
+      debug "checking if port #{port} is responding"
+
+      begin
+        conn = TCPSocket.new(target, port)
+        info "port #{port} is responding"
+        conn.close
+        debug "connection to port closed"
+        status = true
+      rescue
+        info "port #{port} is not responding"
+        status = false
+      end
+
+      status
+    end
+  end
+end