Custom Alerts & InsightConnect workflows

You can automate your team's response to threats identified by custom alerts using the combined power of InsightIDR and InsightConnect. When these Rapid7 Insight products work together, you can create workflows that automatically initiate a predefined action (or actions) in your environment each time a custom alert rule is triggered. For example, you can configure workflows to post notifications to a Slack channel when an alert threshold is reached, or send email notifications to your security team when someone signed onto the VPN violates a company policy.

To use automation with your custom alert rules, you must have a valid license for InsightConnect and an orchestrator installed in your environment. If you do not currently use InsightConnect but would like to take advantage of this capability, talk to your Customer Advisor and they’ll help you get started.

Prerequisite Checklist

• A valid license for InsightIDR or Managed Detection & Response Services
• A valid license for InsightConnect
• The Insight Orchestrator installed on your network

How it works

Custom alerts are generated in InsightIDR whenever an event matches specified conditions, such as a log pattern. Your custom alert data is passed to the InsightIDR Custom Alert Trigger, which is a pre-built API trigger that contains all the fields needed to send custom alert data to InsightConnect, no additional configuration required. InsightConnect uses the InsightIDR Custom Alert Trigger to listen for behavior that your alert has detected. When a custom alert identifies a threat, the trigger sends that data to your workflow, which kicks off any predefined actions associated with the workflow.

Get Started

To set this up, you’ll first need to create a new workflow in InsightConnect using the InsightIDR Custom Alert Trigger. You’ll then add the workflow to your Custom Alert in InsightIDR.

1. Create a new workflow in InsightConnect
2. Create or edit a custom alert in InsightIDR
3. Manage your custom alerts

How to link a custom alert with an InsightConnect Workflow

To trigger automated actions using your custom alerts, you must create a workflow in InsightConnect that uses the InsightIDR Custom Alert trigger.

Create a new workflow in InsightConnect

In this section you will create a workflow with the InsightIDR Custom Alert Trigger and then configure additional workflow steps based on your use case.

Step 1: Add a new workflow

1. From the InsightConnect left menu, click Workflows and select either Active or Draft. You can add workflows from either page.
2. Click Add Workflow.
3. Click Start from Scratch. The Create New Workflow panel will appear.
   • Enter a unique and easily identifiable workflow name. You will enter this workflow name in InsightIDR in a later step.
   • Enter a workflow description, and optionally add tags for labeling purposes.
   • Enter how much time you think this task would take you to complete manually.
   • Click Create. The Choose a Trigger panel will appear.
4. In the From Insight Platform section, click InsightIDR Custom Alert Trigger, and click Continue. .
   • Enter a name for your trigger, such as Custom Alert Trigger, and scroll to the bottom of the panel. (The other fields are preconfigured to contain details about the custom alert and the log in InsightIDR, such as the name and ID, as well as information about the specific log line that caused the custom alert to run.)
   • Click Save Step.
5. In the How To panel, review the guidance for adding your workflow to InsightIDR. We’ll also cover those steps in a later section.
6. Click Close to exit the panel.

Step 2: Add a step to your workflow

InsightConnect workflow steps allow you to define the actions and tasks you want to automate. For example, if you want to receive a Slack notification when a threshold is reached for a custom alert, you would configure that action using a ChatOps step. For detailed information about workflow steps, see Workflow Steps in the InsightConnect documentation.

To add a workflow step:

1. Under your workflow trigger, click +.
2. Select a workflow step type.
3. Enter a name for the step.
4. Under Type, leave the default value.
5. Under Output Format, select +. In the next few steps you’ll identify the fields in your custom alerts that you want to pass to InsightConnect.
6. Find and select the Custom Alert Trigger event.entry variable. This represents the log line that caused the alert to run, and is required.
7. Under Output format, select +.
8. Find and add any additional variables that correspond to specific fields in your custom alert. If your data contains raw syslog, InsightConnect will populate the event.entry field, but you must manually add the destination_user and any additional fields you want to send. The format for the destination_user field is: {{["Demo"].[event].[entryObject].[destination_user]}}
9. Click Preview, and review the variables you selected.
10. Click Save Step.
11. Add any additional workflow steps that you need.

Step 3: Activate the workflow

Once you’ve added all your workflow steps, click Activate in the top right corner of the workflow builder.

Create or edit a custom alert in InsightIDR

The final step in linking your custom alert to an InsightConnect workflow is to select your workflow from the Custom Alert's Notification section.

1. From the InsightIDR left menu, click Detection Rules.
2. Click the Custom Alerts tab.
3. To link your workflow to a new or existing alert, do one of the following:
   • New custom alert: click Add Alert.
   • Existing custom alert: select the alert you want to link to, and skip to step 5 of this procedure.
4. For new alerts, do the following:
   • Enter an alert name and description, and click Next.
   • Select the log you want to use as the basis for your alert, and click next.
   • Select a trigger.
   • Click Next.
5. In the Alert Notifications section, click the InsightConnect Workflow tab.
6. Select the workflow you want to link. You can select an InsightConnect workflow that has been previously associated with a custom alert, or a previously unlinked workflow.

7. If you select a new workflow that has not been previously linked, you will also see a list of all available workflows. 8. After selecting the workflow, it will appear above the input field.

9. Save the custom alert. The workflow in InsightConnect will be triggered when an event generates a custom alert.

This is an example of an artifact in InsightConnect showing some of the fields that were sent as part of the custom alert:

Manage your custom alerts

You can view a list of associated alert recipients, workflows that are associated with an alert, and whether workflows have been deactivated or deleted.

View custom alert recipients

1. From the Custom Alerts screen, click the Labels & Notifications link at the top of the page.
2. In the Labels and Notifications management page, click the Notification Targets tab to see all the recipients that have been configured for custom alerts.

View associated workflows

You can view all workflows associated with custom alerts from the Notifications Targets tab on the Labels and Notifications management page. Click the InsightConnect Workflow button. You will see a list of the workflows that have been associated.

Deactivated or deleted workflows

If a workflow has been deactivated or deleted, you will see the following banner dispalyed: