nexpose 0.2.8 → 0.5.0

data/lib/nexpose/creds.rb

@@ -5,13 +5,12 @@ module Nexpose
   # the credentials will be returned as a security blob and can only
   # be passed back as is during a Site Save operation. This object
   # can only be used to create a new set of credentials.
-  class AdminCredentials
+  #
+  class Credential
     include XMLUtils
 
     # Security blob for an existing set of credentials
-    attr_accessor :securityblob
-    # Designates if this object contains user defined credentials or a security blob
-    attr_accessor :isblob
+    attr_accessor :blob
     # The service for these credentials. Can be All.
     attr_accessor :service
     # The host for these credentials. Can be Any.
@@ -37,22 +36,6 @@ module Nexpose
     # The password to use when escalating privileges (optional)
     attr_accessor :priv_password
 
-    def initialize(isblob = false)
-      @isblob = isblob
-    end
-
-    # Sets the credentials information for this object.
-    def set_credentials(service, host, port, userid, password, realm)
-      @isblob = false
-      @securityblob = nil
-      @service = service
-      @host = host
-      @port = port
-      @userid = userid
-      @password = password
-      @realm = realm
-    end
-
     def self.for_service(service, user, password, realm = nil, host = nil, port = nil)
       cred = new
       cred.service = service
@@ -64,41 +47,13 @@ module Nexpose
       cred
     end
 
-    # Sets privilege escalation credentials.  Type should be either
-    # sudo/su.
-    def set_privilege_credentials(type, username, password)
+    # Sets privilege escalation credentials. Type should be either sudo/su.
+    def add_privilege_credentials(type, username, password)
       @priv_type = type
       @priv_username = username
       @priv_password = password
     end
 
-    # The name of the service.  Possible values are outlined in the
-    # Nexpose API docs.
-    def set_service(service)
-      @service = service
-    end
-
-    def set_host(host)
-      @host = host
-    end
-
-    # Credentials fetched from the API are encrypted into a
-    # securityblob.  If you want to use those credentials on a
-    # different site, copy the blob into the credential.
-    def set_blob(securityblob)
-      @isblob = true
-      @securityblob = securityblob
-    end
-
-    # Add Headers to credentials for httpheaders.
-    def set_headers(headers)
-      @headers = headers
-    end
-
-    def set_html_forms(html_forms)
-      @html_forms = html_forms
-    end
-
     def to_xml
       to_xml_elem.to_s
     end
@@ -117,8 +72,7 @@ module Nexpose
       attributes['privilegeelevationusername'] = @priv_username if @priv_username
       attributes['privilegeelevationpassword'] = @priv_password if @priv_password
 
-      data = isblob ? securityblob : ''
-      xml = make_xml('adminCredentials', attributes, data)
+      xml = make_xml('adminCredentials', attributes, blob)
       xml.add_element(@headers.to_xml_elem) if @headers
       xml.add_element(@html_forms.to_xml_elem) if @html_forms
       xml
@@ -140,8 +94,10 @@ module Nexpose
   end
 
   # Object that represents Header name-value pairs, associated with Web Session Authentication.
+  #
   class Header
     include XMLUtils
+
     # Name, one per Header
     attr_reader :name
     # Value, one per Header
@@ -163,8 +119,10 @@ module Nexpose
   end
 
   # Object that represents Headers, associated with Web Session Authentication.
+  #
   class Headers
     include XMLUtils
+
     # A regular expression used to match against the response to identify authentication failures.
     attr_reader :soft403
     # Base URL of the application for which the form authentication applies.
@@ -197,8 +155,10 @@ module Nexpose
   end
 
   # When using htmlform, this represents the login form information.
+  #
   class Field
     include XMLUtils
+
     # The name of the HTML field (form parameter).
     attr_reader :name
     # The value of the HTML field (form parameter).
@@ -234,8 +194,10 @@ module Nexpose
   end
 
   # When using htmlform, this represents the login form information.
+  #
   class HTMLForm
     include XMLUtils
+
     # The name of the form being submitted.
     attr_reader :name
     # The HTTP action (URL) through which to submit the login form.
@@ -271,15 +233,15 @@ module Nexpose
       fields.each() do |field|
         xml.add_element(field.to_xml_elem)
       end
-
       xml
     end
-
   end
 
   # When using htmlform, this represents the login form information.
+  #
   class HTMLForms
     include XMLUtils
+
     # The URL of the login page containing the login form.
     attr_reader :parentpage
     # A regular expression used to match against the response to identify
@@ -314,7 +276,6 @@ module Nexpose
       end
       xml
     end
-
   end
 
   # When using ssh-key, this represents the PEM-format keypair information.

data/lib/nexpose/dag.rb

@@ -0,0 +1,73 @@
+module Nexpose
+
+  # Dynamic Asset Group object.
+  #
+  class DynamicAssetGroup
+
+    # Unique name of this group.
+    attr_accessor :name
+    # Search criteria that defines which assets this group will aggregate.
+    attr_accessor :criteria
+    # Unique identifier of this group.
+    attr_accessor :id
+    # Description of this asset group.
+    attr_accessor :description
+    # Array of user IDs who have permission to access this group.
+    attr_accessor :users
+
+    def initialize(name, criteria = nil, description = nil)
+      @name, @criteria, @description = name, criteria, description
+      @users = []
+    end
+
+    # Save this dynamic asset group to the Nexpose console.
+    # Warning, saving this object does not set the id. It must be retrieved
+    # independently.
+    #
+    # @param [Connection] nsc Connection to a security console.
+    # @return [Boolean] Whether the group was successfully saved.
+    #
+    def save(nsc)
+      # load includes admin users, but save will fail if they are included.
+      admins = nsc.users.select { |u| u.is_admin }.map { |u| u.id }
+      @users.reject! { |id| admins.member? id }
+      data = JSON.parse(AJAX.form_post(nsc,
+                                       '/data/assetGroup/saveAssetGroup',
+                                       to_map))
+      data['response'] == 'success.'
+    end
+
+    # Load in an existing Dynamic Asset Group configuration.
+    #
+    # @param [Connection] nsc Connection to a security console.
+    # @param [Fixnum] id Unique identifier of an existing group.
+    # @return [DynamicAssetGroup] Dynamic asset group configuration.
+    #
+    def self.load(nsc, id)
+      json = JSON.parse(AJAX.get(nsc, "/data/assetGroup/loadAssetGroup?entityid=#{id}"))
+      raise APIError.new(json, json['message']) if json['response'] =~ /failure/
+      raise ArgumentError.new('Not a dynamic asset group.') unless json['dynamic']
+      dag = new(json['name'], Criteria.parse(json['searchCriteria']), json['tag'])
+      dag.id = id
+      dag.users = json['users']
+      dag
+    end
+
+    def to_map
+      obj = { 'searchCriteria' => @criteria.to_map,
+              'name' => @name,
+              'tag' => @description.nil? ? '' : @description,
+              'dynamic' => true,
+              'users' => @users }
+      map = { 'entityDetails' => JSON.generate(obj) }
+      if @id
+        map['entityid'] = @id
+        map['mode'] = 'edit'
+      else
+        map['entityid'] = false
+        map['mode'] = false
+      end
+      map
+    end
+  end
+end

data/lib/nexpose/data_table.rb

@@ -0,0 +1,134 @@
+module Nexpose
+
+  # Data table functions which extract data from the Nexpose UI.
+  #
+  # The functions in this file are utility functions for accessing data in the
+  # same manner as the Nexpose UI. These functions are not designed for external
+  # use, but to aid exposing data through other methods in the gem.
+  #
+  module DataTable
+    module_function
+
+    # Helper method to get the YUI tables into a consumable Ruby object.
+    #
+    # @param [Connection] console API connection to a Nexpose console.
+    # @param [String] address Controller address relative to https://host:port
+    # @param [Hash] parameters Parameters that need to be sent to the controller
+    # @param [Integer] pagination size
+    # @param [Integer] number of records to return, gets all if not specified
+    #    The following attributes need to be provided:
+    #      'sort' Column to sort by
+    #      'table-id' The ID of the table to get from this controller
+    # @return [Array[Hash]] An array of hashes representing the requested table.
+    #
+    # Example usage:
+    #   DataTable._get_json_table(@console,
+    #                             '/data/asset/site',
+    #                             { 'sort' => 'assetName',
+    #                               'table-id' => 'site-assets',
+    #                               'siteID' => site_id })
+    #
+    def _get_json_table(console, address, parameters, page_size = 500, records = nil)
+      parameters['dir'] = 'DESC'
+      parameters['startIndex'] = -1
+      parameters['results'] = -1
+
+      post = AJAX.form_post(console, address, parameters)
+      data = JSON.parse(post)
+      total = records || data['totalRecords']
+      return [] if total == 0
+
+      rows = []
+      parameters['results'] = page_size
+      while rows.length < total
+        parameters['startIndex'] = rows.length
+
+        data = JSON.parse(AJAX.form_post(console, address, parameters))
+        rows.concat data['records']
+      end
+      rows
+    end
+
+    # Helper method to get a Dyntable into a consumable Ruby object.
+    #
+    # @param [Connection] console API connection to a Nexpose console.
+    # @param [String] address Tag address with parameters relative to
+    #    https://host:port
+    # @return [Array[Hash]] array of hashes representing the requested table.
+    #
+    # Example usage:
+    #   DataTable._get_dyn_table(@console, '/data/asset/os/dyntable.xml?tableID=OSSynopsisTable')
+    #
+    def _get_dyn_table(console, address, payload = nil)
+      if payload
+        response = AJAX.post(console, address, payload)
+      else
+        response = AJAX.get(console, address)
+      end
+      response = REXML::Document.new(response)
+
+      headers = _dyn_headers(response)
+      rows = _dyn_rows(response)
+      rows.map { |row| Hash[headers.zip(row)] }
+    end
+
+    # Parse headers out of a dyntable response.
+    def _dyn_headers(response)
+      headers = []
+      response.elements.each('DynTable/MetaData/Column') do |header|
+        headers << header.attributes['name']
+      end
+      headers
+    end
+
+    # Parse rows out of a dyntable into an array of values.
+    def _dyn_rows(response)
+      rows = []
+      response.elements.each('DynTable/Data/tr') do |row|
+        rows << _dyn_record(row)
+      end
+      rows
+    end
+
+    # Parse records out of the row of a dyntable.
+    def _dyn_record(row)
+      record = []
+      row.elements.each('td') do |value|
+        record << (value.text ? value.text.to_s : '')
+      end
+      record
+    end
+
+    # Clean up the 'type-safe' IDs returned by many table requests.
+    # This is a destructive operation, changing the values in the underlying
+    # hash.
+    #
+    # @param [Array[Hash]] arr Array of hashes representing a data table.
+    # @param [String] id Key value of a type-safe ID to clean up.
+    #
+    # Example usage:
+    #   # For data like: {"assetID"=>{"ID"=>2818}, "assetIP"=>"10.4.16.1", ...}
+    #   _clean_data_table!(data, 'assetID')
+    #
+    def _clean_data_table!(arr, id)
+      arr.reduce([]) do |acc, hash|
+        acc << _clean_id!(hash, id)
+      end
+    end
+
+    # Convert a type-safe ID into a regular ID inside a hash.
+    #
+    # @param [Hash] hash Hash map containing a type-safe ID as one key.
+    # @param [String] id Key value of a type-safe ID to clean up.
+    #
+    def _clean_id!(hash, id)
+      hash.each_pair do |key, value|
+        if key == id
+          hash[key] = value['ID']
+        else
+          hash[key] = value
+        end
+      end
+    end
+  end
+end

data/lib/nexpose/device.rb

@@ -0,0 +1,111 @@
+module Nexpose
+  module NexposeAPI
+    include XMLUtils
+
+    # 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 restrict search to.
+    # @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
+
+    alias_method :find_asset_by_address, :find_device_by_address
+
+    # 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 list_site_devices(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 :devices, :list_site_devices
+    alias_method :list_devices, :list_site_devices
+    alias_method :assets, :list_site_devices
+    alias_method :list_assets, :list_site_devices
+
+    # List the vulnerability findings for a given device ID.
+    #
+    # @param [Fixnum] dev_id Unique identifier of a device (asset).
+    # @return [Array[Vulnerability]] List of vulnerability findings.
+    #
+    def list_device_vulns(dev_id)
+      parameters = { 'devid' => dev_id,
+                     'table-id' => 'vulnerability-listing' }
+      json = DataTable._get_json_table(self,
+                                       '/data/vulnerability/asset-vulnerabilities',
+                                       parameters)
+      json.map { |vuln| VulnFinding.new(vuln) }
+    end
+
+    alias_method :list_asset_vulns, :list_device_vulns
+    alias_method :asset_vulns, :list_device_vulns
+    alias_method :device_vulns, :list_device_vulns
+
+    def delete_device(device_id)
+      r = execute(make_xml('DeviceDeleteRequest', { 'device-id' => device_id }))
+      r.success
+    end
+  end
+
+  # 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
+end