Basic Detection Rules & InsightConnect workflows

Custom Alerts have been renamed to Basic Detection Rules

Starting in May 2023, we will begin rolling out detection terminology changes to better reflect the functions of the Custom Alerts feature:

  • Custom Alerts are now called Basic Detection Rules
  • Pattern Detection Alerts are now called Log Pattern Detection Rules
  • Inactivity Detection Alerts are now called Log Inactivity Detection Rules
  • Change Detection Alerts are now called Log Change Detection Rules

The functions of these features remains the same. These terminology changes will be implemented throughout the documentation and in InsightIDR.

You can automate your team's response to threats identified by basic detection rules 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 basic detection rule is triggered. For example, you can configure workflows to post notifications to a Slack channel when a 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 basic detection 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

Basic detection rule 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 InsightIDR triggers, however the MDR team will not monitor, triage, or respond to events or threats identified by basic detection rules (formerly known as custom alerts).

How it works

Basic detection rules are generated in InsightIDR whenever an event matches specified conditions, such as a log pattern. Your basic detection rule data is passed to the InsightIDR trigger, which is a pre-built API trigger that contains all the fields needed to send basic detection rule data to InsightConnect, no additional configuration required. InsightConnect uses the InsightIDR trigger to listen for behavior that your rule has detected. When a basic detection rule 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 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 trigger. You’ll then add the workflow to your basic detection rule in InsightIDR.

  1. Create a new workflow in InsightConnect
  2. Create or edit a basic detection rule in InsightIDR
  3. Manage your basic detection rules

To trigger automated actions using your basic detection rules, you must create a workflow in InsightConnect that uses the InsightIDR trigger.

JSON vs. Syslog formatted logs

If a basic detection rule is triggered by a JSON formatted log, the linked InsightConnect workflow will automatically display all the fields in that log entry. If the log entry 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 entry, 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 trigger and then configure additional workflow steps based on your use case.

Your workflow must use the InsightIDR trigger

Only workflows with the “InsightIDR Custom Alert” trigger type can be linked to InsightIDR basic detection rules.

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 Basic Detection Rule Trigger, and scroll to the bottom of the panel. (The other fields are preconfigured to contain details about the rule and the log in InsightIDR, such as the name and ID, as well as information about the specific log line that caused the basic detection rule 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 basic detection rule, you would configure that action using a ChatOps step. For detailed information about workflow steps, see Workflow Steps in the InsightConnect documentation.

Basic detection rule data containing raw syslog

If your log entry is formatted in JSON, InsightConnect will automatically populate your basic detection rule 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 basic detection rule 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 rule 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 rule. 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 basic detection rule in InsightIDR

The final step in linking your basic detection rule to an InsightConnect workflow is to select your workflow from the Basic Detection Rule's Notification section.

  1. From the InsightIDR left menu, click Detection Rules.
  2. Click the Basic Detection Rules tab.
  3. To link your workflow to a new or existing basic detection rule, do one of the following:
    • New basic detection rule: click the Detection Rules button.
    • Existing basic detection rule: select the rule you want to link to, and skip to step 5 of this procedure.
  4. For new rules, do the following:
    • Enter a rule name and description, and click Next.
    • Select the log you want to use as the basis for your rule, and click next.
    • Select a trigger.
    • Click Next.
  5. In the 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 basic detection rule, 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 basic detection rule. The workflow in InsightConnect will be triggered when the basic detection rule is triggered.

This is an example of an artifact in InsightConnect showing some of the fields that were sent as part of the basic detection rule:

Custom Alerts and InsightConnect

Manage your basic detection rules

You can view a list of associated notification recipients, workflows that are associated with a basic detection rule, and whether workflows have been deactivated or deleted.

View basic detection rule recipients

  1. From the Basic Detection Rules 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 basic detection rules. Custom Alerts and InsightConnect

View associated workflows

You can view all workflows associated with basic detection rule 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