Class: Nexpose::Site

Inherits:
Object
  • Object
show all
Includes:
Sanitize
Defined in:
lib/nexpose/site.rb

Overview

Configuration object representing a Nexpose site.

For a basic walk-through, see https://github.com/rapid7/nexpose-client/wiki/Using-Sites

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Sanitize

#replace_entities

Constructor Details

#initialize(name = nil, scan_template = 'full-audit-without-web-spider') ⇒ Site

Site constructor. Both arguments are optional.

Parameters:

  • name (String) (defaults to: nil) —

    Unique name of the site.

  • scan_template (String) (defaults to: 'full-audit-without-web-spider') —

    ID of the scan template to use.



154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/nexpose/site.rb', line 154

def initialize(name = nil, scan_template = 'full-audit-without-web-spider')
  @name = name
  @scan_template = scan_template

  @id = -1
  @risk_factor = 1.0
  @config_version = 3
  @is_dynamic = false
  @assets = []
  @schedules = []
  @credentials = []
  @alerts = []
  @exclude = []
  @users = []
  @tags = []
end

Instance Attribute Details

#alerts ⇒ Object

Array

Collection of real-time alerts.

See Also:



125
126
127
 
# File 'lib/nexpose/site.rb', line 125

def alerts
  @alerts
end

#assets ⇒ Object

Array

Collection of assets. May be IPv4, IPv6, or DNS names.

See Also:



95
96
97
 
# File 'lib/nexpose/site.rb', line 95

def assets
  @assets
end

#config_version ⇒ Object

Configuration version. Default: 3



135
136
137
 
# File 'lib/nexpose/site.rb', line 135

def config_version
  @config_version
end

#credentials ⇒ Object

Array

Collection of credentials associated with this site. Does not

include shared credentials.



118
119
120
 
# File 'lib/nexpose/site.rb', line 118

def credentials
  @credentials
end

#criteria ⇒ Object

Asset filter criteria if this site is dynamic.



142
143
144
 
# File 'lib/nexpose/site.rb', line 142

def criteria
  @criteria
end

#description ⇒ Object

Description of the site.



90
91
92
 
# File 'lib/nexpose/site.rb', line 90

def description
  @description
end

#discovery_connection_id ⇒ Object

ID of the discovery connection associated with this site if it is dynamic.



145
146
147
 
# File 'lib/nexpose/site.rb', line 145

def discovery_connection_id
  @discovery_connection_id
end

#engine ⇒ Object

Scan Engine to use. Will use the default engine if nil or -1.



108
109
110
 
# File 'lib/nexpose/site.rb', line 108

def engine
  @engine
end

#exclude ⇒ Object

Array

Collection of excluded assets. May be IPv4, IPv6, or DNS names.



98
99
100
 
# File 'lib/nexpose/site.rb', line 98

def exclude
  @exclude
end

#id ⇒ Object

The site ID. An ID of -1 is used to designate a site that has not been saved to a Nexpose console.



84
85
86
 
# File 'lib/nexpose/site.rb', line 84

def id
  @id
end

#is_dynamic ⇒ Object

Whether or not this site is dynamic. Dynamic sites are created through Asset Discovery Connections.



139
140
141
 
# File 'lib/nexpose/site.rb', line 139

def is_dynamic
  @is_dynamic
end

#name ⇒ Object

Unique name of the site. Required.



87
88
89
 
# File 'lib/nexpose/site.rb', line 87

def name
  @name
end

#organization ⇒ Object

Information about the organization that this site belongs to. Used by some reports.



129
130
131
 
# File 'lib/nexpose/site.rb', line 129

def organization
  @organization
end

#risk_factor ⇒ Object

The risk factor associated with this site. Default: 1.0



114
115
116
 
# File 'lib/nexpose/site.rb', line 114

def risk_factor
  @risk_factor
end

#scan_template ⇒ Object

Scan template to use when starting a scan job. Default: full-audit



101
102
103
 
# File 'lib/nexpose/site.rb', line 101

def scan_template
  @scan_template
end

#scan_template_name ⇒ Object

Friendly name of scan template to use when starting a scan job. Value is populated when a site is saved or loaded from a console.



105
106
107
 
# File 'lib/nexpose/site.rb', line 105

def scan_template_name
  @scan_template_name
end

#schedules ⇒ Object

Array

Schedule starting dates and times for scans, and set their frequency.



111
112
113
 
# File 'lib/nexpose/site.rb', line 111

def schedules
  @schedules
end

#tags ⇒ Object

Array

Collection of TagSummary



148
149
150
 
# File 'lib/nexpose/site.rb', line 148

def tags
  @tags
end

#users ⇒ Object

Array

List of user IDs for users who have access to the site.



132
133
134
 
# File 'lib/nexpose/site.rb', line 132

def users
  @users
end

Class Method Details

.copy(connection, id) ⇒ Site

Copy an existing configuration from a Nexpose instance. Returned object will reset the site ID and append “Copy” to the existing name.

Parameters:

  • connection (Connection) —

    Connection to the security console.

  • id (Fixnum) —

    Site ID of an existing site.

Returns:

  • (Site) —

    Site configuration loaded from a Nexpose console.



321
322
323
324
325
326
 
# File 'lib/nexpose/site.rb', line 321

def self.copy(connection, id)
  site = self.load(connection, id)
  site.id = -1
  site.name = "#{site.name} Copy"
  site
end

.load(connection, id, is_extended = false) ⇒ Site

Load an existing configuration from a Nexpose instance.

Parameters:

  • connection (Connection) —

    Connection to console where site exists.

  • id (Fixnum) —

    Site ID of an existing site.

Returns:

  • (Site) —

    Site configuration loaded from a Nexpose console.



300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/nexpose/site.rb', line 300

def self.load(connection, id, is_extended = false)
  if is_extended
    r = APIRequest.execute(connection.url,
                           %(<SiteConfigRequest session-id="#{connection.session_id}" site-id="#{id}" is_extended="true"/>))
  else
    r = APIRequest.execute(connection.url,
                           %(<SiteConfigRequest session-id="#{connection.session_id}" site-id="#{id}"/>))
  end
  site = parse(r.res)
  site.load_dynamic_attributes(connection) if site.dynamic?
  site
end

.parse(rexml) ⇒ Site

Parse a response from a Nexpose console into a valid Site object.

Parameters:

  • rexml (REXML::Document) —

    XML document to parse.

Returns:

  • (Site) —

    Site object represented by the XML. ## TODO What is returned on failure?



506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
 
# File 'lib/nexpose/site.rb', line 506

def self.parse(rexml)
  rexml.elements.each('//Site') do |s|
    site = Site.new(s.attributes['name'])
    site.id = s.attributes['id'].to_i
    site.description = s.attributes['description']
    site.risk_factor = s.attributes['riskfactor'] || 1.0
    site.is_dynamic = true if s.attributes['isDynamic'] == '1'

    s.elements.each('Description') do |desc|
      site.description = desc.text
    end

    s.elements.each('Users/user') do |user|
      site.users << user.attributes['id'].to_i
    end

    s.elements.each('Organization') do |org|
      site.organization = Organization.parse(org)
    end

    s.elements.each('Hosts/range') do |r|
      site.assets << IPRange.new(r.attributes['from'], r.attributes['to'])
    end
    s.elements.each('Hosts/host') do |host|
      site.assets << HostName.new(host.text)
    end

    s.elements.each('ExcludedHosts/range') do |r|
      site.exclude << IPRange.new(r.attributes['from'], r.attributes['to'])
    end
    s.elements.each('ExcludedHosts/host') do |host|
      site.exclude << HostName.new(host.text)
    end

    s.elements.each('Credentials/adminCredentials') do |cred|
      site.credentials << SiteCredential.parse(cred)
    end

    s.elements.each('ScanConfig') do |scan_config|
      site.scan_template_name = scan_config.attributes['name']
      site.scan_template = scan_config.attributes['templateID']
      site.config_version = scan_config.attributes['configVersion'].to_i
      site.engine = scan_config.attributes['engineID'].to_i
      scan_config.elements.each('Schedules/Schedule') do |schedule|
        site.schedules << Schedule.parse(schedule)
      end
    end

    s.elements.each('Alerting/Alert') do |alert|
      site.alerts << Alert.parse(alert)
    end

    s.elements.each('Tags/Tag') do |tag|
      site.tags << TagSummary.parse_xml(tag)
    end

    return site
  end
  nil
end

Instance Method Details

#_append_shared_creds_to_xml(connection, xml) ⇒ Object 



567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
 
# File 'lib/nexpose/site.rb', line 567

def _append_shared_creds_to_xml(connection, xml)
  xml_w_creds = AJAX.get(connection, "/data/site/config?siteid=#{@id}")
  cred_xml = REXML::XPath.first(REXML::Document.new(xml_w_creds), 'Site/Credentials')
  unless cred_xml.nil?
    creds = REXML::XPath.first(xml, 'Credentials')
    if creds.nil?
      xml.add_element(cred_xml)
    else
      cred_xml.elements.each do |cred|
        if cred.attributes['shared'].to_i == 1
          creds.add_element(cred)
        end
      end
    end
  end
  xml
end

#add_asset(asset) ⇒ Object

Adds an asset to this site, resolving whether an IP or hostname is provided.

Parameters:

  • asset (String) —

    Identifier of an asset, either IP or host name.



230
231
232
233
 
# File 'lib/nexpose/site.rb', line 230

def add_asset(asset)
  obj = HostOrIP.convert(asset)
  @assets << obj
end

#add_host(hostname) ⇒ Object

Adds an asset to this site by host name.

Parameters:

  • hostname (String) —

    FQDN or DNS-resolvable host name of an asset.



184
185
186
 
# File 'lib/nexpose/site.rb', line 184

def add_host(hostname)
  @assets << HostName.new(hostname)
end

#add_ip(ip) ⇒ Object

Adds an asset to this site by IP address.

Parameters:

  • ip (String) —

    IP address of an asset.



198
199
200
 
# File 'lib/nexpose/site.rb', line 198

def add_ip(ip)
  @assets << IPRange.new(ip)
end

#add_ip_range(from, to) ⇒ Object

Adds assets to this site by IP address range.

Parameters:

  • from (String) —

    Beginning IP address of a range.

  • to (String) —

    Ending IP address of a range.



213
214
215
 
# File 'lib/nexpose/site.rb', line 213

def add_ip_range(from, to)
  @assets << IPRange.new(from, to)
end

#as_xml ⇒ String

Generate an XML representation of this site configuration

Returns:

  • (String) —

    XML valid for submission as part of other requests.



433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
 
# File 'lib/nexpose/site.rb', line 433

def as_xml
  xml = REXML::Element.new('Site')
  xml.attributes['id'] = @id
  xml.attributes['name'] = @name
  xml.attributes['description'] = @description
  xml.attributes['riskfactor'] = @risk_factor
  xml.attributes['isDynamic'] = '1' if dynamic?
  # TODO This should be set to 'Amazon Web Services' for AWS.
  xml.attributes['dynamicConfigType'] = 'vSphere' if dynamic?

  if @description && !@description.empty?
    elem = REXML::Element.new('Description')
    elem.add_text(@description)
    xml.add_element(elem)
  end

  unless @users.empty?
    elem = REXML::Element.new('Users')
    @users.each { |user| elem.add_element('user', { 'id' => user }) }
    xml.add_element(elem)
  end

  xml.add_element(@organization.as_xml) if @organization

  elem = REXML::Element.new('Hosts')
  @assets.each { |a| elem.add_element(a.as_xml) }
  xml.add_element(elem)

  elem = REXML::Element.new('ExcludedHosts')
  @exclude.each { |e| elem.add_element(e.as_xml) }
  xml.add_element(elem)

  unless credentials.empty?
    elem = REXML::Element.new('Credentials')
    @credentials.each { |c| elem.add_element(c.as_xml) }
    xml.add_element(elem)
  end

  unless alerts.empty?
    elem = REXML::Element.new('Alerting')
    alerts.each { |a| elem.add_element(a.as_xml) }
    xml.add_element(elem)
  end

  elem = REXML::Element.new('ScanConfig')
  elem.add_attributes({ 'configID' => @id,
                        'name' => @scan_template_name || @scan_template,
                        'templateID' => @scan_template,
                        'configVersion' => @config_version || 3,
                        'engineID' => @engine })
  sched = REXML::Element.new('Schedules')
  @schedules.each { |s| sched.add_element(s.as_xml) }
  elem.add_element(sched)
  xml.add_element(elem)

  unless tags.empty?
    tag_xml = xml.add_element(REXML::Element.new('Tags'))
    @tags.each { |tag| tag_xml.add_element(tag.as_xml) }
  end

  xml
end

#delete(connection) ⇒ Boolean

Delete this site from a Nexpose console.

Parameters:

  • connection (Connection) —

    Connection to console where this site will be saved.

Returns:

  • (Boolean) —

    Whether or not the site was successfully deleted.



361
362
363
364
 
# File 'lib/nexpose/site.rb', line 361

def delete(connection)
  r = connection.execute(%(<SiteDeleteRequest session-id="#{connection.session_id}" site-id="#{@id}"/>))
  r.success
end

#dynamic? ⇒ Boolean

Returns true when the site is dynamic.

Returns:

  • (Boolean) 


172
173
174
 
# File 'lib/nexpose/site.rb', line 172

def dynamic?
  is_dynamic
end

#exclude_asset(asset) ⇒ Object Also known as: exclude_host, exclude_ip

Adds an asset to this site’s exclude list, resolving whether an IP or hostname is provided.

Parameters:

  • asset (String) —

    Identifier of an asset, either IP or host name.



259
260
261
 
# File 'lib/nexpose/site.rb', line 259

def exclude_asset(asset)
  @exclude << HostOrIP.convert(asset)
end

#exclude_ip_range(from, to) ⇒ Object

Adds assets to this site’s exclude list by IP address range.

Parameters:

  • from (String) —

    Beginning IP address of a range.

  • to (String) —

    Ending IP address of a range.



282
283
284
 
# File 'lib/nexpose/site.rb', line 282

def exclude_ip_range(from, to)
  @exclude << IPRange.new(from, to)
end

#load_dynamic_attributes(nsc) ⇒ Criteria

Retrieve the currrent filter criteria used by a dynamic site.

Parameters:

Returns:

  • (Criteria) —

    Current criteria for the site.



420
421
422
423
424
425
 
# File 'lib/nexpose/site.rb', line 420

def load_dynamic_attributes(nsc)
  response = AJAX.get(nsc, "/data/site/loadDynamicSite?entityid=#{@id}")
  json = JSON.parse(response)
  @discovery_connection_id = json['discoveryConfigs']['id']
  @criteria = Criteria.parse(json['searchCriteria'])
end

#remove_asset(asset) ⇒ Object

Remove an asset to this site, resolving whether an IP or hostname is provided.

Parameters:

  • asset (String) —

    Identifier of an asset, either IP or host name.



240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/nexpose/site.rb', line 240

def remove_asset(asset)
  begin
    # If the asset registers as a valid IP, remove as IP.
    IPAddr.new(asset)
    remove_ip(asset)
  rescue ArgumentError => e
    if e.message == 'invalid address'
      remove_host(asset)
    else
      raise "Unable to parse asset: '#{asset}'. #{e.message}"
    end
  end
end

#remove_excluded_asset(asset) ⇒ Object Also known as: remove_excluded_host, remove_excluded_ip

Remove an asset from this site’s exclude list, resolving whether an IP or hostname is provided.

Parameters:

  • asset (String) —

    Identifier of an asset, either IP or host name.



271
272
273
 
# File 'lib/nexpose/site.rb', line 271

def remove_excluded_asset(asset)
  @exclude.reject! { |existing_asset| existing_asset == HostOrIP.convert(asset) }
end

#remove_excluded_ip_range(from, to) ⇒ Object

Remove assets from this site’s exclude list by IP address range.

Parameters:

  • from (String) —

    Beginning IP address of a range.

  • to (String) —

    Ending IP address of a range.



290
291
292
 
# File 'lib/nexpose/site.rb', line 290

def remove_excluded_ip_range(from, to)
  @exclude.reject! { |asset| asset == IPRange.new(from, to) }
end

#remove_host(hostname) ⇒ Object

Remove an asset to this site by host name.

Parameters:

  • hostname (String) —

    FQDN or DNS-resolvable host name of an asset.



191
192
193
 
# File 'lib/nexpose/site.rb', line 191

def remove_host(hostname)
  @assets = assets.reject { |asset| asset == HostName.new(hostname) }
end

#remove_ip(ip) ⇒ Object

Remove an asset to this site by IP address.

Parameters:

  • ip (String) —

    IP address of an asset.



205
206
207
 
# File 'lib/nexpose/site.rb', line 205

def remove_ip(ip)
  @assets = assets.reject { |asset| asset == IPRange.new(ip) }
end

#remove_ip_range(from, to) ⇒ Object

Remove assets to this site by IP address range.

Parameters:

  • from (String) —

    Beginning IP address of a range.

  • to (String) —

    Ending IP address of a range.



221
222
223
 
# File 'lib/nexpose/site.rb', line 221

def remove_ip_range(from, to)
  @assets = assets.reject { |asset| asset == IPRange.new(from, to) }
end

#save(connection) ⇒ Fixnum

Saves this site to a Nexpose console. If the site is dynamic, connection and asset filter changes must be saved through the DiscoveryConnection#update_site call.

Parameters:

  • connection (Connection) —

    Connection to console where this site will be saved.

Returns:

  • (Fixnum) —

    Site ID assigned to this configuration, if successful.



335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
 
# File 'lib/nexpose/site.rb', line 335

def save(connection)
  if dynamic?
    raise APIError.new(nil, 'Cannot save a dynamic site without a discovery connection configured.') unless @discovery_connection_id

    new_site = @id == -1
    save_dynamic_criteria(connection) if new_site

    # Have to retrieve and attach shared creds, or saving will fail.
    xml = _append_shared_creds_to_xml(connection, as_xml)
    response = AJAX.post(connection, '/data/site/config', xml)
    saved = REXML::XPath.first(REXML::Document.new(response), 'ajaxResponse')
    raise APIError.new(response, 'Failed to save dynamic site.') if saved.nil? || saved.attributes['success'].to_i != 1

    save_dynamic_criteria(connection) unless new_site
  else
    r = connection.execute('<SiteSaveRequest session-id="' + connection.session_id + '">' + to_xml + ' </SiteSaveRequest>')
    @id = r.attributes['site-id'].to_i if r.success
  end
  @id
end

#save_dynamic_criteria(nsc) ⇒ Fixnum

Save only the criteria of a dynamic site.

Parameters:

Returns:

  • (Fixnum) —

    Site ID.



387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/nexpose/site.rb', line 387

def save_dynamic_criteria(nsc)
  # Several parameters are passed through the URI
  params = { 'configID' => @discovery_connection_id,
             'entityid' => @id > 0 ? @id : false,
             'mode' => @id > 0 ? 'edit' : false }
  uri = AJAX.parameterize_uri('/data/site/saveSite', params)

  # JSON body of POST request contains details.
  details = { 'dynamic' => true,
              'name' => @name,
              'tag' => @description.nil? ? '' : @description,
              'riskFactor' => @risk_factor,
              # 'vCenter' => @discovery_connection_id,
              'searchCriteria' => @criteria.nil? ? { 'operator' => 'AND' } : @criteria.to_h }
  json = JSON.generate(details)

  response = AJAX.post(nsc, uri, json, AJAX::CONTENT_TYPE::JSON)
  json = JSON.parse(response)
  if json['response'] =~ /success/
    if @id < 1
      @id = json['entityID'].to_i
    end
  else
    raise APIError.new(response, json['message'])
  end
  @id
end

#scan(connection, sync_id = nil) ⇒ Scan

Scan this site.

Parameters:

  • connection (Connection) —

    Connection to console where scan will be launched.

  • sync_id (String) (defaults to: nil) —

    Optional synchronization token.

Returns:

  • (Scan) —

    Scan launch information.



372
373
374
375
376
377
378
379
380
 
# File 'lib/nexpose/site.rb', line 372

def scan(connection, sync_id = nil)
  xml = REXML::Element.new('SiteScanRequest')
  xml.add_attributes({ 'session-id' => connection.session_id,
                       'site-id' => @id,
                       'sync-id' => sync_id })

  response = connection.execute(xml, '1.1', timeout: 60)
  Scan.parse(response.res) if response.success
end

#to_xml ⇒ Object 



496
497
498
 
# File 'lib/nexpose/site.rb', line 496

def to_xml
  as_xml.to_s
end