ServiceNow CMDB Data Synchronization

Overview

The Rapid7 InsightVM Integration for CMDB is a ServiceNow Platform application that provides end-to-end configuration management integration with capabilities to automate:

  • InsightVM Asset Tagging
    • Tag InsightVM assets based on ServiceNow CMDB CI data
  • ServiceNow Asset Import
    • Creation and updating of ServiceNow CMDB CI data based on InsightVM asset data including asset vulnerability and risk related metrics
  • InsightVM Site Configuration
    • Manage InsightVM site scopes based on ServiceNow CMDB CI data

Get Started

Installation

The application can be installed by a ServiceNow instance administrator from the ServiceNow Store:

https://store.servicenow.com/sn_appstore_store.do#!/store/application/a0bc721d1b13b3006a4a85507e4bcb87/

Initial Setup

Install the Configuration Management for Scoped Apps CMDB (com.snc.cmdb.scoped) plugin

The ServiceNow Asset Import functionality of the application utilizes the Configuration Management for Scoped Apps CMDB (com.snc.cmdb.scoped) plugin. Follow the below steps to install it within a ServiceNow instance:

  1. As a ServiceNow instance administrator, go to the System Definition -> Plugins module:
  1. From this module, search for the Configuration Management For Scoped Apps CMDB (com.snc.cmdb.scoped) plugin, click Install.
  1. Click Activate.

Create an ‘InsightVM’ Discovery Source

The application requires a custom discovery source to be created for easy identification of assets that are imported/updated by the integration.

  1. As a ServiceNow instance administrator, go to the System Definition -> Scripts - Background module.
  1. Ensure that the Scope in the module is set to Global.
  2. Run the following script snippet to create the ‘InsightVM’ discovery source:
text
1
var discoverySource = 'InsightVM';
2
var gr = new GlideRecord('sys_choice');
3
gr.addQuery('element', 'discovery_source');
4
gr.addQuery('name', 'cmdb_ci');
5
gr.addQuery('value', discoverySource);
6
gr.query();
7
if (!gr.hasNext()) {
8
var grNew = new GlideRecord('sys_choice');
9
grNew.initialize();
10
grNew.setValue('element', 'discovery_source');
11
grNew.setValue('name', 'cmdb_ci');
12
grNew.setValue('value', discoverySource);
13
grNew.setValue('label', discoverySource);
14
if (!grNew.insert()) {
15
gs.info('Adding discovery source failed for: ' + discoverySource);
16
}
17
}

Create an InsightVM Connection

To establish connectivity to your InsightVM Security Console(s), the application uses an InsightVM Connection configuration. To configure one, follow the below steps:

  1. Begin by creating an InsightVM user account for the application
    • The user needs access to All Sites and All Asset Groups, along with the following permissions: Manage Sites, Manage Tags, View Group Asset Data, Create Reports.

TIP

For additional information on creating users, review the following documentation section:

https://insightvm.help.rapid7.com/docs/managing-users-and-authentication#configure-general-user-account-attributes

  1. With the user created, navigate to the Rapid7 InsightVM Integration for CMDB -> InsightVM Connections module.
  1. Click New to create a new InsightVM Connection configuration.
  2. Enter a user friendly name for the connection.
  3. Complete the remainder of the form and click Submit.

ServiceNow MID Server configuration required

If you do not have a ServiceNow MID Server configured, search for the MID Server Installation module for instructions on installation and configuration of a ServiceNow MID Server. The MID server should be installed with network accessibility to the web interface of the InsightVM Security Console host.

To ensure reliable operation of the integration, the MID server should be located in the same network region as the InsightVM Security Console. For example if the InsightVM Security Console is in the US, the MID server should also be located in the US.

An example InsightVM Connection configuration is shown below:

Required Roles

In order to use the application, you will need to be a ServiceNow admin, or have one of the roles provided by the application assigned to your user:

  • x_r7_rapid7_cmdb_i.integration_admin
    • Access to all application modules
  • x_r7_rapid7_cmdb_i.asset_tagging_user
    • Access to all InsightVM Asset Tagging integration modules
  • x_r7_rapid7_cmdb_i.asset_import_user
    • Access to all ServiceNow Asset Import integration modules
  • x_r7_rapid7_cmdb_i.site_configuration_user
    • Access to all InsightVM Site Configuration integration modules

Configuration

Each integration available in the application has three modules provided:

  1. Jobs
    • Individual integration configurations with scheduling options to specify how frequently the configuration is run.
  2. Maps
    • Individual configuration for the job. Each integration job can contain a list of maps. Details for each map type are provided in the configuration documentation for the corresponding integration.
  3. Run Statistics
    • High level statistics provided from each job execution for an integration.

InsightVM Asset Tagging

The InsightVM Asset Tagging integration provides capabilities to tag InsightVM discovered assets with data from ServiceNow CMDB CI (Configuration Item) records. This can be used to provide context on InsightVM assets for data such as location, business owner, and any other fields that are available in the ServiceNow CMDB.

Tags created by the integration are managed end-to-end by the integration, meaning that they are created, updated, and optionally deleted each time an integration job runs.

Jobs

Each InsightVM Asset Tagging integration job contains the following configuration options:

Field

Description

Name

Friendly name for the integration job configuration

InsightVM Connection

InsightVM Connection to use for InsightVM requests (asset/tag data report generation and tagging operations)

Tag Prefix

Prefix for tags managed by the integration. Only tags with this prefix will be updated by the integration.

Tag Name Maps

Tags to be created from CMDB CI data. Each tag includes a CMDB CI table selection, a field whose value will be the suffix of a tag name, and a type for the tag.

Delete Empty Tags

Whether tags with the defined tag prefix should be deleted if no assets are associated with the tag.

InsightVM Scope

Comma-delimited regular expression patterns for names of InsightVM sites, tags, and asset groups to include in the scope for tagging.

Schedule

Frequency for tagging to run. Should not be scheduled so frequently that the integration is running multiple times simultaneously.

Recommendation: Daily during an hour of the day with minimal InsightVM scanning in progress.

An example job configuration is shown below:

Tag Name Maps

Tag Name Maps are used to define which tags are created/updated by the Asset Tagging feature. For each InsightVM asset in scope for a particular integration job, a CMDB CI lookup is performed against the table specified in the tag configuration. If CMDB CIs are found, the field values from each CI are used to create/update tags with the following format: [TAG PREFIX][FIELD VALUE].

The display name for the Tag Name Map is dynamically generated based on the configuration with the following format: [Table].[Field]:[Type]. Default Tag Name Map configurations included with the application are as follows:

  • cmdb_ci_computer.assignment_group.name:owner
  • cmdb_ci_computer.location.name:location
  • cmdb_ci_computer.owned_by.name:owner
  • cmdb_ci_computer.sys_class_name:custom

Field

Description

Table

Table containing CMDB CIs for the tag.

Filter

Filter to limit the scope of the CMDB CI search for the tag.

Field

Field whose value will be used for creating/updating InsightVM Tags and associated with assets matching the CI.

Type

Type for the tag

Lookup Fields

Fields used when searching for matching CIs based on InsightVM data. InsightVM data retrieval includes the asset's host name, IP address, and MAC address.

Note: Fields are applied to an OR query against the specified table.

IP Address Field

Field used to search for CIs based on an asset's IP address.

MAC Address Field

Field used to search for CIs based on an asset's host name.

Host Name Field

Field used to search for CIs based on an asset's host name.

An example of a Tag Name Map configuration is shown below:

Run Statistics

Run statistics are logged with each run of the InsightVM Asset Tagging integration. Statistics include the following details:

  • Start
    • Date and time when an integration job begins
  • End
    • Date and time when an integration job ends. In the event that an integration job run fails, field will be empty until it is updated by the next integration job run.
  • Tags created
    • Number of tags created based on Tag Name Map configurations and ServiceNow CMDB CI field data
  • Tags updated
    • Number of tags with updated associations from the run
    • Note: Tags are updated each run, even when no changes are required. Tags are bulk updated, meaning that only one request is made for each tag asset association updated during an integration job run.
  • Tags deleted
    • Number of tags with the defined integration prefix deleted during the integration job run due to there no longer being assets associated with the tag
    • Note: Tag deletion only occurs if the ‘Delete Empty Tags’ option is enabled in the InsightVM Asset Tagging job configuration.
  • Tagged assets
    • Number of unique InsightVM assets tagged during the integration job run.
  • Unmatched assets
    • Number of assets for which no matching CIs were identified during the integration job run.

InsightVM Site Configuration

The InsightVM Site Configuration integration provides the capability to create and update InsightVM sites with site names based on ServiceNow CMDB CI data and scopes including the IP address and/or host name from CIs with those field values.

For example, with a Site Name Map of [company.name]-[location.name] and a CI record with a Company Name of ‘Rapid7’ and Location Name of ‘Boston’, the resulting InsightVM site would be sn_Rapid7-Boston (when using the default Site Name Prefix). Each additional asset returned by the configured table and filter for the Site Name Map would have its IP address and/or hostname added to the scope for that site.

Jobs

Each InsightVM Site Configuration integration job contains the following configuration options:

Field

Description

Name

Friendly name for the Site Configuration job record

InsightVM Connection

InsightVM Connection to use for InsightVM requests (site operations)

Site Name Prefix

Prefix for sites managed by the integration. Only sites with the defined prefix will be updated by the integration.

Site Name Maps

List of Site Name Maps (table and field list values) from which InsightVM sites will be created. Up to five field values may be used.

Delete Empty Sites

Whether sites without assets in their scope should be deleted. New sites with no scope during after processing of all CI records will not be created.

Schedule

Frequency for site configuration to run. Should not be scheduled so frequently that the integration is running multiple times simultaneously. Recommendation: Daily during an hour of the day with minimal InsightVM scanning in progress.

Below is an example InsightVM Site Configuration integration configuration:

Site Name Maps

Site Name Maps define which fields are used to construct the site name. Each Site Name Map can contain up to five fields on the selected table, from which the name of the site will be constructed. For example, given the following fields defined for a Site Configuration record:

  1. Company.name
  2. Location.city
  3. sys_class_name

With a delimiter of ‘-’, two example site names would be:

  1. Rapid7-Boston-cmdb_ci_linux_server
  2. Rapid7-Chicago-cmdb_ci_computer

One default Site Name Map is included with the application:

  • company.name-location.name (cmdb_ci_computer)

Configuration details for Site Name Maps are as follows:

Field

Description

Table

Table containing CMDB CIs from which field values will be used for constructing site names.

Filter

Filter to limit the scope of the CMDB CI search for the site configuration.

Name Field (1-5)

Up to five field values used to sequentially construct the name of the InsightVM site.

Additional field selectors are shown as the currently visible ones are populated with values.

Delimiter

Delimiter to add between each field value when constructing site names.

Empty Field Value

Value to use in the site name for the field when there is no value for the field on a CI.

Site Scope Values

Values to include in the site scope for the sites.

IP Address Field

Field whose value will be added to the scope of the InsightVM site. IP addresses are validated by the integration prior to including them in the scope for a site. Only IPv4 addresses are supported.

Hostname Field

Field whose value will be added to the scope of the InsightVM site.

Below is an example Site Name Map configuration:

Run Statistics

Run statistics are logged with each run of the InsightVM Site Configuration integration. Statistics include the following details:

  • Start
    • Date and time when an integration job begins
  • End
    • Date and time when an integration job ends.
    • In the event that an integration job run fails, field will be empty until it is updated by the next integration job run.
  • Sites Created
    • Number of sites created during an integration job run.
  • Sites Updated
    • Number of sites updated during an integration job run.
  • Sites Deleted
    • Number of sites deleted during an integration job run.

ServiceNow CMDB Asset Import

The ServiceNow CMDB Asset Import integration provides the capability to ingest InsightVM asset data into the ServiceNow CMDB. Data imported for each asset includes:

  • IP Address
  • MAC Address
  • Host Name
  • Operating System
  • InsightVM Connection Name
  • Asset ID
  • Risk Score
  • Last Assessed for Vulnerabilities (Date and Time)
  • Criticality Tag
  • Vulnerability Count
  • Critical Vulnerability Count
  • Severe Vulnerability Count
  • Moderate Vulnerability Count

IMPORTANT

Only assets which have a host name that has been discovered by InsightVM can be imported.

Columns created on the cmdb_ci_hardware table for use by this integration include:

  • Rapid7 Asset ID (x_r7_rapid7_cmdb_i_rapid7_asset_id)
  • Rapid7 InsightVM Connection Name (x_r7_rapid7_cmdb_i_rapid7_insightvm_connection_name)
  • Rapid7 Risk Score (x_r7_rapid7_cmdb_i_rapid7_risk_score)
  • Rapid7 Last Assessed for Vulnerabilities (x_r7_rapid7_cmdb_i_rapid7_last_assessed_for_vulnerabilities)
  • Rapid7 Criticality Tag (x_r7_rapid7_cmdb_i_rapid7_criticality_tag)
  • Rapid7 Vulnerabilities (x_r7_rapid7_cmdb_i_rapid7_vulnerabilities)
  • Rapid7 Critical Vulnerabilities (x_r7_rapid7_cmdb_i_rapid7_critical_vulnerabilities)
  • Rapid7 Severe Vulnerabilities (x_r7_rapid7_cmdb_i_rapid7_severe_vulnerabilities)
  • Rapid7 Moderate Vulnerabilities (x_r7_rapid7_cmdb_i_rapid7_moderate_vulnerabilities)

Based on an asset's operating system value retrieved from InsightVM, specific CMDB classes can be associated with the imported asset by configuring CMDB Class Maps.

Note: If no matching CMDB Class Map is found for the asset, it will not be imported into the CMDB. To ensure that all in scope assets are imported, a wildcard CMDB Class Map can be used to assign a generic CMDB class to these records. The included Default Computer map provides this functionality.

Jobs

Each ServiceNow Asset Import integration job contains the following configuration options:

Field

Description

Name

Friendly name for the ServiceNow Asset Import job record

InsightVM Connection

InsightVM Connection to use for InsightVM requests (asset data report generation)

CMDB Class Maps

List of CMDB CI class name and operating system name regular expression patterns to use when mapping InsightVM assets to CMDI CI classes. Note that patterns are processed sequentially, with the first match being used. To ensure that non-specified operating systems are still imported, a default catch all .* pattern should be used as the last map.

InsightVM Scope

Comma-delimited regular expression patterns for names of InsightVM sites, tags, and asset groups to include to further scope the assets to import into the CMDB.

Schedule

Frequency for asset import to run. Should not be scheduled so frequently that the integration is running multiple times simultaneously.

Recommendation: Daily during an hour of the day with minimal InsightVM scanning in progress.

An example job configuration is shown below:

CMDB asset import form

CMDB Class Maps

CMDB Class Maps define case insensitive regular expression patterns used when processing InsightVM assets for import into the CMDB. When a matching regular expression pattern is found, the asset's CMDB Class is set to the one configured for the class map. In a ServiceNow Asset Import job record, CMDB Class Maps are processed sequentially, with the first match being used.

CMDB Class Map records included with the integration are as follows:

  • Linux Server
  • Windows Server
  • Windows Workstation
  • MacOS Device
  • VMware
  • Default Computer

Usually, CMDB Class Maps should be listed in descending order of specificity, e.g a Windows Server class map that specifies a pattern of windows server should appear in the list before one that specifies a pattern of windows.

If no matches are found, the asset will not be imported. As such it is recommended to have a wildcard pattern at the bottom of the CMDB Class Map list in a job record.

Details for CMDB Class Map records are as follows:

Field

Description

Name

Friendly name for the CMDB Class Map

CMDB Class

CMDB Class name to assign to the imported asset when a match for the regular expression pattern is found

Regular expression

Case insensitive regular expression pattern to test against an asset's operating system name from InsightVM

Run Statistics

Run statistics are logged with each run of the ServiceNow Asset Import integration. Statistics include the following details:

  • Start
    • Date and time when an integration job begins
  • End
    • Date and time when an integration job ends.
    • In the event that an integration job run fails, field will be empty until it is updated by the next integration job run.
  • CIs Inserted
    • Number of InsightVM assets identified as new (not found in the CMDB) based on lookup using the ServiceNow Identification Engine.
  • CIs Updated
    • Number of InsightVM assets found and updated based on lookup using the ServiceNow Identification Engine.
  • CIs Deleted
    • Number of CIs removed from the CMDB during the run.
    • Note: This is a possible response from the Identification Engine, but the integration does not itself make requests for CI deletion.
  • CIs Unchanged
    • Number of InsightVM assets with an existing CI that is identical to the data provided from InsightVM.
  • Identification Errors
    • Number of InsightVM assets for which no matching CMDB Class Map was found.
    • This could also be related to other errors during the import process for an individual InsightVM asset.
    • The application logs provide details on each identification error.
    • Note: If the job configuration is intentionally configured to not match all operating systems (by excluding a wildcard class map), the integration will still provide identification error statistics.

Running Integrations

Once integration job records are configured, there are two ways to run each integration:

  1. Defining a schedule on the job configuration for the integration
  2. Clicking the ‘Execute Now’ button when viewing an existing integration configuration

Note: If multiple jobs for a particular integration are configured (i.e InsightVM Asset Tagging), they should not be scheduled in a frequency that would result in overlap between the two jobs. When an integration job starts, temporary data from any running job for that integration is removed; and as such, the running job that started first will not successfully complete. Jobs for separate integrations can run concurrently without conflict.

Each integration will log its start and end to the Diagnostics -> Logs module in the application. In addition, details pertaining to the run of the integration job are also logged to the application logs. Note that some log messages may be out of order in the Logs view (even when sorting by the timestamp) when the logs were written during the same second.

InsightVM Asset Tagging Run Details

Workflow

Below is a diagram which illustrates the workflow for the InsightVM Asset Tagging integration:

Run Logs

During an InsightVM Asset Tagging integration run, the following informational logs are provided to identify specific operations performed by the integration.

Integration Start

When the integration starts, the following message is written to the application log:

1
Started asset_tagging integration run
InsightVM Data Collection

The integration collects the following data from the InsightVM Security Console based on the configuration defined in the job record:

  • In scope asset information
  • Existing tags with the configuration integration prefix

To collect this data, two background jobs are created by the integration:

  • Asset Tagging Asset Data Import Job
  • Asset Tagging Tag Data Import Job

A third background job, ‘Asset Tagging Update Tags after Data Import’, checks the status of these two jobs. Once the asset and tag data has been collected by these jobs, this job begins the tag create/update/delete process.

Messages similar to the following will be logged when a background job has been successfully scheduled:

1
Successfully scheduled job with name Asset Tagging Update Tags after Data Import, sys_id: 0d8451151b65441015b63335cc4bcb95

Once the job is complete, it is deleted by the integration. Jobs for InsightVM data collection will create, generate, import, and delete a report in InsightVM (once the data has been imported). Additional messages related to this process are also logged.

Tag Create/Update/Delete Process

The tagging process begins after data from the InsightVM Security Console is imported. This includes identifying which tags need to be created, which assets need to be associated with each tag, and which tags need to be deleted if the ‘Delete Empty Tags’ configuration option is enabled.

When the tagging process begins, the following message will be logged:

1
Updating tag associations...

Logs related to the tagging process are as follows:

Tag Creation

For tag creation, messages similar to the following will be logged:

1
Created tag with name: sn_Linux Server, type: CUSTOM
Tag Update

For tag updates, messages similar to the following will be logged:

1
Adding 2 assets to tag sn_Computer
2
Updated tag with ID: 447
Tag Deletion

If there are tags that need to be deleted and this option is enabled, a message similar to the following will be logged to indicate the start of this process:

1
Deleting 5 tags that no longer have assets

For each tag that is deleted, a message similar to the following will be logged:

1
Deleting tag sn_NoMoreAssets:CUSTOM
Completion

At completion of the integration run, multiple messages related to job cleanup will be logged. In addition, the following message indicating run success will be logged:

1
Finished asset_tagging integration run

InsightVM Site Configuration Run Details

Workflow

Below is a diagram which illustrates the workflow for the InsightVM Site Configuration integration:

Run Logs

During an InsightVM Site Configuration integration run, the following informational logs are provided to identify specific operations performed by the integration.

Integration Start

When the integration starts, the following message is written to the application log:

1
Started site_configuration integration run
Site Creation

When a site is created in InsightVM, a message similar to the following will be logged:

1
Successfully created InsightVM site with name sn_Rapid7-Boston
Site Update

When the scope of an InsightVM site is updated, a message similar to the following will be logged:

1
Updated site sn_Rapid7-Boston scope with 57 addresses
Site Deletion

If there are sites with empty scopes and the ‘Delete Empty Sites’ configuration option is enabled, a message similar to the following will be logged for each site that is deleted:

1
Deleted site with empty scope sn_Rapid7-Boston
Completion

At completion of the integration run, the following message indicating run success will be logged:

1
Finished site_configuration integration run

ServiceNow CMDB Asset Import Run Details

Workflow

Below is a diagram which illustrates the workflow for the ServiceNow Asset Import integration:

Run Logs

During an- ServiceNow CMDB Asset Import integration run, the following informational logs are provided to identify specific operations performed by the integration.

Integration Start

When the integration starts, the following message is written to the application log:

1
Started asset_import integration run
InsightVM Data Collection

The integration collects the following data from the InsightVM Security Console based on the configuration defined in the job record:

  • In scope asset information

To collect this data, one background job is created by the integration:

  • Asset Import Asset Data Import Job

Messages similar to the following will be logged when a background job has been successfully scheduled:

1
Successfully scheduled job with name Asset Import Asset Data Import Job, sys_id: 0d8451151b65441015b63335cc4bcb95
CMDB Asset Import

As part of the Asset Import Asset Data Import Job, the report data from InsightVM is imported to a temporary integration table; and during the import process, imported into the ServiceNow CMDB.

Each InsightVM asset in the report is processed based on the CMDB Class Maps defined for the configuration which are used to identify the CMDB class to associate with the InsightVM asset. The ServiceNow Identification Engine API is then used to look up the asset based on its hostname. Where a matching CI is found using the name field, the CI is updated. Only assets with hostnames discovered by InsightVM will be imported into the CMDB by the integration. In the scenario an additional field is required for Identification Engine lookups for the ServiceNow environment, the lookup will fail and the asset will not be imported into ServiceNow as a CMDB CI record.

Import Start

When the asset import process begins, the following message is logged:

1
Beginning ServiceNow CMDB Asset Import process...

Note: To reduce the volume of log messages related to the import process, only error messages are logged during the import process. Successful CI create/update operations are not logged.

Identification Errors

Identification errors are logged by the integration. In the event that no matching CMDB Class Map is found for a particular InsightVM asset’s operating system, the asset is not imported.

To indicate that no matching CMDB Class Map was found for an asset, a message similar to the following is logged with the details:

1
Failed to find an OS -> Class mapping for source data, {"ip_address":"192.168.1.1","mac_address":"00:00:00:00:00:00","name":"WindowsServer1","os":"Microsoft Windows Server 2012 R2 Standard Edition"}, cannot continue! Configuration Sys ID: d3c5ffb01b21041015b63335cc4bcb64

Note: In the event that the ServiceNow CMDB Asset Import job configuration intentionally leaves out a wildcard pattern to ensure that all assets are imported, these errors will still be logged; however, they can be ignored.

Import Errors

Any errors outside of identification errors during the asset import process are also logged.

Import Completion

When the asset import process is complete, a message similar to the following will be logged:

1
Processed 34 total records during CMDB CI integration
Completion

At completion of the integration run, multiple messages related to job cleanup will be logged. In addition, the following message indicating run success will be logged:

1
Finished asset_import integration run

FAQ

How long do integrations take to run?

The duration of an integration run is dependent on a number of factors:

  • InsightVM host resources
  • InsightVM asset count
  • ServiceNow data import performance

Logs are provided to generally show which operations are being performed by each integration. In addition, the Run Statistics module can provide insight into how long each integration tags to run as it provides ‘start’ and ‘end’ metrics for each.

How frequently can I run the integrations?

Integrations can be run as often as makes sense given factors like scan or CMDB update frequency. The only requirement imposed by the application is that integrations with multiple jobs do not overlap. E.g two InsightVM Asset Tagging integration jobs may not run at the same time, but one InsightVM Asset Tagging job and one ServiceNow Asset Import job may run concurrently.

Can multiple jobs for the same integration be configured?

As many jobs as needed to facilitate the desired data synchronization workflow may be configured, so long that only one job for a particular integration is running at a given time. Different jobs can be run on independent frequencies and even connect to separate InsightVM Security Consoles.

Troubleshooting

Diagnostics

The Diagnostics module in the application menu provides access to the logs for the application, along with access to some of the internal components for troubleshooting purposes. Modules within this module include:

  • Logs
    • Logs from all integrations provided with the application
    • Note: In the event that an exception is not caught by the application, it will not appear under this module. If troubleshooting a run failure or other issue, it is also recommended to review the System Logs -> System Log -> All module for additional details
  • Integration Internal Jobs
    • Transient background jobs table used by the InsightVM Asset Tagging and ServiceNow Asset Import integrations
  • Data Sources
    • List of application data sources used by the InsightVM Asset Tagging and ServiceNow Asset Import integrations for import of data from InsightVM.

Debug Level Logging

If additional logging is required, you can enable debug level logging by following these steps:

  1. In the ServiceNow Filter navigation (which is the primary search), enter sys_properties.list into the filter menu and hit Enter.
  2. Select New and create a new property with the following information:
    • Name: x_r7_rapid7_cmdb_i.logging.verbosity
    • Choices: debug,info,warn,error
    • Value: debug
  3. Once saved, log out and then log back into ServiceNow to enable debug logging.

Avoid property collision

If the property created in step 2 already exists, an error will occur upon saving. If this happens, update the existing record with the above information instead of creating a new property.

Common Issues

Integration fails to run

When attempting to run an integration after a prior failure, you may see the following error in the application log:

1
Integration is already running, only one instance of an integration can run at time

This error can occur due to one of the following cases:

  • A valid job for the integration is already running.
  • Stale records in the Internal Integration Jobs table from a prior job that were not cleaned up are preventing the integration from running again.

If there is a valid job running, wait for that job to complete. Otherwise, follow these steps to clean up the Internal Integration Jobs table:

  1. Confirm that stale records exist by going to the Rapid7 InsightVM Integration for CMDB -> Diagnostics -> Internal Integration Jobs module and verify that records are listed.
  2. Go to the System Definition -> Scripts - Background module and enter the following script:
1
var gr = new GlideRecord('x_r7_rapid7_cmdb_i_integration_job');
2
gr.query()
3
gr.deleteMultiple()
  1. Verify that the scope is set to global.
  2. Click Run script to execute the script.

If the script runs successfully, you will see a message indicating the number of records that were deleted from the x_r7_rapid7_cmdb_i_integration_job table.

Successful deletion of stale internal integration jobs records

If execution of the script failed, try repeating the steps with the scope set to Rapid7 InsightVM Integration for CMDB.

Accessing another application's resources

When the integration is configured to access tables (or other resources) outside of those it owns, it needs what's known in ServiceNow as cross-scope access. Without cross-scope access, the integration will fail to execute. By default, the integration is configured with cross-scope access to the following CMDB tables:

  • cmdb_ci
  • cmdb_ci_computer

Some examples of when cross-scope access is needed:

  • If a Tag Name Map's Table property is set to cmdb_ci_vmware_instance
  • If a Site Name Map's Table property is set to cmdb_ci_win_server.

This also applies to any custom application's resources accessed by the integration.

To create cross-scope access, perform the following steps in the ServiceNow UI:

  1. Navigate to System Applications > Application Cross-Scope Access.
  2. Select New record.
    • Source Scope: Rapid7 InsightVM Integration for CMDB
    • Target Scope: {{Target Scope}}
    • Target Name: {{Target Name}}
    • Target Type: {{Target Type}}
    • Operation: {{Operation}}
    • Status: Allowed

Filling in the placeholder values with the appropriate values should be performed before submitting the changes.

As an example, if the integration needs to read values from cmdb_ci_vmware_instance because of a custom Tag Name Map, the cross-scope access record would look similar to:

  • Source Scope: Rapid7 InsightVM Integration for CMDB
  • Target Scope: Global
  • Target Name: cmdb_ci_vmware_instance
  • Target Type: Table
  • Operation: Read
  • Status: Allowed

No assets are imported by the ServiceNow Asset Import integration

InsightVM discovery source not created

An error message in the application log stating the following indicates that the 'InsightVM' discovery source for the application was not created:

text
1
IdentificationEngine Error Request: {"items":[{"className":"cmdb_ci_linux_server","lookup":[{"className":"cmdb_ci_network_adapter","values":{"ip_address":"192.168.1.1","mac_address":"00:00:00:00:00:00"}}],"values":{"ip_address":192.168.1.1","mac_address":"00:00:00:00:00:00","name":"linux1","os":"Ubuntu Linux 16.04","sys_class_name":"cmdb_ci_linux_server"}}]}, Response: {"items":[{"sysId":"Unknown","identifierEntrySysId":"Unknown","errors":[{"error":"INVALID_INPUT_DATA","message":"In payload invalid data source [InsightVM] exist. You need to provide a valid choice value from field [discovery_source] in table [cmdb_ci]"}],"identificationAttempts":[]}],"relations":[],"logContextId":"b9b87bb41b21041015b63335cc4bcbbe"}

The ‘message’ section in the above log displays the following message, “In payload invalid data source [InsightVM] exist. You need to provide a valid choice value from field [discovery_source] in table [cmdb_ci]”, indicating that the discovery source is not created. Follow the steps in Initial Setup section of this guide to configure discovery source, then try running the job again.

Configuration Management For Scoped Apps CMDB plugin not installed

An error message stating the following indicates the Configuration Management For Scoped Apps CMDB (com.snc.cmdbb.scoped) plugin is not installed. Follow the instructions in the Initial Setup section of this guide to install the plugin, then try running the job again.

1
Configuration Management For Scoped Apps CMDB (com.snc.cmdb.scoped) plugin is not installed.

Processed 0 total records during CMDB CI integration

InsightVM Scope configuration

Review the InsightVM Scope configuration for the job and validate that assets should be included based on the defined regular expression patterns.

CMDB Class Map configuration

Review the CMDB Class Maps defined for the job configuration and validate that assets in scope for the job have operating systems matching those patterns.

If no CMDB Class Map matches are found for an asset, a message similar to the following will be logged:

1
Failed to find an OS -> Class mapping for source data, {"ip_address":"192.168.1.1","mac_address":"00:00:00:00:00:00","name":"WindowsServer1","os":"Microsoft Windows Server 2012 R2 Standard Edition"}, cannot continue! Configuration Sys ID: d3c5ffb01b21041015b63335cc4bcb64

InsightVM connectivity issues

Authentication Failure

A log message similar to the following indicates authentication failure to the InsightVM security console:

1
site_configuration integration failed to run: {"message":"An error occurred executing the paged REST request for Rapid7 VM endpoint: /api/3/sites, method: undefined, error:Error: There was an error retrieving results from the paged endpoint. Error: The supplied credentials are invalid."}

Validate the credentials and host information for the InsightVM connection assigned to the integration job configuration and try running the job again.

Security Console Down

A log message similar to the following may indicate that the InsightVM Security Console host may be down or unresponsive:

1
site_configuration integration failed to run: {"message":"An error occurred executing the paged REST request for Rapid7 VM endpoint: /api/3/sites, method: undefined, error:Error: There was an error retrieving results from the paged endpoint. Error: The supplied credentials are invalid."}

Manually review the status of the InsightVM Security Console application and the status of the host. If assistance is needed to restore service of the Security Console application, contact Rapid7 support.

ServiceNow connectivity issues

MID server connectivity issues

A message similar to the following indicates that there may be an issue with the ServiceNow MID server configured for the InsightVM Connection on an integration job configuration:

1
asset_import integration failed to run: {"message":"An error occurred executing the paged REST request for Rapid7 VM endpoint: /api/3/sites/, method: undefined, error:com.glide.ecc.ECCResponseTimeoutException: No response for ECC message request with sysid=1a5d1e091ba9041015b63335cc4bcb75 after waiting for 30 seconds in ECC Queue"}

To review the status of a MID server, go to the MID Servers -> Servers module in ServiceNow. For resolution of connectivity issue on a MID server, refer to ServiceNow’s documentation.

No tags created by the InsightVM Asset Tagging integration

InsightVM Scope configuration

Review the InsightVM Scope configuration for the job and validate that assets should be included based on the defined regular expression patterns.

Tag Name Maps configuration

Review the Tag Name Maps configuration for the job configuration and validate that data is available in the fields selected. Also ensure that the selected IP Address, Hostname, and MAC address fields are correct for the records on the selected Table.

No assets are assigned to InsightVM tags

ServiceNow MID server max payload size

Depending on the size of your environment, the reports generated by the integration jobs may result in very large responses between the ServiceNow MID server and the ServiceNow platform. The MID Server max payload size default of 20 MB meets most customer needs. However, if you get this error when running a job, it means the MID server was not able to fulfill the request due to the response size:{""message"":""Received non-OK status code (0), response: null""} .

To avoid this issue, increase the max payload size. You can refer to this ServiceNow knowledge base article for more information: https://hi.service-now.com/kb_view.do?sysparm_article=KB0748591.

You can define the max payload size globally or per MID Server by following these steps:

  1. In ServiceNow, go to MID Server > Properties.
  2. Create a new property.
    1. Name: mid.eccq.max_payload_size
    2. Value: 40000000
  3. Either set globally or for a specific MID Server.
  4. Save and restart the MID server from within ServiceNow UI.

No sites created by the InsightVM Site Configuration integration

Site Name Maps configuration

Review the Site Name Maps configuration for the job configuration, validate that CIs exist on the selected Table, and ensure that CIs on that table have values in the selected Name Fields [1-5].

Imported assets do not have the correct CMDB class assigned

Review the regular expression patterns defined in the CMDB Class Maps for the integration job configuration and try running the job again.

Not all tables are listed for the Table dropdown in a Tag Name Map or Site Name Map configuration

The application only supports cmdb_ci prefixed tables for Tag Name Map and Site Name Map configurations.

Not all fields are listed in the Field** dropdowns in a Tag Name Map or Site Name Map configuration

The application only supports values of type string as selections on Field selectors.

Receive "Execute operation on script include 'SysRelatedList' from scope 'Rapid7 InsightVM Integration for CMDB' was denied" error when saving Connection

This issue occurs when the "Rapid7 InsightVM Integration for CMDB" application is not able to execute a script include for SysRelatedList resulting in a failure message when saving the Connection.

ServiceNow CMDB privilege error

This can be resolved by navigating in ServiceNow to:

  • System Applications > Application Cross-Scope Access
  • New record
    • Source Scope: Rapid7 InsightVM Integration for CMDB
    • Target Scope: Global
    • Target Name: SysRelatedList
    • Target Type: Script Include
    • Operation: Execute API
    • Status: Allowed

ServiceNow CMDB cross scope privilege

Once the Application Cross-Scope Access record has been created, you will now be able to create the Connection without receiving the save denied error.