Scripting Scenario: Custom role and bulk report access

Document created by S Tempest Employee on Apr 4, 2014Last modified by S Tempest Employee on Apr 4, 2014
Version 3Show Document
  • View in full screen mode

(TL;DR: Susie, Bob's crafty sister, is already done. Click here to see the finished script.)


Spurred on by his last great success with adhoc scanning, Bob takes on a new challenge. Bob's brother, Steve, has started a new job at the same company. Bob doesn't know what "nepotism" means. Anyway... Steve has been assigned to print all of the reports for the Honolulu Headquarters for the executive staff. First things first, Bob needs to create an account for Steve. Based on his previous experience with Steve, Bob wants to make sure that he gives Steve a role that *only* allows him to view reports.


As we've learned, Bob prefers to create tools to do his work for him. As with any API script this begins with loading the Nexpose Gem into the script:


require 'nexpose'



And then logging into Nexpose with the following information:


  •     A user ID = Bob
  •      Password = IamSuperCool
  •      The Nexpose hostname or IP address = localhost



@host = 'localhost'
@userid = 'bob'
@password = 'IamSuperCool'

nsc =, @userid, @password)
puts 'Logging into Nexpose'
puts 'Logged into Nexpose'



Once logged in, Bob proceeds to create a new user account for Steve with the following information:


  •      User name = steve
  •      Full name = Steve
  •      Password = BobsBro


@new_user_name = 'steve'
@new_user_fullname = 'Steve'
@new_user_password = 'BobsBro'

puts "Creating a new Nexpose user for #{@new_user_fullname}"
user =, @new_user_fullname, @new_user_password)
puts 'Successfully created new user'



Bob goes into Nexpose to validate Steve's access and realizes the default user role is not what he wants Steve to have. Bob decides to create a custom role with only the permissions Steve needs. Bob knows that if he wants to add more users in the future with just this permission he would have to create a custom role from scratch every single time.


To save effort, Bob creates a new re-usable custom role utilizing functionality only available in the Nexpose API. To do this, Bob needs the following information:


  •      Role name = report-viewer
  •      Role full name = Report Viewer
  •      Role id = -1 (a negative value instructs Nexpose to generate a new id)
  •      Role privileges:
    •          Ticket and report assignee
    •          View site asset data


@role_name = 'report-viewer'
@role_full_name = 'Report Viewer'
puts "Creating a new custom role: #{@role_full_name}"
role =, @role_full_name, -1)
role.privileges << Nexpose::Privilege::Global::TICKET_ASSIGNEE
role.privileges << Nexpose::Privilege::Site::VIEW_ASSET_DATA
puts 'Successfully created new custom role'



Now that Bob has created the custom role, he needs to change Steve's existing account to use the new custom role. Once again Bob has lucked out because the script still has the user object referenced for Steve's account.


puts "Changing role for #{@new_user_fullname} to #{@role_full_name}"
user.role_name = @role_name
puts 'Successfully changed role'



Now that Bob is as happy as he could be with Steve's access, it's time to grant Steve access to the Honolulu Headquarters reports. The first thing he has to do is find the site ID for the Honolulu Headquarters. To do this, Bob will need the following information:


  •      Site name = Honolulu Headquarters


@site_id_access = nil
@site_name = 'Honolulu Headquarters'

puts "Searching for #{@site_name}'s id"
site_listing = nsc.list_sites
site_listing.each do |site|
  if == @site_name
    puts "Found #{@site_name}'s id: #{}"
    @site_id_access =



Since his code successfully returned the site ID, Bob then uses that to search all reports that contain that site's assets. Once the script finds all of the relevant reports, it can grant Steve access in bulk.


puts 'Retrieving listing of reports'
report_listing = nsc.list_reports

report_listing.each do |report_summary|
  report_config = Nexpose::ReportConfig.load(nsc, report_summary.config_id)
  report_config.filters.each do |p|
    if p.type == 'site'
      if == @site_id_access
        puts "Adding #{@new_user_fullname} to the access list for #{}"
        report_config.users <<
        puts 'Successfully updated report user access list'



Because Bob is a fastidious man, once again he logs out of Nexpose and exits the script when it completes.


puts 'Logging out'



Since Steve screwed him over last time, Bob shares his proud achievement with his sister Susie, who surprisingly follows in Steve's footsteps by stealing Bob's code and posting it on Security Street, taking all of the credit.



Thanks to Gavin Schneider and ospannero