Nexpose Ticketing Engine.

This is the official gem package for the Ruby Nexpose Ticketing engine.

To share your scripts, or to discuss different approaches, please visit the Rapid7 forums for Nexpose: community.rapid7.com/community/nexpose

For assistance with using the gem please email the Rapid7 integrations support team at support@rapid7.com.

About

The Nexpose Ticketing integration allows customers to create incident tickets based upon vulnerabilities found across their systems. The integration runs a report for a chosen site or tag group in Nexpose and then creates tickets based on the report, either for each machine or vulnerability, as specified by the ticketing mode selected. On subsequent scans, new tickets are created, existing tickets are updated (and potentially closed if resolved) based on any differences since the previous scan was performed.

The integration has three ticket generation modes: * Default mode: This mode will create one ticket per instance of a vulnerability i.e. a vulnerability present on three machines will have three tickets. This mode makes for smaller, more actionable incidents but has the potential to generate a large number of tickets. This mode can only create and close tickets. It does not update any information in existing tickets. * IP mode: This mode creates a single ticket containing all vulnerabilities for each asset. This reduces the total number of incidents but can greatly increase the size of work notes. On subsequent scans the ticket is updated to include new vulnerabilities and will mark fixed issues as 'old'. * Vulnerability mode: This mode will create a ticket for each vulnerability, listing every scanned asset affected by this vulnerability. This reduces the total number of incidents but can greatly increase the size of work notes. On subsequent scans the ticket is updated to include any new information about the vulnerability and new assets with this vulnerability. Vulnerability mode is not compatable with tag runs.

Ruby Version: >= 2.1.5

Supported Ticketing systems: JIRA; Remedy ITSM; ServiceNow; ServiceDesk

For more information, as well as service specific information, please refer to the integration documentation which can be requested from the Rapid7 support team.

Installation

Ticketing service integrations with Nexpose require the nexpose_ticketing Ruby gem that facilitates communication between Nexpose and the various ticketing services. Before installing the gem, ensure a Ruby interpreter is installed on the system running the gem, as well as RubyGems.

To install the gem, run the command:

$ gem install nexpose_ticketing

Usage

Documentation for setting up each integration can be requested from support@rapid7.com

To use the JIRA implementation please follow these steps: * Edit the jira.config file under the gem config folder and add the necessary data. * Edit the ticket_service.config under the gem config folder and add the necessary data. * Run the nexpose_ticketing file under the bin folder. If installed with gem the command console> nexpose_ticketing jira should suffice. Replace 'jira' with your chosen helper for other implementations

Note: Gem is usually installed under * Windows: C:Ruby<version>librubygemsversiongems * Linux: * Using RVM - /home/<user>/.rvm/gems/<version>/gems/ * Or using a general install - /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 <install_location>/lib/nexpose_ticketing/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:

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 Ticketing 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_ticketing servicename -e

or

nexpose_ticketing servicename --encrypt_config

Contributions

To develop your own implementation for Ticketing service 'foo':

  1. Create a helper class that implements the following methods:

  2. Initialize: This is the constructor that will take the implementation options and the service options. It should inherit from the base_helper class.

  3. create_ticket(tickets) - This method should implement the transport class for the 'foo' service (https, smtp, SOAP, etc).

  4. prepare_create_tickets(vulnerability_list, nexpose_identifier_id) - This method will take the vulnerability_list in CSV format and transform it into 'foo' accepted data (JSON, XML, etc). The implemented helpers group data into a single ticket according to the current ticketing mode: Per IP in IP mode and per vulnerability in Vulnerability mode.

  5. For full functionality (updating and closing tickets), also implement the following methods:

  6. update_tickets(tickets) - This method should implement the transport class for the 'foo' service (https, smtp, SOAP, etc), to send updated ticket descriptions to the service for specific existing tickets.

  7. prepare_update_tickets(vulnerability_list, nexpose_identifier_id) - This method will take the vulnerability_list in CSV format and transform it into 'foo' accepted data (JSON, XML, etc) for updating exisiting tickets.

  8. close_tickets(tickets) - This method should implement the transport class for the 'foo' service (https, smtp, SOAP, etc), to send closure messages to the service for a specific exisiting ticket.

  9. prepare_close_tickets(vulnerability_list, nexpose_identifier_id) - This method will take the vulnerability_list in CSV format and transform it into 'foo' accepted data (JSON, XML, etc) containing information about the tickets to close.

  10. A configuration file will be needed in the config folder for service specific options. This is loaded at the start of operation. Please refer to the existing configuration files, as certain options are common to all services.

Please see jira_helper.rb under helpers for an helper example, and two_vulns_report.csv under the test folder for a sample CSV report. For more information about developing a new helper, including implementing the different ticketing modes, please see the 'Developer Guide for Nexpose Ticketing' document.

We welcome contributions to this package. We ask only that pull requests and patches adhere to our coding standards.

Changelog

1.5.2

26-05-17
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.

1.5.1

16-05-17 Minor update to change storage location of log files.

1.5.0

16-05-17
Added an encryption configuration file. Usernames and passwords within the configuration files are now encrypted when the application runs.

1.4.2

10-05-17

Fixed issue where an initial integration run would fail if a site had been scanned more than once, but its' latest scan was a Discovery Scan.

Updated the ticket_service documentation to include information about a fix for the “Unable to find hostname” issue, seen with the ServiceNow helper.

1.4.1

11-04-17

Resolved issue with creating Initial tickets using the ServiceNow helper

1.4.0

11-04-17

General Ticket Generation

The Nexpose Ticketing gem has moved away from generating most of its data for current vulnerabilities via the Nexpose reporting engine and ad-hoc reports. - It now uses the Nexpose-Client gem to retrieve current information on vulnerabilities affecting assets on a per site or per tag basis.
- For calculating new, same or old vulnerability information, a basic report of the previous scan is still generated for comparison.
- Overall, the speed of the Ticketing gem has been improved for larger data sets.

Ticket Service
Ticket Repository
ServiceNow Helper
GemSpec

1.3.0

25-01-17

JIRA Helper

Improved error logging. The helper now logs meaningful data returned for each error from JIRA.

Historical Tracking

Previously, the last_scan_data file was not updated until the integration was complete. If the integration failed mid-operation, it would attempt to create tickets for all sites, even if this was previously done before the failure. Each sites' data is now updated after tickets are generated.

Bug Fixes

General bug fixes for most classes. Notable listed below

Ticket Service
Ticket Repository
JIRA Helper
ServiceNow Helper
Ticketing Modes
Queries

1.2.0

Configuration Options

Ticketing mode must be specified using the entire title, rather than a single character. e.g. 'Vulnerability' instead of 'V' Added the following configuration option: - log_console - NXLogger also gets printed to the console.

Extensibility

Code for the ticket_service, ticket_repository and helpers has been refactored to make it easier for the end-user to modify. Classes listed below now provide common functionality across different implementations.

Ticketing Modes
Ticketing Helpers

1.1.0

10-02-2016

Configuration

Added the following configuration options: - max_ticket_length - Specifies a maximum length for the description field of a ticket. - max_title_length - Specifies a maximum length for the title of a ticket. - max_num_refs - Specifies the maximum number of references included in a vulnerability description.

1.0.2

08-02-2016

Encoding is now enforced as UTF-8 when parsing CSV files - fixes environment-specific errors.

Jira Helper:
NX Logger:
ServiceNow:

1.0.1

19-01-2016

ServiceNow Helper:
NX Logger:
Ticket Service:
Report Helper:

1.0.0

10-12-2015

Queries:
Remedy Helper:
ServiceNow Helper:
ServiceDesk Helper:
JiraHelper:
CommonHelper: