nexpose 0.2.8 → 0.5.0

data/lib/nexpose/engine.rb

@@ -0,0 +1,194 @@
+module Nexpose
+  module NexposeAPI
+    include XMLUtils
+
+    # Removes a scan engine from the list of available engines.
+    #
+    # @param [Fixnum] engine_id Unique ID of an existing engine to remove.
+    # @param [String] scope Whether the engine is global or silo scoped.
+    # @return [Boolean] true if engine successfully deleted.
+    #
+    def delete_engine(engine_id, scope = 'silo')
+      xml = make_xml('EngineDeleteRequest',
+                     {'engine-id' => engine_id, 'scope' => scope})
+      response = execute(xml, '1.2')
+      response.success
+    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
+
+    # 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
+      end
+      arr
+    end
+
+    alias_method :engines, :list_engines
+  end
+
+  # Object representing the current details of a scan engine attached to the
+  # security console.
+  #
+  class EngineSummary
+
+    # A unique ID that identifies this scan engine.
+    attr_reader :id
+    # The name of this scan engine.
+    attr_reader :name
+    # The hostname or IP address of the engine.
+    attr_reader :address
+    # The port there the engine is listening.
+    attr_reader :port
+    # 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
+
+    def initialize(id, name, address, port, status, scope = 'silo')
+      @id = id
+      @name = name
+      @address = address
+      @port = port
+      @status = status
+      @scope = scope
+    end
+  end
+
+  # Engine connnection to a Nexpose console.
+  #
+  class Engine
+
+    # Unique numeric identifier for the scan engine, assigned by the console
+    # in the order of creation.
+    attr_accessor :id
+    # The IP address or DNS name of a scan engine.
+    attr_accessor :address
+    # A name assigned to the scan engine by the security console.
+    attr_accessor :name
+    # The port on which the engine listens for requests from the security
+    # console.
+    attr_accessor :port
+    # Whether the engine has a global or silo-specific scope.
+    attr_accessor :scope
+    # Relative priority of a scan engine.
+    # One of: very-low, low, normal, high, very-high
+    attr_accessor :priority
+
+    # Sites to which the scan engine is assigned.
+    attr_accessor :sites
+
+    def initialize(address, name = nil, port = 40814)
+      @id = -1
+      @address = address
+      @name = name
+      @name ||= address
+      @port = port
+      @scope = 'silo'
+      @sites = []
+    end
+
+    def self.load(connection, id)
+      xml = '<EngineConfigRequest session-id="' + connection.session_id + '"'
+      xml << %( engine-id="#{id}")
+      xml << ' />'
+      r = connection.execute(xml, '1.2')
+
+      if r.success
+        r.res.elements.each('EngineConfigResponse/EngineConfig') do |config|
+          engine = Engine.new(config.attributes['address'],
+                              config.attributes['name'],
+                              config.attributes['port'])
+          engine.id = config.attributes['id']
+          engine.scope = config.attributes['scope'] if config.attributes['scope']
+          engine.priority = config.attributes['priority'] if config.attributes['priority']
+          config.elements.each('Site') do |site|
+            engine.sites << SiteSummary.new(site.attributes['id'], site.attributes['name'])
+          end
+          return engine
+        end
+      end
+      nil
+    end
+
+    # Assign a site to this scan engine.
+    #
+    # @param [Fixnum] site_id Unique numerical ID of the site.
+    #
+    def add_site(site_id)
+      sites << SiteSummary.new(site_id, nil)
+    end
+
+    def to_xml
+      xml = '<EngineConfig'
+      xml << %( id="#{id}")
+      xml << %( address="#{address}")
+      xml << %( name="#{name}")
+      xml << %( port="#{port}")
+      xml << %( scope="#{scope}") if scope
+      xml << %( priority="#{priority}") if priority
+      xml << '>'
+      sites.each do |site|
+        xml << %(<Site id="#{site.id}" />)
+      end
+      xml << '</EngineConfig>'
+      xml
+    end
+
+    # Save this engine configuration to the security console.
+    #
+    # @param [Connection] connection Connection to console where site exists.
+    # @return [Fixnum] ID assigned to the scan engine.
+    #
+    def save(connection)
+      xml = '<EngineSaveRequest session-id="' + connection.session_id + '">'
+      xml << to_xml
+      xml << '</EngineSaveRequest>'
+
+      r = connection.execute(xml, '1.2')
+      if r.success
+        r.res.elements.each('EngineSaveResponse/EngineConfig') do |v|
+          return @id = v.attributes['id']
+        end
+      end
+    end
+
+    # Delete this scan engine configuration from the security console.
+    #
+    # @param [Connection] connection Connection to console where site exists.
+    #
+    def delete(connection)
+      connection.delete_engine(@id, @scope)
+    end
+  end
+end

data/lib/nexpose/filter.rb

@@ -0,0 +1,341 @@
+module Nexpose
+
+  module NexposeAPI
+
+    # Perform an asset filter search that will locate assets matching the
+    # provided conditions.
+    #
+    # For example, the following call will return assets with Java installed:
+    #   nsc.filter(Search::Field::SOFTWARE, Search::Operator::CONTAINS, 'java')
+    #
+    # @param [String] field Constant from Search::Field
+    # @param [String] operator Constant from Search::Operator
+    # @param [String] value Search term or constant from Search::Value
+    # @return [Array[Asset]] List of matching assets.
+    #
+    def filter(field, operator, value = '')
+      criterion = Criterion.new(field, operator, value)
+      criteria = Criteria.new(criterion)
+      search(criteria)
+    end
+
+    # Perform a search that will match the criteria provided.
+    #
+    # For example, the following call will return assets with Java and .NET:
+    #   java_criterion = Criterion.new(Search::Field::SOFTWARE,
+    #                                  Search::Operator::CONTAINS,
+    #                                  'java')
+    #   dot_net_criterion = Criterion.new(Search::Field::SOFTWARE,
+    #                                     Search::Operator::CONTAINS,
+    #                                     '.net')
+    #   criteria = Criteria.new([java_criterion, dot_net_criterion])
+    #   results = nsc.search(criteria)
+    #
+    # @param [Criteria] criteria Criteria search object.
+    # @return [Array[Asset]] List of matching assets.
+    #
+    def search(criteria)
+      results = DataTable._get_json_table(self,
+                                          '/data/asset/filterAssets',
+                                          criteria._to_payload)
+      results.map { |a| Asset.new(a) }
+    end
+  end
+
+  # Constans for performing Asset Filter searches and generating Dynamic Asset
+  # Groups.
+  #
+  module Search
+    module_function
+
+    # Search constants
+
+    # Only these values are accepted for a field value.
+    #
+    module Field
+
+      # Search for an Asset by name.
+      # Valid Operators: IS, IS_NOT, STARTS_WITH, ENDS_WITH, CONTAINS, NOT_CONTAINS
+      ASSET = 'ASSET'
+
+      # Valid Operators: IS, IS_NOT
+      # Valid Values (See Value::AccessComplexity): LOW, MEDIUM, HIGH
+      CVSS_ACCESS_COMPLEXITY = 'CVSS_ACCESS_COMPLEXITY'
+
+      # Valid Operators: IS, IS_NOT
+      # Valid Values (See Value::AccessVector): LOCAL, ADJACENT, NETWORK
+      CVSS_ACCESS_VECTOR = 'CVSS_ACCESS_VECTOR'
+
+      # Valid Operators: IS, IS_NOT
+      # Valid Values (See Value::AuthenticationRequired): NONE, SINGLE, MULTIPLE
+      CVSS_AUTHENTICATION_REQUIRED = 'CVSS_AUTHENTICATION_REQUIRED'
+
+      # Valid Operators: IS, IS_NOT
+      # Valid Values (See Value::CVSSImpact): NONE, PARTIAL, COMPLETE
+      CVSS_AVAILABILITY_IMPACT = 'CVSS_AVAILABILITY_IMPACT'
+
+      # Valid Operators: IS, IS_NOT
+      # Valid Values (See Value::CVSSImpact): NONE, PARTIAL, COMPLETE
+      CVSS_CONFIDENTIALITY_IMPACT = 'CVSS_CONFIDENTIALITY_IMPACT'
+
+      # Valid Operators: IS, IS_NOT
+      # Valid Values (See Value::CVSSImpact): NONE, PARTIAL, COMPLETE
+      CVSS_INTEGRITY_IMPACT = 'CVSS_INTEGRITY_IMPACT'
+
+      # Valid Operators: IS, IS_NOT, IN_RANGE, GREATER_THAN, LESS_THAN
+      # Valid Values: Floats from 0.0 to 10.0
+      CVSS_SCORE = 'CVSS_SCORE'
+
+      # Valid Operators: IN, NOT_IN
+      # Valid Values (See Value::HostType): UNKNOWN, VIRTUAL, HYPERVISOR, BARE_METAL
+      HOST_TYPE = 'HOST_TYPE'
+
+      # Valid Operators: IN, NOT_IN
+      # Valid Values (See Value::IPType): IPv4, IPv6
+      IP_ADDRESS_TYPE = 'IP_ADDRESS_TYPE'
+
+      # Valid Operators: IN
+      # Valid Values (See Value::IPType): IPv4, IPv6
+      IP_ALT_ADDRESS_TYPE = 'IP_ALT_ADDRESS_TYPE'
+
+      # Valid Operators: IN, NOT_IN
+      IP_RANGE = 'IP_RANGE'
+
+      # Valid Operators: CONTAINS, NOT_CONTAINS, IS_EMPTY, IS_NOT_EMPTY
+      OS = 'OS'
+
+      # Valid Operators: IS
+      # Valid Values (See Value::PCICompliance): PASS, FAIL
+      PCI_COMPLIANCE_STATUS = 'PCI_COMPLIANCE_STATUS'
+
+      # Valid Operators: IS, IS_NOT, IN_RANGE, GREATER_THAN, LESS_THAN
+      RISK_SCORE = 'RISK_SCORE'
+
+      # Search based on the last scan date of an asset.
+      # Valid Operators: ON_OR_BEFORE, ON_OR_AFTER, BETWEEN, EARLIER_THAN,
+      #                  WITHIN_THE_LAST
+      # Valid Values: Use Value::ScanDate::FORMAT for date arguments.
+      #               Use FixNum for day arguments.
+      SCAN_DATE = 'SCAN_DATE'
+
+      # Valid Operators: CONTAINS, NOT_CONTAINS
+      SERVICE = 'SERVICE'
+
+      # Search based on the Site ID of an asset.
+      # (Note that underlying search used Site ID, despite 'site name' value.)
+      # Valid Operators: IN, NOT_IN
+      # Valid Values: FixNum Site ID of the site.
+      SITE_ID = 'SITE_NAME'
+
+      # Valid Operators: CONTAINS, NOT_CONTAINS
+      SOFTWARE = 'SOFTWARE'
+
+      # Search against vulnerability titles that an asset contains.
+      # Valid Operators: CONTAINS, NOT_CONTAINS
+      VULNERABILITY = 'VULNERABILITY'
+
+      # Valid Operators: INCLUDE, DO_NOT_INCLUDE
+      # Valid Values (See Value::VulnerabilityExposure): MALWARE, METASPLOIT, DATABASE
+      VULNERABILITY_EXPOSURES = 'VULNERABILITY_EXPOSURES'
+    end
+
+    # List of acceptable operators. Not all fields accept all operators.
+    #
+    module Operator
+      CONTAINS = 'CONTAINS'
+      NOT_CONTAINS = 'NOT_CONTAINS'
+      IS = 'IS'
+      IS_NOT = 'IS_NOT'
+      IN = 'IN'
+      NOT_IN = 'NOT_IN'
+      IN_RANGE = 'IN_RANGE'
+      STARTS_WITH = 'STARTS_WITH'
+      ENDS_WITH = 'ENDS_WITH'
+      ON_OR_BEFORE = 'ON_OR_BEFORE'
+      ON_OR_AFTER = 'ON_OR_AFTER'
+      WITHIN_THE_LAST = 'WITHIN_THE_LAST'
+      GREATER_THAN = 'GREATER_THAN'
+      LESS_THAN = 'LESS_THAN'
+      IS_EMPTY = 'IS_EMPTY'
+      IS_NOT_EMPTY = 'IS_NOT_EMPTY'
+      INCLUDE = 'INCLUDE'
+      DO_NOT_INCLUDE = 'DO_NOT_INCLUDE'
+    end
+
+    # Specialized values used by certain search fields
+    #
+    module Value
+
+      module AccessComplexity
+        LOW = 'L'
+        MEDIUM = 'M'
+        HIGH = 'H'
+      end
+
+      module AccessVector
+        LOCAL = 'L'
+        ADJACENT = 'A'
+        NETWORK = 'N'
+      end
+
+      module AuthenticationRequired
+        NONE = 'N'
+        SINGLE = 'S'
+        MULTIPLE = 'M'
+      end
+
+      module CVSSImpact
+        NONE = 'N'
+        PARTIAL = 'P'
+        COMPLETE = 'C'
+      end
+
+      module HostType
+        UNKNOWN = '0'
+        VIRTUAL = '1'
+        HYPERVISOR = '2'
+        BARE_METAL = '3'
+      end
+
+      module IPType
+        IPv4 = '0'
+        IPv6 = '1'
+      end
+
+      module PCICompliance
+        PASS = '1'
+        FAIL = '0'
+      end
+
+      module ScanDate
+        # Pass this format to #strftime() to get expected format for requests.
+        FORMAT = '%m/%d/%Y'
+      end
+
+      module VulnerabilityExposure
+        MALWARE = 'type:"malware_type", name:"malwarekit"'
+        # TODO: A problem in Nexpose causes these values to not be constant.
+        METASPLOIT = 'type:"exploit_source_type", name:"2"'
+        DATABASE = 'type:"exploit_source_type", name:"1"'
+      end
+    end
+  end
+
+  # Individual search criterion.
+  #
+  class Criterion
+
+    # Search field. One of Nexpose::Search::Field
+    # @see Nexpose::Search::Field for any restrictions on the other attibutes.
+    attr_accessor :field
+    # Search operator. One of Nexpose::Search::Operator
+    attr_accessor :operator
+    # Search value. A search string or one of Nexpose::Search::Value
+    attr_accessor :value
+
+    def initialize(field, operator, value = '')
+      @field, @operator = field.upcase, operator.upcase
+      if value.kind_of? Array
+        @value = value.map { |v| v.to_s }
+      else
+        @value = value.to_s
+      end
+    end
+
+    # Convert this object into the map format expected by Nexpose.
+    #
+    def to_map
+      { 'metadata' => { 'fieldName' => field },
+        'operator' => operator,
+        'values' => value.kind_of?(Array) ? value : [value] }
+    end
+
+    def self.parse(json)
+      Criterion.new(json['metadata']['fieldName'],
+                    json['operator'],
+                    json['values'])
+    end
+  end
+
+  # Join search criteria for an asset filter search or dynamic asset group.
+  #
+  class Criteria
+
+    # Whether to match any or all filters. One of 'OR' or 'AND'.
+    attr_accessor :match
+    # Array of criteria to match against.
+    attr_accessor :criteria
+
+    def initialize(criteria = [], match = 'AND')
+      if criteria.kind_of?(Array)
+        @criteria = criteria
+      else
+        @criteria = [criteria]
+      end
+      @match = match.upcase
+    end
+
+    def to_map
+      { 'operator' => @match,
+        'criteria' => @criteria.map { |c| c.to_map } }
+    end
+
+    # Convert this object into the format expected by Nexpose.
+    #
+    def to_json
+      JSON.generate(to_map)
+    end
+
+    # Generate the payload needed for a POST request for Asset Filter.
+    #
+    def _to_payload
+      { 'dir' => -1,
+        'results' => -1,
+        'sort' => 'assetIP',
+        'startIndex' => -1,
+        'table-id' => 'assetfilter',
+        'searchCriteria' => to_json }
+    end
+
+    def self.parse(json)
+      ret = Criteria.new([], json['operator'])
+      json['criteria'].each do |c|
+        ret.criteria << Criterion.parse(c)
+      end
+      ret
+    end
+  end
+
+  # Asset data as returned by an Asset Filter search.
+  #
+  class Asset
+
+    # Unique identifier of this asset. Also known as device ID.
+    attr_reader :id
+
+    attr_reader :ip
+    attr_reader :name
+    attr_reader :os
+
+    attr_reader :exploit_count
+    attr_reader :malware_count
+    attr_reader :vuln_count
+    attr_reader :risk_score
+
+    attr_reader :site_id
+    attr_reader :last_scan
+
+    def initialize(json)
+      @id = json['assetID']['ID'].to_i
+      @ip = json['assetIP']
+      @name = json['assetName']
+      @os = json['assetOSName']
+      @exploit_count = json['exploitCount'].to_i
+      @malware_count = json['malwareCount'].to_i
+      @vuln_count = json['vulnCount'].to_i
+      @risk_score = json['riskScore'].to_f
+      @site_id = json['siteID']
+      @last_scan = Time.at(json['lastScanDate'] / 1000)
+    end
+  end
+end