nexpose 0.2.8 → 0.5.0

data/lib/nexpose/report_template.rb

@@ -0,0 +1,249 @@
+module Nexpose
+
+  # NexposeAPI module is mixed into the Connection object, and all methods are
+  # expected to be called from there.
+  #
+  module NexposeAPI
+    include XMLUtils
+
+    # Provide a list of all report templates the user can access on the
+    # Security Console.
+    #
+    # @return [Array[ReportTemplateSummary]] List of current report templates.
+    #
+    def list_report_templates
+      r = execute(make_xml('ReportTemplateListingRequest', {}))
+      templates = []
+      if r.success
+        r.res.elements.each('//ReportTemplateSummary') do |template|
+          templates << ReportTemplateSummary.parse(template)
+        end
+      end
+      templates
+    end
+
+    alias_method :report_templates, :list_report_templates
+
+    # Deletes an existing, custom report template.
+    # Cannot delete built-in templates.
+    #
+    # @param [String] template_id Unique identifier of the report template to remove.
+    #
+    def delete_report_template(template_id)
+      AJAX.delete(self, "/data/report/templates/#{template_id}")
+    end
+  end
+
+  # Data object for report template summary information.
+  # Not meant for use in creating new templates.
+  #
+  class ReportTemplateSummary
+
+    # The ID of the report template.
+    attr_reader :id
+    # The name of the report template.
+    attr_reader :name
+    # One of: data|document. With a data template, you can export
+    # comma-separated value (CSV) files with vulnerability-based data.
+    # With a document template, you can create PDF, RTF, HTML, or XML reports
+    # with asset-based information.
+    attr_reader :type
+    # The visibility (scope) of the report template. One of: global|silo
+    attr_reader :scope
+    # Whether the report template is built-in, and therefore cannot be modified.
+    attr_reader :built_in
+    # Description of the report template.
+    attr_reader :description
+
+    def initialize(id, name, type, scope, built_in, description)
+      @id = id
+      @name = name
+      @type = type
+      @scope = scope
+      @built_in = built_in
+      @description = description
+    end
+
+    def delete(connection)
+      connection.delete_report_template(@id)
+    end
+
+    def self.parse(xml)
+      description = nil
+      xml.elements.each('description') { |desc| description = desc.text }
+      ReportTemplateSummary.new(xml.attributes['id'],
+                                xml.attributes['name'],
+                                xml.attributes['type'],
+                                xml.attributes['scope'],
+                                xml.attributes['builtin'] == '1',
+                                description)
+    end
+  end
+
+  # Definition object for a report template.
+  #
+  class ReportTemplate
+
+    # The ID of the report template.
+    attr_accessor :id
+    # The name of the report template.
+    attr_accessor :name
+    # With a data template, you can export comma-separated value (CSV) files
+    # with vulnerability-based data. With a document template, you can create
+    # PDF, RTF, HTML, or XML reports with asset-based information. When you
+    # retrieve a report template, the type will always be visible even though
+    # type is implied. When ReportTemplate is sent as a request, and the type
+    # attribute is not provided, the type attribute defaults to document,
+    # allowing for backward compatibility with existing API clients.
+    attr_accessor :type
+    # The visibility (scope) of the report template.
+    # One of: global|silo
+    attr_accessor :scope
+    # The report template is built-in, and cannot be modified.
+    attr_accessor :built_in
+    # Description of this report template.
+    attr_accessor :description
+
+    # Array of report sections.
+    attr_accessor :sections
+    # Map of report properties.
+    attr_accessor :properties
+    # Array of report attributes, in the order they will be present in a report.
+    attr_accessor :attributes
+    # Display asset names with IPs.
+    attr_accessor :show_device_names
+
+    def initialize(name, type = 'document', id = -1, scope = 'silo', built_in = false)
+      @name = name
+      @type = type
+      @id = id
+      @scope = scope
+      @built_in = built_in
+
+      @sections = []
+      @properties = {}
+      @attributes = []
+      @show_device_names = false
+    end
+
+    # Save the configuration for a report template.
+    def save(connection)
+      xml = %(<ReportTemplateSaveRequest session-id='#{connection.session_id}' scope='#{@scope}'>)
+      xml << to_xml
+      xml << '</ReportTemplateSaveRequest>'
+      response = connection.execute(xml)
+      if response.success
+        @id = response.attributes['template-id']
+      end
+    end
+
+    # Retrieve the configuration for a report template.
+    def self.load(connection, template_id)
+      xml = %(<ReportTemplateConfigRequest session-id='#{connection.session_id}' template-id='#{template_id}'/>)
+      ReportTemplate.parse(connection.execute(xml))
+    end
+
+    def delete(connection)
+      connection.delete_report_template(@id)
+    end
+
+    include Sanitize
+
+    def to_xml
+      xml = %(<ReportTemplate id='#{@id}' name='#{@name}' type='#{@type}')
+      xml << %( scope='#{@scope}') if @scope
+      xml << %( builtin='#{@built_in}') if @built_in
+      xml << '>'
+      xml << %(<description>#{@description}</description>) if @description
+
+      unless @attributes.empty?
+        xml << '<ReportAttributes>'
+        @attributes.each do |attr|
+          xml << %(<ReportAttribute name='#{attr}'/>)
+        end
+        xml << '</ReportAttributes>'
+      end
+
+      unless @sections.empty?
+        xml << '<ReportSections>'
+        properties.each_pair do |name, value|
+          xml << %(<property name='#{name}'>#{replace_entities(value)}</property>)
+        end
+        @sections.each { |section| xml << section.to_xml }
+        xml << '</ReportSections>'
+      end
+
+      xml << %(<Settings><showDeviceNames enabled='#{@show_device_names ? 1 : 0}' /></Settings>)
+      xml << '</ReportTemplate>'
+    end
+
+    def self.parse(xml)
+      xml.res.elements.each('//ReportTemplate') do |tmp|
+        template = ReportTemplate.new(tmp.attributes['name'],
+                                      tmp.attributes['type'],
+                                      tmp.attributes['id'],
+                                      tmp.attributes['scope'] || 'silo',
+                                      tmp.attributes['builtin'])
+        tmp.elements.each('//description') do |desc|
+          template.description = desc.text
+        end
+
+        tmp.elements.each('//ReportAttributes/ReportAttribute') do |attr|
+          template.attributes << attr.attributes['name']
+        end
+
+        tmp.elements.each('//ReportSections/property') do |property|
+          template.properties[property.attributes['name']] = property.text
+        end
+
+        tmp.elements.each('//ReportSection') do |section|
+          template.sections << Section.parse(section)
+        end
+
+        tmp.elements.each('//showDeviceNames') do |show|
+          template.show_device_names = show.attributes['enabled'] == '1'
+        end
+
+        return template
+      end
+      nil
+    end
+  end
+
+  # Section specific content to include in a report template.
+  #
+  class Section
+
+    # Name of the report section.
+    attr_accessor :name
+    # Map of properties specific to the report section.
+    attr_accessor :properties
+
+    def initialize(name)
+      @name = name
+      @properties = {}
+    end
+
+    include Sanitize
+
+    def to_xml
+      xml = %(<ReportSection name='#{@name}'>)
+      properties.each_pair do |name, value|
+        xml << %(<property name='#{name}'>#{replace_entities(value)}</property>)
+      end
+      xml << '</ReportSection>'
+    end
+
+    def self.parse(xml)
+      name = xml.attributes['name']
+      xml.elements.each("//ReportSection[@name='#{name}']") do |elem|
+        section = Section.new(name)
+        elem.elements.each("//ReportSection[@name='#{name}']/property") do |property|
+          section.properties[property.attributes['name']] = property.text
+        end
+        return section
+      end
+      nil
+    end
+  end
+end

data/lib/nexpose/scan.rb

@@ -2,12 +2,141 @@ module Nexpose
   module NexposeAPI
     include XMLUtils
 
+    # Perform an ad hoc scan of a single device.
+    #
+    # @param [Device] device Device to scan.
+    # @return [Scan] Scan launch information.
+    #
+    def scan_device(device)
+      scan_devices([device])
+    end
+
+    # Perform an ad hoc scan of a subset of devices for a site.
+    # Nexpose only allows devices from a single site to be submitted per
+    # request.
+    # Method is designed to take objects from a Device listing.
+    #
+    # For example:
+    #   devices = nsc.devices(5)
+    #   nsc.scan_devices(devices.take(10))
+    #
+    # @param [Array[Device]] devices List of devices to scan.
+    # @return [Scan] Scan launch information.
+    #
+    def scan_devices(devices)
+      site_id = devices.map { |d| d.site_id }.uniq.first
+      xml = make_xml('SiteDevicesScanRequest', { 'site-id' => site_id })
+      elem = REXML::Element.new('Devices')
+      devices.each do |device|
+        elem.add_element('device', { 'id' => "#{device.id}" })
+      end
+      xml.add_element(elem)
+
+      _scan_ad_hoc(xml)
+    end
+
+    # Perform an ad hoc scan of a single asset of a site.
+    #
+    # @param [Fixnum] site_id Site ID that the assets belong to.
+    # @param [HostName|IPRange] asset Asset to scan.
+    # @return [Scan] Scan launch information.
+    #
+    def scan_asset(site_id, asset)
+      scan_assets(site_id, [asset])
+    end
+
+    # Perform an ad hoc scan of a subset of assets for a site.
+    # Only assets from a single site should be submitted per request.
+    # Method is designed to take objects filtered from Site#assets.
+    #
+    # For example:
+    #   site = Site.load(nsc, 5)
+    #   nsc.scan_assets(5, site.assets.take(10))
+    #
+    # @param [Fixnum] site_id Site ID that the assets belong to.
+    # @param [Array[HostName|IPRange]] assets List of assets to scan.
+    # @return [Scan] Scan launch information.
+    #
+    def scan_assets(site_id, assets)
+      xml = make_xml('SiteDevicesScanRequest', { 'site-id' => site_id })
+      hosts = REXML::Element.new('Hosts')
+      assets.each { |asset| _append_asset!(hosts, asset) }
+      xml.add_element(hosts)
+
+      _scan_ad_hoc(xml)
+    end
+
+    # Perform an ad hoc scan of a subset of IP addresses for a site.
+    # Only IPs from a single site can be submitted per request,
+    # and IP addresses must already be included in the site configuration.
+    # Method is designed for scanning when the targets are coming from an
+    # external source that does not have access to internal identfiers.
+    #
+    # For example:
+    #   to_scan = ['192.168.2.1', '192.168.2.107']
+    #   nsc.scan_ips(5, to_scan)
+    #
+    # @param [Fixnum] site_id Site ID that the assets belong to.
+    # @param [Array[String]] ip_addresses Array of IP addresses to scan.
+    # @return [Scan] Scan launch information.
+    #
+    def scan_ips(site_id, ip_addresses)
+      xml = make_xml('SiteDevicesScanRequest', { 'site-id' => site_id })
+      hosts = REXML::Element.new('Hosts')
+      ip_addresses.each do |ip|
+        xml.add_element('range', { 'from' => ip })
+      end
+      xml.add_element(hosts)
+
+      _scan_ad_hoc(xml)
+    end
+
+    # Initiate a site scan.
+    #
+    # @param [Fixnum] site_id Site ID to scan.
+    # @return [Scan] Scan launch information.
+    #
+    def scan_site(site_id)
+      xml = make_xml('SiteScanRequest', { 'site-id' => site_id })
+      response = execute(xml)
+      Scan.parse(response.res) if response.success
+    end
+
+    # Utility method for appending a HostName or IPRange object into an
+    # XML object, in preparation for ad hoc scanning.
+    #
+    # @param [REXML::Document] xml Prepared API call to execute.
+    # @param [HostName|IPRange] asset Asset to append to XML.
+    #
+    def _append_asset!(xml, asset)
+      if asset.kind_of? Nexpose::IPRange
+        xml.add_element('range', { 'from' => asset.from, 'to' => asset.to })
+      else  # Assume HostName
+        host = REXML::Element.new('host')
+        host.text = asset.host
+        xml.add_element(host)
+      end
+    end
+
+    # Utility method for executing prepared XML and extracting Scan launch
+    # information.
+    #
+    # @param [REXML::Document] xml Prepared API call to execute.
+    # @return [Scan] Scan launch information.
+    #
+    def _scan_ad_hoc(xml)
+      r = execute(xml)
+      Scan.parse(r.res)
+    end
+
     # Stop a running or paused scan.
     #
     # @param [Fixnum] scan_id ID of the scan to stop.
-    # @param [Fixnum] wait_sec Number of seconds to wait for status to be updated. Default: 0
-    def scan_stop(scan_id, wait_sec = 0)
-      r = execute(make_xml('ScanStopRequest', {'scan-id' => scan_id}))
+    # @param [Fixnum] wait_sec Number of seconds to wait for status to be
+    #   updated.
+    #
+    def stop_scan(scan_id, wait_sec = 0)
+      r = execute(make_xml('ScanStopRequest', { 'scan-id' => scan_id }))
       if r.success
         so_far = 0
         while so_far < wait_sec
@@ -20,36 +149,36 @@ module Nexpose
       r.success
     end
 
-    def scan_status(param)
-      r = execute(make_xml('ScanStatusRequest', {'scan-id' => param}))
+    # Retrieve the status of a scan.
+    #
+    # @param [Fixnum] scan_id The scan ID.
+    # @return [String] Current status of the scan.
+    #
+    def scan_status(scan_id)
+      r = execute(make_xml('ScanStatusRequest', { 'scan-id' => scan_id }))
       r.success ? r.attributes['status'] : nil
     end
 
-    #----------------------------------------------------------------
     # Resumes a scan.
     #
-    # @param scan_id The scan ID.
-    # @return Success(0|1) if it exists or null.
-    #----------------------------------------------------------------
-    def scan_resume(scan_id)
-      r = execute(make_xml('ScanResumeRequest', {'scan-id' => scan_id}))
+    # @param [Fixnum] scan_id The scan ID.
+    #
+    def resume_scan(scan_id)
+      r = execute(make_xml('ScanResumeRequest', { 'scan-id' => scan_id }))
       r.success ? r.attributes['success'] : nil
     end
 
-
-    #----------------------------------------------------------------
     # Pauses a scan.
     #
-    # @param scan_id The scan ID.
-    # @return Success(0|1) if it exists or null.
-    #----------------------------------------------------------------
-    def scan_pause(scan_id)
-      r = execute(make_xml('ScanPauseRequest',{ 'scan-id' => scan_id}))
+    # @param [Fixnum] scan_id The scan ID.
+    #
+    def pause_scan(scan_id)
+      r = execute(make_xml('ScanPauseRequest', { 'scan-id' => scan_id }))
       r.success ? r.attributes['success'] : nil
     end
 
-    # Retrieve a list of current scan activities across all Scan Engines managed
-    # by Nexpose.
+    # 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.
@@ -67,10 +196,11 @@ module Nexpose
 
     # Get scan statistics, including node and vulnerability breakdowns.
     #
+    # @param [Fixnum] scan_id Scan ID to retrieve statistics for.
     # @return [ScanSummary] ScanSummary object providing statistics for the scan.
     #
     def scan_statistics(scan_id)
-      r = execute(make_xml('ScanStatisticsRequest', {'scan-id' => scan_id}))
+      r = execute(make_xml('ScanStatisticsRequest', { 'scan-id' => scan_id }))
       if r.success
         ScanSummary.parse(r.res.elements['//ScanSummary'])
       else
@@ -79,7 +209,6 @@ module Nexpose
     end
   end
 
-  # === Description
   # Object that represents a summary of a scan.
   #
   class ScanSummary
@@ -129,28 +258,33 @@ module Nexpose
       start_time = nil
       unless xml.attributes['startTime'] == ''
         start_time = DateTime.parse(xml.attributes['startTime'].to_s).to_time
+        # Timestamp is UTC, but parsed as local time.
+        start_time -= start_time.gmt_offset
       end
 
       # End time is often not present, since reporting on running scans.
       end_time = nil
       if xml.attributes['endTime']
         end_time = DateTime.parse(xml.attributes['endTime'].to_s).to_time
+        # Timestamp is UTC, but parsed as local time.
+        end_time -= end_time.gmt_offset
       end
-      return ScanSummary.new(xml.attributes['scan-id'].to_i,
-                             xml.attributes['site-id'].to_i,
-                             xml.attributes['engine-id'].to_i,
-                             xml.attributes['status'],
-                             start_time,
-                             end_time,
-                             msg,
-                             tasks,
-                             nodes,
-                             vulns)
+      ScanSummary.new(xml.attributes['scan-id'].to_i,
+                      xml.attributes['site-id'].to_i,
+                      xml.attributes['engine-id'].to_i,
+                      xml.attributes['status'],
+                      start_time,
+                      end_time,
+                      msg,
+                      tasks,
+                      nodes,
+                      vulns)
     end
 
     # Value class to tracking task counts.
     #
     class Tasks
+
       attr_reader :pending, :active, :completed
 
       def initialize(pending, active, completed)
@@ -164,15 +298,16 @@ module Nexpose
       #
       def self.parse(rexml)
         return nil unless rexml
-        return Tasks.new(rexml.attributes['pending'].to_i,
-                         rexml.attributes['active'].to_i,
-                         rexml.attributes['completed'].to_i)
+        Tasks.new(rexml.attributes['pending'].to_i,
+                  rexml.attributes['active'].to_i,
+                  rexml.attributes['completed'].to_i)
       end
     end
 
     # Value class for tracking node counts.
     #
     class Nodes
+
       attr_reader :live, :dead, :filtered, :unresolved, :other
 
       def initialize(live, dead, filtered, unresolved, other)
@@ -186,20 +321,21 @@ module Nexpose
       #
       def self.parse(rexml)
         return nil unless rexml
-        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)
+        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
 
     # 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
+                  :not_vuln_exploit, :not_vuln_version,
+                  :error, :disabled, :other
 
       def initialize(vuln_exploit, vuln_version, vuln_potential,
                      not_vuln_exploit, not_vuln_version,
@@ -246,6 +382,7 @@ module Nexpose
       # and vuln-potential.
       #
       class Status
+
         attr_reader :severities, :count
 
         def initialize(severity = nil, count = 0)
@@ -269,19 +406,24 @@ module Nexpose
     end
   end
 
-  # TODO: review
-  # <scanFilter scanStop='0' scanFailed='0' scanStart='1'/>
-  # === Description
+  # Struct class for tracking scan launch information.
   #
-  class ScanFilter
-    attr_reader :scan_stop
-    attr_reader :scan_failed
-    attr_reader :scan_start
-
-    def initialize(scan_stop, scan_failed, scan_start)
-      @scan_stop = scan_stop
-      @scan_failed = scan_failed
-      @scan_start = scan_start
+  class Scan
+
+    # The scan ID when a scan is successfully launched.
+    attr_reader :id
+    # The engine the scan was dispatched to.
+    attr_reader :engine
+
+    def initialize(scan_id, engine_id)
+      @id, @engine = scan_id, engine_id
+    end
+
+    def self.parse(xml)
+      xml.elements.each('//Scan') do |scan|
+        return new(scan.attributes['scan-id'].to_i,
+                   scan.attributes['engine-id'].to_i)
+      end
     end
   end
 end