Rapid7 InsightIDR v2.0.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.

Version information

Connector Version: 2.0.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.0.0

Following enhancements have been made to the Rapid7 InsightIDR Connector in version 2.0.0:

• The field type of the Status parameter, in the action Get Investigation List, has been changed from multiselect to a text field that accepts comma-separated values.
• Added the following parameters to the action Get Investigation List:
  • Source
  • Priority
  • Assignee Email
  • Sort
  • Multi Customer
  • Tags
• Updated the output schema of the action Get Investigation List.
• In the action Close Investigations, the Source parameter has been changed from select to a text field.
• Added the following parameters to the action Close Investigations:
  • Disposition
  • Detection Rule RRN
• Added the following actions:
  • Create Investigation
  • Update Investigation
  • Get Investigation Details
  • Get Alerts Associated With Investigation
  • Search Investigations
  • Create Comment
  • Get Comments
  • Delete Comment
• Deprecated the action Update Investigation Status.

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 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.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
• Create Comment
• Create Investigation
• Delete Comment
• Get Alerts Associated With Investigation
• Get Comments
• Get Investigation Details
• Get Investigation List
• 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 connector upgrade and delete.