nexpose 0.1.2 → 0.1.3

data/lib/nexpose/scan.rb

@@ -48,59 +48,31 @@ module Nexpose
       r.success ? r.attributes['success'] : nil
     end
 
+    # Retrieve a list of current scan activities across all Scan Engines managed
+    # by Nexpose.
+    #
+    # @return [Array[ScanSummary]] Array of ScanSummary objects associated with
+    #   each active scan on the engines.
+    #
     def scan_activity
       r = execute(make_xml('ScanActivityRequest', {}))
+      res = []
       if (r.success)
-        res = []
         r.res.elements.each("//ScanSummary") do |scan|
-          res << {
-            :scan_id => scan.attributes['scan-id'].to_i,
-            :site_id => scan.attributes['site-id'].to_i,
-            :engine_id => scan.attributes['engine-id'].to_i,
-            :status => scan.attributes['status'].to_s,
-            :start_time => Date.parse(scan.attributes['startTime'].to_s).to_time
-          }
+          res << ScanSummary.parse(scan)
         end
-        res
-      else
-        false
       end
+      res
     end
 
-    def scan_statistics(param)
-      r = execute(make_xml('ScanStatisticsRequest', {'scan-id' => param}))
-      if (r.success)
-        res = {}
-        r.res.elements.each("//ScanSummary/nodes") do |node|
-          res[:nodes] = {}
-          node.attributes.keys.each do |k|
-            res[:nodes][k] = node.attributes[k].to_i
-          end
-        end
-        r.res.elements.each("//ScanSummary/tasks") do |task|
-          res[:task] = {}
-          task.attributes.keys.each do |k|
-            res[:task][k] = task.attributes[k].to_i
-          end
-        end
-        r.res.elements.each("//ScanSummary/vulnerabilities") do |vuln|
-          res[:vulns] ||= {}
-          k = vuln.attributes['status'] + (vuln.attributes['severity'] ? ("-" + vuln.attributes['severity']) : '')
-          res[:vulns][k] = vuln.attributes['count'].to_i
-        end
-        r.res.elements.each("//ScanSummary") do |summ|
-          res[:summary] = {}
-          summ.attributes.keys.each do |k|
-            res[:summary][k] = summ.attributes[k]
-            if (res[:summary][k] =~ /^\d+$/)
-              res[:summary][k] = res[:summary][k].to_i
-            end
-          end
-        end
-        r.res.elements.each("//ScanSummary/message") do |message|
-          res[:message] = message.text
-        end
-        res
+    # Get scan statistics, including node and vulnerability breakdowns.
+    #
+    # @return [ScanSummary] ScanSummary object providing statistics for the scan.
+    #
+    def scan_statistics(scan_id)
+      r = execute(make_xml('ScanStatisticsRequest', {'scan-id' => scan_id}))
+      if r.success
+        ScanSummary.parse(r.res)
       else
         false
       end
@@ -111,115 +83,188 @@ module Nexpose
   # Object that represents a summary of a scan.
   #
   class ScanSummary
+
     # The Scan ID of the Scan
     attr_reader :scan_id
-    # The Engine ID used to perform the scan
+    # The site that was scanned.
+    attr_reader :site_id
+    # The Engine ID the scan was dispatched to.
     attr_reader :engine_id
-    # TODO: add description
-    attr_reader :name
     # The scan start time
-    attr_reader :startTime
+    attr_reader :start_time
     # The scan finish time
-    attr_reader :endTime
-    # The scan status (running|finished|stopped|error| dispatched|paused|aborted|uknown)
+    attr_reader :end_time
+    # The scan status.
+    # One of: running|finished|stopped|error|dispatched|paused|aborted|uknown
     attr_reader :status
-    # The number of pending tasks
-    attr_reader :tasks_pending
-    # The number of active tasks
-    attr_reader :tasks_active
-    # The number of completed tasks
-    attr_reader :tasks_completed
-    # The number of "live" nodes
-    attr_reader :nodes_live
-    # The number of "dead" nodes
-    attr_reader :nodes_dead
-    # The number of filtered nodes
-    attr_reader :nodes_filtered
-    # The number of unresolved nodes
-    attr_reader :nodes_unresolved
-    # The number of "other" nodes
-    attr_reader :nodes_other
-    # Confirmed vulnerabilities found (indexed by severity)
-    # Associative array, indexed by severity
-    attr_reader :vuln_exploit
-    # Unconfirmed vulnerabilities found (indexed by severity)
-    # Associative array, indexed by severity
-    attr_reader :vuln_version
-    # Not vulnerable checks run (confirmed)
-    attr_reader :not_vuln_exploit
-    # Not vulnerable checks run (unconfirmed)
-    attr_reader :not_vuln_version
-    # Vulnerability check errors
-    attr_reader :vuln_error
-    # Vulnerability checks disabled
-    attr_reader :vuln_disabled
-    # Vulnerability checks other
-    attr_reader :vuln_other
+
+    # The reason the scan was stopped or failed, if applicable.
+    attr_reader :message
+
+    # Task statistics, including pending, active, and completed tasks.
+    attr_reader :tasks
+    # Node statistics, including live, dead, filtered, and unresolved.
+    attr_reader :nodes
+    # Vulnerability statistics, including statuses, severities, and counts.
+    attr_reader :vulnerabilities
 
     # Constructor
-    # ScanSummary(can_id, $engine_id, $name, tartTime, $endTime, tatus)
-    def initialize(scan_id, engine_id, name, startTime, endTime, status)
+    def initialize(scan_id, site_id, engine_id, status, start_time, end_time, message, tasks, nodes, vulnerabilities)
+      @scan_id, @site_id, @engine_id, @status, @start_time, @end_time = scan_id, site_id, engine_id, status, start_time, end_time
+      @message, @tasks, @nodes, @vulnerabilities = message, tasks, nodes, vulnerabilities
+    end
 
-      @scan_id = scan_id
-      @engine_id = engine_id
-      @name = name
-      @startTime = startTime
-      @endTime = endTime
-      @status = status
+    # Parse a response from a Nexpose console into a valid ScanSummary object.
+    #
+    # @param [REXML::Document] rexml XML document to parse.
+    # @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
 
+      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)
+      end
     end
 
-  end
+    # Value class to tracking task counts.
+    #
+    class Tasks
+      attr_reader :pending, :active, :completed
 
-  # TODO
-  # === Description
-  # Object that represents the overview statistics for a particular scan.
-  #
-  # === Examples
-  #
-  #   # Create a new Nexpose Connection on the default port and Login
-  #   nsc = Connection.new("10.1.40.10","nxadmin","password")
-  #   nsc.login()
-  #
-  #   # Get a Site (Site ID = 12) from the NSC
-  #   site = new Site(nsc,12)
-  #
-  #   # Start a Scan of this site and pause for 1 minute
-  #   scan1 = site.scanSite()
-  #   sleep(60)
-  #
-  #   # Get the Scan Statistics for this scan
-  #   scanStatistics = new ScanStatistics(nsc,scan1["scan_id"])
-  #
-  #   # Print out number of confirmed vulnerabilities with a 10 severity
-  #   puts scanStatistics.scansummary.vuln_exploit[10]
-  #
-  #   # Print out the number of pending tasks left in the scan
-  #   puts scanStatistics.scan_summary.tasks_pending
-  #
-  class ScanStatistics
-    # 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 :reseponse_xml
-    # The Scan ID
-    attr_reader :scan_id
-    # The ScanSummary of the scan
-    attr_reader :scan_summary
-    # The NSC Connection associated with this object
-    attr_reader :connection
+      def initialize(pending, active, completed)
+        @pending, @active, @completed = pending, active, completed
+      end
+
+      # Parse REXML to Tasks object.
+      #
+      # @param [REXML::Document] rexml XML document to parse.
+      # @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
+      end
+    end
+
+    # Value class for tracking node counts.
+    #
+    class Nodes
+      attr_reader :live, :dead, :filtered, :unresolved, :other
 
-    # Vulnerability checks other
-    attr_reader :vuln_other
+      def initialize(live, dead, filtered, unresolved, other)
+        @live, @dead, @filtered, @unresolved, @other = live, dead, filtered, unresolved, other
+      end
 
-    def initialize(connection, scan_id)
-      @error = false
-      @connection = connection
-      @scan_id = scan_id
+      # Parse REXML to Nodes object.
+      #
+      # @param [REXML::Document] rexml XML document to parse.
+      # @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
+      end
+    end
+
+    # Value class for tracking vulnerability counts.
+    #
+    class Vulnerabilities
+      attr_reader :vuln_exploit, :vuln_version, :vuln_potential,
+        :not_vuln_exploit, :not_vuln_version,
+        :error, :disabled, :other
+
+      def initialize(vuln_exploit, vuln_version, vuln_potential,
+                     not_vuln_exploit, not_vuln_version,
+                     error, disabled, other)
+        @vuln_exploit, @vuln_version, @vuln_potential,
+          @not_vuln_exploit, @not_vuln_version,
+          @error, @disabled, @other =
+          vuln_exploit, vuln_version, vuln_potential,
+          not_vuln_exploit, not_vuln_version,
+          error, disabled, other
+      end
+      
+      # Parse REXML to Vulnerabilities object.
+      #
+      # @param [REXML::Document] rexml XML document to parse.
+      # @return [Vulnerabilities] Vulnerability summary represented by the XML.
+      #
+      def self.parse(rexml)
+        map = {}
+        rexml.elements.each("//ScanSummary/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)
+          else
+            map[vuln.attributes['status']] = Status.new(vuln.attributes['severity'], vuln.attributes['count'].to_i)
+          end
+        end
+        Vulnerabilities.new(map['vuln-exploit'],
+                            map['vuln-version'],
+                            map['vuln-potential'],
+                            map['not-vuln-exploit'],
+                            map['not-vuln-version'],
+                            map['error'],
+                            map['disabled'],
+                            map['other'])
+      end
+
+      # Value class for tracking vulnerability status counts.
+      #
+      # Severities will only be mapped if they are provided in the response,
+      # which currently only happens for vuln-exploit, vuln-version,
+      # and vuln-potential.
+      #
+      class Status
+        attr_reader :severities, :count
+
+        def initialize(severity = nil, count = 0)
+          if severity
+            @severities = {}
+            @count = 0
+            add_severity(severity.to_i, count)
+          else
+            @severities = nil
+            @count = count
+          end
+        end
+
+        # For vuln-exploit, vuln-version, and vuln-potential,
+        # map the count at a severity level, but also maintain an overall count.
+        def add_severity(severity, count)
+          @count += count
+          @severities[severity] = count
+        end
+      end
     end
   end
 

data/lib/nexpose/scan_engine.rb

@@ -7,6 +7,23 @@ module Nexpose
       xml = make_xml('EngineDeleteRequest', {'engine-id' => engine_id})
       execute(xml, '1.2')
     end
+
+    # Provide a list of current scan activities for a specific Scan Engine.
+    #
+    # @return [Array[ScanSummary]] Array of ScanSummary objects associated with
+    #   each active scan on the engine.
+    #
+    def engine_activity(engine_id)
+      xml = make_xml('EngineActivityRequest', {'engine-id' => engine_id})
+      r = execute(xml)
+      arr = []
+      if r.success
+        r.res.elements.each("//ScanSummary") do |scan_event|
+          arr << ScanSummary.parse(scan_event)
+        end
+      end
+      arr
+    end
   end
 
   # ==== Description
@@ -45,10 +62,6 @@ module Nexpose
     end
   end
 
-  # TODO
-  class EngineActivity
-  end
-
   # ==== Description
   # Object that represents the summary of a scan engine.
   #

data/lib/nexpose/site.rb

@@ -56,28 +56,21 @@ module Nexpose
       end
     end
 
-    #-----------------------------------------------------------------------
-    # TODO: Needs to be expanded to included details
-    #       Also confusing. Name clashes with field on Site
-    #-----------------------------------------------------------------------
+    # Retrieve a list of all previous scans of the site.
+    #
+    # @param [FixNum] site_id Site ID to request scan history for.
+    # @return [Array[ScanSummary]] Array of ScanSummary objects representing
+    #   each scan run to date on the site provided.
+    #
     def site_scan_history(site_id)
-      r = execute(make_xml('SiteScanHistoryRequest', {'site-id' => site_id.to_s}))
-
-      if (r.success)
-        res = []
-        r.res.elements.each("//ScanSummary") do |site_scan_history|
-          res << {
-            :site_id => site_scan_history.attributes['site-id'].to_i,
-            :scan_id => site_scan_history.attributes['scan-id'].to_i,
-            :engine_id => site_scan_history.attributes['engine-id'].to_i,
-            :start_time => site_scan_history.attributes['startTime'].to_s,
-            :end_time => site_scan_history.attributes['endTime'].to_s
-          }
+      r = execute(make_xml('SiteScanHistoryRequest', {'site-id' => site_id}))
+      res = []
+      if r.success
+        r.res.elements.each("//ScanSummary") do |scan_event|
+          res << ScanSummary.parse(scan_event)
         end
-        res
-      else
-        false
       end
+      res
     end
 
     #-----------------------------------------------------------------------
@@ -480,50 +473,6 @@ module Nexpose
     end
   end
 
-  # === Description
-  # Object that represents the scan history of a site.
-  #
-  class SiteScanHistory
-    # 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 response received by this object
-    attr_reader :response
-    # The NSC Connection associated with this object
-    attr_reader :connection
-    # The Site ID
-    attr_reader :site_id
-    # //Array containing (ScanSummary*)
-    attr_reader :scan_summaries
-
-    def initialize(connection, id)
-      @site_id = id
-      @error = false
-      @connection = connection
-      @scan_summaries = []
-
-      @request_xml = '<SiteScanHistoryRequest' + ' session-id="' + @connection.session_id + '" site-id="' + "#{@site_id}" + '"/>'
-      r = @connection.execute(@request_xml)
-      @response = r
-
-      if r and r.success
-        r.res.elements.each('//ScanSummary') do |summary|
-          scan_id=summary.attributes['scan-id'].to_i
-          engine_id=summary.attributes['engine-id'].to_i
-          name=summary.attributes['name'].to_s
-          start_time=summary.attributes['startTime'].to_s
-          end_time=summary.attributes['endTime'].to_s
-          status=summary.attributes['status'].to_s
-          scan_summary = ScanSummary.new(scan_id, engine_id, name, start_time, end_time, status)
-          scan_summaries << scan_summary
-        end
-      end
-    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.
   #

metadata

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