Modify Detection Rules

You can modify detection rules to better suit the needs of your team and your environment. In the Detection Rule Library tab of the Detection Rules page, click into a detection rule to open the Rule Details peek panel. Here, you can customize the rule by:

You can also refer to the Relative Activity score to help you determine which detection rules may benefit from customization.

Modifying detection rules as an MDR customer

If you are a Managed Detection and Response (MDR) customer, the Rapid7 SOC team will manage tuning supported detection rules to your environment. You are able to make modifications to rules that are the responsibility of your organization, including changing the Rule Action, Rule Priority and adding exceptions. You can also filter detection rules by those managed by your organization, and those managed by the MDR SOC by using the Responsibility filter on the Detection Library tab.

Change Rule Action

You can configure the Rule Action to change how InsightIDR reacts when a detection occurs.

Available Rule Actions include:

  • 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.

To change the Rule Action:

  1. Open the Rule Details peek panel by clicking on a detection rule.
  2. In the Rule Action dropdown, choose whether you’d like the detection rule to Create Investigations, Tracks Notable Events, or be switched Off.

You can also change the Rule Action for multiple detection rules at a time:

  1. Select the checkboxes in the Detection Rule Library table for the detection rules you’d like to make changes to. At this time, you can only select detection rules visible on your current page. Navigating to another page or applying filters will clear your current selections.
  2. Bulk action options will appear. Choose the Rule Action you’d like to apply across your selected detection rules.
  3. A confirmation message will appear, indicating your changes were made successfully.

Change Rule Priority

Rule Priority is applied to investigations created by the detection rule. You can configure the Rule Priority to sort and filter your investigations by those most important to your organization.

To change the Rule Priority:

  1. Open the Rule Details peek panel by clicking on a detection rule.
  2. In the Rule Priority dropdown, select from one of these options: Critical, High, Medium, Low or Unspecified.

You can also change the Rule Priority for multiple detection rules at a time:

  1. Select the checkboxes in the Detection Rule Library table for the detection rules you’d like to make changes to. At this time, you can only select detection rules visible on your current page. Navigating to another page or applying filters will clear your current selections.
  2. Bulk action options will appear. In the Rule Action dropdown, you must select Creates Investigations to be able to apply a priority.
  3. Select the priority you’d like to apply from the Rule Priority dropdown.
  4. A confirmation message will appear, indicating your changes were made successfully.

Add exceptions

You can add exceptions to detection rules to modify the rule action and the priority of investigations created by the rule for specific users, assets, IP addresses, etc. For example, you may want to add exceptions to:

  • Increase the Rule Action to Creates Investigations and increase the Rule Priority to Critical for events involving C-suite level users. Investigations created from these user events would appear on the Investigations page automatically sorted as Critical Priority.
  • Increase the Rule Action to Creates Investigations and increase the Rule Priority to High if an asset’s geolocation originates from specific countries. Investigations created from these asset’s events would appear on the Investigations page automatically sorted as High Priority.
  • Decrease the Rule Action to Tracks Notable Events or Off for events detected by users authorized to be performing those actions. Priority would not apply as it only affects investigations.

Step 1: Open the rule details panel

  1. From the Detection Rule Library tab, find and select the detection rule for which you want to add an exception. The Rule Details page opens.
  2. Click the Exceptions tab.
  3. Click the Create an Exception button. This is where you'll specify the exception details.

Step 2: Review content in your environment that matched this detection rule

If the logic of this rule has matched content in your environment, you can review data from recent alerts and notable events caused by the detection(s). This match data can help you determine which key value pairs you’d like to add an exception for.

You can hover over desired key value pairs and click the Add key-value pair to exception button to automatically add them to your exception. If you would like to edit these key-value pairs, or add new ones, you can do so in Step 4: Add key-value pairs.

Step 3: Select an exception-level Rule Action and Priority

Select an exception-level rule action from the dropdown options to determine how InsightIDR should react when your exception conditions are met. This setting will override the rule-level action of the detection rule.

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 would have been affected by your exception over the next 7 days. After 7 days, an Assessment Report is created and the exception is automatically deactivated, unless you manually change it. 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.

If you select “Creates Investigations” as the exception-level rule action, you can optionally select an exception-level priority for investigations created from the key-value pair(s) you define. If you choose not to select an exception-level priority, your exception will inherit the rule priority.

Step 4: Define exception logic

You can define the logic of your exception with key-value pairs, or a Log Entry Query Language (LEQL) query.

Define exception logic with key-value pairs

Enter the details for one or more key-value pairs that you would like to add an exception for. A key-value pair consists of two elements: a key that defines the data set, and a value that belongs to the set.

Use these best practices when specifying key-value pairs:

  • Review the match content generated by this detection rule to hover over key-value pairs and easily add them to your exception.
  • Use exception operators to define the relationship between the key and the value. You can also add multiple pairs using the AND operator by clicking the Add key-value pair button.
  • When entering your key-value pair, you do not need to include quotes or escape special characters by using backslashes. For example, if your value is written in a JSON file as "C:\\windows\\command.exe", you should enter C:\windows\command.exe into the value field. If you do escape special characters when entering your value, a message will pop up giving you the option to remove them.
Add nested key-value pairs

If your key-value pair is nested within other keys, use a period to define the path. For example, in the following data set, owner, description, and author are nested under the key exe_file, which is nested under process:

json
1
"process": {
2
"start_time": "2021-10-08T19:07:21.075Z",
3
"name": "ADLWRCT.exe",
4
"pid": 13800,
5
"session": 64,
6
"exe_file": {
7
"owner": "NT AUTHORITY\\SYSTEM",
8
"description": "Adware products",
9
"author": "LunarWinds"
10
}
11
}

If you wanted to add an exception for author, you would enter process.exe_file.author under key and LunarWinds under value.

Define exception logic using a LEQL query

Click the Convert to LEQL button to write your exception logic using a LEQL query. Any key-value pairs that you have entered for this exception will be added to your new query.

Reverting to key-value pair mode will clear your query

You can click the Revert to key-value pairs button to return key-value pair mode. This will clear all data from your query, and any exception logic you have entered will be lost.

Preview your exception:

Click the Preview button to see how your exception would have affected past payloads generated by this detection rule.

The Exception Preview modal will open and populate with the 20 most recent payloads from the last 30 days containing the key-value pair(s) you entered. This payload data was generated by alerts and notable events when the rule logic for this detection rule matched data in your environment.

Payloads are labeled Affected and Unaffected to indicate whether your exception would have caused a different Rule Action or Rule Priority to apply, had the exception been in effect. For example, if your exception sets the Rule Action to Off, the alerts corresponding to affected payloads would have been suppressed.

You can also modify the view to better find what you are looking for:

  • Use the Show dropdown to see either Affected or Unaffected payloads or both.
  • Click Select keys to show to display only specified keys within the payload.
  • Click Collapse all dates or use the caret buttons for each individual payload to hide the payload data and only display an overview.

Step 5: Add a name and a note

Enter an Exception Name, and optionally add a note to provide additional context about your exception.

Click Create Exception to save.

Exception Operators

Use exception operators to define the relationship between a key and a value in a key-value pair. Select the checkbox to activate or deactivate case-sensitive operators.

Case-sensitive operators

OperatorDescription
isThe key-value pair will be excluded from the rule action when the value is the specified text.
containsThe key-value pair will be excluded from the rule action when the value contains the specified text.
starts-withThe key-value pair will be excluded from the rule action when the value starts with the specified text.
ends-withThe key-value pair will be excluded from the rule action when the value ends with the specified text.
matches regexThe key-value pair will be excluded from the rule action when the value matches the specified regex.
matches CIDRThe key-value pair will be excluded from the rule action when the value matches the specified CIDR IP addresses.

Case-insensitive operators

OperatorDescription
iisThe key-value pair will be excluded from the rule action when the value is case-insensitively the specified text.
icontainsThe key-value pair will be excluded from the rule action when the value case-insensitively contains the specified text.
istarts-withThe key-value pair will be excluded from the rule action when the value case-insensitively starts with the specified text.
iends-withThe key-value pair will be excluded from the rule action when the value case-insensitively ends with the specified text.

Edit exceptions

You can edit an exception after it has been created.

  1. Open the Rule Details peek panel by clicking on a detection rule and navigate to the Exceptions tab.
  2. Click the pencil icon for the exception you would like to edit.
  3. Make your desired modifications and click Save changes.

Delete exceptions

Deleting exceptions is permanent and cannot be undone.

  1. Open the Rule Details peek panel by clicking on a detection rule and navigate to the Exceptions tab.
  2. Click the trash icon for the exception you would like to delete.
  3. In the pop up, confirm you would like to delete the exception.

View Exception Matches

When data in your environment matches the key-value pairs defined by your exception, an Exception Match is recorded. This value indicates how many times an exception to the detection rule has occurred, overriding the rule-level Action and Priority selections.

To view the number of Exception Matches over the last 30 days:

  • Click into a detection rule and navigate to the Exceptions tab. You will see the number of Exception Matches under the name of each of your exceptions.
  • Within the table on the Detection Rule Library page, locate the Exception Matches column. Here, you can view the total number of exception matches per detection rule over the last 30 days.

View Assessment Reports

Assessment reports are generated for detection rules and exceptions after the 7-day Assess Activity period is complete. To configure Assess Activity, you can change the Rule Action for detection rules and exceptions. Assess Activity allows you to:

  • Evaluate the activity that a detection rule generates to ensure the rule is not creating unnecessary noise. After the 7-day Assess Activity period, the Rule Action is automatically switched off, unless you manually change it.
  • Evaluate how an exception would affect the number of detections generated to ensure the exception is performing as expected. After the 7-day Assess Activity period, the exception is automatically deactivated, unless you manually change the Rule Action.

You can view the results of assessments from the last 7 days by clicking Assessment Reports on the Detection Management page. After this period, you can find the assessment results by navigating to the rule details and clicking the Modification History tab.

Understand Relative Activity

Relative Activity is a score of 1-1000 given to each detection rule that is calculated based on these parameters:

  • How often the Rule Logic matches data in your environment per asset.
  • How often the Rule Logic matches data in your environment per minute.
  • How often the Rule Logic matches data in your environment relative to other detection rules.
  • How often a detection rule is throttled relative to other rules.

The score is calculated over a rolling 24-hour period, and takes into account any exceptions that switch off the rule and any threshold conditions that have been set.

You can use the Relative Activity score to:

  • Identify detection rules that are set to Assess Activity that might cause frequent investigations or notable events if the Rule Action is changed.
  • Determine which detection rules may benefit from additional tuning by adding exceptions or configuring the Rule Action.

We are continuing to evaluate Relative Activity

The Relative Activity score may evolve over time as Rapid7 refines its capabilities and analyzes additional use cases.