Integrate InsightVM with ServiceNow Security Operations
The Rapid7 Integration for Security Operations allows you to incorporate InsightVM vulnerability assessment data into your ServiceNow Security Operations instance using a purpose-built API. You can then consume this data with dashboards and other ServiceNow analytics tools.
With this integration, you can:
- Import Rapid7 InsightVM scan data directly into ServiceNow Security Operations.
- Gain more context and visibility into individual vulnerabilities and overall risk.
- Reduce exposure time through data-centric collaboration between IT Operations and Security.
- Maximize output while minimizing effort through an automated and closed-loop workflow.
- Easily deploy the integration from the ServiceNow Marketplace.
How this integration works
Here’s a high-level overview of how this integration works:
- InsightVM scans your environment to assess your assets' level of risk and processes the vulnerability data.
- ServiceNow Security Operations (SecOps) periodically queries InsightVM for the latest vulnerability information.
- ServiceNow creates remediation tickets for vulnerabilities and closes tickets that have been fixed.
- With future queries of InsightVM, ServiceNow checks closed tickets for successful remediation.
API request characteristics
When viewing assessment results produced by this integration, be aware that the API requests it executes only compare vulnerability results for an asset between 2 dates (using the currentTime and comparisonTime parameters). The end result is a simple differential produced by comparing the two snapshots of the asset's state at those times. It will not return historical data collected between those dates. Further, the creation of new remediation tickets and the closure of pre-existing tickets in ServiceNow is determined by this same differential.
If you prefer to include unchanged vulnerabilities that fall within the currentTime and the comparisonTime in the response, specify the includeSame=true parameter in the request.
Best practice recommendations
To ensure that you're best set up for success with this integration, Rapid7 recommends the following configuration best practices:
- ServiceNow query scheduling - When possible, configure this integration to query InsightVM for data shortly after your regularly scheduled scans are expected to complete. If you also use the Insight Agent to perform vulnerability assessments on your assets, the query timing you intend to configure should also take place just after each instance of your Security Console's Insight Platform synchronization interval (this interval determines how frequently your Security Console downloads new Insight Agent-based assessment data packages). Configuring an effective ServiceNow query schedule ensures that the integration is using the most recent data.
Supported search filters
The following table contains the supported search filters that you can use to refine your results in ServiceNow.
Asset filters
Asset filter list
| API Domain | Filter | Description |
|---|---|---|
| asset | id | The ID assigned to the asset. |
| asset | host_name | The hostname of the asset. |
| asset | ipv4 | The IP address of the asset in IPv4 format. |
| asset | ipv6 | The IP address of the asset in IPv6 format. |
| asset | mac | The MAC address of the asset. |
| asset | risk_score | The risk score calculated for the asset. |
| asset | last_scan_end | The time at which the most recent scan for this asset was completed. |
| asset | total_vulnerabilities | The number of vulnerabilities found on the asset, including those vulnerabilities that are unchanged between scans. |
| asset | exploits | The number of known exploits that could be used against vulnerabilities found on this asset. |
| asset | malware_kits | The number of malware kits that are available to be used against vulnerabilities found on this asset. |
| asset | os_name | The name of the operating system that the asset is running. |
| asset | os_architecture | The architecture of the operating system. |
| asset | os_type | The type of operating system that's installed. |
| asset | os_system_name | The system name of the operating system. |
| asset | os_family | The family that the operating system is part of. |
| asset | os_version | The version of the operating system that's installed. |
| asset | os_description | The description of the operating system that's installed. |
| asset | type | The host type of the asset (physical, virtual, etc). |
| asset | tags | The tags that are associated to the asset. |
| asset | sites | The sites that this asset is a member of. |
| asset | vulnerability_id | The ID of the vulnerability finding on the asset. |
| asset | protocol | The protocol through which the vulnerability was found on the asset. |
| asset | port | The port through which the vulnerability was found on the asset. |
| asset | first_found | The date when the vulnerability was first found on the asset. |
| asset | title | The title of the vulnerability on the asset. |
| asset | description | The description of the vulnerability on the asset. |
| asset | severity | The corresponding severity level of the vulnerability on the asset. |
| asset | severity_score | The severity score of the vulnerability on the asset. InsightVM severity scores are calculated by rounding CVSS scores to the nearest whole number and are used to assign a severity level to the vulnerability. |
| asset | cvss_score | The CVSS score of the vulnerability on the asset. This includes both v2 and v3 scores when they are available. |
| asset | cves | The CVE IDs associated with the vulnerability on the asset. |
| asset | published | The date when the vulnerability on the asset was first published. |
| asset | modified | The date when the vulnerability on the asset was modified after its initial publishing date. |
Vulnerability filters
Vulnerability filter list
| API Domain | Filter | Description |
|---|---|---|
| vulnerability | id | The ID of the vulnerability. |
| vulnerability | added | The date when the vulnerability was added. |
| vulnerability | title | The title of the vulnerability. |
| vulnerability | malware_kits | The number of malware kits that are available to be used against the vulnerability. |
| vulnerability | categories | The categories the vulnerability falls under. |
| vulnerability | exploits | The number of known exploits that could be used against the vulnerability. |
| vulnerability | description | The description of the vulnerability. |
| vulnerability | severity | The corresponding severity level of the vulnerability. |
| vulnerability | severity_score | The severity score of the vulnerability. InsightVM severity scores are calculated by rounding CVSS scores to the nearest whole number and are used to assign a severity level to the vulnerability. |
| vulnerability | cvss_score | The CVSS score of the vulnerability. This includes both v2 and v3 scores when they are available. |
| vulnerability | cves | The CVE IDs associated with the vulnerability. |
| vulnerability | published | The date when the vulnerability was first published. |
| vulnerability | modified | The date when the vulnerability was modified after its initial publishing date. |
| vulnerability | risk_score | The calculated risk score of the vulnerability according to InsightVM's risk model. |
| vulnerability | pci_severity_score | The severity score of the vulnerability according to PCI standards. |
| vulnerability | pci_fail | Indicates that the vulnerability is a failure of PCI standards or not. |
| vulnerability | cvss_v2_vector | The full CVSSv2 vector for the vulnerability. For example, AV:L/AC:M/Au:N/C:P/I:P/A:P |
| vulnerability | cvss_v2_access_vector | The CVSSv2 Access Vector (AV) metric for the vulnerability. |
| vulnerability | cvss_v2_access_complexity | The CVSSv2 Access Complexity (AC) metric for the vulnerability. |
| vulnerability | cvss_v2_authentication | The CVSSv2 Authentication (Au) metric for the vulnerability. |
| vulnerability | cvss_v2_confidentiality_impact | The CVSSv2 Confidentiality Impact (C) metric for the vulnerability. |
| vulnerability | cvss_v2_integrity_impact | The CVSSv2 Integrity Impact (I) metric for the vulnerability. |
| vulnerability | cvss_v2_availability_impact | The CVSSv2 Availability Impact (A) metric for the vulnerability. |
| vulnerability | cvss_v3_vector | The full CVSSv3 vector for the vulnerability. For example, AV:A/AC:L/PR:N/UI:R/S:U/C:L/I:L/A:L |
| vulnerability | cvss_v3_attack_vector | The CVSSv3 Attack Vector (AV) metric for the vulnerability. |
| vulnerability | cvss_v3_attack_complexity | The CVSSv3 Attack Complexity (AC) metric for the vulnerability. |
| vulnerability | cvss_v3_privileges_required | The CVSSv3 Privileges Required (PR) metric for the vulnerability. |
| vulnerability | cvss_v3_user_interaction | The CVSSv3 User Interaction (UI) metric for the vulnerability. |
| vulnerability | cvss_v3_scope | The CVSSv3 Scope (S) metric for the vulnerability. |
| vulnerability | cvss_v3_confidentiality_impact | The CVSSv3 Confidentiality Impact (C) metric for the vulnerability. |
| vulnerability | cvss_v3_integrity_impact | The CVSSv3 Integrity Impact (I) metric for the vulnerability. |
| vulnerability | cvss_v3_availability_impact | The CVSSv3 Availability Impact (A) metric for the vulnerability. |
Requirements
Before you get started with this integration, verify that you meet the following requirements.
Network traffic rules for the Insight Platform
Is your Rapid7 product subscription provisioned for the United States? Check your region code first!
As of April 12th, 2021, all new customers subscribing to Rapid7 Insight products that elect to store their data in the United States will be provisioned for one of three data centers. Since these data centers have unique endpoints, any firewall rules you configure must correspond to the data center your organization is assigned to. Follow these steps to determine which United States data center your organization is part of:
- Go to insight.rapid7.com and sign in with your Insight account email address and password.
- Navigate to the Platform Home page.
- If you are not taken to this page by default, expand the product dropdown in the upper left and click My Account.
- Look for the Data Storage Region tag in the upper right corner of the page below your account name. Your United States region tag will show one of the following data centers:
- United States - 1
- United States - 2
- United States - 3
For ServiceNow to retrieve data from InsightVM, your network must allow outbound traffic to the hostname that corresponds to your current InsightVM data region. The following table contains hostnames for each of the current InsightVM data regions:
| Region | Hostname |
|---|---|
| United States - 1 | us.api.insight.rapid7.com |
| United States - 2 | us2.api.insight.rapid7.com |
| United States - 3 | us3.api.insight.rapid7.com |
| Canada | ca.api.insight.rapid7.com |
| Europe | eu.api.insight.rapid7.com |
| Japan | ap.api.insight.rapid7.com |
| Australia | au.api.insight.rapid7.com |
Make sure to configure your network for the correct region!
The region that houses your InsightVM data depends entirely on what region was selected during your InsightVM deployment. The network rule you configure here must correspond to the data region you selected previously in InsightVM, or this integration will be unable to retrieve any data.
Rapid7 API key
Your Rapid7 API key allows ServiceNow to request data from your InsightVM environment. For your API key to be usable with this integration, it must be generated by an Insight Platform user with the Platform Administrator role.
We’ll cover how to generate your API key in the deployment procedure.
System requirements
The integration has several system requirements that you must satisfy, including installed plugins and user roles. You can review these requirements on the integrations’ ServiceNow Store page:
Deployment
Complete the following steps to deploy the Rapid7 Integration for Security Operations.
Generate your API key
Platform Administrator role required
As a reminder, you must generate your API key with an Insight Platform user that has the Platform Administrator role. API keys generated by Insight Platform users in other roles will not be usable with this integration.
Follow these steps to generate your API key:
- Go to insight.rapid7.com and sign in with your Insight account email address and password.
- Click the API Key Management tab on your left menu.
- On the API Keys page, switch to the User Key view and click + New User Key.
- On the Generate New User Key panel, select the organization to which your InsightVM deployment belongs from the dropdown list.
- Finally, give your API key a name for reference purposes. Click Generate to finish.
- With your API key generated, copy and save the key in a secure location.
This is your only chance to copy this API key!
For security purposes, your API key will not be viewable again after this opportunity. Make sure you copy and save it now.
If you inadvertently skip this step, you can always generate a new API key.
- Click Done after copying your API key. The key record will now appear by name in your User Key table.
Install and configure the integration
Now that you have your API key handy, follow these steps to access and install the Rapid7 Integration for Security Operations in ServiceNow:
- Go to the Rapid7 Integration for Security Operations page in the ServiceNow store to add the integration to your ServiceNow application.
- As covered in the requirements, this store page details the plugins and permissions you must already have installed to run the integration. For guidance on installing the integration app itself, see the Install and configure the Rapid7 Integration for Security Operations application ServiceNow document.
Integration types
The ServiceNow document listed previously details separate procedures for two integration types:
- InsightVM integration type
- Data warehouse integration type
The procedures in this article are meant for the InsightVM integration type.
- After installing the integration, log in to your ServiceNow application and navigate to the Rapid7 Vulnerability Integration on your left menu.
- Expand the Administration dropdown and click Configuration.
- Select InsightVM from the Integration Type dropdown.
- On the Integration Setup tab, select the region that corresponds to your InsightVM data region from the Server URL dropdown.
- Paste your API key in the provided field.
- Click Test Credentials to verify that the integration is configured correctly and can communicate with InsightVM.
- If the credential test succeeds, the Validation Status field will display Valid. Click Save to finish your integration deployment.
- If the credential test fails, verify that you’ve configured your network traffic rules for the correct data region and check that your Server URL and API Key values are input correctly before trying again.
Rapid7 Integration for Security Operations deployment complete!
InsightVM data will now appear in your ServiceNow application to help manage your remediation efforts.
Frequently asked questions
The following sections contain answers to some frequently asked questions about this integration and how it works.
I'm getting asset inventory data, but no vulnerability data on those assets. Why is this happening?
Make sure that you are setting a comparisonTime value in your query. Without this value, there is no date and time to run a comparison against. Consequently, the API will only return vulnerabilities that were new since the currentTime of your query, which is either the current time as set in the API request or the moment the request is executed. Additionally, the API only returns lists of new and remediated vulnerabilities. If a vulnerability is present that was also present at the time you were comparing against, this vulnerability will not appear in the response. If you've set a comparisonTime and there are no new or remediated vulnerabilities coming back from the endpoint as expected, contact the Rapid7 Support team.
I'm trying to get all remediated vulnerabilities on an asset using a very old comparisonTime and a very recent currentTime, but they aren't appearing. Why is this happening?
Make sure that you're setting a comparisonTime at a point where the asset you want to query for actually existed. If the asset did not exist at the comparisonTime you specified, there won't be any vulnerabilities that existed at that time either. Consequently, there will be no remediated vulnerabilities to return at the currentTime if no vulnerabilities existed at the comparisonTime.
If the number of total vulnerabilities is greater than 0, why don't I see any vulnerabilities in the "New" or "Remediated" list?
The API does not include unchanged vulnerabilities (meaning those vulnerabilities that are currently found on an asset that were already present during the last scan) in the response unless you set a parameter manually in the request that exposes this information. The total number of vulnerabilities is still correct; unchanged vulnerabilities are just hidden by default. You can modify your request with the includeSame=true parameter to expose those unchanged vulnerabilities in the response.
How is the "Remediated" date for a vulnerability on the remediated list calculated?
The API defines the remediation time for a vulnerability as the first date when an asset was scanned and that particular vulnerability was not found.
My response is missing some information. What happened?
If an asset or vulnerability does not have a certain property (such as asset tags or similar optional properties), that property will not appear in your response.
What is the cursor and how do I use it?
The cursor parameter allows you to search through sorted data in large responses. For example, if your API request produces a response that includes a cursor parameter value itself, you can then make another request that specifies this cursor value to retrieve the next page of data. Remember that cursor parameters are very specific to the exact queries that generate them. If your request produces a cursor and you intend to use it, your next request must exactly match the query criteria you used previously (the only difference being that you are providing the previously returned cursor value in the second request).
What are the recommended maximum page sizes?
Rapid7 recommends a page maximum of 100 for assets and 500 for vulnerabilities. If your requests also specify includeSame=true, set the page maximum to 50 for assets. When using a Vulnerability filter we recommend setting the request size to 25 as this filter type can impact performance. Request size can remain at 50 if no filters are applied or if only the asset filter is applied. Response times will vary depending on the amount of data that is retrieved for each request.
What format are responses in?
Responses can be formatted in JSON or XML depending on what you configure in the request header.
What vulnerability metrics does the API use?
The API uses both vulnerability finding metrics and vulnerability instance metrics. Each vulnerability instance includes the vulnerability proof, the vulnerability check that was used, and other relevant information. Each asset will report the total number of vulnerability findings. If new instances are found or remediated, those will be listed as well.
Can I generate a report from my InsightVM dashboard to use as a baseline comparison between ServiceNow Security Operations and InsightVM?
Yes. In InsightVM, go to any expandable, global vulnerability-based card (such as Vulnerabilities By CVSS Score) and export the entire table's contents as a CSV file. Import this CSV file into whatever spreadsheet software you have available and calculate the sum of the Instances column. You can compare this value to the figure shown in the Detection table in ServiceNow Security Operations.
Can I combine data from this integration with data from the data warehouse integration in the ServiceNow product itself?
No. The two integrations are completely separate from each other. If both integrations are options for deployment in your environment, choose one (and only one) to be used with ServiceNow.
How does ServiceNow handle deleted assets in InsightVM?
Assets that are deleted from InsightVM will no longer be returned by the API with subsequent requests. As a result, the corresponding asset in ServiceNow Security Operations will become stale. ServiceNow has its own retention policy that can address this scenario by removing asset records that have not been updated after a configured number of days. Consult your ServiceNow product documentation for instructions.