nexpose 0.2.8 → 0.5.0

data/lib/nexpose/scan_template.rb

@@ -0,0 +1,103 @@
+module Nexpose
+  module NexposeAPI
+
+    # List the scan templates currently configured on the console.
+    #
+    # @return [Array[String]] list of scan templates IDs.
+    #
+    def list_scan_templates
+      templates = JSON.parse(AJAX.get(self, '/data/scan/templates'))
+      templates['valueList']
+    end
+
+    alias_method :scan_templates, :list_scan_templates
+
+    # Delete a scan template from the console.
+    # Cannot be used to delete a built-in template.
+    #
+    # @param [String] id Unique identifier of an existing scan template.
+    #
+    def delete_scan_template(id)
+      AJAX.delete(self, "/data/scan/templates/#{URI.encode(id)}")
+    end
+  end
+
+  # Configuration object for a scan template.
+  # This class is only a partial representation of some of the features
+  # available for configuration.
+  #
+  class ScanTemplate
+
+    # Unique identifier of the scan template.
+    attr_accessor :id
+
+    attr_accessor :name
+    attr_accessor :description
+
+    # Whether to correlate reliable checks with regular checks.
+    attr_accessor :correlate
+
+    # Parsed XML of a scan template
+    attr_accessor :xml
+
+    def initialize(xml)
+      @xml = xml
+
+      root = REXML::XPath.first(xml, 'ScanTemplate')
+      @id = root.attributes['id']
+
+      desc = REXML::XPath.first(root, 'templateDescription')
+      @name = desc.attributes['title']
+      @description = desc.text.to_s
+
+      vuln_checks = REXML::XPath.first(root, 'VulnerabilityChecks')
+      @correlate = vuln_checks.attributes['correlate'] == '1'
+    end
+
+    # Save this scan template configuration to a Nexpose console.
+    #
+    def save(nsc)
+      root = REXML::XPath.first(@xml, 'ScanTemplate')
+      existing = root.attributes['id'] == @id
+      root.attributes['id'] = @id unless existing
+
+      desc = REXML::XPath.first(root, 'templateDescription')
+      desc.attributes['title'] = @name
+      desc.text = @description
+
+      vuln_checks = REXML::XPath.first(root, 'VulnerabilityChecks')
+      vuln_checks.attributes['correlate'] = (@correlate ? '1' : '0')
+
+      if existing
+        response = AJAX.put(nsc, "/data/scan/templates/#{URI.encode(id)}", xml)
+      else
+        response = JSON.parse(AJAX.post(nsc, '/data/scan/templates', xml))
+        @id = response['value']
+      end
+    end
+
+    # Load an existing scan template.
+    #
+    # @param [Connection] nsc API connection to a Nexpose console.
+    # @param [String] id Unique identifier of an existing scan template.
+    # @return [ScanTemplate] The requested scan template configuration.
+    #
+    def self.load(nsc, id)
+      response = JSON.parse(AJAX.get(nsc, "/data/scan/templates/#{URI.encode(id)}"))
+      new(REXML::Document.new(response['value']))
+    end
+
+    # Copy an existing scan template, changing the id and title.
+    #
+    # @param [Connection] nsc API connection to a Nexpose console.
+    # @param [String] id Unique identifier of an existing scan template.
+    # @return [ScanTemplate] A copy of the requested scan template configuration.
+    #
+    def self.copy(nsc, id)
+      dupe = load(nsc, id)
+      dupe.id = "#{dupe.id}-copy"
+      dupe.title = "#{dupe.title} Copy"
+      dupe
+    end
+  end
+end

data/lib/nexpose/site.rb

@@ -2,79 +2,15 @@ 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 = nil)
-      r = execute(make_xml('SiteDeviceListingRequest', {'site-id' => site_id}))
-
-      devices = []
-      if r.success
-        r.res.elements.each('SiteDeviceListingResponse/SiteDevices') do |site|
-          site_id = site.attributes['site-id'].to_i
-          site.elements.each('device') do |device|
-            devices << Device.new(device.attributes['id'].to_i,
-                              device.attributes['address'],
-                              site_id,
-                              device.attributes['riskfactor'].to_f,
-                              device.attributes['riskscore'].to_f)
-          end
-        end
-      end
-      devices
-    end
-
-    alias_method :assets, :site_device_listing
-    alias_method :devices, :site_device_listing
-    alias_method :list_devices, :site_device_listing
-
-    # Find a Device by its address.
-    #
-    # This is a convenience method for finding a single device from a SiteDeviceListing.
-    # If no site_id is provided, the first matching device will be returned when a device
-    # occurs across multiple sites.
-    #
-    # @param [String] address Address of the device to find. Usually the IP address.
-    # @param [FixNum] site_id Site ID to request scan history for.
-    # @return [Device] The first matching Device with the provided address, if found.
-    #
-    def find_device_by_address(address, site_id = nil)
-      r = execute(make_xml('SiteDeviceListingRequest', {'site-id' => site_id}))
-      if r.success
-        device = REXML::XPath.first(r.res, "SiteDeviceListingResponse/SiteDevices/device[@address='#{address}']")
-        return Device.new(device.attributes['id'].to_i,
-                          device.attributes['address'],
-                          device.parent.attributes['site-id'],
-                          device.attributes['riskfactor'].to_f,
-                          device.attributes['riskscore'].to_f) if device
-      end
-      nil
-    end
-
-    # Delete the specified site and all associated scan data.
-    #
-    # @return Whether or not the delete request succeeded.
-    #
-    def site_delete(site_id)
-      r = execute(make_xml('SiteDeleteRequest', {'site-id' => site_id}))
-      r.success
-    end
-
     # Retrieve a list of all sites the user is authorized to view or manage.
     #
     # @return [Array[SiteSummary]] Array of SiteSummary objects.
-    # 
-    def site_listing
+    #
+    def list_sites
       r = execute(make_xml('SiteListingRequest'))
       arr = []
-      if (r.success)
-        r.res.elements.each("SiteListingResponse/SiteSummary") do |site|
+      if r.success
+        r.res.elements.each('SiteListingResponse/SiteSummary') do |site|
           arr << SiteSummary.new(site.attributes['id'].to_i,
                                  site.attributes['name'],
                                  site.attributes['description'],
@@ -85,8 +21,16 @@ module Nexpose
       arr
     end
 
-    alias_method :list_sites, :site_listing
-    alias_method :sites, :site_listing
+    alias_method :sites, :list_sites
+
+    # Delete the specified site and all associated scan data.
+    #
+    # @return Whether or not the delete request succeeded.
+    #
+    def delete_site(site_id)
+      r = execute(make_xml('SiteDeleteRequest', {'site-id' => site_id}))
+      r.success
+    end
 
     # Retrieve a list of all previous scans of the site.
     #
@@ -111,68 +55,11 @@ module Nexpose
     # Method will not return data on an active scan.
     #
     # @param [FixNum] site_id Site ID to find latest scan for.
+    # @return [ScanSummary] details of the last completed scan for a site.
     #
     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.
-    #
-    # devices - An Array of device IDs
-    # hosts - An Array of Hashes [o]=>{:range=>"from,to"} [1]=>{:host=>host}
-    #-----------------------------------------------------------------------
-    def site_device_scan_start(site_id, devices, hosts = nil)
-
-      if hosts == nil and devices == nil
-        raise ArgumentError.new('Both the device and host list is nil.')
-      end
-
-      xml = make_xml('SiteDevicesScanRequest', {'site-id' => site_id})
-
-      if devices != nil
-        inner_xml = REXML::Element.new 'Devices'
-        for device_id in devices
-          inner_xml.add_element 'device', {'id' => "#{device_id}"}
-        end
-        xml.add_element inner_xml
-      end
-
-      if hosts
-        inner_xml = REXML::Element.new 'Hosts'
-        hosts.each_index do |x|
-          if hosts[x].key? :range
-            from, to = hosts[x][:range].split(',')
-            if to
-              inner_xml.add_element 'range', {'to' => to, 'from' => from}
-            else
-              inner_xml.add_element 'range', {'from' => from}
-            end
-          end
-          if hosts[x].key? :host
-            host_element = REXML::Element.new 'host'
-            host_element.text = "#{hosts[x][:host]}"
-            inner_xml.add_element host_element
-          end
-        end
-        xml.add_element inner_xml
-      end
-
-      r = execute xml
-      if r.success
-        r.res.elements.each('//Scan') do |scan_info|
-          return {
-            :scan_id => scan_info.attributes['scan-id'].to_i,
-            :engine_id => scan_info.attributes['engine-id'].to_i
-          }
-        end
-      else
-        false
-      end
-    end
-
-    alias_method :site_device_scan, :site_device_scan_start
-    alias_method :adhoc_device_scan, :site_device_scan_start
   end
 
   # Configuration object representing a Nexpose site.
@@ -270,6 +157,14 @@ module Nexpose
       @assets << IPRange.new(ip)
     end
 
+    # Adds assets to this site by IP address range.
+    #
+    # @param [String] from Beginning IP address of a range.
+    # @param [String] to Ending IP address of a range.
+    def add_ip_range(from, to)
+      @assets << IPRange.new(from, to)
+    end
+
     # Adds an asset to this site, resolving whether an IP or hostname is
     # provided.
     #
@@ -277,12 +172,14 @@ module Nexpose
     #
     def add_asset(asset)
       begin
+        # If the asset registers as a valid IP, store as IP.
+        ip = IPAddr.new(asset)
         add_ip(asset)
       rescue ArgumentError => e
         if e.message == 'invalid address'
           add_host(asset)
         else
-          raise "Unable to parse asset: '#{asset}'"
+          raise "Unable to parse asset: '#{asset}'. #{e.message}"
         end
       end
     end
@@ -292,16 +189,21 @@ module Nexpose
     # @param [Connection] connection Connection to console where site exists.
     # @param [Fixnum] id Site ID of an existing site.
     # @return [Site] Site configuration loaded from a Nexpose console.
+    #
     def self.load(connection, id)
-      r = APIRequest.execute(connection.url, %Q(<SiteConfigRequest session-id="#{connection.session_id}" site-id="#{id}"/>))
+      r = APIRequest.execute(connection.url,
+                             %(<SiteConfigRequest session-id="#{connection.session_id}" site-id="#{id}"/>))
       parse(r.res)
     end
 
     # Copy an existing configuration from a Nexpose instance.
+    # Returned object will reset the site ID and append "Copy" to the existing
+    # name.
     #
-    # @param [Connection] connection Connection to console where scan will be launched.
+    # @param [Connection] connection Connection to the security console.
     # @param [Fixnum] id Site ID of an existing site.
     # @return [Site] Site configuration loaded from a Nexpose console.
+    #
     def self.copy(connection, id)
       site = self.load(connection, id)
       site.id = -1
@@ -313,19 +215,19 @@ module Nexpose
     #
     # @param [Connection] connection Connection to console where this site will be saved.
     # @return [Fixnum] Site ID assigned to this configuration, if successful.
+    #
     def save(connection)
       r = connection.execute('<SiteSaveRequest session-id="' + connection.session_id + '">' + to_xml + ' </SiteSaveRequest>')
-      if r.success
-        @id = r.attributes['site-id'].to_i
-      end
+      @id = r.attributes['site-id'].to_i if r.success
     end
 
     # Delete this site from a Nexpose console.
     #
     # @param [Connection] connection Connection to console where this site will be saved.
     # @return [Boolean] Whether or not the site was successfully deleted.
+    #
     def delete(connection)
-      r = connection.execute(%Q{<SiteDeleteRequest session-id="#{connection.session_id}" site-id="#{@id}"/>})
+      r = connection.execute(%(<SiteDeleteRequest session-id="#{connection.session_id}" site-id="#{@id}"/>))
       r.success
     end
 
@@ -333,32 +235,34 @@ module Nexpose
     #
     # @param [Connection] connection Connection to console where scan will be launched.
     # @param [String] sync_id Optional synchronization token.
-    # @return [Fixnum, Fixnum] Scan ID and engine ID where the scan was launched.
+    # @return [Scan] Scan launch information.
+    #
     def scan(connection, sync_id = nil)
       xml = REXML::Element.new('SiteScanRequest')
-      xml.add_attributes({'session-id' => connection.session_id,
-                          'site-id' => @id,
-                          'sync-id' => sync_id})
+      xml.add_attributes({ 'session-id' => connection.session_id,
+                           'site-id' => @id,
+                           'sync-id' => sync_id })
 
       response = connection.execute(xml)
-      if response.success
-        scan = REXML::XPath.first(response.res, '/SiteScanResponse/Scan/')
-        [scan.attributes['scan-id'].to_i, scan.attributes['engine-id'].to_i]
-      end
+      Scan.parse(response.res) if response.success
     end
 
+    include Sanitize
+
     # Generate an XML representation of this site configuration
+    #
     # @return [String] XML valid for submission as part of other requests.
+    #
     def to_xml
-      xml = %Q(<Site id='#{id}' name='#{name}' description='#{description}' riskfactor='#{risk_factor}'>)
+      xml = %(<Site id='#{id}' name='#{replace_entities(name)}' description='#{description}' riskfactor='#{risk_factor}'>)
 
       xml << '<Hosts>'
-      xml << assets.reduce('') { |acc, host| acc << host.to_xml }
+      xml << assets.reduce('') { |a, e| a << e.to_xml }
       xml << '</Hosts>'
 
       unless exclude.empty?
         xml << '<ExcludedHosts>'
-        xml << exclude.reduce('') { |acc, host| acc << host.to_xml }
+        xml << exclude.reduce('') { |a, e| a << e.to_xml }
         xml << '</ExcludedHosts>'
       end
 
@@ -378,7 +282,7 @@ module Nexpose
         xml << '</Alerting>'
       end
 
-      xml << %Q(<ScanConfig configID="#{@id}" name="#{@scan_template_name || @scan_template}" templateID="#{@scan_template}" configVersion="#{@config_version || 3}" engineID="#{@engine}">)
+      xml << %(<ScanConfig configID="#{@id}" name="#{@scan_template_name || @scan_template}" templateID="#{@scan_template}" configVersion="#{@config_version || 3}" engineID="#{@engine}">)
 
       xml << '<Schedules>'
       @schedules.each do |schedule|
@@ -394,6 +298,7 @@ module Nexpose
     # @param [REXML::Document] rexml XML document to parse.
     # @return [Site] Site object represented by the XML.
     #  ## TODO What is returned on failure?
+    #
     def self.parse(rexml)
       rexml.elements.each('SiteConfigResponse/Site') do |s|
         site = Site.new(s.attributes['name'])
@@ -417,8 +322,8 @@ module Nexpose
         end
 
         s.elements.each('Credentials/adminCredentials') do |credconf|
-          cred = AdminCredentials.new(true)
-          cred.set_service(credconf.attributes['service'])
+          cred = Credential.new
+          cred.service = credconf.attributes['service']
           cred.set_blob(credconf.get_text)
           site.credentials << cred
         end
@@ -443,62 +348,6 @@ module Nexpose
     end
   end
 
-  # === Description
-  # Object that represents a listing of all of the sites available on an NSC.
-  #
-  # === Example
-  #   # Create a new Nexpose Connection on the default port and Login
-  #   nsc = Connection.new("10.1.40.10","nxadmin","password")
-  #   nsc->login;
-  #
-  #   # Get Site Listing
-  #   sitelisting = SiteListing.new(nsc)
-  #
-  #   # Enumerate through all of the SiteSummaries
-  #   sitelisting.sites.each do |sitesummary|
-  #       # Do some operation on each site
-  #   end
-  #
-  class SiteListing
-
-    # The NSC Connection associated with this object
-    attr_reader :connection
-    # Array containing SiteSummary objects for each site in the connection
-    attr_reader :sites
-    # The number of sites
-    attr_reader :site_count
-
-    # Constructor
-    # SiteListing (connection)
-    def initialize(connection)
-      @sites = []
-
-      @connection = connection
-
-      r = @connection.execute('<SiteListingRequest session-id="' + @connection.session_id.to_s + '"/>')
-
-      if r.success
-        parse(r.res)
-      else
-        raise APIError.new(r, 'Failed to get site listing.')
-      end
-    end
-
-    def parse(r)
-      r.elements.each('SiteListingResponse/SiteSummary') do |s|
-        site_summary = SiteSummary.new(
-          s.attributes['id'].to_s,
-          s.attributes['name'],
-          s.attributes['description'],
-          s.attributes['riskfactor'].to_s
-        )
-        @sites.push(site_summary)
-      end
-      @site_count = @sites.length
-    end
-  end
-
-  # === Description
   # Object that represents the summary of a Nexpose Site.
   #
   class SiteSummary
@@ -516,7 +365,7 @@ module Nexpose
 
     # Constructor
     # SiteSummary(id, name, description, riskfactor = 1)
-    def initialize(id, name, description, risk_factor = 1.0, risk_score = 0.0)
+    def initialize(id, name, description = nil, risk_factor = 1.0, risk_score = 0.0)
       @id = id
       @name = name
       @description = description
@@ -525,33 +374,10 @@ module Nexpose
     end
   end
 
-  # === Description
-  # Object that represents a single device in a Nexpose security console.
-  #
-  class Device
-
-    # A unique device ID (assigned automatically by the Nexpose console).
-    attr_reader :id
-    # IP Address or Hostname of this device.
-    attr_reader :address
-    # 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, address, site_id, risk_factor = 1.0, risk_score = 0.0)
-      @id = id.to_i
-      @address = address
-      @site_id = site_id.to_i
-      @risk_factor = risk_factor.to_f
-      @risk_score = risk_score.to_f
-    end
-  end
-
   # Object that represents a hostname to be added to a site.
+  #
   class HostName
+
     # Named host (usually DNS or Netbios name).
     attr_accessor :host
 
@@ -584,9 +410,9 @@ module Nexpose
     end
   end
 
-  # === Description
   # Object that represents a single IP address or an inclusive range of IP addresses.
   # If to is nil then the from field will be used to specify a single IP Address only.
+  #
   class IPRange
 
     # Start of range *Required
@@ -595,18 +421,46 @@ module Nexpose
     attr_accessor :to
 
     def initialize(from, to = nil)
-      @from = IPAddr.new(from)
-      @to = IPAddr.new(to) if to
+      @from = from
+      @to = to unless from == to
     end
 
     include Comparable
 
     def <=>(other)
-      to_xml <=> other.to_xml
+      from = IPAddr.new(@from)
+      to = @to.nil? ? from : IPAddr.new(@to)
+      cf_from = IPAddr.new(other.from)
+      cf_to = IPAddr.new(other.to.nil? ? other.from : other.to)
+      if cf_to < from
+        1
+      elsif to < cf_from
+        -1
+      else # Overlapping
+        0
+      end
+    end
+
+    def ==(other)
+      eql?(other)
     end
 
     def eql?(other)
-      to_xml == other.to_xml
+      @from == other.from && @to == other.to
+    end
+
+    def include?(single_ip)
+      from = IPAddr.new(@from)
+      to = @to.nil? ? from : IPAddr.new(@to)
+      other = IPAddr.new(single_ip)
+
+      if other < from
+        false
+      elsif to < other
+        false
+      else
+        true
+      end
     end
 
     def hash
@@ -615,7 +469,7 @@ module Nexpose
 
     def to_xml_elem
       xml = REXML::Element.new('range')
-      xml.add_attributes({'from' => @from, 'to' => @to})
+      xml.add_attributes({ 'from' => @from, 'to' => @to })
       xml
     end