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

Custom alert monitoring is outside the scope of Rapid7 Managed Services

If you are an MDR customer with a valid InsightConnect license, you can take advantage of the InsightIDR Custom Alert Trigger, however the MDR team will not monitor, triage, or respond to events or threats identified by custom alerts.

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.

How can I access the InsightIDR Trigger?

The InsightIDR Custom Alert Trigger lives in InsightConnect, and is accessible from the API Trigger configuration details panel. The InsightIDR Trigger is available by default to any customer with the required prerequisites. It will only display if you have a valid license for both InsightConnect and InsightIDR or MDR.

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

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

JSON vs. Syslog formatted logs

If a custom alert is triggered by a JSON formatted log, the linked InsightConnect workflow will automatically display all the fields in that log line. If the log line is unstructured (for example raw syslog), only the event.entry field will automatically display. To pass data from any other fields in an unstructured log line, you must manually add those fields to the workflow.

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.

Your workflow must use the InsightIDR Custom Alert Trigger

Only workflows with the “InsightIDR Custom Alert” trigger type can be linked to InsightIDR custom alerts.

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. Custom Alerts and InsightConnect.
    • 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.

Custom alert data containing raw syslog

If your log line is formatted in JSON, InsightConnect will automatically populate your custom alert fields. 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.

To add a workflow step:

  1. Under your workflow trigger, click +. Custom Alerts and InsightConnect
  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. Custom Alerts and 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. Custom Alerts and InsightConnect
  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]}} Custom Alerts and InsightConnect
  9. Click Preview, and review the variables you selected. Custom Alerts and InsightConnect
  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. Custom Alerts and InsightConnect
  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.

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

If the workflow is inactive or a draft, a label will be appended to the workflow name. Workflows with these statuses will not run until they’re activated.

Custom Alerts and InsightConnect 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:

Custom Alerts and InsightConnect

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. Custom Alerts and InsightConnect
  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. Custom Alerts and InsightConnect

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. Custom Alerts and InsightConnect You will see a list of the workflows that have been associated. Custom Alerts and InsightConnect

Deactivated or deleted workflows

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