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') ⇒ 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.



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/nexpose/site.rb', line 131

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

Instance Attribute Details

#alerts ⇒ Object

Array

Collection of real-time alerts.

See Also:



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

def alerts
  @alerts
end

#assets ⇒ Object

Array

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

See Also:



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

def assets
  @assets
end

#config_version ⇒ Object

Configuration version. Default: 3



120
121
122
 
# File 'lib/nexpose/site.rb', line 120

def config_version
  @config_version
end

#credentials ⇒ Object

Array

Collection of credentials associated with this site. Does not

include shared credentials.



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

def credentials
  @credentials
end

#description ⇒ Object

Description of the site.



79
80
81
 
# File 'lib/nexpose/site.rb', line 79

def description
  @description
end

#engine ⇒ Object

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



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

def engine
  @engine
end

#exclude ⇒ Object

Array

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



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

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.



73
74
75
 
# File 'lib/nexpose/site.rb', line 73

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.



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

def is_dynamic
  @is_dynamic
end

#name ⇒ Object

Unique name of the site. Required.



76
77
78
 
# File 'lib/nexpose/site.rb', line 76

def name
  @name
end

#risk_factor ⇒ Object

The risk factor associated with this site. Default: 1.0



103
104
105
 
# File 'lib/nexpose/site.rb', line 103

def risk_factor
  @risk_factor
end

#scan_template ⇒ Object

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



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

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.



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

def scan_template_name
  @scan_template_name
end

#schedules ⇒ Object

Array

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



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

def schedules
  @schedules
end

#users ⇒ Object

Array

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



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

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.



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

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.



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

def self.load(connection, id)
  r = APIRequest.execute(connection.url,
                         %(<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?



314
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
 
# File 'lib/nexpose/site.rb', line 314

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('Users/user') do |user|
      site.users << user.attributes['id'].to_i
    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 << Credential.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

    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.



179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/nexpose/site.rb', line 179

def add_asset(asset)
  begin
    # If the asset registers as a valid IP, store as IP.
    ip = IPAddr.new(asset)
    add_ip(asset)
  rescue ArgumentError => e
    if e.message == 'invalid address'
      add_host(asset)
    else
      raise "Unable to parse asset: '#{asset}'. #{e.message}"
    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.



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

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.



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

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.



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

def add_ip_range(from, to)
  @assets << IPRange.new(from, to)
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.



235
236
237
238
 
# File 'lib/nexpose/site.rb', line 235

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) 


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

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.



225
226
227
228
 
# File 'lib/nexpose/site.rb', line 225

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



246
247
248
249
250
251
252
253
254
 
# File 'lib/nexpose/site.rb', line 246

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 ⇒ String

Generate an XML representation of this site configuration

Returns:

  • (String) —

    XML valid for submission as part of other requests.



262
263
264
265
266
267
268
269
270
271
272
273
274
275
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
 
# File 'lib/nexpose/site.rb', line 262

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

  unless @users.empty?
    xml << '<Users>'
    @users.each { |user| xml << "<user id='#{user}'/>" }
    xml << '</Users>'
  end

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

  unless exclude.empty?
    xml << '<ExcludedHosts>'
    xml << exclude.reduce('') { |a, e| a << e.to_xml }
    xml << '</ExcludedHosts>'
  end

  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 << %(<ScanConfig configID="#{@id}" name="#{@scan_template_name || @scan_template}" templateID="#{@scan_template}" configVersion="#{@config_version || 3}" engineID="#{@engine}">)

  xml << '<Schedules>'
  @schedules.each do |schedule|
    xml << schedule.to_xml
  end
  xml << '</Schedules>'
  xml << '</ScanConfig>'
  xml << '</Site>'
end