nexpose 0.0.9 → 0.0.91

data/lib/nexpose/ticket.rb

@@ -0,0 +1,108 @@
+module Nexpose
+	module NexposeAPI
+		include XMLUtils
+
+		#
+		# Create a NeXpose ticket
+		#
+		# ticket_info: A hash of the data to be used to create a ticket in NeXpose:
+		# :name        => The name of the ticket (Required)
+		# :device_id   => The NeXpose device ID for the device being ticketed (Required)
+		# :assigned_to => The NeXpose user to whom this ticket is assigned (Required)
+		# :priority    => "low,moderate,normal,high,critical" (Required)
+		#
+		# :vulnerabilities => An array of NeXpose vuln IDs. This is NOT the same as vuln ID.  (Required)
+		# :comments        => An array of comments to accompany this ticket
+		#
+		# @return The ticket ID if the ticket creation was successful, {@code false} otherwise
+		#
+		def create_ticket ticket_info
+			ticket_name = ticket_info[:name]
+			unless ticket_name
+				raise ArgumentError.new 'Ticket name is required'
+			end
+
+			device_id = ticket_info[:device_id]
+			unless device_id
+				raise ArgumentError.new 'Device ID is required'
+			end
+
+			assigned_to = ticket_info[:assigned_to]
+			unless assigned_to
+				raise ArgumentError.new 'Assignee name is required'
+			end
+
+			priority = ticket_info[:priority]
+			unless priority
+				raise ArgumentError.new 'Ticket priority is required'
+			end
+
+			vulnerabilities = ticket_info[:vulnerabilities]
+			if not vulnerabilities or vulnerabilities.count < 1
+				raise ArgumentError.new 'Vulnerabilities are required'
+			end
+
+			comments = ticket_info[:comments]
+			base_xml = make_xml 'TicketCreateRequest'
+
+			required_attributes = {
+				'name' => ticket_name,
+				'priority' => priority,
+				'device-id' => device_id,
+				'assigned-to' => assigned_to
+			}
+
+			create_request_xml = REXML::Element.new 'TicketCreate'
+			create_request_xml.add_attributes required_attributes
+
+			# Add vulnerabilities
+			vulnerabilities_xml = REXML::Element.new 'Vulnerabilities'
+			vulnerabilities.each do |vuln_id|
+				vulnerabilities_xml.add_element 'Vulnerability', {'id' => vuln_id}
+			end
+			create_request_xml.add_element vulnerabilities_xml
+
+			# Add comments
+			if comments and comments.count > 0
+				comments_xml = REXML::Element.new 'Comments'
+				comments.each do |comment|
+					comment_xml = REXML::Element.new 'Comment'
+					comment_xml.add_text comment
+					comments_xml.add_element comment_xml
+				end
+
+				create_request_xml.add_element comments_xml
+			end
+
+			base_xml.add_element create_request_xml
+			r = execute base_xml, '1.2'
+			if r.success
+				r.res.elements.each('TicketCreateResponse') do |group|
+					return group.attributes['id'].to_i
+				end
+			else
+				false
+			end
+		end
+
+		#
+		# Deletes a NeXpose ticket.
+		#
+		# ticket_ids: An array of ticket IDs to be deleted.
+		#
+		# @returns {@code true} iff the call was successfull. {@code false} otherwise.
+		#
+		def delete_ticket ticket_ids
+			if not ticket_ids or ticket_ids.count < 1
+				raise ArgumentError.new 'The tickets to delete should not be null or empty'
+			end
+
+			base_xml = make_xml 'TicketDeleteRequest'
+			ticket_ids.each do |id|
+				base_xml.add_element 'Ticket', {'id' => id}
+			end
+
+			(execute base_xml, '1.2').success
+		end
+	end
+end

data/lib/nexpose/util.rb

@@ -0,0 +1,35 @@
+module Nexpose
+
+	module Sanitize
+		def replace_entities(str)
+			ret = str.dup
+			ret.gsub!(/&/, "&")
+			ret.gsub!(/'/, "'")
+			ret.gsub!(/"/, """)
+			ret.gsub!(/</, "&lt;")
+			ret.gsub!(/>/, "&gt;")
+			ret
+		end
+	end
+
+	module XMLUtils
+		def parse_xml(xml)
+			::REXML::Document.new(xml.to_s)
+		end
+
+		def make_xml(name, opts={}, data='', append_session_id=true)
+			xml = REXML::Element.new(name)
+			if (@session_id and append_session_id)
+				xml.attributes['session-id'] = @session_id
+			end
+
+			opts.keys.each do |k|
+				xml.attributes[k] = "#{opts[k]}"
+			end
+
+			xml.text = data
+
+			xml
+		end
+	end
+end

data/lib/nexpose/vuln.rb

@@ -0,0 +1,520 @@
+module Nexpose
+	module NexposeAPI
+		include XMLUtils
+
+		###################
+		# VULN EXCEPTIONS #
+		###################
+
+		#-----------------------------------------------------------------------
+		# Returns an array of vulnerability exceptions and their associated
+		# attributes.
+		#
+		# @param status - (optional) The status of the vulnerability exception:
+		# "Under Review", "Approved", "Rejected"
+		#-----------------------------------------------------------------------
+		def vuln_listing status=nil
+			option = {}
+
+			if status && !status.empty?
+				if status =~ /Under Review|Approved|Rejected/
+					option['status'] = status
+				else
+					raise ArgumentError.new 'The vulnerability status passed in is invalid!'
+				end
+			end
+
+			xml = make_xml('VulnerabilityExceptionListingRequest', option)
+			r = execute xml, '1.2'
+
+			if r.success
+				res = []
+				r.res.elements.each("//VulnerabilityException") do |ve|
+					submitter_comment = ve.elements['submitter-comment']
+					reviewer_comment = ve.elements['reviewer-comment']
+					res << {
+						:vuln_id => ve.attributes['vuln-id'],
+						:exception_id => ve.attributes['exception-id'],
+						:submitter => ve.attributes['submitter'],
+						:reviewer => ve.attributes['reviewer'],
+						:status => ve.attributes['status'],
+						:reason => ve.attributes['reason'],
+						:scope => ve.attributes['scope'],
+						:device_id => ve.attributes['device-id'],
+						:port_no => ve.attributes['port-no'],
+						:expiration_date => ve.attributes['expiration-date'],
+						:vuln_key => ve.attributes['vuln-key'],
+						:submitter_comment => submitter_comment.nil? ? '' : submitter_comment.text,
+						:reviewer_comment => reviewer_comment.nil? ? '' : reviewer_comment.text
+					}
+				end
+				res
+			else
+				false
+			end
+		end
+
+		#-------------------------------------------------------------------------------------------------------------------
+		# Creates a vulnerability exception.
+		#
+		# @param input - data used to create the vulnerability exception:
+		# :vuln_id - The Nexpose vulnerability ID.
+		# :reason - The reason for the exception
+		#         values - "False Positive", "Compensating Control", "Acceptable Use", "Acceptable Risk", "Other"
+		# :scope - The scope type  (NOTE: The case is important)
+		#        values - "All Instances", "All Instances on a Specific Asset", "Specific Instance of a specific Asset"
+		# :comment - A user comment
+		# :device-id - Used for specific instances related to "All Instances on a Specific Asset" AND "Specific Instance of Specific Asset"
+		# :port - All assets on this port related to "Specific Instance of a specific Asset"
+		# :vuln-key - The vulnerability key related to the "Specific Instance of a specific Asset"
+		#
+		# @returns exception-id - The Id associated with this create request
+		#-------------------------------------------------------------------------------------------------------------------
+		def vuln_exception_create input
+			options = {}
+
+			if input.nil?
+				raise ArgumentError.new 'The input element cannot be null'
+			end
+
+			vuln_id = input[:vuln_id]
+			if !vuln_id
+				raise ArgumentError.new 'The vulnerability ID is required'
+			end
+			options['vuln-id'] = vuln_id
+
+			reason = input[:reason]
+			if reason.nil? || reason.empty?
+				raise ArgumentError.new 'The reason is required'
+			end
+
+			unless reason =~ /False Positive|Compensating Control|Acceptable Use|Acceptable Risk|Other/
+				raise ArgumentError.new 'The reason type is invalid'
+			end
+			options['reason'] = reason
+
+			scope = input[:scope]
+			if scope.nil? || scope.empty?
+				raise ArgumentError.new 'The scope is required'
+			end
+
+			# For scope case matters.
+			unless scope =~ /All Instances|All Instances on a Specific Asset|Specific Instance of Specific Asset/
+				raise ArgumentError.new 'The scope type is invalid'
+			end
+
+			if scope =~ /All Instances on a Specific Asset|Specific Instance of Specific Asset/
+				device_id = input[:device_id]
+				vuln_key = input[:vuln_key]
+				port = input[:port]
+				if device_id
+					options['device-id'] = device_id
+				end
+
+				if (scope =~ /All Instances on a Specific Asset/ && (vuln_key || port))
+					raise ArgumentError.new "Vulnerability key or port cannot be used with the scope specified"
+				end
+
+				if vuln_key
+					options['vuln-key'] = vuln_key
+				end
+
+				if port
+					options['port-no'] = port
+				end
+			end
+			options['scope'] = scope
+
+			xml = make_xml('VulnerabilityExceptionCreateRequest', options)
+
+			comment = input[:comment]
+			if comment && !comment.empty?
+				comment_xml = make_xml('comment', {}, comment, false)
+				xml.add_element comment_xml
+			else
+				raise ArgumentError.new 'The comment cannot be empty'
+			end
+
+			r = execute xml, '1.2'
+			if r.success
+				r.res.elements.each("//VulnerabilityExceptionCreateResponse") do |vecr|
+					return vecr.attributes['exception-id']
+				end
+			else
+				false
+			end
+		end
+
+		#-------------------------------------------------------------------------------------------------------------------
+		# Resubmit a vulnerability exception.
+		#
+		# @param input - data used to create the vulnerability exception:
+		# :vuln_id - The Nexpose vulnerability ID. (required)
+		# :reason - The reason for the exception (optional)
+		#         values - "False Positive", "Compensating Control", "Acceptable Use", "Acceptable Risk", "Other"
+		# :comment - A user comment  (required)
+		#-------------------------------------------------------------------------------------------------------------------
+		def vuln_exception_resubmit input
+			options = {}
+
+			if input.nil?
+				raise ArgumentError.new 'The input element cannot be null'
+			end
+
+			exception_id = input[:exception_id]
+			if !exception_id
+				raise ArgumentError.new 'The exception ID is required'
+			end
+			options['exception-id'] = exception_id
+
+			reason = input[:reason]
+			if !reason.nil? && !reason.empty?
+				unless reason =~ /False Positive|Compensating Control|Acceptable Use|Acceptable Risk|Other/
+					raise ArgumentError.new 'The reason type is invalid'
+				end
+				options['reason'] = reason
+
+			end
+
+			xml = make_xml('VulnerabilityExceptionResubmitRequest', options)
+
+			comment = input[:comment]
+			if comment && !comment.empty?
+				comment_xml = make_xml('comment', {}, comment, false)
+				xml.add_element comment_xml
+			end
+
+			r = execute xml, '1.2'
+			r.success
+		end
+
+		#-------------------------------------------------------------------------------------------------------------------
+		# Allows a previously submitted exception that has not been approved to be withdrawn.
+		#
+		# @param exception_id - The exception id returned after the vuln exception was submitted for creation.
+		#-------------------------------------------------------------------------------------------------------------------
+		def vuln_exception_recall exception_id
+			xml = make_xml('VulnerabilityExceptionRecallRequest', {'exception-id' => exception_id})
+			r = execute xml, '1.2'
+			r.success
+		end
+
+
+		#-------------------------------------------------------------------------------------------------------------------
+		# Allows a submitted vulnerability exception to be approved.
+		#
+		# @param input:
+		# :exception_id - The exception id returned after the vuln exception was submitted for creation.
+		# :comment - An optional comment
+		#-------------------------------------------------------------------------------------------------------------------
+		def vuln_exception_approve input
+			exception_id = input[:exception_id]
+			if !exception_id
+				raise ArgumentError.new 'Exception Id is required'
+			end
+
+			xml = make_xml('VulnerabilityExceptionApproveRequest', {'exception-id' => exception_id})
+			comment = input[:comment]
+			if comment && !comment.empty?
+				comment_xml = make_xml('comment', {}, comment, false)
+				xml.add_element comment_xml
+			end
+
+			r = execute xml, '1.2'
+			r.success
+		end
+
+		#-------------------------------------------------------------------------------------------------------------------
+		# Rejects a submitted vulnerability exception to be approved.
+		#
+		# @param input:
+		# :exception_id - The exception id returned after the vuln exception was submitted for creation.
+		# :comment - An optional comment
+		#-------------------------------------------------------------------------------------------------------------------
+		def vuln_exception_reject input
+			exception_id = input[:exception_id]
+			if !exception_id
+				raise ArgumentError.new 'Exception Id is required'
+			end
+
+			xml = make_xml('VulnerabilityExceptionRejectRequest', {'exception-id' => exception_id})
+			comment = input[:comment]
+			if comment && !comment.empty?
+				comment_xml = make_xml('comment', {}, comment, false)
+				xml.add_element comment_xml
+			end
+
+			r = execute xml, '1.2'
+			r.success
+		end
+
+		#-------------------------------------------------------------------------------------------------------------------
+		# Updates a vulnerability exception comment.
+		#
+		# @param input:
+		# :exception_id - The exception id returned after the vuln exception was submitted for creation.
+		# :submitter_comment - The submitter comment
+		# :reviewer_comment - The reviewer comment
+		#-------------------------------------------------------------------------------------------------------------------
+		def vuln_exception_update_comment input
+			exception_id = input[:exception_id]
+			if !exception_id
+				raise ArgumentError.new 'Exception Id is required'
+			end
+
+			xml = make_xml('VulnerabilityExceptionUpdateCommentRequest', {'exception-id' => exception_id})
+			submitter_comment = input[:submitter_comment]
+			if submitter_comment && !submitter_comment.empty?
+				comment_xml = make_xml('submitter-comment', {}, submitter_comment, false)
+				xml.add_element comment_xml
+			end
+
+			reviewer_comment = input[:reviewer_comment]
+			if reviewer_comment && !reviewer_comment.empty?
+				comment_xml = make_xml('reviewer-comment', {}, reviewer_comment, false)
+				xml.add_element comment_xml
+			end
+
+			r = execute xml, '1.2'
+			r.success
+		end
+
+		#-------------------------------------------------------------------------------------------------------------------
+		# Update the expiration date for a vulnerability exception.
+		#
+		# @param input
+		# :exception_id - The exception id returned after the vulnerability exception was submitted for creation.
+		# :expiration_date - The new expiration date format: YYYY-MM-DD
+		#-------------------------------------------------------------------------------------------------------------------
+		def vuln_exception_update_expiration_date input
+			exception_id = input[:exception_id]
+			if !exception_id
+				raise ArgumentError.new 'Exception Id is required'
+			end
+
+			expiration_date = input[:expiration_date]
+			if expiration_date && !expiration_date.empty? && expiration_date =~ /\A\d{4}-(\d{2})-(\d{2})\z/
+				if $1.to_i > 12
+					raise ArgumentError.new 'The expiration date month value is invalid'
+				end
+
+				if $2.to_i > 31
+					raise ArgumentError.new 'The expiration date day value is invalid'
+				end
+			else
+				raise ArgumentError.new 'Expiration date is invalid'
+			end
+
+			options = {}
+			options['exception-id'] = exception_id
+			options['expiration-date'] = expiration_date
+			xml = make_xml('VulnerabilityExceptionUpdateExpirationDateRequest', options)
+			r = execute xml, '1.2'
+			r.success
+		end
+
+		#-------------------------------------------------------------------------------------------------------------------
+		# Deletes a submitted vulnerability exception to be approved.
+		#
+		# @param exception_id - The exception id returned after the vuln exception was submitted for creation.
+		#-------------------------------------------------------------------------------------------------------------------
+		def vuln_exception_delete exception_id
+			if !exception_id
+				raise ArgumentError.new 'Exception Id is required'
+			end
+
+			xml = make_xml('VulnerabilityExceptionDeleteRequest', {'exception-id' => exception_id})
+			r = execute xml, '1.2'
+			r.success
+		end
+	end
+
+	# === Description
+	# Object that represents a listing of all of the vulnerabilities in the vulnerability database
+	#
+	class VulnerabilityListing
+
+		# 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
+		# The NSC Connection associated with this object
+		attr_reader :connection
+		# Array containing (VulnerabilitySummary*)
+		attr_reader :vulnerability_summaries
+		# The number of vulnerability definitions
+		attr_reader :vulnerability_count
+
+		# Constructor
+		# VulnerabilityListing(connection)
+		def initialize(connection)
+			@error = false
+			@vulnerability_summaries = []
+			@connection = connection
+
+			r = @connection.execute('<VulnerabilityListingRequest session-id="' + @connection.session_id + '"/>')
+
+			if (r.success)
+				r.res.elements.each('VulnerabilityListingResponse/VulnerabilitySummary') do |v|
+					@vulnerability_summaries.push(VulnerabilitySummary.new(v.attributes['id'], v.attributes["title"], v.attributes["severity"]))
+				end
+			else
+				@error = true
+				@error_msg = 'VulnerabilitySummaryRequest Parse Error'
+			end
+			@vulnerability_count = @vulnerability_summaries.length
+		end
+	end
+
+	# === Description
+	# Object that represents the summary of an entry in the vulnerability database
+	#
+	class VulnerabilitySummary
+
+		# The unique ID string for this vulnerability
+		attr_reader :id
+		# The title of this vulnerability
+		attr_reader :title
+		# The severity of this vulnerability (1 – 10)
+		attr_reader :severity
+
+		# Constructor
+		# VulnerabilitySummary(id, title, severity)
+		def initialize(id, title, severity)
+			@id = id
+			@title = title
+			@severity = severity
+
+		end
+
+	end
+
+	# === Description
+	# Object that represents the details for an entry in the vulnerability database
+	#
+	class VulnerabilityDetail
+		# 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
+		# The NSC Connection associated with this object
+		attr_reader :connection
+		# The unique ID string for this vulnerability
+		attr_reader :id
+		# The title of this vulnerability
+		attr_reader :title
+		# The severity of this vulnerability (1 – 10)
+		attr_reader :severity
+		# The pciSeverity of this vulnerability
+		attr_reader :pciSeverity
+		# The CVSS score of this vulnerability
+		attr_reader :cvssScore
+		# The CVSS vector of this vulnerability
+		attr_reader :cvssVector
+		# The date this vulnerability was published
+		attr_reader :published
+		# The date this vulnerability was added to NeXpose
+		attr_reader :added
+		# The last date this vulnerability was modified
+		attr_reader :modified
+		# The HTML Description of this vulnerability
+		attr_reader :description
+		# External References for this vulnerability
+		# Array containing (Reference)
+		attr_reader :references
+		# The HTML Solution for this vulnerability
+		attr_reader :solution
+
+		# Constructor
+		# VulnerabilityListing(connection,id)
+		def initialize(connection, id)
+
+			@error = false
+			@connection = connection
+			@id = id
+			@references = []
+
+			r = @connection.execute('<VulnerabilityDetailsRequest session-id="' + @connection.session_id + '" vuln-id="' + @id + '"/>')
+
+			if (r.success)
+				r.res.elements.each('VulnerabilityDetailsResponse/Vulnerability') do |v|
+					@id = v.attributes['id']
+					@title = v.attributes["title"]
+					@severity = v.attributes["severity"]
+					@pciSeverity = v.attributes['pciSeverity']
+					@cvssScore = v.attributes['cvssScore']
+					@cvssVector = v.attributes['cvssVector']
+					@published = v.attributes['published']
+					@added = v.attributes['added']
+					@modified = v.attributes['modified']
+
+					v.elements.each('description') do |d|
+						@description = d.to_s.gsub(/\<\/?description\>/i, '')
+					end
+
+					v.elements.each('solution') do |s|
+						@solution = s.to_s.gsub(/\<\/?solution\>/i, '')
+					end
+
+					v.elements.each('references/reference') do |r|
+						@references.push(Reference.new(r.attributes['source'], r.text))
+					end
+				end
+			else
+				@error = true
+				@error_msg = 'VulnerabilitySummaryRequest Parse Error'
+			end
+
+		end
+	end
+
+	# === Description
+	#
+	class Reference
+
+		attr_reader :source
+		attr_reader :reference
+
+		def initialize(source, reference)
+			@source = source
+			@reference = reference
+		end
+	end
+
+	# TODO: review
+	# === Description
+	#
+	class VulnFilter
+
+		attr_reader :typeMask
+		attr_reader :maxAlerts
+		attr_reader :severityThreshold
+
+		def initialize(typeMask, severityThreshold, maxAlerts = -1)
+			@typeMask = typeMask
+			@maxAlerts = maxAlerts
+			@severityThreshold = severityThreshold
+		end
+
+		include Sanitize
+
+		def to_xml
+			xml = "<vulnFilter "
+			xml << %Q{ typeMask="#{replace_entities(typeMask)}"}
+			xml << %Q{ maxAlerts="#{replace_entities(maxAlerts)}"}
+			xml << %Q{ severityThreshold="#{replace_entities(severityThreshold)}"}
+			xml << "/>"
+
+			xml
+		end
+
+	end
+end