Scanning with the Gem

Here's a walk-through of how to scan, as of version 3.2.0 of the gem.

In order to keep verbosity to a minimum, all of the examples assume that the Nexpose module has been included:

include Nexpose

As with all uses of the gem, in order to interact with a Nexpose console you will need an active, valid connection. The following line can be assumed for all code below:

nsc = Connection.new('10.2.0.1', 'nxadmin', 'secret-password')
nsc.login

Scanning a Site

Nexpose scanning if focused around sites, so the simplest way to scan is to simply launch a site scan. If you have loaded the Site object, it has a scan method.

site = Site.load(nsc, 142)
scan = site.scan(nsc)

Site scans can be launched without loading the Site object, by accessing the Connection directly.

scan = nsc.scan_site(142)

This returns a Scan object, which has id and engine attributes. The ID can then be used to poll the current status of the scan. The engine ID can be useful when you are using a scan engine pool.

Running an ad hoc Scan

Ad hoc scans are commonly used to run a scan against a limited subset of assets on a site. There are a number of ways to view existing assets and targets for a site, and there are matching methods for the different approaches. Note that these call do need site ID information (the Device class contains the information already).

Scanning Devices

Several calls in the gem return an Array of Devices. These can then be turned around and passed back to a scan method. Here we get all the devices for site 142, re-scan the highest risk assets on that site.

devices = nsc.devices(142)
high_risk = devices.select { |d| d.risk_score > 100000 }
scan = nsc.scan_devices(high_risk)

Scanning by IP Address

Sometimes you may pull in a list of IP addresses from somewhere else. Perhaps another department comes back with a list of IPs that they have remediated based upon your report. They need to you rescan just those IP addresses to confirm that their fixes are good.

remediated = ['192.168.2.1', '192.168.2.107']
scan = nsc.scan_ips(142, remediated)

Scanning Defined Assets

You can also scan based upon the assets defined in the Site configuration. Here we just arbitrarily rescan the first five defined assets from an existing site.

site = Site.load(nsc, 142)
scan = nsc.scan_assets(142, site.included_addresses.take(5))

Running a Scan against an Asset Group

Another common use case is to scan assets based upon membership in an asset group. Asset groups can cross sites, so this isn't currently a simple process in the UI. The gem allows us to collate the information about group devices and launch multiple scans. Essentially, an ad hoc scan is launched against each site for just the devices in a group. This works against both static and dynamic asset groups.

group = AssetGroup.load(nsc, 97)
scans = group.rescan_assets(nsc)

Polling Scan Status

For many scripts, you may wish to track the current status of a scan, particularly if you are waiting to take another action when the scan completes. This example uses the Scan object returned from the launch scan call above. It will loop over the scan status until it is no longer running (which may not be what you want for long running scans).

begin
  sleep(30)
  status = nsc.scan_status(scan.id)
end while status != Scan::Status::FINISHED

Scheduling Scans

Sites can have schedules configured to run periodically. The most important thing to note is that timestamps through the gem are in UTC, so you'll want to keep that in mind when scheduling. This example creates a schedule which recurs monthly on the given date.

⚠️ This example is outdated!

site = Site.load(nsc, 142)
site.schedules.clear  # Remove existing schedule, if any.
schedule = Schedule.new(Schedule::Type::MONTHLY_DATE, 1, '20131001T000000000')
schedule.max_duration = 480  # in minutes, so 8 hours.
schedule.repeater_type = 'continue'
site.schedules << schedule
site.save(nsc)