Custom Detection Rules

You can write custom detection rules to detect threats that are specific to your environment, industry, or organization. Custom detection rules allow you to take advantage of the same capabilities that are available for out-of-the-box detection rules, including:

If you have questions while writing your rules, you can refer to the Custom Detection Rules FAQ.

Before you begin

Before you start creating custom detection rules, it is important to note that there are a few safeguards in place to ensure fair use across our customer base:

  • Custom detection rules are subject to a throttle rate, which means that if your rule triggers a large quantity of detections in a small time frame, the number of detections sent to investigations is capped at 10 detections per minute.
  • By default, there is a limit of 50 custom detection rules that can be created per organization. If your organization's needs exceed this limit, contact your Customer Success Manager to inquire about a limit adjustment.
  • A custom detection rule may be suspended by Rapid7 at any time if it causes a negative impact on your Rapid7 detection system. Rules that have been deactivated are indicated by a Stopped label. Read more about detection rules that have been stopped.

Create a Custom Detection Rule

You can create a custom detection rule from these locations within InsightIDR:

  • On the Detection Rules page, click the Create Detection Rule button to launch the creation modal.
  • On the Log Search page, click the Query Actions button (•••) > Create Custom Detection Rule to launch the creation modal. If you have any logs selected or a valid LEQL query entered in Log Search, your rule will be pre-populated with the corresponding event type, logs, and query.

Step 1: Name and describe your rule

Enter a name and description for your rule. Optionally, you can provide a recommendation of remediation actions to take when your rule is triggered.

Step 2: Set the rule action and priority

Select a rule action from the dropdown options to determine how InsightIDR should react when your rule conditions are met. You can choose to create an investigation, track a notable event, assess activity, or keep the rule off. Rapid7 recommends initially setting the rule action to Assess Activity to allow you to preview the number of detections your rule will generate for 7 days.

Available rule actions
  • Creates Investigations automatically creates an investigation in InsightIDR when a detection occurs. You can configure email notifications when investigations are created. Use this option when you would like to be notified of events when they happen.
  • Tracks Notable Events automatically adds a notable event to related investigations when a detection occurs. Use this option for events that might provide additional context to help you understand the activity that has occurred.
  • Assess Activity tracks the number of detections that occur and generates a relative activity score over the next 7 days. After 7 days, an Assessment Report is created and the Rule Action is automatically switched off, unless you manually change it. The detection data is not used in investigations. Use this option for events where you would like to track detection activity, but do not want to be notified.
  • Off means rules are not tracked or used in InsightIDR. Use this option for events you do not want to track. Rules that have been turned off do not count towards your custom detection rule limit.

If you select Creates Investigations as the rule action, you can select a priority level that will be applied to investigations created by your rule.

Step 3: Select a data source for your rule

Select the event type and corresponding logs that your rule will apply to. The event type determines the log data your rule detects on. You can refine the data you'd like your rule to apply to by deselecting logs to exclude them from the data set.

Step 4: Define your rule logic and evaluate your query

Use Log Entry Query Language (LEQL) to write the logic for your rule. To view LEQL operators and capabilities, read Components for Building a Query.

Your rule logic query is built using multiple clauses:

  1. The FROM clause defines which data your rule will detect on, and is prepopulated based on the event type you selected in the previous step. To change this value, you must update your event type selection.
  2. The WHERE clause specifies criteria that needs to match for your rule to detect, and is defined by a LEQL query.

Step 5: Add conditions

You can add conditions to complement your rule logic and refine when a detection occurs. Conditions can be useful for creating higher fidelity detection rules and reducing noise.

View in-product examples for additional context

You can view examples of conditions in practice to see how adding conditions work in a real-life scenario. These examples may be helpful if you are configuring conditions for the first time.

Group matched data from specific keys

You can optionally specify up to 3 keys to group related data together. Your rule will only match on events that occur within these groups. You must set a threshold to apply to these keys.

Detect on unique values in a specific key

You can optionally specify a key to count unique values associated with this key. Your rule will only match on events that contain unique values. You must set a threshold to apply to these keys.

Set a threshold

You can optionally add a threshold to customize when a detection will be generated, which may help you reduce noise in your environment. Specify the number of matches that are required to generate a detection and the time frame in which the system must identify them. A threshold can be applied to just your rule logic detailed in your query, or any keys specified.

Note: The maximum number of matches you can specify is 5000, and the maximum time range you can set is 24 hours.

The throttle limit may override your threshold conditions

Custom detection rules are subject to a throttle rate of 10 detections per minute. This means that if your threshold is set to generate detections multiple times within a 1-minute period or less, the number of detections will be capped at 10.

Add exceptions and automation

After you create a custom detection rule, you can add exceptions and automation workflows to your rule to speed up the investigative process.

Add exceptions

You can add exceptions to custom detection rules to modify the rule action and the priority of investigations created by the rule for specific users, assets, and IP addresses. To learn more about modifying your detection rule, read Add Exceptions.

Add automation

You can trigger an InsightConnect automation workflow to run every time a detection occurs for your custom detection rule. These workflows can help your team mitigate manual tasks by containing assets, enriching data, and notifying you when a detection occurs. To learn about how to add automation, read Get started with ABA Automation.

Edit a custom detection rule

You can edit a custom detection rule to modify any of its settings.

To edit a custom detection rule:

  1. Navigate to the Detection Rules page from the left navigation, and select the custom detection rule you’d like to deactivate.
  2. Click the ellipses icon (•••) in the rule’s header, and select Edit Rule.
  3. Make your desired edits and click Save Changes to update your rule. A green banner will appear confirming you successfully edited the rule.

Delete a custom detection rule

You can delete a custom detection rule to stop it from detecting events in your environment. All exceptions for the rule will be also deactivated.

You can still find the rule in your Detection Library for reference by selecting to show Deleted Custom Rules from the Custom Detection Rules filter. All investigations created from the rule will also remain in your Investigations tab.

To delete a custom detection rule:

  1. Navigate to the Detection Rules page from the left navigation, select the custom detection rule you’d like to delete.
  2. Click the ellipses icon (•••) in the rule’s header, and select Delete Rule.
  3. You will be prompted with a modal to confirm the deletion. Click Delete Detection Rule. A green banner will appear confirming you successfully deleted the rule.

Once a detection rule has been deleted, you can restore it following the same steps.

To restore a custom detection rule:

  1. Navigate to the Detection Rules page from the left navigation, select the custom detection rule you’d like to restore.
  2. Click the ellipses icon (•••) in the rule’s header, and select Restore Rule.
  3. You will be prompted with a modal to confirm the restoration. Review the existing Rule Action and Rule Priority and click Restore the Detection Rule. A green banner will appear confirming your rule has been successfully restored.

Stopped detection rules

Detection rules with a Stopped label have been either manually deactivated by Rapid7 for causing an unexpected error, or automatically deactivated for overloading the detection system. If you see a rule with a Stopped label, click Show details within the orange warning banner to view a description of what happened and recommendations to fix the issue.