nexpose 0.0.98 → 0.1.0

data/README.markdown

@@ -1,7 +1,17 @@
-# Nexpose
-
-This is the official gem package for the Ruby Nexpose API included in the Metasploit Framework. This version is based on SVN revision 12430.
-The upstream for this gem can be found at https://metasploit.com/svn/framework3/trunk/lib/rapid7
-
-# Credits
-Rapid7 LLC
+# Nexpose
+
+This is the official gem package for the Ruby Nexpose API.
+
+For assistance with using the gem, to share your scripts, or to discuss different approaches, please visit the Rapid7 forums for Nexpose: https://community.rapid7.com/community/nexpose
+
+## Contributions
+
+This package is currently a work in progress. Most of the Nexpose API is exposed, but there are some operations missing. Also, there are stylistic differences between different calls that we hope to eliminate over time. We welcome contributions to this package. We ask only that pull requests and patches adhere to our coding standards.
+
+* Favor returning classes over key-value maps. Classes tend to be easier for users to manipulate and use.
+* 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.
+
+## Credits
+
+Rapid7 LLC

data/Rakefile

@@ -1,22 +1,17 @@
-# encoding: utf-8
- 
-task :build => :update do
-	Rake::Task['clean'].execute
-	puts "[*] Building nexpose.gemspec"
-	system "gem build nexpose.gemspec &> /dev/null"
-end
- 
-task :release => :build do
-	puts "[*] Pushing nexpose to rubygems.org"
-	system "gem push nexpose-*.gem &> /dev/null"
-	Rake::Task['clean'].execute
-end
-
-task :clean do
-	system "rm *.gem &> /dev/null"
-end
-
-task :update do
-	system "rm -f lib/nexpose.rb"
-	system "svn export https://metasploit.com/svn/framework3/trunk/lib/rapid7/nexpose.rb lib/nexpose.rb"
-end
+# encoding: utf-8
+ 
+task :build do
+	Rake::Task['clean'].execute
+	puts "[*] Building nexpose.gemspec"
+	system "gem build nexpose.gemspec &> /dev/null"
+end
+ 
+task :release => :build do
+	puts "[*] Pushing nexpose to rubygems.org"
+	system "gem push nexpose-*.gem &> /dev/null"
+	Rake::Task['clean'].execute
+end
+
+task :clean do
+	system "rm *.gem &> /dev/null"
+end

data/lib/README.md

@@ -0,0 +1,5 @@
+# Nexpose Client
+
+The nexpose.rb file should act simply as a means of collecing all the sub-elements of the client into a single module.
+
+If adding or adjusting code, please note that all calls directly against the Connection object are currently implemented within the NexposeAPI module. This style of call should mostly be for listing and simple query calls, and not for configuration requests that will return an editable class.

data/lib/nexpose.rb

@@ -1,130 +1,104 @@
-#
-# The NeXpose API
-#
-=begin
-
-Copyright (C) 2009-2011, Rapid7 LLC
-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 LLC 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.
-
-=end
-
-#
-# WARNING! This code makes an SSL connection to the NeXpose server, but does NOT
-#          verify the certificate at this time. This can be a security issue if
-#          an attacker is able to man-in-the-middle the connection between the
-#          Metasploit console and the NeXpose server. In the common case of
-#          running NeXpose and Metasploit on the same host, this is a low risk.
-#
-
-#
-# WARNING! This code is still rough and going through substantive changes. While
-#          you can build tools using this library today, keep in mind that method
-#          names and parameters may change in the future.
-#
-
-require 'date'
-require 'rexml/document'
-require 'net/https'
-require 'net/http'
-require 'uri'
-require 'rex/mime'
-require 'nexpose/error'
-require 'nexpose/util'
-require 'nexpose/user'
-require 'nexpose/api_request'
-require 'nexpose/misc'
-require 'nexpose/report'
-require 'nexpose/scan'
-require 'nexpose/scan_engine'
-require 'nexpose/silo'
-require 'nexpose/site'
-require 'nexpose/ticket'
-require 'nexpose/vuln'
-require 'nexpose/creds'
-require 'nexpose/connection'
-
-module Nexpose
-
-	# TODO add
-	def self.site_device_scan(connection, site_id, device_array, host_array, debug = false)
-
-		request_xml = '<SiteDevicesScanRequest session-id="' + connection.session_id.to_s + '" site-id="' + site_id.to_s + '">'
-		request_xml += '<Devices>'
-		device_array.each do |d|
-			request_xml += '<device id="' + d.to_s + '"/>'
-		end
-		request_xml += '</Devices>'
-		request_xml += '<Hosts>'
-		# The host array can only by single IP addresses for now. TODO: Expand to full API Spec.
-		host_array.each do |h|
-			request_xml += '<range from="' + h.to_s + '"/>'
-		end
-		request_xml += '</Hosts>'
-		request_xml += '</SiteDevicesScanRequest>'
-
-		r = connection.execute(request_xml)
-		r.success ? {:engine_id => r.attributes['engine_id'], :scan_id => r.attributes['scan-id']} : nil
-	end
-
-	# === Description
-	# TODO
-	def self.getAttribute(attribute, xml)
-		value = ''
-		#@value = substr(substr(strstr(strstr(@xml,@attribute),'"'),1),0,strpos(substr(strstr(strstr(@xml,@attribute),'"'),1),'"'))
-		value
-	end
-
-	# === Description
-	# Returns an ISO 8601 formatted date/time stamp. All dates in NeXpose must use this format.
-	def self.get_iso_8601_date(int_date)
-		#@date_mod = date('Ymd\THis000', @int_date)
-		date_mod = ''
-		return date_mod
-	end
-
-	# ==== Description
-	# Echos the last XML API request and response for the specified object.  (Useful for debugging)
-	def self.printXML(object)
-		puts "request" + object.request_xml.to_s
-		puts "response is " + object.response_xml.to_s
-	end
-
-
-	def self.testa(ip, port, user, passwd)
-		nsc = Connection.new(ip, user, passwd, port)
-
-		nsc.login
-		site_listing = SiteListing.new(nsc)
-
-		site_listing.sites.each do |site|
-			puts "name is #{site.site_name}"
-			puts "id is #{site.id}"
-		end
-	end
-
-end
+#
+# The Nexpose API
+#
+=begin
+
+Copyright (C) 2009-2012, Rapid7 LLC
+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 LLC 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.
+
+=end
+
+#
+# WARNING! This code makes an SSL connection to the Nexpose server, but does NOT
+#          verify the certificate at this time. This can be a security issue if
+#          an attacker is able to man-in-the-middle the connection between the
+#          Metasploit console and the Nexpose server. In the common case of
+#          running Nexpose and Metasploit on the same host, this is a low risk.
+#
+
+#
+# WARNING! This code is still rough and going through substantive changes. While
+#          you can build tools using this library today, keep in mind that
+#          method names and parameters may change in the future.
+#
+
+require 'date'
+require 'rexml/document'
+require 'net/https'
+require 'net/http'
+require 'uri'
+require 'rex/mime'
+require 'ipaddr'
+require 'nexpose/error'
+require 'nexpose/util'
+require 'nexpose/user'
+require 'nexpose/api_request'
+require 'nexpose/manage'
+require 'nexpose/misc'
+require 'nexpose/report'
+require 'nexpose/scan'
+require 'nexpose/scan_engine'
+require 'nexpose/silo'
+require 'nexpose/site'
+require 'nexpose/ticket'
+require 'nexpose/vuln'
+require 'nexpose/creds'
+require 'nexpose/connection'
+require 'nexpose/role'
+require 'nexpose/common'
+
+module Nexpose
+
+  # TODO add
+  def self.site_device_scan(connection, site_id, device_array, host_array, debug = false)
+
+    request_xml = '<SiteDevicesScanRequest session-id="' + connection.session_id.to_s + '" site-id="' + site_id.to_s + '">'
+    request_xml += '<Devices>'
+    device_array.each do |d|
+      request_xml += '<device id="' + d.to_s + '"/>'
+    end
+    request_xml += '</Devices>'
+    request_xml += '<Hosts>'
+    # The host array can only by single IP addresses for now. TODO: Expand to full API Spec.
+    host_array.each do |h|
+      request_xml += '<range from="' + h.to_s + '"/>'
+    end
+    request_xml += '</Hosts>'
+    request_xml += '</SiteDevicesScanRequest>'
+
+    r = connection.execute(request_xml)
+    r.success ? {:engine_id => r.attributes['engine_id'], :scan_id => r.attributes['scan-id']} : nil
+  end
+
+  # ==== Description
+  # Echos the last XML API request and response for the specified object.  (Useful for debugging)
+  def self.printXML(object)
+    puts "request" + object.request_xml.to_s
+    puts "response is " + object.response_xml.to_s
+  end
+end

data/lib/nexpose/api_request.rb

@@ -1,144 +1,133 @@
-module Nexpose
-	class APIRequest
-		include XMLUtils
-
-		attr_reader :http
-		attr_reader :uri
-		attr_reader :headers
-		attr_reader :retry_count
-		attr_reader :time_out
-		attr_reader :pause
-
-		attr_reader :req
-		attr_reader :res
-		attr_reader :sid
-		attr_reader :success
-
-		attr_reader :error
-		attr_reader :trace
-
-		attr_reader :raw_response
-		attr_reader :raw_response_data
-
-		#
-		#
-		#
-		def initialize(req, url, api_version='1.1')
-			@url = url
-			@req = req
-			@api_version = api_version
-			@url = @url.sub('API_VERSION', @api_version)
-			prepare_http_client
-		end
-
-		#
-		#
-		#
-		def prepare_http_client
-			@retry_count = 0
-			@retry_count_max = 10
-			@time_out = 30
-			@pause = 2
-			@uri = URI.parse(@url)
-			@http = Net::HTTP.new(@uri.host, @uri.port)
-			@http.use_ssl = true
-			#
-			# XXX: This is obviously a security issue, however, we handle this at the client level by forcing
-			#      a confirmation when the nexpose host is not localhost. In a perfect world, we would present
-			#      the server signature before accepting it, but this requires either a direct callback inside
-			#      of this module back to whatever UI, or opens a race condition between accept and attempt.
-			#
-			@http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-			@headers = {'Content-Type' => 'text/xml'}
-			@success = false
-		end
-
-		#
-		#
-		#
-		def execute
-			@conn_tries = 0
-
-			begin
-				prepare_http_client
-				@raw_response = @http.post(@uri.path, @req, @headers)
-				@raw_response_data = @raw_response.read_body
-				@res = parse_xml(@raw_response_data)
-
-				if (not @res.root)
-					@error = "NeXpose service returned invalid XML"
-					return @sid
-				end
-
-				@sid = attributes['session-id']
-
-				if (attributes['success'] and attributes['success'].to_i == 1)
-					@success = true
-				elsif @api_version =~ /1.2/ and @res and (@res.get_elements '//Exception').count < 1
-					@success = true
-				else
-					@success = false
-					@res.elements.each('//Failure/Exception') do |s|
-						s.elements.each('message') do |m|
-							@error = m.text
-						end
-						s.elements.each('stacktrace') do |m|
-							@trace = m.text
-						end
-					end
-				end
-				# This is a hack to handle corner cases where a heavily loaded NeXpose instance
-				# drops our HTTP connection before processing. We try 5 times to establish a
-				# connection in these situations. The actual exception occurs in the Ruby
-				# http library, which is why we use such generic error classes.
-			rescue ::ArgumentError, ::NoMethodError
-				if @conn_tries < 5
-					@conn_tries += 1
-					retry
-				end
-			rescue ::Timeout::Error
-				if @conn_tries < 5
-					@conn_tries += 1
-					retry
-				end
-				@error = "NeXpose host did not respond"
-			rescue ::Errno::EHOSTUNREACH, ::Errno::ENETDOWN, ::Errno::ENETUNREACH, ::Errno::ENETRESET, ::Errno::EHOSTDOWN, ::Errno::EACCES, ::Errno::EINVAL, ::Errno::EADDRNOTAVAIL
-				@error = "NeXpose host is unreachable"
-				# Handle console-level interrupts
-			rescue ::Interrupt
-				@error = "received a user interrupt"
-			rescue ::Errno::ECONNRESET, ::Errno::ECONNREFUSED, ::Errno::ENOTCONN, ::Errno::ECONNABORTED
-				@error = "NeXpose service is not available"
-			rescue ::REXML::ParseException
-				@error = "NeXpose has not been properly licensed"
-			end
-
-			if !(@success or @error)
-				@error = "NeXpose service returned an unrecognized response: #{@raw_response_data.inspect}"
-			end
-
-			@sid
-		end
-
-		#
-		#
-		#
-		def attributes(*args)
-			return if not @res.root
-			@res.root.attributes(*args)
-		end
-
-		#
-		#
-		#
-		def self.execute(url, req, api_version='1.1')
-			obj = self.new(req, url, api_version)
-			obj.execute
-			if (not obj.success)
-				raise APIError.new(obj, "Action failed: #{obj.error}")
-			end
-			obj
-		end
-
-	end
-end
+module Nexpose
+  class APIRequest
+    include XMLUtils
+
+    attr_reader :http
+    attr_reader :uri
+    attr_reader :headers
+    attr_reader :retry_count
+    attr_reader :time_out
+    attr_reader :pause
+
+    attr_reader :req
+    attr_reader :res
+    attr_reader :sid
+    attr_reader :success
+
+    attr_reader :error
+    attr_reader :trace
+
+    attr_reader :raw_response
+    attr_reader :raw_response_data
+
+    def initialize(req, url, api_version='1.1')
+      @url = url
+      @req = req
+      @api_version = api_version
+      @url = @url.sub('API_VERSION', @api_version)
+      prepare_http_client
+    end
+
+    def prepare_http_client
+      @retry_count = 0
+      @retry_count_max = 10
+      @time_out = 30
+      @pause = 2
+      @uri = URI.parse(@url)
+      @http = Net::HTTP.new(@uri.host, @uri.port)
+      @http.use_ssl = true
+      #
+      # XXX: This is obviously a security issue, however, we handle this at the client level by forcing
+      #      a confirmation when the nexpose host is not localhost. In a perfect world, we would present
+      #      the server signature before accepting it, but this requires either a direct callback inside
+      #      of this module back to whatever UI, or opens a race condition between accept and attempt.
+      @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      @headers = {'Content-Type' => 'text/xml'}
+      @success = false
+    end
+
+    def execute
+      @conn_tries = 0
+
+      begin
+        prepare_http_client
+        @raw_response = @http.post(@uri.path, @req, @headers)
+        @raw_response_data = @raw_response.read_body
+        @res = parse_xml(@raw_response_data)
+
+        if (not @res.root)
+          @error = 'Nexpose service returned invalid XML.'
+          return @sid
+        end
+
+        @sid = attributes['session-id']
+
+        if (attributes['success'] and attributes['success'].to_i == 1)
+          @success = true
+        elsif @api_version =~ /1.2/ and @res and (@res.get_elements '//Exception').count < 1
+          @success = true
+        else
+          @success = false
+          @res.elements.each('//Failure/Exception') do |s|
+            s.elements.each('message') do |m|
+              @error = m.text
+            end
+            s.elements.each('stacktrace') do |m|
+              @trace = m.text
+            end
+          end
+        end
+        # This is a hack to handle corner cases where a heavily loaded Nexpose instance
+        # drops our HTTP connection before processing. We try 5 times to establish a
+        # connection in these situations. The actual exception occurs in the Ruby
+        # http library, which is why we use such generic error classes.
+      rescue OpenSSL::SSL::SSLError
+        if @conn_tries < 5
+          @conn_tries += 1
+          retry
+        end
+      rescue ::ArgumentError, ::NoMethodError
+        if @conn_tries < 5
+          @conn_tries += 1
+          retry
+        end
+      rescue ::Timeout::Error
+        if @conn_tries < 5
+          @conn_tries += 1
+          retry
+        end
+        @error = 'Nexpose host did not respond.'
+      rescue ::Errno::EHOSTUNREACH, ::Errno::ENETDOWN, ::Errno::ENETUNREACH, ::Errno::ENETRESET, ::Errno::EHOSTDOWN, ::Errno::EACCES, ::Errno::EINVAL, ::Errno::EADDRNOTAVAIL
+        @error = 'Nexpose host is unreachable.'
+        # Handle console-level interrupts
+      rescue ::Interrupt
+        @error = 'Received a user interrupt.'
+      rescue ::Errno::ECONNRESET, ::Errno::ECONNREFUSED, ::Errno::ENOTCONN, ::Errno::ECONNABORTED
+        @error = 'Nexpose service is not available.'
+      rescue ::REXML::ParseException
+        @error = 'Nexpose has not been properly licensed.'
+      end
+
+      if !(@success or @error)
+        @error = "Nexpose service returned an unrecognized response: #{@raw_response_data.inspect}"
+      end
+
+      @sid
+    end
+
+    def attributes(*args)
+      return if not @res.root
+      @res.root.attributes(*args)
+    end
+
+    def self.execute(url, req, api_version='1.1')
+      obj = self.new(req, url, api_version)
+      obj.execute
+      if (not obj.success)
+        raise APIError.new(obj, "Action failed: #{obj.error}")
+      end
+      obj
+    end
+
+  end
+end