Detection Rule Exceptions

Detection rule exceptions modify the rule action and 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.

For more information on detection rules, visit Detection Rules.

Explore exceptions

There are 2 ways to explore your exceptions:

• To view all exceptions across your organization, navigate to Detection Rules > Exceptions.
  • From this page, you can click an exception's name to open the Exception Details panel where you can view the details, logic, audit log, and any assessment reports for the exception. You can also click the associated detection rule's name to open the rule details panel.
• To view exceptions associated with a specific rule, navigate to Detection Rules > Detection Rule Library and click a Detection Rule name or the Exceptions value for a rule to open the rule details panel.

Exception status

Exception status is viewable from the Exceptions page or the rule details panel. Exceptions can be either active, inactive, or deleted. If an exception is active, it will perform its associated action when triggered. An exception may be inactive if it recently completed assessment, it has invalid LEQL variables, or Rapid7 has turned it off for performance reasons. Deleted exceptions can be recalled at anytime using the Deleted filter.

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 has occurred, overriding the rule-level Action and Priority selections.

To view total exception matches for a Detection Rule:

1. Navigate to Detection Rules > Detection Rule Library.
2. Search or filter for a particular exception.

The number of exception matches is displayed in the main table.

To view exception matches for a given exception:

Assessment reports

Assessment reports are generated for 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 is automatically switched off, unless you manually change the Rule Action.
• 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.

To view assessment reports:

Add exceptions

You can add exceptions from the rule details panel in the Detection Rules Library. Visit Modify Detection Rules for details.

Step 1: Open the rule details panel

1. From Exceptions, find and select the detection rule you want to add an exception for. The rule details panel opens.
2. Click the Exceptions tab.
3. Click Create New Exception.

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 matched data can help you determine which key value pairs you’d like to add an exception for.

After expanding an alert or event payload, you can click Add key-value pair to exception 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.

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

Select an exception-level Rule Action from the dropdown menu to determine how InsightIDR should react when your exception conditions are met. This setting overrides the rule-level action of the Detection Rule.

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:

• 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 Add key-value pair.
• 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.

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
} 

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 are added to your new query.

Preview your exception

Click Preview to see how your exception would have affected past payloads generated by this Detection Rule.

The Exception Preview modal opens and populates 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 Suppress Activity, 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.

Manage exceptions

You can edit or delete existing exceptions from the Exceptions page or from the rule details panel. For details on editing and deleting exceptions from the rule details panel visit Modify Detection Rules.

To edit an exception:

To delete an exception: