InsightConnect Workflow

Abstract

This is an overview of the Rapid7 InsightConnect automation that I created collaboratively with Caydon Thomas during my internship at National Heritage Academies (NHA). It reduces that amount of time that security analysts and support technicians spend initiating and tracking endpoint remediation tickets by allowing one to interactively build and submit service requests. Error handling, execution status updates (analogous to return codes), help, and troubleshooting features are built-in.

Diagram

Documentation

A copy of the documentation that I created for this workflow can be read below. Some minor details have been changed or omitted to protect potentially sensitive information about how the automation has been integrated into NHA’s operations.

Description

This workflow is intended to make it easier to send tickets to TSC when a security incident occurs. When this workflow is enabled, you can post a special message in Slack to interactively build and submit a TDX ticket to the email queue via Slack message replies and reactions. Before sending the ticket, you will be allowed to select a template and review the email.

The following ticket templates are supported:

Template	Requires…	Subject	Body
Unwanted Program	`email`, `hostname`	[Intentionally omitted]	[Intentionally omitted]
Malware (isolated)	`email`, `hostname`	[Intentionally omitted]	[Intentionally omitted]
Malware (un-isolated)	`email`, `hostname`	[Intentionally omitted]	[Intentionally omitted]
Password Reset (account compromised)	`email`	[Intentionally omitted]	[Intentionally omitted]
Password Reset (suspicious authentication)	`email`	[Intentionally omitted]	[Intentionally omitted]

Example

@Rapid7 InsightConnect tdx [email protected] hostname

@Rapid7 InsightConnect mentions the Rapid7 InsightConnect user on Slack
tdx is the workflow trigger phrase
[email protected] is the email of the user in the ticket
hostname is the hostname of the device in the ticket

Usage

To use this workflow, mention the Rapid7 InsightConnect user from the workflow trigger channel in a message that contains the workflow trigger phrase and any information required by your ticket template. The trigger phrase, user email, and device hostname can be supplied in any order (space-separated).

Every message must include at least:

the @Rapid7 InsightConnect mention
the workflow trigger phrase
the email address of the user in the ticket
- note: this is the email address of the user that the ticket is about - not the address that sends or receives the ticket email itself

Caveats

A TDX service has been configured to monitor the ticket queue inbox for emails generated by this workflow with specific/special subjects. Do not change ticket email subjects in this workflow without notifying the team responsible for the TDX service. Otherwise, the process that TSC uses to update IT Security on ticket resolutions will break.

Parameters

The behavior of this workflow can be changed with the following parameters:

Parameter	Description	Notes
`Trigger Channel`	Slack channel that the workflow will monitor for and respond to messages in.
`Trigger Regex`	Regex that, when matched, triggers the workflow when the Rapid7 InsightConnect user in mentioned in Slack.
`Email Regex`	Regex pattern used to match an email address.
`Hostname Regex`	Regex pattern used to match device hostnames.
`Email Sender`	Email address used to send the ticket message.
`Email Destination`	Email address that will receive the ticket message from the email sender.
`Unwanted Program Subject`	Email subject used for unwanted program tickets.	see caveat 1
`Unwanted Program Body`	Email body used for unwanted program tickets.
`Malware Subject`	Email subject used for malware tickets.	see caveat 1
`Malware Body - Isolated`	Email body used for malware tickets where the device has been isolated.
`Malware Body - Unisolated`	Email body used for malware tickets where the device is still un-isolated.
`Password Reset Subject`	Email subject used for password reset tickets.	see caveat 1
`Password Reset Body - Account Compromised`	Email body used for account compromised password reset tickets.
`Password Reset Body - Suspicious Authentication`	Email body used for suspicious authentication password reset tickets.

Improvements

Because it is possible to get the email address of the analyst that sends the command in Slack, we could have an option to send a copy of the final ticket email message to the user’s inbox for additional confirmation that the ticket was submitted.