About the connector
Rapid7 InsightIDR is an intruder analytics solution that gives you the confidence to detect and investigate security incidents faster.
This article provides information about the Rapid7 InsightIDR connector, which facilitates automated interactions, using the Rapid7 InsightIDR API and FortiSOAR™ playbooks. Add the Rapid7 InsightIDR connector as a step in FortiSOAR™ playbooks and perform automated operations, such as updating the status of a specified investigation or adding indicators to a specified threat.
Version information
Connector Version: 1.0.0
FortiSOAR™ Version Tested on: 5.0.0-866
Authored By: Fortinet
Certified: Yes
Installing the connector
From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™repository and run the yum command as a root user to install connectors:
yum install cyops-connector-rapid7-insightidr
Prerequisites to configuring the connector
- You must have the region code for the region that hosts your data and the API key configured for your account for using the Rapid7 InsightIDR API.
- To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
Configuring the connector
For the procedure to configure a connector, click here
Configuration parameters
In FortiSOAR™, on the Connectors page, click the Rapid7 InsightIDR connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details.
| Parameter |
Description |
| Region Code |
The region code for the region that hosts your data. In the URL, us.idr.insight.rapid7.com, the region code is us. |
| API Key |
API key configured for your account for using the Rapid7 InsightIDR API. |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
Actions supported by the connector
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 and onwards:
| Function |
Description |
Annotation and Category |
| Get Investigation List |
Retrieves all investigations or investigations that match the input parameters that you have specified using the Rapid7 InsightIDR API. |
get_investigations
Investigation |
| Update Investigation Status |
Updates the status of the specified investigation using the Rapid7 InsightIDR API based on the Investigation ID and status you have specified.
The Rapid7 InsightIDR API returns the specified investigation with its status updated to the new state. If the specified investigation already has the given status no change is made, but the investigation will still be returned. |
update_status
Investigation |
| Close Investigations |
Closes all investigations that match the input parameters that you have specified using the Rapid7 InsightIDR API.
The Rapid7 InsightIDR API returns the number of investigations that were closed and a list of their IDs. |
close_investigation
Investigation |
| Add Indicators to Threat |
Adds InsightIDR threat indicators to the threat that matches the specified threat key that you have specified using the Rapid7 InsightIDR API. |
add_indicators
Investigation |
| Replace Indicators for Threat |
Replaces InsightIDR threat indicators in the threat that matches the specified threat key that you have specified using the Rapid7 InsightIDR API. |
replace_indicators
Investigation |
operation: Get Investigation List
Input parameters
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list is returned.
| Parameter |
Description |
| Status |
Investigation status based on which you want to retrieve the investigation from the Rapid7 InsightIDR API. You can choose Open, Closed, or both.
If the investigation status is specified, then this operation will return only those investigations whose status match one of the entries in the list will be returned. If the investigation status is not specified, then this operation will return investigations with any status. |
| Start Time |
ISO formatted timestamp. If specified, then this operation will return only those investigations whose createTime is after this date from the Rapid7 InsightIDR API. |
| End Time |
ISO formatted timestamp. If specified, then this operation will return only those investigations whose createTime is before this date from the Rapid7 InsightIDR API. |
| Page Number |
0 based index of the page that this operation should return. |
| Records Per Page |
Maximum number of results that this operation should return per page. By default this is set to 20. |
Output
The output contains the following populated JSON schema:
{
"data": [
{
"alerts": [
{
"type_description": "",
"type": "",
"first_event_time": ""
}
],
"title": "",
"id": "",
"created_time": "",
"assignee": {
"name": "",
"email": ""
},
"status": "",
"source": ""
}
],
"metadata": {
"size": "",
"total_data": "",
"total_pages": "",
"index": ""
}
}
operation: Update Investigation Status
Input parameters
| Parameter |
Description |
| Investigation ID |
ID of the investigation whose status you want to update using the Rapid7 InsightIDR API. |
| Status |
Status that you want to set for the specified investigation. You can choose between Open or Closed. |
Output
The output contains the following populated JSON schema:
{
"alerts": [
{
"type_description": "",
"type": "",
"first_event_time": ""
}
],
"title": "",
"id": "",
"created_time": "",
"assignee": {
"name": "",
"email": ""
},
"status": "",
"source": ""
}
operation: Close Investigations
Input parameters
| Parameter |
Description |
| Source |
Source of the investigation that you want to close using the Rapid7 InsightIDR API. This operation will close only investigations from this source. You can choose between, ALERT, MANUAL, or HUNT. |
| Alert Type |
If you select the source as ALERT, then in the Alert Type field you must specify the category of alert to be closed, i.e, in this case the Alert Type field is a mandatory field.
If you select the source as MANUAL or HUNT, then in the Alert Type field you can specify the category of alert to be closed, i.e, in these cases the Alert Type field is not a mandatory field. |
| From |
Timestamp that specifies the createTime of the investigation. Only those investigations that have the createTime after the timestamp specified in the field will be closed using the Rapid7 InsightIDR API. |
| To |
Timestamp that specifies the createTime of the investigation. Only those investigations that have the createTime before the timestamp specified in the field will be closed using the Rapid7 InsightIDR API. |
| Max Investigations to Close |
(Optional) Maximum number of investigations that you want to to close using this operation. If this parameter is not specified then there is no maximum limit and all the investigations based on your filter criteria will be closed. The minimum value set for this parameter is 0.
Important: Recommended not to specify any value in the Max Investigations to Close parameter since the value specified in this parameter must be greater than or equal to the number of results fetched by this operation. If you specify a value lesser than the number of results fetched, then this operation will fail. |
Output
The output contains the following populated JSON schema:
{
"ids": [
"",
""
],
"num_closed": ""
}
operation: Add Indicators to Threat
Input parameters
| Parameter |
Description |
| Threat Key |
Key of a threat to which you want to add indicators using the Rapid7 InsightIDR API. |
| Indicators to Add |
Input format of the indicators to be added to the specified threat. You can select one of the following options:
JSON, CSV, or Upload File.
If you choose JSON, then enter the JSON that contains the threat indicators in the Indicators field.
If you choose CSV, then enter a comma-separated list of the threat indicators in the Indicators field.
If you choose Upload File, then you can upload a file that contains the threat indicators directly from the FortiSOAR™ by specifying the reference or file path of the file that you want to upload. Supported file formats are: JSON, CSV, or STIX XML. |
Following is an example of adding indicators using STIX XML:
<stix:STIX_Package xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:stix="http://stix.mitre.org/stix-1"
xmlns:indicator="http://stix.mitre.org/Indicator-2"
xmlns:cybox="http://cybox.mitre.org/cybox-2"
xmlns:DomainNameObj="http://cybox.mitre.org/objects#DomainNameObject-1"
xmlns:cyboxVocabs="http://cybox.mitre.org/default_vocabularies-2"
xmlns:stixVocabs="http://stix.mitre.org/default_vocabularies-1"
xmlns:example="http://example.com/"
xsi:schemaLocation=
"http://stix.mitre.org/stix-1 …/stix_core.xsd
http://stix.mitre.org/Indicator-2 …/indicator.xsd
http://cybox.mitre.org/default_vocabularies-2 …/cybox/cybox_default_vocabularies.xsd
http://stix.mitre.org/default_vocabularies-1 …/stix_default_vocabularies.xsd
http://cybox.mitre.org/objects#DomainNameObject-1 …/cybox/objects/Domain_Name_Object.xsd"
id="example:STIXPackage-f61cd874-494d-4194-a3e6-6b487dbb6d6e"
timestamp="2014-05-08T09:00:00.000000Z"
version=“1.1.1”>
stix:STIX_Header
stix:TitleExample watchlist that contains domain information.</stix:Title>
<stix:Package_Intent xsi:type=“stixVocabs:PackageIntentVocab-1.0”>Indicators - Watchlist</stix:Package_Intent>
</stix:STIX_Header>
stix:Indicators
<stix:Indicator xsi:type=“indicator:IndicatorType” id=“example:Indicator-2e20c5b2-56fa-46cd-9662-8f199c69d2c9” timestamp=“2014-05-08T09:00:00.000000Z”>
<indicator:Type xsi:type=“stixVocabs:IndicatorTypeVocab-1.1”>Domain Watchlist</indicator:Type>
indicator:DescriptionSample domain Indicator for this watchlist</indicator:Description>
<indicator:Observable id=“example:Observable-87c9a5bb-d005-4b3e-8081-99f720fad62b”>
<cybox:Object id=“example:Object-12c760ba-cd2c-4f5d-a37d-18212eac7928”>
<cybox:Properties xsi:type=“DomainNameObj:DomainNameObjectType” type=“FQDN”>
<DomainNameObj:Value condition=“Equals” apply_condition=“ANY”>malicious1.example.com##comma##malicious2.example.com##comma##malicious3.example.com</DomainNameObj:Value>
</cybox:Properties>
</cybox:Object>
</indicator:Observable>
<indicator:Observable id=“NCCIC:Observable-fb5606ea-23f0-472d-babf-8b7e89571881”>
<cybox:Object id=“NCCIC:Object-a105a51a-c324-11e7-b25d-64006a91c899”>
<cybox:Properties xsi:type=“AddressObj:AddressObjectType” category=“ipv4-addr” is_spoofed=“false”>
<AddressObj:Address_Value condition=“Equals”>185.134.98.141</AddressObj:Address_Value>
</cybox:Properties>
</cybox:Object>
</indicator:Observable>
</stix:Indicator>
</stix:Indicators>
</stix:STIX_Package>
Output
The output contains the following populated JSON schema:
{
"threat": {
"indicator_count": "",
"published": "",
"note": "",
"name": ""
},
"rejected_indicators": []
}
operation: Replace Indicators for Threat
Input parameters
| Parameter |
Description |
| Threat Key |
Key of a threat in which you want to replace indicators using the Rapid7 InsightIDR API. |
| Indicators to Replace |
Input format of the indicators to be replaced in the specified threat. You can select one of the following options:
JSON, CSV, or Upload File.
If you choose JSON, then enter the JSON that contains the threat indicators in the Indicators field.
If you choose CSV, then enter a comma-separated list of the threat indicators in the Indicators field.
If you choose Upload File, then you can upload a file that contains the threat indicators directly from the FortiSOAR™ by specifying the reference or file path of the file that you want to upload. Supported file formats are: JSON, CSV, or STIX XML. |
Following is an example of replacing indicators using JSON:
For example, Copy Expand all Collapse all
{
“ips”: [
“192.168.0.1”
],
“hashes”: [
“b95663ec7339033cf1fde459a34b6606”
],
“domain_names”: [
“rapid7.com”
],
“urls”: [
“http://example.com/page”
]
}
Output
The output contains the following populated JSON schema:
{
"threat": {
"indicator_count": "",
"published": "",
"note": "",
"name": ""
},
"rejected_indicators": []
}
Included playbooks
The Sample - Rapid7 InsightIDR - 1.0.0 playbook collection comes bundled with the Rapid7 InsightIDR connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Rapid7 InsightIDR connector.
- Add Indicators to Threat
- Close Investigations
- Get Investigation List
- Replace Indicators for Threat
- Update Investigation Status
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.
