nexpose 0.0.9 → 0.0.91

data/lib/nexpose/api_request.rb

@@ -0,0 +1,144 @@
+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

data/lib/nexpose/connection.rb

@@ -0,0 +1,106 @@
+module Nexpose
+
+	# === Description
+	# Object that represents a connection to a NeXpose Security Console.
+	#
+	# === Examples
+	#   # Create a new Nexpose Connection on the default port
+	#   nsc = Connection.new("10.1.40.10","nxadmin","password")
+	#
+	#   # Login to NSC and Establish a Session ID
+	#   nsc.login()
+	#
+	#   # Check Session ID
+	#   if (nsc.session_id)
+	#       puts "Login Successful"
+	#   else
+	#       puts "Login Failure"
+	#   end
+	#
+	#   # //Logout
+	#   logout_success = nsc.logout()
+	#   if (! logout_success)
+	#       puts "Logout Failure" + "<p>" + nsc.error_msg.to_s
+	#   end
+	#
+	class Connection
+		include XMLUtils
+		include NexposeAPI
+
+		# true if an error condition exists; false otherwise
+		attr_reader :error
+		# Error message string
+		attr_reader :error_msg
+		# The last XML request sent by this object
+		attr_reader :request_xml
+		# The last XML response received by this object
+		attr_reader :response_xml
+		# Session ID of this connection
+		attr_reader :session_id
+		# The hostname or IP Address of the NSC
+		attr_reader :host
+		# The port of the NSC (default is 3780)
+		attr_reader :port
+		# The username used to login to the NSC
+		attr_reader :username
+		# The password used to login to the NSC
+		attr_reader :password
+		# The URL for communication
+		attr_reader :url
+
+		# Constructor for Connection
+		def initialize(ip, user, pass, port = 3780, silo_id = nil)
+			@host = ip
+			@port = port
+			@username = user
+			@password = pass
+			@silo_id = silo_id
+			@session_id = nil
+			@error = false
+			@url = "https://#{@host}:#{@port}/api/API_VERSION/xml"
+		end
+
+		# Establish a new connection and Session ID
+		def login
+			begin
+				login_hash = {'sync-id' => 0, 'password' => @password, 'user-id' => @username}
+				unless @silo_id.nil?
+					login_hash['silo-id'] = @silo_id
+				end
+				r = execute(make_xml('LoginRequest', login_hash))
+			rescue APIError
+				raise AuthenticationFailed.new(r)
+			end
+			if (r.success)
+				@session_id = r.sid
+				true
+			end
+		end
+
+		# Logout of the current connection
+		def logout
+			r = execute(make_xml('LogoutRequest', {'sync-id' => 0}))
+			if (r.success)
+				return true
+			end
+			raise APIError.new(r, 'Logout failed')
+		end
+
+		# Execute an API request
+		def execute(xml, version = '1.1')
+			@api_version = version
+			APIRequest.execute(@url, xml.to_s, @api_version)
+		end
+
+		# Download a specific URL
+		def download(url)
+			uri = URI.parse(url)
+			http = Net::HTTP.new(@host, @port)
+			http.use_ssl = true
+			http.verify_mode = OpenSSL::SSL::VERIFY_NONE # XXX: security issue
+			headers = {'Cookie' => "nexposeCCSessionID=#{@session_id}"}
+			resp, data = http.get(uri.path, headers)
+			data
+		end
+	end
+end

data/lib/nexpose/creds.rb

@@ -0,0 +1,189 @@
+module Nexpose
+   include Sanitize
+
+   # === Description
+   # Object that represents administrative credentials to be used during a scan. When retrived from an existing site configuration 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
+      # Security blob for an existing set of credentials
+      attr_reader :securityblob
+      # Designates if this object contains user defined credentials or a security blob
+      attr_reader :isblob
+      # The service for these credentials. Can be All.
+      attr_reader :service
+      # The host for these credentials. Can be Any.
+      attr_reader :host
+      # The port on which to use these credentials.
+      attr_reader :port
+      # The user id or username
+      attr_reader :userid
+      # The password
+      attr_reader :password
+      # The realm for these credentials
+      attr_reader :realm
+      # When using httpheaders, this represents the set of headers to pass
+      # with the authentication request.
+      attr_reader :headers
+
+      def initialize(isblob = false)
+         @isblob = isblob
+      end
+
+      # Sets the credentials information for this object.
+      def setCredentials(service, host, port, userid, password, realm)
+         @isblob = false
+         @securityblob = nil
+         @service = service
+         @host = host
+         @port = port
+         @userid = userid
+         @password = password
+         @realm = realm
+      end
+
+      # TODO: add description
+      def setService(service)
+         @service = service
+      end
+
+      def setHost(host)
+         @host = host
+      end
+
+      # TODO: add description
+      def setBlob(securityblob)
+         @isblob = true
+         @securityblob = securityblob
+      end
+
+      # Add Headers to credentials for httpheaders.
+      def setHeaders(headers)
+         @headers = headers
+      end
+
+      def to_xml
+         xml = ''
+         xml << '<adminCredentials'
+         xml << %Q{ service="#{replace_entities(service)}"} if (service)
+         xml << %Q{ userid="#{replace_entities(userid)}"} if (userid)
+         xml << %Q{ password="#{replace_entities(password)}"} if (password)
+         xml << %Q{ realm="#{replace_entities(realm)}"} if (realm)
+         xml << %Q{ host="#{replace_entities(host)}"} if (host)
+         xml << %Q{ port="#{replace_entities(port)}"} if (port)
+         xml << '>'
+         xml << replace_entities(securityblob) if (isblob)
+         xml << @headers.to_xml()
+         xml << '</adminCredentials>'
+
+         xml
+      end
+   end
+
+   # Object that represents Header name-value pairs, associated with Web Session Authentication.
+   class Header
+      # Name, one per Header
+      attr_reader :name
+      # Value, one per Header
+      attr_reader :value
+
+      # Construct with name value pair
+      def initialize(name, value)
+         @name = name
+         @value = value
+      end
+
+      def to_xml
+         xml = ''
+         xml << '<Header'
+         xml << %Q{ name="#{replace_entities(name)}"} if (name)
+         xml << %Q{ value="#{replace_entities(value)}"} if (value)
+         xml << '/>'
+         xml
+      end
+   end
+
+   # Object that represents Headers, associated with Web Session Authentication.
+   class Headers
+      # 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.
+      attr_reader :webapproot
+      # When using httpheaders, this represents the set of headers to pass with the authentication request.
+      attr_reader :headers
+
+      def initialize(webapproot, soft403)
+         @headers = []
+         @webapproot = webapproot
+         @soft403 = soft403
+      end
+
+      def addHeader(header)
+         @headers.push(header)
+      end
+
+
+      def to_xml
+         xml = ''
+         xml << '<Headers'
+         xml << %Q{ soft403="#{replace_entities(soft403)}"} if (soft403)
+         xml << %Q{ webapproot="#{replace_entities(webapproot)}"} if (webapproot)
+         xml << '>'
+         @headers.each do |header|
+            xml << header.to_xml
+         end
+         xml << '</Headers>'
+         xml
+      end
+   end
+
+   # When using htmlform, this represents the login form information.
+   class Field
+      # The name of the HTML field (form parameter).
+      attr_reader :name
+      # The value of the HTML field (form parameter).
+      attr_reader :value
+      # The type of the HTML field (form parameter).
+      attr_reader :type
+      # Is the HTML field (form parameter) dynamically generated? If so,
+      # the login page is requested and the value of the field is extracted
+      # from the response.
+      attr_reader :dynamic
+      # If the HTML field (form parameter) is a radio button, checkbox or select
+      # field, this flag determines if the field should be checked (selected).
+      attr_reader :checked
+
+      # TODO
+   end
+
+   # When using htmlform, this represents the login form information.
+   class HTMLForm
+      # The name of the form being submitted.
+      attr_reader :name
+      # The HTTP action (URL) through which to submit the login form.
+      attr_reader :action
+      # The HTTP request method with which to submit the form.
+      attr_reader :method
+      # The HTTP encoding type with which to submit the form.
+      attr_reader :enctype
+
+      # TODO
+   end
+
+   # When using htmlform, this represents the login form information.
+   class HTMLForms
+      # The URL of the login page containing the login form.
+      attr_reader :parentpage
+      # 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.
+      attr_reader :webapproot
+
+      # TODO
+   end
+
+   # When using ssh-key, this represents the PEM-format keypair information.
+   class PEMKey
+      # TODO
+   end
+end

data/lib/nexpose/error.rb

@@ -0,0 +1,21 @@
+module Nexpose
+	class APIError < ::RuntimeError
+		attr_accessor :req, :reason
+
+		def initialize(req, reason = '')
+			@req = req
+			@reason = reason
+		end
+
+		def to_s
+			"NexposeAPI: #{@reason}"
+		end
+	end
+
+	class AuthenticationFailed < APIError
+		def initialize(req)
+			@req = req
+			@reason = "Login Failed"
+		end
+	end
+end