boris 1.0.0.beta.1 → 1.0.1

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 1.0.1
+* Renamed Profiles to Profilers
+* Moved networking helper methods to newly created Network module
+* Separated Structure and Profilers
+* Profilers are now separate classes for easier subclassing
+* Simplified logging
+
+# 1.0.0.beta1
+* Initial public release
+
+# 1.0.0* was yanked

data/README.md

@@ -1,17 +1,18 @@
 # Boris
-## A networked-device scanning solution
+## Networked-device scanning library written in Ruby
 
 * Code: http://github.com/alkalinecoffee/boris
-* Documentation: http://rdoc.info/github/alkalinecoffee/boris/master/frames
+* Developer's blog: http://www.sharkwavemedia.com
+* Documentation: http://rdoc.info/github/alkalinecoffee/boris/frames
 * Issues: https://github.com/alkalinecoffee/boris/issues
 
 ## Introduction
 Boris is a library that facilitates the communication between you and various networked devices over SNMP, SSH and WMI, pulling a large amount of configuration items including installed software, network settings, serial numbers, user accounts, disk utilization, and more.
 
-Out of the box, Boris has server support for Windows, Red Hat, and Solaris (with other platforms available with future plugins), with a focus on returning precisely formatted data, no matter which platforms your organization may have deployed.  Through the use of profiles, Boris can easily be extended by the developer to include other platforms.  Highly suitable for small and large environments alike looking to pull configuration data from various platforms.
+Out of the box, Boris has server support for Red Hat, Solaris,and Windows (with other platforms available with future plugins), with a focus on returning precisely formatted data, no matter which platforms your organization may have deployed.  Through the use of profilers, Boris can easily be extended by the developer to include other platforms.  Highly suitable for small and large environments alike looking to pull configuration data from various platforms.
 
 ## Features
-* Out of the box, pulls information from RedHat Linux, Solaris 10, and Windows servers
+* Currently, pulls information from Red Hat Linux, Solaris, and Windows servers (support for OS X, F5 BIG-IP, and Cisco IOS devices in the works)
 * Utilizes SNMP, SSH, and WMI communication technologies
 * Expandable to include other networked devices, such as switches, load balancers, and other operating systems
 
@@ -24,43 +25,109 @@ Let's pull some information from a RedHat Enterprise Linux server on our network
 ```ruby
 require 'boris'
 
-target = Boris::Target.new('redhatserver01.mydomain.com')
+# 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)
-puts target.suggested_connection_method
+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
-puts target.tcp_port_responding?(22)
+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=>'joe', :password=>'mypassword', :connection_types=>[:ssh])
+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.
+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?
-  # detect which profile to load up (is this target running windows? solaris? or what?).  if we can't
-  # detect a suitable profile, this will throw an error
-  target.detect_profile
+  # we can try to detect which profiler to load up (is this target running windows? solaris? or
+  # what?).  if we can't detect a suitable profiler, this will throw an error.
+  target.detect_profiler
+
+  puts target.profiler.class
+
+  # 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)
+
+  # retrieved items can be referenced two ways:
+  puts target[:network_interfaces].inspect
+  puts target.profiler.network_interfaces.inspect
+
+  # we can also call #retrieve_all to grab everything we can from this target (file systems, hardware,
+  # installed applications, etc.)
+  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)
+  puts target.connector.values_at('cat /etc/redhat-release')
+  puts target.connector.value_at('uname -a')
+  
+  # NOTE: if this were a Windows server, you would send WMI queries instead of shell commands, ie:
+  #
+  # 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
+```
 
-  puts target.target_profile
+## 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:
 
-  # we can call individual methods to grab specific information we may be interested in (or call
-  # #retrieve_all to grab everything we can)
-  target.get_hardware
+```ruby
+# use the target's connector to grab multiple values.  #values_at will return an array with each line
+# returned as an item in the returned array.
+multiple_lines_of_data = target.connector.values_at('/path/to/some/script')
 
-  puts target.hardware.inspect
+# to grab only the first line from a script or file, you can use #value_at:
+single_line_of_data = target.connector.value_at('/path/to/some/script')
+```
 
-  # finally, we can package up all of the data into json format for portability
-  puts target.to_json
-end
+Running commands in this fashion utilizes the #exec function from Net::SSH.
 
-target.disconnect
+For a Windows host, which uses WMI vice SSH, you can send WMI queries or registry keys to the connector to get information:
+
+```ruby
+# 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):
+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:
+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:
+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 effeciently 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.
+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:**
 
@@ -75,20 +142,35 @@ Through a number of queries and algorithms, Boris effeciently polls devices on t
 * **network interfaces** - ethernet and fibre channel interfaces, including IPs, MAC addresses, connection status
 * **operating system** - name, version, kernel, date installed
 
-See {Boris::Profiles::Structure} for more details on the data structure.
+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...
 
-## Profiles
-Profiles 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 profile 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 profiles built-in for some popular platforms, but can be easily extended to include other devices.
+## 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
+
+## 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.
+
+**Here is a list of known scan account requirements for each platform:**
 
-## Requirements
-* Ruby 1.9.3 (only tested on MRI)
-* Net/SSH gem
-* NetAddr gem
-* SNMP gem
-* Mocha (for tests only)
-* Shoulda (for tests only)
+* **Linux (any flavor)**
+  * User must have `sudo` for `dmidecode`
+* **Solaris**
+  * User must have `sudo` for `fcinfo`
+* **Windows**
+  * User must be a member of local Administrator group (looking into what other groups provide required access)
 
-## LICENSE
+## License
 This software is provided under the MIT license.  See the LICENSE.md file.

data/Rakefile

@@ -0,0 +1,19 @@
+require 'rake'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+
+require 'boris/version'
+
+task :build do
+  system 'gem build boris.gemspec'
+end
+
+task :install => :build do
+  system "gem install boris-#{Boris::VERSION}.gem"
+end
+
+task :release => :build do
+  system "git tag -a v#{Boris::VERSION} -m 'Pushed #{Boris::VERSION}'"
+  system 'git push --tags'
+  system "gem push boris-#{Boris::VERSION}.gem"
+end

data/lib/boris.rb

@@ -14,17 +14,4 @@ require 'thread'
 require 'win32ole' if PLATFORM == :win32
 
 require 'boris/lumberjack'
-
-require 'boris/errors'
-require 'boris/options'
 require 'boris/target'
-
-require 'boris/helpers/array'
-require 'boris/helpers/constants'
-require 'boris/helpers/hash'
-require 'boris/helpers/scrubber'
-require 'boris/helpers/string'
-
-module Boris
-
-end

data/lib/boris/connectors.rb

@@ -1,4 +1,10 @@
 module Boris
+  # The Connector class is the parent of the main Connector types that Boris
+  # utilizes (WMI, SNMP, and SSH). It's primary purpose is to create the general
+  # structure of a connector and offer some debugging messages for different
+  # actions. Typically, Connector objects would not be created by user code.
+  # Instead, your own connectors would be a subclass of Connector with calls
+  # to super as appropriate.
   class Connector
     include Lumberjack
 
@@ -7,31 +13,43 @@ module Boris
     attr_reader :options
     attr_reader :reconnectable
 
-    def initialize(host, cred, options, logger=nil)
-      debug 'creating connection object'
-
+    def initialize(host, cred={})
+      @logger = Boris.logger
+      
       @host = host
       @user = cred[:user]
       @password = cred[:password]
       @connected = false
       @reconnectable = true
-
-      @logger = logger
+      debug 'creating connection object'
     end
 
+    # Convience method for retrieveing the connection status for this Connector.
+    #
+    #  connector.connected? #=> true
+    #
+    # @return [Boolean] true if connected
     def connected?
       @connected
     end
 
+    # Disconnect from the host.
     def disconnect
-      debug 'closing connection to host'
+      info 'closing connection to host'
       @connected = false
     end
 
+    # Establish our connection.
     def establish_connection
       debug 'attempting connection'
     end
 
+    # Only to be called from a child class, as this method only performs some simple
+    # checks for errors and provides debugging messages.  Not intended to be directly
+    # called from user code.
+    #
+    # @param [String] request the command we wish to execute over this connection
+    # @param [Integer] limit the maximum number of results we wish to return
     def values_at(request, limit)
       if !limit.kind_of?(Integer)
         raise ArgumentError, "non-integer limit specified (#{limit.inspect})"
@@ -41,7 +59,7 @@ module Boris
 
       amount = limit == 1 ? 'single value' : 'multiple values'
 
-      debug "issuing request for #{amount} (#{request.inspect})"
+      debug "issuing request for #{amount} (#{request})"
     end
   end
 end

data/lib/boris/connectors/snmp.rb

@@ -2,20 +2,32 @@ require 'boris/connectors'
 
 module Boris
   class SNMPConnector < Connector
-    def initialize(host, cred, options, logger=nil)
-      super(host, cred, options, logger)
+    
+    # Create an instance of SNMPConnector 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 SNMP library.
+    #
+    # @param [String] host hostname or IP address
+    # @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={})
+      super(host, cred)
       @snmp_options = options[:snmp_options].merge(:host=>@host, :version=>:SNMPv1, :community=>@user)
 
       #snmp connections are always reconnectable
       @reconnectable = true
     end
 
+    # Disconnect from the host.
     def disconnect
       super
       @transport = nil
       debug 'connections closed'
     end
 
+    # Establish our connection.
+    # @return [SNMPConnector] instance of SNMPConnector
     def establish_connection
       super
 
@@ -30,13 +42,21 @@ module Boris
         warn "connection failed (#{error.message})"
       end
 
-      return self
+      self
     end
 
+    # Return a single value from our request.
+    # @param [String] request the command we wish to execute over this connection
+    # @return [String] the first row/line returned by the host
     def value_at(request)
       values_at(request, 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 [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, limit=nil)
       super(request, limit)
 
@@ -46,7 +66,7 @@ module Boris
         row.each {|item| return_data << {:name=>item.name.to_s, :value=>item.value}}
       end
 
-      info "#{return_data.size} row(s) returned"
+      debug "#{return_data.size} row(s) returned"
 
       limit = return_data.size if limit.nil?
 

data/lib/boris/connectors/ssh.rb

@@ -2,22 +2,36 @@ require 'boris/connectors'
 
 module Boris
   class SSHConnector < Connector
-    def initialize(host, cred, options, logger=nil)
+
+    # Create an instance of SSHConnector 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 Net/SSH library.
+    #
+    # @param [String] host hostname or IP address
+    # @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={})
       @ssh_options = options[:ssh_options]
       @ssh_options[:password] = @password if @password
 
-      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?
+      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?
+      end
 
-      super(host, cred, options, logger)
+      super(host, cred)
     end
 
+    # Disconnect from the host.
     def disconnect
       super
       @transport = nil
       debug 'connections closed'
     end
     
+    # Establish our connection.
+    # @return [SSHConnector] instance of SSHConnector
     def establish_connection
       super
 
@@ -42,13 +56,25 @@ module Boris
         info 'connection does not seem to be available (so we will not retry)'
       end unless @transport
 
-      return self
+      self
     end
 
+    # Return a single value from our request.
+    # @param [String] request the command we wish to execute over this connection
+    # @param [Boolean] request_pty if true, we should request psuedo-terminal (PTY).
+    #   This is necessary if we are calling a command that uses elevated privileges (sudo).
+    # @return [String] the first row/line returned by the host
     def value_at(request, request_pty=false)
       values_at(request, request_pty, 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 [Boolean] request_pty if true, we should request psuedo-terminal (PTY).
+    #   This is necessary if we are calling a command that uses elevated privileges (sudo).
+    # @param [Integer] limit the optional maximum number of results we wish to return
+    # @return [Array] an array of rows returned by the command
     def values_at(request, request_pty=false, limit=nil)
       super(request, limit)
       
@@ -100,7 +126,7 @@ module Boris
 
       return_data = return_data.join.split(/\n/)
 
-      info "#{return_data.size} row(s) returned"
+      debug "#{return_data.size} row(s) returned"
 
       limit = return_data.size if limit.nil?