nexpose 0.1.3 → 0.1.4

data/lib/nexpose/scan.rb

@@ -120,31 +120,27 @@ module Nexpose
     # @return [ScanSummary] Scan summary represented by the XML.
     #
     def self.parse(rexml)
-      tasks = Tasks.parse(rexml)
-      nodes = Nodes.parse(rexml)
-      vulns = Vulnerabilities.parse(rexml)
-      msg = nil
-      rexml.elements.each("//ScanSummary/message") do |message|
-        msg = message.text
-      end
+      tasks = Tasks.parse(rexml.elements['tasks'])
+      nodes = Nodes.parse(rexml.elements['nodes'])
+      vulns = Vulnerabilities.parse(rexml.attributes['scan-id'], rexml)
+      msg = rexml.elements['message'] ?  rexml.elements['message'].text : nil
 
-      rexml.elements.each("//ScanSummary") do |scan|
-        start_time = DateTime.parse(scan.attributes['startTime'].to_s).to_time
-        # End time is often not present, since reporting on running scans.
-        if scan.attributes['endTime']
-          end_time = DateTime.parse(scan.attributes['endTime'].to_s).to_time
-        end
-        return ScanSummary.new(scan.attributes['scan-id'].to_i,
-                               scan.attributes['site-id'].to_i,
-                               scan.attributes['engine-id'].to_i,
-                               scan.attributes['status'], 
-                               start_time,
-                               end_time,
-                               msg,
-                               tasks,
-                               nodes,
-                               vulns)
+      start_time = DateTime.parse(rexml.attributes['startTime'].to_s).to_time
+      # End time is often not present, since reporting on running scans.
+      end_time = nil
+      if rexml.attributes['endTime']
+        end_time = DateTime.parse(rexml.attributes['endTime'].to_s).to_time
       end
+      return ScanSummary.new(rexml.attributes['scan-id'].to_i,
+                             rexml.attributes['site-id'].to_i,
+                             rexml.attributes['engine-id'].to_i,
+                             rexml.attributes['status'], 
+                             start_time,
+                             end_time,
+                             msg,
+                             tasks,
+                             nodes,
+                             vulns)
     end
 
     # Value class to tracking task counts.
@@ -162,11 +158,9 @@ module Nexpose
       # @return [Tasks] Task summary represented by the XML.
       #
       def self.parse(rexml)
-        rexml.elements.each("//ScanSummary/tasks") do |task|
-          return Tasks.new(task.attributes['pending'],
-                           task.attributes['active'],
-                           task.attributes['completed'])
-        end
+        return Tasks.new(rexml.attributes['pending'].to_i,
+                         rexml.attributes['active'].to_i,
+                         rexml.attributes['completed'].to_i)
       end
     end
 
@@ -185,13 +179,11 @@ module Nexpose
       # @return [Nodes] Node summary represented by the XML.
       #
       def self.parse(rexml)
-        rexml.elements.each("//ScanSummary/nodes") do |node|
-          return Nodes.new(node.attributes['live'],
-                           node.attributes['dead'],
-                           node.attributes['filtered'],
-                           node.attributes['unresolved'],
-                           node.attributes['other'])
-        end
+        return Nodes.new(rexml.attributes['live'].to_i,
+                         rexml.attributes['dead'].to_i,
+                         rexml.attributes['filtered'].to_i,
+                         rexml.attributes['unresolved'].to_i,
+                         rexml.attributes['other'].to_i)
       end
     end
 
@@ -215,12 +207,13 @@ module Nexpose
       
       # Parse REXML to Vulnerabilities object.
       #
+      # @param [FixNum] scan_id Scan ID to collect vulnerability data for.
       # @param [REXML::Document] rexml XML document to parse.
       # @return [Vulnerabilities] Vulnerability summary represented by the XML.
       #
-      def self.parse(rexml)
+      def self.parse(scan_id, rexml)
         map = {}
-        rexml.elements.each("//ScanSummary/vulnerabilities") do |vuln|
+        rexml.elements.each("//ScanSummary[contains(@scan-id,'#{scan_id}')]/vulnerabilities") do |vuln|
           status = map[vuln.attributes['status']]
           if status && vuln.attributes['status'] =~ /^vuln-/
             status.add_severity(vuln.attributes['severity'].to_i, vuln.attributes['count'].to_i)

data/lib/nexpose/scan_engine.rb

@@ -24,76 +24,48 @@ module Nexpose
       end
       arr
     end
-  end
-
-  # ==== Description
-  # Object that represents a listing of all of the scan engines available on to an NSC.
-  class EngineListing
-    # true if an error condition exists; false otherwise
-    attr_reader :error
-    # Error message string
-    attr_reader :error_msg
-    # The last XML request sent by this object
-    attr_reader :connection
-    # Array containing (EngineSummary*)
-    attr_reader :engines
-    # The number of scan engines
-    attr_reader :engine_count
-
-    # Constructor
-    # EngineListing (connection)
-    def initialize(connection)
-      @connection = connection
-      @engines = []
-      @engine_count = 0
-      @error = false
-      r = @connection.execute('<EngineListingRequest session-id="' + @connection.session_id + '"/>', '1.2')
 
-      if r.success
-        r.res.elements.each('EngineListingResponse/EngineSummary') do |v|
-          @engines.push(EngineSummary.new(v.attributes['id'], v.attributes['name'], v.attributes['address'],
-                                          v.attributes['port'], v.attributes['status']))
+    # Retrieve a list of all Scan Engines managed by the Security Console.
+    #
+    # @return [Array[EngineSummary]] Array of EngineSummary objects associated with
+    #   each engine associated with this security console.
+    #
+    def list_engines
+      response = execute(make_xml('EngineListingRequest'))
+      arr = []
+      if response.success
+        response.res.elements.each("//EngineSummary") do |engine|
+          arr << EngineSummary.new(engine.attributes['id'].to_i,
+                                   engine.attributes['name'],
+                                   engine.attributes['address'],
+                                   engine.attributes['port'].to_i,
+                                   engine.attributes['status'])
         end
-      else
-        @error = true
-        @error_msg = 'EngineListingRequest Parse Error'
       end
-      @engine_count = @engines.length
+      arr
     end
+
+    alias_method :engines, :list_engines
   end
 
-  # ==== Description
-  # Object that represents the summary of a scan engine.
-  #
-  # ==== Examples
-  #
-  #   # Create a new Nexpose Connection on the default port and Login
-  #   nsc = Connection.new("10.1.40.10","nxadmin","password")
-  #   nsc.login()
-  #
-  #   # Get the engine listing for the connection
-  #   enginelisting = EngineListing.new(nsc)
-  #
-  #   # Print out the status of the first scan engine
-  #   puts enginelisting.engines[0].status
+  # Object representing the current details of a scan engine attached to the security console.
   #
   class EngineSummary
-    # A unique ID that identifies this scan engine
+
+    # A unique ID that identifies this scan engine.
     attr_reader :id
-    # The name of this scan engine
+    # The name of this scan engine.
     attr_reader :name
-    # The hostname or IP address of the engine
+    # The hostname or IP address of the engine.
     attr_reader :address
-    # The port there the engine is listening
+    # The port there the engine is listening.
     attr_reader :port
-    # The engine status (active|pending-auth| incompatible|not-responding|unknown)
+    # The engine status. One of: active|pending-auth|incompatible|not-responding|unknown
     attr_reader :status
     # A parameter that specifies whether the engine has a global
     # or silo-specific scope.
     attr_reader :scope
 
-    # Constructor
-    # EngineSummary(id, name, address, port, status, scope)
     def initialize(id, name, address, port, status, scope = 'silo')
       @id = id
       @name = name
@@ -102,10 +74,6 @@ module Nexpose
       @status = status
       @scope = scope
     end
-
-    def to_s
-      "Engine: #@name [ID: #@id] #@address:#@port, Status: #@status, Scope: #@scope"
-    end
   end
 
   #-------------------------------------------------------------------------------------------------------------------
@@ -303,10 +271,10 @@ module Nexpose
           @scope = pool.attributes['scope']
           @engines = []
           r.res.elements.each('EnginePoolDetailsResponse/EnginePool/EngineSummary') do |summary|
-            @engines.push(EngineSummary.new(summary.attributes['id'],
+            @engines.push(EngineSummary.new(summary.attributes['id'].to_i,
                                             summary.attributes['name'],
                                             summary.attributes['address'],
-                                            summary.attributes['port'],
+                                            summary.attributes['port'].to_i,
                                             summary.attributes['status'],
                                             summary.attributes['scope']))
           end

data/lib/nexpose/site.rb

@@ -2,60 +2,69 @@ module Nexpose
   module NexposeAPI
     include XMLUtils
 
+    # Retrieve a list of all of the assets in a site.
     #
+    # If no site-id is specified, then return all of the assets
+    # for the Nexpose console, grouped by site-id.
     #
+    # @param [FixNum] site_id Site ID to request device listing for. Optional.
+    # @return [Array[Device]] Array of devices associated with the site, or
+    #   all devices on the console if no site is provided.
     #
-    def site_device_listing(site_id)
-      r = execute(make_xml('SiteDeviceListingRequest', {'site-id' => site_id.to_s}))
+    def site_device_listing(site_id = nil)
+      r = execute(make_xml('SiteDeviceListingRequest', {'site-id' => site_id}))
 
-      if (r.success)
-        res = []
-        r.res.elements.each("//device") do |device|
-          res << {
-            :device_id => device.attributes['id'].to_i,
-            # TODO Covert to using?
-            #   :address => IPAddr.new(device.attributes['address']),
-            :address => device.attributes['address'].to_s,
-            :risk_factor => device.attributes['riskfactor'].to_f,
-            :risk_score => device.attributes['riskscore'].to_f,
-          }
+      arr = []
+      if r.success
+        r.res.elements.each('//SiteDevices') do |site|
+          site_id = site.attributes['site-id'].to_i
+          site.elements.each("//SiteDevices[contains(@site-id,'#{site_id}')]/device") do |device|
+            arr << Device.new(device.attributes['id'].to_i,
+                              device.attributes['address'],
+                              site_id,
+                              device.attributes['riskfactor'].to_f,
+                              device.attributes['riskscore'].to_f)
+          end
         end
-        res
-      else
-        false
       end
+      arr
     end
 
+    alias_method :assets, :site_device_listing
+    alias_method :devices, :site_device_listing
+    alias_method :list_devices, :site_device_listing
+
+    # Delete the specified site and all associated scan data.
     #
-    #
+    # @return Whether or not the delete request succeeded.
     #
     def site_delete(param)
       r = execute(make_xml('SiteDeleteRequest', {'site-id' => param}))
       r.success
     end
 
+    # Retrieve a list of all sites the user is authorized to view or manage.
     #
-    #
-    # TODO Should just return empty array if doesn't work?
+    # @return [Array[SiteSummary]] Array of SiteSummary objects.
+    # 
     def site_listing
-      r = execute(make_xml('SiteListingRequest', {}))
-
+      r = execute(make_xml('SiteListingRequest'))
+      arr = []
       if (r.success)
-        res = []
         r.res.elements.each("//SiteSummary") do |site|
-          res << {
-            :site_id => site.attributes['id'].to_i,
-            :name => site.attributes['name'].to_s,
-            :risk_factor => site.attributes['riskfactor'].to_f,
-            :risk_score => site.attributes['riskscore'].to_f,
-          }
+          arr << SiteSummary.new(site.attributes['id'].to_i,
+                                 site.attributes['name'],
+                                 site.attributes['description'],
+                                 site.attributes['riskfactor'].to_f,
+                                 site.attributes['riskscore'].to_f)
         end
-        res
-      else
-        false
       end
+      arr
     end
 
+    alias_method :list_sites, :site_listing
+    alias_method :sites, :site_listing
+
     # Retrieve a list of all previous scans of the site.
     #
     # @param [FixNum] site_id Site ID to request scan history for.
@@ -73,6 +82,18 @@ module Nexpose
       res
     end
 
+    # Retrieve the scan summary statistics for the latest completed scan
+    # on a site.
+    #
+    # Method will not return data on an active scan.
+    #
+    # @param [FixNum] site_id Site ID to find latest scan for.
+    #
+    def last_scan(site_id)
+      site_scan_history(site_id).select { |scan| scan.end_time }
+                                .max_by { |scan| scan.end_time }
+    end
+
     #-----------------------------------------------------------------------
     # Starts device specific site scanning.
     #
@@ -436,8 +457,8 @@ module Nexpose
       r.elements.each('SiteListingResponse/SiteSummary') do |s|
         site_summary = SiteSummary.new(
           s.attributes['id'].to_s,
-          s.attributes['name'].to_s,
-          s.attributes['description'].to_s,
+          s.attributes['name'],
+          s.attributes['description'],
           s.attributes['riskfactor'].to_s
         )
         @sites.push(site_summary)
@@ -450,101 +471,51 @@ module Nexpose
   # Object that represents the summary of a Nexpose Site.
   #
   class SiteSummary
-    # The Site ID
+
+    # The Site ID.
     attr_reader :id
-    # The Site Name
-    attr_reader :site_name
-    # A Description of the Site
+    # The Site Name.
+    attr_reader :name
+    # A Description of the Site.
     attr_reader :description
-    # User assigned risk multiplier
-    attr_reader :riskfactor
+    # User assigned risk multiplier.
+    attr_reader :risk_factor
+    # Current computed risk score for the site.
+    attr_reader :risk_factor
 
     # Constructor
-    # SiteSummary(id, site_name, description, riskfactor = 1)
-    def initialize(id, site_name, description, riskfactor = 1.0)
+    # SiteSummary(id, name, description, riskfactor = 1)
+    def initialize(id, name, description, risk_factor = 1.0, risk_score = 0.0)
       @id = id
-      @site_name = site_name
+      @name = name
       @description = description
-      @riskfactor = riskfactor
-    end
-
-    def _set_id(id)
-      @id = id
-    end
-  end
-
-  # === Description
-  # Object that represents a listing of devices for a site or the entire NSC. Note that only devices which are accessible to the account used to create the connection object will be returned. This object is created and populated automatically with the instantiation of a new Site object.
-  #
-  class SiteDeviceListing
-
-    # true if an error condition exists; false otherwise
-    attr_reader :error
-    # Error message string
-    attr_reader :error_msg
-    # The last XML request sent by this object
-    attr_reader :request_xml
-    # The last XML response received by this object
-    attr_reader :response_xml
-    # The NSC Connection associated with this object
-    attr_reader :connection
-    # The Site ID. 0 if all sites are specified.
-    attr_reader :site_id
-    # //Array of (Device)*
-    attr_reader :devices
-
-    def initialize(connection, site_id = 0)
-
-      @site_id = site_id
-      @error = false
-      @connection = connection
-      @devices = []
-
-      r = nil
-      if (@site_id)
-        r = @connection.execute('<SiteDeviceListingRequest session-id="' + connection.session_id + '" site-id="' + "#{@site_id}" + '"/>')
-        if r.success
-          r.res.elements.each('SiteDeviceListingResponse/SiteDevices/device') do |d|
-            @devices.push(Device.new(d.attributes['id'], @site_id, d.attributes["address"], d.attributes["riskfactor"], d.attributes["riskscore"]))
-          end
-        end
-      else
-        r = @connection.execute('<SiteDeviceListingRequest session-id="' + connection.session_id + '"/>')
-        if r.success
-          r.res.elements.each('SiteDeviceListingResponse/SiteDevices') do |rr|
-            @sid = rr.attribute("site-id")
-            rr.elements.each('device') do |d|
-              @devices.push(Device.new(d.attributes['id'], @sid, d.attributes["address"], d.attributes['riskfactor'], d.attributes['riskscore']))
-            end
-          end
-        end
-      end
+      @risk_factor = risk_factor
+      @risk_score = risk_score
     end
   end
 
   # === Description
-  # Object that represents a single device in an NSC.
+  # Object that represents a single device in a Nexpose security console.
   #
   class Device
 
-    # A unique device ID (assigned by the NSC)
+    # A unique device ID (assigned automatically by the Nexpose console).
     attr_reader :id
-    # The site ID of this devices site
-    attr_reader :site_id
-    # IP Address or Hostname of this device
+    # IP Address or Hostname of this device.
     attr_reader :address
-    # User assigned risk multiplier
-    attr_reader :riskfactor
-    # Nexpose risk score
-    attr_reader :riskscore
+    # User assigned risk multiplier.
+    attr_reader :risk_factor
+    # Nexpose risk score.
+    attr_reader :risk_score
+    # Site ID that this device is associated with.
+    attr_reader :site_id
 
-    def initialize(id, site_id, address, riskfactor=1, riskscore=0)
+    def initialize(id, address, site_id, risk_factor = 1.0, risk_score = 0.0)
       @id = id
-      @site_id = site_id
       @address = address
-      @riskfactor = riskfactor
-      @riskscore = riskscore
-
+      @site_id = site_id
+      @risk_factor = risk_factor
+      @risk_score = risk_score
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexpose
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-06 00:00:00.000000000 Z
+date: 2013-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: librex