Last updated at Wed, 23 Aug 2017 20:29:45 GMT

The nexpose gem, a Ruby library for accessing the Nexpose API (and more), has been updated to version 0.5. This version includes a number of small breaking changes from the previous version of the gem (0.2.8), hence the jump in version.

Nearly all of the 1.1 and 1.2 versions of the Nexpose API are implemented by the gem. (The missing calls center around multi-tenancy and vAsset discovery, licensed features.)

New Features

This version of the gem allows for some new methods previously unavailable through the API.

Search for Vuln Checks

You can now search for vulnerability checks matching the provided term. It will return an array of matching results. This will also provide the Nexpose vulnerability check ID which is needed for some other calls. In the example below, we pull details for a single PHP vulnerability.

matching_checks = nsc.find_vuln_check('CVE-2013-4635')

Get Vulns by Asset

You can retrieve the vulnerability findings specific to the given asset (device) ID. It will return an array of VulnFinding objects, which includes information such as the vulnerability title, CVSS score, published date, risk, etc.

vulns = nsc.list_device_vulns(838)

Asset Filter Search

You can perform asset filter searches through the gem now. There are a number of constants defined to help in constructing your search, like the Field and Operator constants in the example below. This example returns an array of assets which have ".net" software. The asset information includes the unique ID, IP address, last scan date, vulnerability count, and more.

matching_assets = nsc.filter(Search::Field::SOFTWARE,  
                                 Search::Operator::CONTAINS,  
                                 '.net')

Dynamic Asset Groups

Asset filtering provides the basis for Dynamic Asset Groups, so if you have defined search criteria, you can use it to define an Asset Group. The existing group method, list_asset_groups (or simply groups), can be used to list all asset groups, static and dynamic. And the AssetGroup.load method should be used to get a list of all current assets which are part of the group. The new DynamicAssetGroup class only handles group configuration at this time.

    linux = Criterion.new('OS', 'CONTAINS', 'linux')  
    ssh = Criterion.new('SOFTWARE', 'CONTAINS', 'ssh')  
    criteria = Criteria.new([linux, ssh], 'AND')  
    dag = DynamicAssetGroup.new('linux ssh', criteria, 'Linux assets with SSH enabled.')  
    dag.save(nsc)

Delete Report Templates

You can remove custom report templates through the gem now. You only need to provide the report template ID (call nsc.report_templates for the full list).

    nsc.delete_report_template('custom-audit-report')

Scan Templates

List the scan templates currently configured on the console. Delete scan templates through the second call.

    nsc.scan_templates  
    nsc.delete_scan_template('custom-full-audit')

Syntax Changes

The syntax changes focus on having a unified design across the gem. This should make the gem easier to use for newcomers, and should make it easy to guess what a method should look like. There were inconsistencies in older versions of the gem, where some methods would use "get" and others "load" for what was conceptually the same thing. Method names could be delete_xyz or xyz_delete. Some methods took object as arguments, where others took maps.

Conversion to the latest version should be simple, but if you have any problems, feel free to ping here or at the github repository. If you do not update to the latest version, you will continue to use whichever version you last downloaded. To continue to use an older version explicitly, add the following to your scripts:

    gem 'nexpose', '0.2.8'  
    require 'nexpose'