Class: Nexpose::Role

Inherits:
RoleSummary show all
Includes:
Sanitize
Defined in:
lib/nexpose/role.rb

Constant Summary collapse

GLOBAL_ADMINISTRATOR =

Constants, mapping UI terms to role names expected by API.

'global-admin'
ASSET_OWNER =
'system-admin'
CONTROLS_INSIGHT_ONLY =
'controls-insight-only'
SECURITY_MANAGER =
'security-manager'
SITE_OWNER =
'site-admin'
USER =
'user'

Instance Attribute Summary collapse

Attributes inherited from RoleSummary

#description, #enabled, #full_name, #id, #name, #scope

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Sanitize

#replace_entities

Constructor Details

#initialize(name, full_name, id = -1,, enabled = true, scope = Scope::SILO) ⇒ Role

Returns a new instance of Role.



141
142
143
144
145
146
147
148
# File 'lib/nexpose/role.rb', line 141

def initialize(name, full_name, id = -1, enabled = true, scope = Scope::SILO)
  @name       = name
  @full_name  = full_name
  @id         = id.to_i
  @enabled    = enabled
  @scope      = scope
  @privileges = []
end

Instance Attribute Details

#existingObject

Flag to track whether this role exists already on the Nexpose console. Flag determines behavior of #save method.



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

def existing
  @existing
end

#privilegesObject

Array of all privileges which are enabled for this role. Note: Although the underlying XML has different requirements, this only checks for presence.

See Also:



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

def privileges
  @privileges
end

Class Method Details

.copy(nsc, name, scope = Scope::SILO) ⇒ Role

Copy an existing Role to build a new role off of it. Role will not have a valid name or full_name, so they will need to be provided before saving.

Parameters:

  • nsc (Connection)

    Nexpose connection.

  • name (String)

    The short name of the role which you wish to copy.

  • scope (String) (defaults to: Scope::SILO)

    Whether the role has global or silo scope. @see Nexpose::Scope

Returns:

  • (Role)

    requested role.



198
199
200
201
202
203
204
# File 'lib/nexpose/role.rb', line 198

def self.copy(nsc, name, scope = Scope::SILO)
  role          = load(nsc, name, scope)
  role.name     = role.full_name = nil
  role.id       = -1
  role.existing = false
  role
end

.load(nsc, name, scope = Scope::SILO) ⇒ Role

Retrieve a detailed description of a single role.

Parameters:

  • nsc (Connection)

    Nexpose connection.

  • name (String)

    The short name of the role.

  • scope (String) (defaults to: Scope::SILO)

    Whether the role has global or silo scope. @see Nexpose::Scope Scope doesn’t appear to be required when requesting installed roles.

Returns:

  • (Role)

    requested role.



158
159
160
161
162
163
164
165
166
167
# File 'lib/nexpose/role.rb', line 158

def self.load(nsc, name, scope = Scope::SILO)
  xml = nsc.make_xml('RoleDetailsRequest')
  xml.add_element('Role', { 'name' => name, 'scope' => scope })
  response = APIRequest.execute(nsc.url, xml, '1.2', { timeout: nsc.timeout, open_timeout: nsc.open_timeout })

  if response.success
    elem = REXML::XPath.first(response.res, 'RoleDetailsResponse/Role/')
    parse(elem)
  end
end

.parse(xml) ⇒ Object



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
# File 'lib/nexpose/role.rb', line 214

def self.parse(xml)
  role = new(xml.attributes['name'],
             xml.attributes['full-name'],
             xml.attributes['id'].to_i,
             xml.attributes['enabled'] == 'true',
             xml.attributes['scope'])

  role.description = REXML::XPath.first(xml, 'Description').text
  role.existing = true

  # Only grab enabled privileges.
  xml.elements.each("GlobalPrivileges/child::*[@enabled='true']") do |privilege|
    role.privileges << privilege.name
  end
  xml.elements.each("SitePrivileges/child::*[@enabled='true']") do |privilege|
    role.privileges << privilege.name
  end
  xml.elements.each("AssetGroupPrivileges/child::*[@enabled='true']") do |privilege|
    role.privileges << privilege.name
  end
  role
end

Instance Method Details

#as_xmlObject



241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
# File 'lib/nexpose/role.rb', line 241

def as_xml
  xml = REXML::Element.new('Role')
  xml.add_attributes({ 'name' => @name, 'full-name' => @full_name, 'enabled' => enabled, 'scope' => @scope })
  xml.add_attribute('id', @id) if @id > 0
  xml.add_element('Description').text = @description

  site_privileges = xml.add_element('SitePrivileges')
  Privilege::Site.constants.each do |field|
    as_s = Privilege::Site.const_get(field)
    enabled = privileges.member? as_s
    site_privileges.add_element(as_s, { 'enabled' => enabled })
  end

  asset_group_privileges = xml.add_element('AssetGroupPrivileges')
  Privilege::AssetGroup.constants.each do |field|
    as_s = Privilege::AssetGroup.const_get(field)
    enabled = privileges.member? as_s
    asset_group_privileges.add_element(as_s, { 'enabled' => enabled })
  end

  global_privileges = xml.add_element('GlobalPrivileges')
  Privilege::Global.constants.each do |field|
    as_s = Privilege::Global.const_get(field)
    enabled = privileges.member? as_s
    global_privileges.add_element(as_s, { 'enabled' => enabled })
  end

  xml
end

#delete(nsc) ⇒ Object

Remove this role from the Nexpose console.

Parameters:



210
211
212
# File 'lib/nexpose/role.rb', line 210

def delete(nsc)
  nsc.role_delete(name, scope)
end

#save(nsc) ⇒ Object

Create or save a Role to the Nexpose console.

Parameters:



175
176
177
178
179
180
181
182
183
184
185
186
187
188
# File 'lib/nexpose/role.rb', line 175

def save(nsc)
  if @existing
    xml = nsc.make_xml('RoleUpdateRequest')
  else
    xml = nsc.make_xml('RoleCreateRequest')
  end
  xml.add_element(as_xml)

  response  = APIRequest.execute(nsc.url, xml, '1.2', { timeout: nsc.timeout, open_timeout: nsc.open_timeout })
  xml       = REXML::XPath.first(response.res, 'RoleCreateResponse')
  @id       = xml.attributes['id'].to_i unless @existing
  @existing = true
  response.success
end

#to_xmlObject



237
238
239
# File 'lib/nexpose/role.rb', line 237

def to_xml
  as_xml.to_s
end