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.



193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/nexpose/site.rb', line 193

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 = []
end

Instance Attribute Details

#alerts ⇒ Object

Array

Collection of real-time alerts.

See Also:



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

def alerts
  @alerts
end

#assets ⇒ Object

Array

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

See Also:



154
155
156
 
# File 'lib/nexpose/site.rb', line 154

def assets
  @assets
end

#config_version ⇒ Object

Configuration version. Default: 3



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

def config_version
  @config_version
end

#credentials ⇒ Object

Array

Collection of credentials associated with this site.



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

def credentials
  @credentials
end

#description ⇒ Object

Description of the site.



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

def description
  @description
end

#engine ⇒ Object

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



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

def engine
  @engine
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.



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

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.



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

def is_dynamic
  @is_dynamic
end

#name ⇒ Object

Unique name of the site. Required.



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

def name
  @name
end

#risk_factor ⇒ Object

The risk factor associated with this site. Default: 1.0



170
171
172
 
# File 'lib/nexpose/site.rb', line 170

def risk_factor
  @risk_factor
end

#scan_template ⇒ Object

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



157
158
159
 
# File 'lib/nexpose/site.rb', line 157

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.



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

def scan_template_name
  @scan_template_name
end

#schedules ⇒ Object

Array

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



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

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.



227
228
229
230
231
232
 
# File 'lib/nexpose/site.rb', line 227

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 scan will be launched.

  • id (Fixnum) —

    Site ID of an existing site.

Returns:

  • (Site) —

    Site configuration loaded from a Nexpose console.



217
218
219
220
 
# File 'lib/nexpose/site.rb', line 217

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?



315
316
317
318
319
320
321
322
323
324
325
326
327
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
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'lib/nexpose/site.rb', line 315

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('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('Credentials') do |cred|
      # TODO
    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.addRecipient(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('vulnFilter') 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

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



250
251
252
253
 
# File 'lib/nexpose/site.rb', line 250

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) 


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

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.



238
239
240
241
242
243
244
 
# File 'lib/nexpose/site.rb', line 238

def save(connection)
  r = connection.execute('<SiteSaveRequest session-id="' + connection.session_id + '">' + to_xml + ' </SiteSaveRequest>')
  if (r.success)
    @id = r.attributes['site-id']
    return @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 syncronization token.

Returns:

  • (Fixnum, Fixnum) —

    Scan ID and engine ID where the scan was launched.



260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/nexpose/site.rb', line 260

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
    response.res.elements.each('/SiteScanResponse/Scan/') do |scan|
      return [scan.attributes['scan-id'].to_i, scan.attributes['engine-id'].to_i]
    end
  end
end

#to_xml ⇒ String

Generate an XML representation of this site configuration

Returns:

  • (String) —

    XML valid for submission as part of other requests.



276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/nexpose/site.rb', line 276

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>'

  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