class Nexpose::VulnException

A vulnerability exception.

Certain attributes are necessary for some exception scopes, even though they are optional otherwise.

Attributes

asset_group_id[RW]

ID of the Asset Group, if this exception applies to all instances on an asset group

asset_id[RW]

ID of asset, if this exception applies to only one asset.

device_id[RW]

ID of asset, if this exception applies to only one asset.

device_id=[RW]

ID of asset, if this exception applies to only one asset.

expiration[RW]

The date an exception will expire, causing the vulnerability to be included in report risk scores.

id[RW]

Unique identifier assigned to an exception.

port[RW]

Port on a asset, if this exception applies to a specific port.

reason[RW]

The reason for the exception status. @see Nexpose::VulnException::Reason

review_date[RW]

Date when the Review occurred [Time]

reviewer[RW]

The name of the reviewer of the exception.

reviewer_comment[RW]

Any comment provided by the reviewer.

scope[RW]

The scope of the exception. @see Nexpose::VulnException::Scope

site_id[RW]

Id of the site, if this exception applies to all instances on a site

status[RW]

The state of the exception in the work flow process. @see Nexpose::VulnException::Status

submit_date[RW]

Date when Submit occurred [Time]

submitter[RW]

The name of submitter of the exception.

submitter_comment[RW]

Any comment provided by the submitter.

vuln_id[RW]

Unique identifier of a vulnerability.

vuln_key[RW]

The specific vulnerable component in a discovered instance of the vulnerability referenced by the vuln_id, such as a program, file or user account.

Public Class Methods

new(vuln_id, scope, reason, status = nil) click to toggle source
# File lib/nexpose/vuln_exception.rb, line 193
def initialize(vuln_id, scope, reason, status = nil)
  @vuln_id = vuln_id
  @scope   = scope
  @reason  = reason
  @status  = status
end
parse(xml) click to toggle source
# File lib/nexpose/vuln_exception.rb, line 388
def self.parse(xml)
  exception = new(xml.attributes['vuln-id'],
                  xml.attributes['scope'],
                  xml.attributes['reason'],
                  xml.attributes['status'])

  exception.id = xml.attributes['exception-id']
  exception.submitter = xml.attributes['submitter']
  exception.reviewer = xml.attributes['reviewer']
  exception.asset_id = xml.attributes['device-id']
  exception.port = xml.attributes['port-no']
  exception.vuln_key = xml.attributes['vuln-key']
  # TODO: Convert to Date/Time object?
  exception.expiration = xml.attributes['expiration-date']

  submitter_comment = xml.elements['submitter-comment']
  exception.submitter_comment = submitter_comment.text if submitter_comment
  reviewer_comment = xml.elements['reviewer-comment']
  exception.reviewer_comment = reviewer_comment.text if reviewer_comment

  exception
end

Public Instance Methods

approve(connection, comment = nil) click to toggle source

Approve a vulnerability exception request, update comments and expiration dates on vulnerability exceptions that are “Under Review”.

@param [Connection] connection Connection to security console. @param [String] comment Comment to accompany the approval. @return [Boolean] Whether or not the approval was accepted by the console.

# File lib/nexpose/vuln_exception.rb, line 271
def approve(connection, comment = nil)
  xml = connection.make_xml('VulnerabilityExceptionApproveRequest',
                            { 'exception-id' => @id })
  if comment
    cxml = REXML::Element.new('comment')
    cxml.add_text(comment)
    xml.add_element(cxml)
    @reviewer_comment = comment
  end

  connection.execute(xml, '1.2').success
end
delete(connection) click to toggle source

Deletes this vulnerability exception.

@param [Connection] connection Connection to security console. @return [Boolean] Whether or not deletion was successful.

# File lib/nexpose/vuln_exception.rb, line 308
def delete(connection)
  connection.delete_vuln_exception(@id)
end
recall(connection) click to toggle source

Recall a vulnerability exception. Recall is used by a submitter to undo an exception request that has not been approved yet.

You can only recall a vulnerability exception that has 'Under Review' status.

@param [Connection] connection Connection to security console. @return [Boolean] Whether or not the recall was accepted by the console.

# File lib/nexpose/vuln_exception.rb, line 260
def recall(connection)
  connection.recall_vuln_exception(id)
end
reject(connection, comment = nil) click to toggle source

Reject a vulnerability exception request and update comments for the vulnerability exception request.

@param [Connection] connection Connection to security console. @param [String] comment Comment to accompany the rejection. @return [Boolean] Whether or not the reject was accepted by the console.

# File lib/nexpose/vuln_exception.rb, line 291
def reject(connection, comment = nil)
  xml = connection.make_xml('VulnerabilityExceptionRejectRequest',
                            { 'exception-id' => @id })
  if comment
    cxml = REXML::Element.new('comment')
    cxml.add_text(comment)
    xml.add_element(cxml)
  end

  connection.execute(xml, '1.2').success
end
resubmit(connection) click to toggle source

Resubmit a vulnerability exception request with a new comment and reason after an exception has been rejected.

You can only resubmit a request that has a “Rejected” status; if an exception is “Approved” or “Under Review” you will receive an error message stating that the exception request cannot be resubmitted.

This call will use the object's current state to resubmit.

@param [Connection] connection Connection to security console. @return [Boolean] Whether or not the resubmission was valid.

# File lib/nexpose/vuln_exception.rb, line 246
def resubmit(connection)
  raise ArgumentError.new('Only Rejected exceptions can be resubmitted.') unless @status == Status::REJECTED
  connection.resubmit_vuln_exception(@id, @submitter_comment, @reason)
end
save(connection, comment = nil) click to toggle source

Submit this exception on the security console.

@param [Connection] connection Connection to security console. @return [Fixnum] Newly assigned exception ID.

# File lib/nexpose/vuln_exception.rb, line 205
def save(connection, comment = nil)
  validate

  xml = connection.make_xml('VulnerabilityExceptionCreateRequest')
  xml.add_attributes({ 'vuln-id' => @vuln_id,
                       'scope' => @scope,
                       'reason' => @reason })
  case @scope
  when Scope::ALL_INSTANCES_ON_A_SPECIFIC_ASSET
    xml.add_attributes({ 'device-id' => @asset_id })
  when Scope::SPECIFIC_INSTANCE_OF_SPECIFIC_ASSET
    xml.add_attributes({ 'device-id' => @asset_id,
                         'port-no' => @port,
                         'vuln-key' => @vuln_key })
  when Scope::ALL_INSTANCES_IN_A_SPECIFIC_SITE
    xml.add_attributes({ 'site-id ' => @site_id })
  end

  @submitter_comment = comment if comment
  if @submitter_comment
    comment_elem = REXML::Element.new('comment')
    comment_elem.add_text(@submitter_comment)
    xml.add_element(comment_elem)
  end

  response = connection.execute(xml, '1.2')
  @id = response.attributes['exception-id'].to_i if response.success
end
update_expiration_date(connection, new_date) click to toggle source

Update the expiration date for this exception. The expiration time cannot be in the past.

@param [Connection] connection Connection to security console. @param [String] new_date Date in the format “YYYY-MM-DD”. @return [Boolean] Whether the update was successfully submitted.

# File lib/nexpose/vuln_exception.rb, line 358
def update_expiration_date(connection, new_date)
  xml = connection.make_xml('VulnerabilityExceptionUpdateExpirationDateRequest',
                            { 'exception-id' => @id,
                              'expiration-date' => new_date })
  connection.execute(xml, '1.2').success
end
update_reviewer_comment(connection, comment) click to toggle source

Update security console with reviewer comment on this vulnerability exceptions.

@param [Connection] connection Connection to security console. @param [String] comment Reviewer comment on this exception. @return [Boolean] Whether the comment was successfully submitted.

# File lib/nexpose/vuln_exception.rb, line 340
def update_reviewer_comment(connection, comment)
  xml = connection.make_xml('VulnerabilityExceptionUpdateCommentRequest',
                            { 'exception-id' => @id })
  cxml = REXML::Element.new('reviewer-comment')
  cxml.add_text(comment)
  xml.add_element(cxml)
  @reviewer_comment = comment

  connection.execute(xml, '1.2').success
end
update_submitter_comment(connection, comment) click to toggle source

Update security console with submitter comment on this vulnerability exceptions.

Cannot update a submit comment unless exception is under review or has expired.

@param [Connection] connection Connection to security console. @param [String] comment Submitter comment on this exception. @return [Boolean] Whether the comment was successfully submitted.

# File lib/nexpose/vuln_exception.rb, line 322
def update_submitter_comment(connection, comment)
  xml = connection.make_xml('VulnerabilityExceptionUpdateCommentRequest',
                            { 'exception-id' => @id })
  cxml = REXML::Element.new('submitter-comment')
  cxml.add_text(comment)
  xml.add_element(cxml)
  @submitter_comment = comment

  connection.execute(xml, '1.2').success
end
validate() click to toggle source

Validate that this exception meets to requires for the assigned scope.

# File lib/nexpose/vuln_exception.rb, line 367
def validate
  raise ArgumentError.new('No vuln_id.') unless @vuln_id
  raise ArgumentError.new('No scope.') unless @scope
  raise ArgumentError.new('No reason.') unless @reason

  case @scope
  when Scope::ALL_INSTANCES
    @asset_id = @port = @vuln_key = nil
  when Scope::ALL_INSTANCES_ON_A_SPECIFIC_ASSET
    raise ArgumentError.new('No asset_id.') unless @asset_id
    @port = @vuln_key = nil
  when Scope::SPECIFIC_INSTANCE_OF_SPECIFIC_ASSET
    raise ArgumentError.new('No asset_id.') unless @asset_id
    raise ArgumentError.new('Port or vuln_key is required.') unless @port || @vuln_key
  when Scope::ALL_INSTANCES_IN_A_SPECIFIC_SITE
    raise ArgumentError.new('No site_id.') unless @site_id
  else
    raise ArgumentError.new("Invalid scope: #{@scope}")
  end
end