nexpose 0.6.5 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c5104a1f9ff2537b542608d4c5c8d42418bb42ca
-  data.tar.gz: 6c5315d6fde97465c5d1120d15990562b518c91d
+  metadata.gz: 28266093c49d6743e5a662298252c67779d54659
+  data.tar.gz: e1525369d7ee0b2052c87c0b3d14f763085f5276
 SHA512:
-  metadata.gz: bfe59dabbed124dbb3f0ab2e40b37bfe1a37252fc7b68c479dc1c0ebad8da7726a40074e20ca6b4cd99b1767a23fab33ac293cfac31f95a59067e10abb404a35
-  data.tar.gz: 32b85bfd2c1f0f281a2d02302d8381639af4a728dbd6c3b193b5dc633117edc2470767bbc50c4c09b3ae739bbdd8a714f650a3f1c1f3b4ebdd57def0445b34dd
+  metadata.gz: baa5a71852ad9259b8086ad9e0a6983cedd152f6da5efbbd3278070e4b633c4c81abd1eeb414aacb33a9010705df40ba30a46e30d85e103028a796f0c3883e10
+  data.tar.gz: 481d97ce05e9b5976a3f679dcc502d6f071db593e28dab6fd4be00ccfc365680405c2eda62cb5bdb897059e1de1e78e830043e05b52089cf8303efc684b51c79

data/COPYING

@@ -0,0 +1,33 @@
+Copyright (C) 2014, Rapid7, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+	  this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above copyright notice,
+	  this list of conditions and the following disclaimer in the documentation
+	  and/or other materials provided with the distribution.
+
+    * Neither the name of Rapid7, Inc. nor the names of its contributors
+	  may be used to endorse or promote products derived from this software
+	  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+================================================================================
+
+The nexpose-client gem is provided under the 3-clause BSD license above.
+
+The copyright on this package is held by Rapid7, Inc.

data/README.markdown

@@ -1,4 +1,4 @@
-# Nexpose
+# Nexpose-Client
 
 This is the official gem package for the Ruby Nexpose API.
 
@@ -19,6 +19,10 @@ Our coding standards include:
 * Unless otherwise noted, code should adhere to the Ruby Style Guide: https://github.com/bbatsov/ruby-style-guide
 * Use YARDoc comment style to improve the API documentation of the gem.
 
+## License
+
+The nexpose-client gem is provided under the 3-Clause BSD License. See [COPYING](COPYING) for details.
+ 
 ## Credits
 
-Rapid7 LLC
+Rapid7, Inc.

data/lib/nexpose.rb

@@ -66,11 +66,14 @@ require 'nexpose/creds'
 require 'nexpose/shared_cred'
 require 'nexpose/data_table'
 require 'nexpose/device'
+require 'nexpose/discovery'
+require 'nexpose/discovery/filter'
 require 'nexpose/engine'
 require 'nexpose/filter'
 require 'nexpose/group'
 require 'nexpose/dag'
 require 'nexpose/manage'
+require 'nexpose/multi_tenant_user'
 require 'nexpose/pool'
 require 'nexpose/report'
 require 'nexpose/report_template'
@@ -78,7 +81,10 @@ require 'nexpose/role'
 require 'nexpose/scan'
 require 'nexpose/scan_template'
 require 'nexpose/silo'
+require 'nexpose/silo_profile'
 require 'nexpose/site'
+require 'nexpose/tag'
+require 'nexpose/tag/criteria'
 require 'nexpose/ticket'
 require 'nexpose/user'
 require 'nexpose/vuln'

data/lib/nexpose/ajax.rb

@@ -10,6 +10,12 @@ module Nexpose
   module AJAX
     module_function
 
+    module CONTENT_TYPE
+      XML = 'text/xml; charset=UTF-8'
+      JSON = 'application/json; charset-utf-8'
+      FORM = 'application/x-www-form-urlencoded; charset=UTF-8'
+    end
+
     # GET call to a Nexpose controller.
     #
     # @param [Connection] nsc API connection to a Nexpose console.
@@ -17,7 +23,7 @@ module Nexpose
     # @param [String] content_type Content type to use when issuing the GET.
     # @return [String|REXML::Document|Hash] The response from the call.
     #
-    def get(nsc, uri, content_type = 'text/xml; charset=UTF-8')
+    def get(nsc, uri, content_type = CONTENT_TYPE::XML)
       get = Net::HTTP::Get.new(uri)
       get.set_content_type(content_type)
       _request(nsc, get)
@@ -31,7 +37,7 @@ module Nexpose
     # @param [String] content_type Content type to use when issuing the PUT.
     # @return [String] The response from the call.
     #
-    def put(nsc, uri, payload = nil, content_type = 'text/xml; charset=UTF-8')
+    def put(nsc, uri, payload = nil, content_type = CONTENT_TYPE::XML)
       put = Net::HTTP::Put.new(uri)
       put.set_content_type(content_type)
       put.body = payload.to_s if payload
@@ -46,13 +52,28 @@ module Nexpose
     # @param [String] content_type Content type to use when issuing the POST.
     # @return [String|REXML::Document|Hash] The response from the call.
     #
-    def post(nsc, uri, payload = nil, content_type = 'text/xml')
+    def post(nsc, uri, payload = nil, content_type = CONTENT_TYPE::XML)
       post = Net::HTTP::Post.new(uri)
       post.set_content_type(content_type)
       post.body = payload.to_s if payload
       _request(nsc, post)
     end
 
+    # PATCH call to a Nexpose controller.
+    #
+    # @param [Connection] nsc API connection to a Nexpose console.
+    # @param [String] uri Controller address relative to https://host:port
+    # @param [String|REXML::Document] payload XML document required by the call.
+    # @param [String] content_type Content type to use when issuing the PATCH.
+    # @return [String] The response from the call.
+    #
+    def patch(nsc, uri, payload = nil, content_type = CONTENT_TYPE::XML)
+      patch = Net::HTTP::Patch.new(uri)
+      patch.set_content_type(content_type)
+      patch.body = payload.to_s if payload
+      _request(nsc, patch)
+    end
+
     # POST call to a Nexpose controller that uses a form-post model.
     # This is here to support legacy use of POST in old controllers.
     #
@@ -63,7 +84,7 @@ module Nexpose
     # @param [String] content_type Content type to use when issuing the POST.
     # @return [Hash] The parsed JSON response from the call.
     #
-    def form_post(nsc, uri, parameters, content_type = 'application/x-www-form-urlencoded; charset=UTF-8')
+    def form_post(nsc, uri, parameters, content_type = CONTENT_TYPE::FORM)
       post = Net::HTTP::Post.new(uri)
       post.set_content_type(content_type)
       post.set_form_data(parameters)
@@ -75,7 +96,7 @@ module Nexpose
     # @param [Connection] nsc API connection to a Nexpose console.
     # @param [String] uri Controller address relative to https://host:port
     # @param [String] content_type Content type to use when issuing the DELETE.
-    def delete(nsc, uri, content_type = 'text/xml')
+    def delete(nsc, uri, content_type = CONTENT_TYPE::XML)
       delete = Net::HTTP::Delete.new(uri)
       delete.set_content_type(content_type)
       _request(nsc, delete)
@@ -89,7 +110,7 @@ module Nexpose
     # @return [Hash] The parametrized URI.
 
     def parametrize_uri(uri, parameters)
-      uri = uri.concat(('?').concat(parameters.map { |k, v| "#{k}=#{CGI.escape(v[0].to_s)}" }.join('&'))) if parameters
+      uri = uri.concat(('?').concat(parameters.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join('&'))) if parameters
     end
 
     ###

data/lib/nexpose/dag.rb

@@ -31,9 +31,9 @@ module Nexpose
       # 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))
+      params = @id ? { 'entityid' => @id, 'mode' => 'edit' } : { 'entityid' => false, 'mode' => false } 
+      uri = AJAX.parametrize_uri('/data/assetGroup/saveAssetGroup', params)
+      data = JSON.parse(AJAX.post(nsc, uri, _to_entity_details, AJAX::CONTENT_TYPE::JSON))
       data['response'] == 'success.'
     end
 
@@ -53,21 +53,13 @@ module Nexpose
       dag
     end
 
-    def to_map
+    def _to_entity_details
       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
+      JSON.generate(obj)
     end
   end
 end

data/lib/nexpose/data_table.rb

@@ -28,7 +28,7 @@ module Nexpose
     #                               'table-id' => 'site-assets',
     #                               'siteID' => site_id })
     #
-    def _get_json_table(console, address, parameters, page_size = 500, records = nil)
+    def _get_json_table(console, address, parameters = {}, page_size = 500, records = nil)
       parameters['dir'] = 'DESC'
       parameters['startIndex'] = -1
       parameters['results'] = -1

data/lib/nexpose/discovery.rb

@@ -0,0 +1,191 @@
+module Nexpose
+
+  class Connection
+
+    # Retrieve information about all available connections for dynamic
+    # discovery of assets, including whether or not connections are active.
+    #
+    def list_discovery_connections
+      xml = make_xml('DiscoveryConnectionListingRequest')
+      response = execute(xml, '1.2')
+      connections = []
+      response.res.elements.each('DiscoveryConnectionListingResponse/DiscoveryConnectionSummary') do |conn|
+        connections << DiscoveryConnection.parse(conn)
+      end
+      connections
+    end
+    alias_method :discovery_connections, :list_discovery_connections
+
+    # Delete an existing connection to a target used for dynamic discovery of assets.
+    #
+    # @param [Fixnum] id ID of an existing discovery connection.
+    #
+    def delete_discovery_connection(id)
+      xml = make_xml('DiscoveryConnectionDeleteRequest', { 'id' => id })
+      response = execute(xml, '1.2')
+      response.success
+    end
+  end
+
+  class DiscoveryConnection
+    include XMLUtils
+
+    module Protocol
+      HTTP = 'HTTP'
+      HTTPS = 'HTTPS'
+    end
+
+    # A unique identifier for this connection.
+    attr_accessor :id
+
+    # A unique name for this connection.
+    attr_accessor :name
+
+    # The IP address or fully qualified domain name of the server.
+    attr_accessor :address
+
+    # A user name that can be used to log into the server.
+    attr_accessor :user
+
+    # The password to use when connecting with the defined user.
+    attr_accessor :password
+
+    # The protocol used for conneting to the server. One of DiscoveryConnection::Protocol
+    attr_accessor :protocol
+
+    # The port used for connecting to the server. A valid port from 1 to 65535.
+    attr_accessor :port
+
+    # Whether or not the connection is active.
+    # Discovery is only possible when the connection is active.
+    attr_accessor :status
+
+    # Create a new discovery connection.
+    #
+    # @param [String] name Name to assign to this connection.
+    # @param [String] address IP or fully qualified domain name of the
+    #    connection server.
+    # @param [String] user User name for credentials on this connection.
+    # @param [String] password Password for credentials on this connection.
+    #
+    def initialize(name, address, user, password = nil)
+      @name, @address, @user, @password = name, address, user, password
+      @id = -1
+      @port = 443
+      @protocol = Protocol::HTTPS
+    end
+
+    # Save this discovery connection to a Nexpose console.
+    #
+    # @param [Connection] nsc Connection to a console.
+    #
+    def save(nsc)
+      if @id == -1
+        xml = nsc.make_xml('DiscoveryConnectionCreateRequest')
+      else
+        xml = nsc.make_xml('DiscoveryConnectionUpdateRequest')
+      end
+      xml.add_element(as_xml)
+      response = nsc.execute(xml, '1.2')
+      if response.success
+        ret = REXML::XPath.first(response.res, 'DiscoveryConnectionCreateResponse')
+        @id = ret.attributes['id'].to_i unless ret.nil?
+      end
+      @id
+    end
+
+    # Perform dynamic discover of assets against this connection.
+    #
+    # @param [Connection] nsc Connection to a console.
+    # @param [Criteria] criteria Criteria search object narrowing which assets
+    #   to filter.
+    # @return [Array[DiscoveredAsset]] All discovered assets matching the criteria.
+    #
+    def discover(nsc, criteria = nil)
+      parameters = { 'table-id' => 'assetdiscovery',
+                     'sort' => 'assetDiscoveryName',
+                     'searchCriteria' => criteria.nil? ? 'null' : criteria.to_json,
+                     'configID' => @id }
+      data = DataTable._get_json_table(nsc, '/data/discoveryAsset/discoverAssets', parameters)
+      data.map { |a| DiscoveredAsset.parse(a) }
+    end
+
+    # Initiates a connection to a target used for dynamic discovery of assets.
+    # As long as a connection is active, dynamic discovery is continuous.
+    #
+    # @param [Connection] nsc Connection to a console.
+    #
+    def connect(nsc)
+      xml = nsc.make_xml('DiscoveryConnectionConnectRequest', { 'id' => id })
+      response = nsc.execute(xml, '1.2')
+      response.success
+    end
+
+    # Delete this connection from the console.
+    #
+    # @param [Connection] nsc Connection to a console.
+    #
+    def delete(nsc)
+      nsc.delete_discovery_connection(@id)
+    end
+
+    def as_xml
+      xml = REXML::Element.new('DiscoveryConnection')
+      xml.add_attributes({ 'name' => @name,
+                           'address' => @address,
+                           'port' => @port,
+                           'protocol' => @protocol,
+                           'user-name' => @user,
+                           'password' => @password })
+      xml
+    end
+
+    def to_xml
+      as_xml.to_s
+    end
+
+    def self.parse(xml)
+      conn = new(xml.attributes['name'],
+                 xml.attributes['address'],
+                 xml.attributes['user-name'])
+      conn.id = xml.attributes['id'].to_i
+      conn.protocol = xml.attributes['protocol']
+      conn.port = xml.attributes['port'].to_i
+      conn.status = xml.attributes['connection-status']
+      conn
+    end
+  end
+
+  class DiscoveredAsset
+
+    attr_accessor :name
+    attr_accessor :ip
+    attr_accessor :host
+    attr_accessor :datacenter
+    attr_accessor :cluster
+    attr_accessor :pool
+    attr_accessor :os
+    attr_accessor :status
+
+    def initialize(&block)
+      instance_eval &block if block_given?
+    end
+
+    def on?
+      @status == 'On'
+    end
+
+    def self.parse(json)
+      new do |asset|
+        asset.ip = json['IPAddress']
+        asset.os = json['OSName']
+        asset.name = json['assetDiscoveryName']
+        asset.cluster = json['cluster']
+        asset.datacenter = json['datacenter']
+        asset.host = json['host']
+        asset.status = json['powerStatus']
+        asset.pool = json['resourcePool']
+      end
+    end
+  end
+end

data/lib/nexpose/discovery/filter.rb

@@ -0,0 +1,36 @@
+module Nexpose
+  module Search
+    module Field
+
+      # Valid Operators: IS, IS_NOT, CONTAINS, NOT_CONTAINS, STARTS_WITH
+      CLUSTER = 'CLUSTER'
+
+      # Valid Operators: IS, IS_NOT
+      DATACENTER ='DATACENTER'
+
+      # Valid Operators: CONTAINS, NOT_CONTAINS
+      GUEST_OS_FAMILY = 'GUEST_OS_FAMILY'
+
+      # Valid Operators: IN, NOT_IN
+      IP_ADDRESS_RANGE = 'IP_ADDRESS'
+
+      # Valid Operators: IN, NOT_IN
+      # Valid Values (See Value::PowerState): ON, OFF, SUSPENDED
+      POWER_STATE = 'POWER_STATE'
+
+      # Valid Operators: CONTAINS, NOT_CONTAINS
+      RESOURCE_POOL_PATH ='RESOURCE_POOL_PATH'
+
+      # Valid Operators: IS, IS_NOT, CONTAINS, NOT_CONTAINS, STARTS_WITH
+      VIRTUAL_MACHINE_NAME = 'VM'
+    end
+
+    module Value
+      module PowerState
+        ON = 'poweredOn'
+        OFF = 'poweredOff'
+        SUSPENDED = 'suspended'
+      end
+    end
+  end
+end