Rapid7 InsightIDR v2.1.0

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.

You can use FortiSOAR™'s Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling investigations from Rapid7 InsightIDR. For more information, see the Data Ingestion Support section.

Version information

Connector Version: 2.1.0

FortiSOAR™ Version Tested on: 7.4.3-3294

Rapid7 InsightIDR Version Tested on: Cloud Setup

Authored By: Fortinet

Certified: Yes

Release Notes for version 2.1.0

The following enhancements have been made to the Rapid7 InsightIDR Connector in version 2.1.0:

• Added Data Ingestion support and its corresponding playbooks.
• Added an optional parameter named 'Get All Records' input parameter to the Get Investigation List and Get Alerts Associated With Investigation actions.

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.

You can also use the yum command as a root user to install the connector:

yum install cyops-connector-rapid7-insightidr

Prerequisites to configuring the connector

• You must have the credentials of the Rapid7 InsightIDR server to which you will connect and perform automated operations.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the Rapid7 InsightIDR server.

Minimum Permissions Required

• Not applicable

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:

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:

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.

Output

The output contains the following populated JSON schema:

{
    "data": [
        {
            "rrn": "",
            "organization_id": "",
            "title": "",
            "source": "",
            "status": "",
            "priority": "",
            "last_accessed": "",
            "created_time": "",
            "disposition": "",
            "assignee": {
                "name": "",
                "email": ""
            },
            "first_alert_time": "",
            "latest_alert_time": "",
            "tags": [],
            "responsibility": ""
        }
    ],
    "metadata": {
        "index": "",
        "size": "",
        "total_pages": "",
        "total_data": ""
    }
}

operation: Close Investigations

Input parameters

Output

The output contains the following populated JSON schema:

{
    "ids": [],
    "num_closed": ""
}

operation: Add Indicators to Threat

Input parameters

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

Output

The output contains the following populated JSON schema:

{ 
    "threat": { 
        "indicator_count": "", 
        "published": "", 
        "note": "", 
        "name": "" 
    }, 
    "rejected_indicators": [] 
}

operation: Create Investigation

Input parameters

Output

The output contains the following populated JSON schema:

{
    "rrn": "",
    "organization_id": "",
    "title": "",
    "source": "",
    "status": "",
    "priority": "",
    "last_accessed": "",
    "created_time": "",
    "disposition": "",
    "assignee": {
        "name": "",
        "email": ""
    },
    "first_alert_time": "",
    "latest_alert_time": "",
    "tags": [],
    "responsibility": ""
}

operation: Update Investigation

Input parameters

Output

The output contains the following populated JSON schema:

{
    "rrn": "",
    "organization_id": "",
    "title": "",
    "source": "",
    "status": "",
    "priority": "",
    "last_accessed": "",
    "created_time": "",
    "disposition": "",
    "assignee": {
        "name": "",
        "email": ""
    },
    "first_alert_time": "",
    "latest_alert_time": "",
    "tags": [],
    "responsibility": ""
}

operation: Get Investigation Details

Input parameters

Output

The output contains the following populated JSON schema:

{
    "rrn": "",
    "organization_id": "",
    "title": "",
    "source": "",
    "status": "",
    "priority": "",
    "last_accessed": "",
    "created_time": "",
    "disposition": "",
    "assignee": {
        "name": "",
        "email": ""
    },
    "first_alert_time": "",
    "latest_alert_time": "",
    "tags": [],
    "responsibility": ""
}

operation: Get Alerts Associated With Investigation

Input parameters

Output

The output contains the following populated JSON schema:

{
    "data": [
        {
            "id": "",
            "title": "",
            "alert_type": "",
            "alert_type_description": "",
            "created_time": "",
            "first_event_time": "",
            "latest_event_time": "",
            "alert_source": "",
            "detection_rule_rrn": {
                "rule_name": "",
                "rule_rrn": ""
            }
        }
    ],
    "metadata": {
        "index": "",
        "size": "",
        "total_pages": "",
        "total_data": ""
    }
}

operation: Search Investigations

Input parameters

Output

The output contains the following populated JSON schema:

{
    "data": [
        {
            "rrn": "",
            "organization_id": "",
            "title": "",
            "source": "",
            "status": "",
            "priority": "",
            "last_accessed": "",
            "created_time": "",
            "disposition": "",
            "assignee": {
                "name": "",
                "email": ""
            },
            "first_alert_time": "",
            "latest_alert_time": "",
            "tags": [],
            "responsibility": ""
        }
    ],
    "metadata": {
        "index": "",
        "size": "",
        "total_pages": "",
        "total_data": ""
    }
}

operation: Create Comment

Input parameters

Output

The output contains the following populated JSON schema:

{
    "created_time": "",
    "rrn": "",
    "target": "",
    "creator": {
        "type": "",
        "name": ""
    },
    "body": "",
    "visibility": "",
    "attachments": [
        {
            "rrn": "",
            "creator": {
                "type": "",
                "name": ""
            },
            "created_time": "",
            "file_name": "",
            "mime_type": "",
            "size": "",
            "scan_status": ""
        }
    ]
}

operation: Get Comments

Input parameters

Output

The output contains the following populated JSON schema:

{
    "data": [
        {
            "created_time": "",
            "rrn": "",
            "target": "",
            "creator": {
                "type": "",
                "name": ""
            },
            "body": "",
            "visibility": "",
            "attachments": [
                {
                    "rrn": "",
                    "creator": {
                        "type": "",
                        "name": ""
                    },
                    "created_time": "",
                    "file_name": "",
                    "mime_type": "",
                    "size": "",
                    "scan_status": ""
                }
            ]
        }
    ],
    "metadata": {
        "index": "",
        "size": "",
        "total_pages": "",
        "total_data": ""
    }
}

operation: Delete Comment

Input parameters

Output

The output contains the following populated JSON schema:

{
    "message": ""
}

Included playbooks

The Sample - Rapid7 InsightIDR - 2.1.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
• Create Comment
• Create Investigation
• Delete Comment
• Get Alerts Associated With Investigation
• Get Comments
• Get Investigation Details
• Get Investigation List
• Rapid7 InsightIDR > Fetch and Create Investigations
• >> Rapid7 InsightIDR > Fetch Associated alerts for Investigation
• Rapid7 InsightIDR > Ingest
• Replace Indicators for Threat
• Search Investigations
• Update Investigation

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 the connector upgrade and delete.

Data Ingestion Support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling investigations from Rapid7 InsightIDR. Currently, "investigations" in Rapid7 InsightIDR are mapped to "alerts" in FortiSOAR™. For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation.

Configure Data Ingestion

You can configure data ingestion using the “Data Ingestion Wizard” to seamlessly map the incoming Rapid7 InsightIDR "Investigations" to FortiSOAR™ "Alerts".

The Data Ingestion Wizard enables you to configure the scheduled pulling of data from Rapid7 InsightIDR into FortiSOAR™. It also lets you pull some sample data from Rapid7 InsightIDR using which you can define the mapping of data between Rapid7 InsightIDR and FortiSOAR™. The mapping of common fields is generally already done by the Data Ingestion Wizard; users are mostly required to only map any custom fields that are added to the Rapid7 InsightIDR investigation.

1. To begin configuring data ingestion, click Configure Data Ingestion on the Rapid7 InsightIDR connector’s "Configurations" page.
   Click Let’s Start by fetching some data, to open the “Fetch Sample Data” screen.
   
   Sample data is required to create a field mapping between Rapid7 InsightIDR data and FortiSOAR™. The sample data is pulled from connector actions or ingestion playbooks.
2. On the Fetch Data screen, provide the configurations required to fetch Rapid7 InsightIDR data.
   In the Pull Investigations which are Created in Past X Minutes field, specify the last X minutes from when you want to fetch investigations that have been created in Rapid7 InsightIDR. Additionally, you can choose to pull data from Rapid7 InsightIDR by specifying various filter criteria such as "Status of Investigation", "Source", "Priority", or "Assignee Email". Select the Ingest Alerts Related to Investigation checkbox to fetch alerts associated with the investigations that are being pulled from Rapid7 InsightIDR:
   
   Once you have completed specifying the configurations, click Fetch Data.

3. On the Field Mapping screen, map the fields of a Rapid7 InsightIDR investigation to the fields of an alert present in FortiSOAR™.
   To map a field, click the key in the sample data to add the “jinja” value of the field. For example, to map the title parameter of a Rapid7 InsightIDR investigation to the Name parameter of a FortiSOAR™ alert, click the Name field and then click the title field to populate its keys:
   
   For more information on field mapping, see the Data Ingestion chapter in the "Connectors Guide" in the FortiSOAR™ product documentation. Once you have completed the mapping of fields, click Save Mapping & Continue.

4. Use the Scheduling screen to configure schedule-based ingestion, i.e., specify the polling frequency to Rapid7 InsightIDR, so that the content gets pulled from the Rapid7 InsightIDR integration into FortiSOAR™.
   On the Scheduling screen, from the Do you want to schedule the ingestion? drop-down list, select Yes.
   In the “Configure Schedule Settings” section, specify the Cron expression for the schedule. For example, if you want to pull data from Rapid7 InsightIDR every morning at 5 am, click Daily, and in the hour box enter 5 , and in the minute box enter 0:
   
   Once you have completed scheduling, click Save Settings & Continue.

5. The Summary screen displays a summary of the mapping done, and it also contains links to the Ingestion playbooks. Click Done to complete the data ingestion and exit the Data Ingestion Wizard.