PxnxJruby

This is the official gem package for the Nexpose Cisco PxGrid Integration.

For assistance with using the gem please email the Rapid7 support team at [email protected].

Installation

Please follow the Cisco ISE documentation for instructions on installing Cisco ISE, enabling PxGrid and setting up certificates on the pxGrid client and target node(s).

The script was created using JRuby: as such, a JRuby interpreter must be installed on the system where it’s going to run. The following link shows the different options for installing Ruby in several platforms:

http://jruby.org/

Add this line to your application's Gemfile:

gem 'nexpose_pxgrid'

And then execute:

$ bundle

Or install it yourself as:

$ gem install nexpose_pxgrid

From Cisco Docs

If the client is connecting to the pxGrid Controller for the first time, an account is established on the pxGrid Controller. In pxGrid’s auto-registration mode (set by administrator through the ISE web-based user interface), the client is allowed to communicate once the account is created. Whereas if auto registration mode is turned off, the node and authorization group assignment of the node remains in Pending Approval mode and not allowed to communicate over pxGrid until it is approved by the administrator. Also, the user must be part of the EPS group.

Usage

To use the PxGrid integration after installing the gem and configuring the Cisco ISE:

  • Set up the KeyStore and TrustStore using certificates from the machine running the integration as well as the Cisco ISE installation.
    Please request documentation for this integration from support if you require more information on how set up the certificate stores, or see the Cisco PxGrid documentation.
  • Edit the pxnx.config file under the gem config folder and add the necessary data.
  • Set up the necessary Environment variables, containing information on the ISE instance, as listed in the documentation.
  • Run the nexpose_pxgrid file from within the bin folder.
    If the gem was installed via RubyGems, calling the command jruby nexpose_pxgrid should suffice.

Note: The gem is usually installed under

  • Windows: C:\Ruby<version>\lib\ruby\gems\version\gems
  • Linux: /var/lib/gems/<version>/gems/
    Please refer to your particular Ruby documentation for actual installation folder.

A logger is also implemented by default, and the log can be found under /var/lib/logs/; please refer to the log file in case of an error.

Encryption Settings

The usernames and passwords within the configuration files are automatically encrypted when the integration runs. The key and IV files used during encryption/decryption are saved within the config folder by default.

Setting Custom Locations for Encryption Files

To set custom locations for the key and IV files, update the following values within the encryption.config file:

  • key_filename - The absolute path to where the key file will be created.
  • iv_file - The absolute path to where the IV file will be created.

To set a custom path after the integration has already executed, the files must be moved to the new location manually.

Encrypting the Configuration without running the Integration

The Nexpose PxGrid integration can encrypt its configuration file without running the gem. This allows users to secure their login information for future use e.g for use in a cron-schedule.

The command to do so is: 

nexpose_pxgrid -e

or 

nexpose_pxgrid --encrypt_config

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake false to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/pxnx_jruby.

License

The gem is available as open source under the terms of the MIT License.

Changelog

0.1.6

Implemented encryption for the configuration file, removing the storage of clear text passwords. Usernames and passwords within the configuration files are now encrypted when the application runs.

Command line options have been added to the gem. Several are common to all Nexpose gem integrations. Call the gem with '-h' or '--help' to view these options.

0.1.5

Added option to allow the port of the Nexpose Console to be chosen. Fixed an issue where devices were not correctly being quarantined.

0.1.4

Added option to allow the scan type to be chosen when assessing assets joining the network. (Zac Youtz)