Class: Nexpose::Site

Inherits:
Object
  • Object
show all
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

Constructor Details

#initialize(name = nil, scan_template = 'full-audit') ⇒ 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') —

    ID of the scan template to use.



215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/nexpose/site.rb', line 215

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

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

Instance Attribute Details

#alerts ⇒ Object

Array

Collection of real-time alerts.

See Also:



201
202
203
 
# File 'lib/nexpose/site.rb', line 201

def alerts
  @alerts
end

#assets ⇒ Object

Array

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

See Also:



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

def assets
  @assets
end

#config_version ⇒ Object

Configuration version. Default: 3



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

def config_version
  @config_version
end

#credentials ⇒ Object

Array

Collection of credentials associated with this site.



195
196
197
 
# File 'lib/nexpose/site.rb', line 195

def credentials
  @credentials
end

#description ⇒ Object

Description of the site.



168
169
170
 
# File 'lib/nexpose/site.rb', line 168

def description
  @description
end

#engine ⇒ Object

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



186
187
188
 
# File 'lib/nexpose/site.rb', line 186

def engine
  @engine
end

#exclude ⇒ Object

Array

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



176
177
178
 
# File 'lib/nexpose/site.rb', line 176

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.



162
163
164
 
# File 'lib/nexpose/site.rb', line 162

def id
  @id
end

#is_dynamic ⇒ Object

Whether or not this site is dynamic. Dynamic sites are created through Asset Discovery Connections. Modifying their behavior through the API is not recommended.



209
210
211
 
# File 'lib/nexpose/site.rb', line 209

def is_dynamic
  @is_dynamic
end

#name ⇒ Object

Unique name of the site. Required.



165
166
167
 
# File 'lib/nexpose/site.rb', line 165

def name
  @name
end

#risk_factor ⇒ Object

The risk factor associated with this site. Default: 1.0



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

def risk_factor
  @risk_factor
end

#scan_template ⇒ Object

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



179
180
181
 
# File 'lib/nexpose/site.rb', line 179

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.



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

def scan_template_name
  @scan_template_name
end

#schedules ⇒ Object

Array

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



189
190
191
 
# File 'lib/nexpose/site.rb', line 189

def schedules
  @schedules
end

Class Method Details

.copy(connection, id) ⇒ Site

Copy an existing configuration from a Nexpose instance.

Parameters:

  • connection (Connection) —

    Connection to console where scan will be launched.

  • id (Fixnum) —

    Site ID of an existing site.

Returns:

  • (Site) —

    Site configuration loaded from a Nexpose console.



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

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

.load(connection, id) ⇒ 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.



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

def self.load(connection, id)
  r = APIRequest.execute(connection.url, %Q(<SiteConfigRequest session-id="#{connection.session_id}" site-id="#{id}"/>))
  parse(r.res)
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?



371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
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
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
 
# File 'lib/nexpose/site.rb', line 371

def self.parse(rexml)
  rexml.elements.each('SiteConfigResponse/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('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 |credconf|
      cred = AdminCredentials.new(true)
      cred.set_service(credconf.attributes['service'])
      cred.set_blob(credconf.get_text)
      site.credentials << 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 |sched|
        schedule = Schedule.new(sched.attributes['type'],
                                sched.attributes['interval'],
                                sched.attributes['start'],
                                sched.attributes['enabled'])
        site.schedules << schedule
      end
    end

    s.elements.each('Alerting/Alert') do |a|
      a.elements.each('smtpAlert') do |smtp|
        smtp_alert = SMTPAlert.new(a.attributes['name'], smtp.attributes['sender'], smtp.attributes['limitText'], a.attributes['enabled'])

        smtp.elements.each('recipient') do |recipient|
          smtp_alert.add_recipient(recipient.text)
        end
        site.alerts << smtp_alert
      end

      a.elements.each('snmpAlert') do |snmp|
        snmp_alert = SNMPAlert.new(a.attributes['name'], snmp.attributes['community'], snmp.attributes['server'], a.attributes['enabled'])
        site.alerts << snmp_alert
      end

      a.elements.each('syslogAlert') do |syslog|
        syslog_alert = SyslogAlert.new(a.attributes['name'], syslog.attributes['server'], a.attributes['enabled'])
        site.alerts << syslog_alert
      end

      #a.elements.each('vuln_filter') do |vulnFilter|
      #  vulnfilter = new VulnFilter.new(a.attributes["typemask"], a.attributes["severityThreshold"], $attrs["MAXALERTS"])
      #  Pop off the top alert on the stack
      #  $alert = @alerts.pop()
      #  Add the new recipient string to the Alert Object
      #  $alert.setVulnFilter($vulnfilter)
      #  Push the alert back on to the alert stack
      #  array_push($this->alerts, $alert)
      #end

      #a.elements.each('scanFilter') do |scanFilter|
      #  <scanFilter scanStop='0' scanFailed='0' scanStart='1'/>
      #  scanfilter = ScanFilter.new(scanFilter.attributes['scanStop'],scanFilter.attributes['scanFailed'],scanFilter.attributes['scanStart'])
      #  alert = @alerts.pop()
      #  alert.setScanFilter(scanfilter)
      #  @alerts.push(alert)
      #end
    end

    return site
  end
  nil
end

Instance Method Details

#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.



254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/nexpose/site.rb', line 254

def add_asset(asset)
  begin
    add_ip(asset)
  rescue ArgumentError => e
    if e.message == 'invalid address'
      add_host(asset)
    else
      raise "Unable to parse asset: '#{asset}'"
    end
  end
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.



238
239
240
 
# File 'lib/nexpose/site.rb', line 238

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.



245
246
247
 
# File 'lib/nexpose/site.rb', line 245

def add_ip(ip)
  @assets << IPRange.new(ip)
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.



303
304
305
306
 
# File 'lib/nexpose/site.rb', line 303

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

#dynamic? ⇒ Boolean

Returns true when the site is dynamic.

Returns:

  • (Boolean) 


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

def dynamic?
  is_dynamic
end

#save(connection) ⇒ Fixnum

Saves this site to a Nexpose console.

Parameters:

  • connection (Connection) —

    Connection to console where this site will be saved.

Returns:

  • (Fixnum) —

    Site ID assigned to this configuration, if successful.



292
293
294
295
296
297
 
# File 'lib/nexpose/site.rb', line 292

def save(connection)
  r = connection.execute('<SiteSaveRequest session-id="' + connection.session_id + '">' + to_xml + ' </SiteSaveRequest>')
  if r.success
    @id = r.attributes['site-id']
  end
end

#scan(connection, sync_id = nil) ⇒ Fixnum

Scan this site.

Parameters:

  • connection (Connection) —

    Connection to console where scan will be launched.

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

    Optional synchronization token.

Returns:

  • (Fixnum, Fixnum) —

    Scan ID and engine ID where the scan was launched.



313
314
315
316
317
318
319
320
321
322
323
324
 
# File 'lib/nexpose/site.rb', line 313

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)
  if response.success
    scan = REXML::XPath.first(response.res, '/SiteScanResponse/Scan/')
    [scan.attributes['scan-id'].to_i, scan.attributes['engine-id'].to_i]
  end
end

#to_xml ⇒ String

Generate an XML representation of this site configuration

Returns:

  • (String) —

    XML valid for submission as part of other requests.



328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/nexpose/site.rb', line 328

def to_xml
  xml = %Q(<Site id='#{id}' name='#{name}' description='#{description}' riskfactor='#{risk_factor}'>)

  xml << '<Hosts>'
  xml << assets.reduce('') { |acc, host| acc << host.to_xml }
  xml << '</Hosts>'

  xml << '<ExcludedHosts>'
  xml << exclude.reduce('') { |acc, host| acc << host.to_xml }
  xml << '</ExcludedHosts>'

  unless credentials.empty?
    xml << '<Credentials>'
    credentials.each do |c|
      xml << c.to_xml if c.respond_to? :to_xml
    end
    xml << '</Credentials>'
  end

  unless alerts.empty?
    xml << '<Alerting>'
    alerts.each do |a|
      xml << a.to_xml if a.respond_to? :to_xml
    end
    xml << '</Alerting>'
  end

  xml << %Q(<ScanConfig configID="#{@id}" name="#{@scan_template_name || @scan_template}" templateID="#{@scan_template}" configVersion="#{@config_version || 3}" engineID="#{@engine}">)

  xml << '<Schedules>'
  @schedules.each do |sched|
    xml << %Q{<Schedule enabled="#{sched.enabled ? 1 : 0}" type="#{sched.type}" interval="#{sched.interval}" start="#{sched.start}" />}
  end
  xml << '</Schedules>'
  xml << '</ScanConfig>'
  xml << '</Site>'
end