Creating and managing custom detection rules

Overview

Blumira's Incident Detection Engineers build and maintain the detection rules that monitor your logs. If your organization is entitled to custom detections, you can also build your own detection rules on the Detection Rules page (Settings > Detection Rules), without a request to Blumira. A custom detection rule belongs to your organization. It generates findings the same way that a Blumira-built rule does.

With custom detections, you can do the following:

• Copy an existing real-time detection rule, and then adjust it for your environment.
• Build a new real-time detection rule from scratch using up to 10 data types.
• Turn a saved report into a custom detection.
• Preview a rule against your recent logs to see how much it matches.
• Write the analysis that a responder reads on every finding from your rule.

Detection rule basics

A detection rule watches one type of log for a specific pattern of activity. When that pattern appears in your logs, Blumira creates a finding and notifies your team.

Every custom detection rule has the following parts:

Roles

Custom detections require both an entitlement on your account and the correct role. The following table describes what each role can do:

Identifying custom detections

On the Detection Rules page (Settings > Detection Rules), filter the list using the "Authored custom detections" preset. In the table, a custom detection rule shows a Custom badge next to the rule name. Only real-time detection rules carry the badge.

The Status column shows the current state of each rule, including any change in progress. See Checking the status of a detection rule.

Hover on the badge to see how the rule was created. The tooltip shows one of the following:

• Created for your organization: someone in your organization authored the rule.
• Blumira built for your organization: Blumira built the rule for your organization alone.
• Blumira built for your organization group: the rule belongs to your organization group. This tooltip also appears on a sub-account when an MSP parent organization deploys one of its own custom rules to that sub-account.

Creating a custom detection by cloning

A clone is the fastest way to create a custom detection rule, because it starts from logic that already runs in your environment. You can clone any real-time detection rule that Blumira provides.

To clone an existing detection rule, do the following:

1. On the Detection Rules page (Settings > Detection Rules), locate a real-time detection rule to base your rule on.
2. Click the rule's row to open the actions menu, and then click Clone.
3. In the Clone detection window, edit the default or type a new name in the Name box.
4. Click Clone.

Blumira creates an editable copy that your organization owns. The clone keeps the conditions of the original rule. To change those conditions, see Editing the detection logic.

Changing the log types on a clone

To change the log types that a clone reads, use the Data source list in the Edit detection window. Blumira warns you before you remove one of the original log types.

The following limits apply to a clone:

• If the original rule specifies log types, every OR group in the clone must keep at least one log type.
• You cannot exclude a log type or match log types with a pattern.
• A rule can read up to 10 log types.
• Log type rows inherited from the original rule are read-only in the conditions.

Creating a custom detection from scratch

Build a rule from scratch when no existing detection rule covers the activity that you want to detect.

To build a custom detection rule from scratch, do the following:

1. Navigate to the Detection Rules page (Settings > Detection Rules).
2. Click Create Custom Detections.

3. In the Data source list, select up to 10 log types.

   Tip: Blumira ingests some vendors through more than one connector, so the list contains similar names. Each entry ends with its raw type value, such as (type=office365_aad). Match that value to the connector that sends your logs. A rule on the wrong entry previews zero matches.
4. Review the locked first condition. Blumira adds a read-only "Type is" row that scopes the rule to your data source. You cannot edit or remove this row.

5. Add your own conditions below the locked row. For each condition, select a field, select an operator, and then type a value.

   Note: The operators available to you depend on the type of the field that you select. You can group conditions with AND, OR, and NOT, up to four levels deep.
6. Click Preview, and then review the result. See Previewing a custom detection.
7. Select a Category and a Finding priority.
   Note: Risk findings are always priority P3 and do not support automated host isolation.
   
8. Write the Analysis for the rule. See Writing the Analysis for a finding.
9. Click Create detection.

Creating a custom detection from a report

If you already built a report in Report Builder that finds the activity you care about, you can turn it into a custom detection rule. Blumira fills in the data sources, name, and conditions from the report.

To create a custom detection rule from a saved report, do the following:

1. Navigate to Report Builder, and then open your saved reports.
2. In the row for the report, click the Convert Report to Detection icon.
   
3. On the Create Custom Detection page, review the data sources, name, and conditions that Blumira filled in.
   
4. Finish the rule as described in "Creating a custom detection from scratch," starting with the preview.

To create a custom detection rule from the report that you are building, open the more options menu (…) in Report Builder, and then click Create Detection.

The option to create a custom detection appears only on custom reports that your organization saved in Report Builder. It does not appear on global reports that Blumira provides; however, you can save a global report as a custom copy then use your report copy to build your custom detection.

Blumira cannot convert every report. If a report cannot be converted, Blumira shows the reason in the row or as a tooltip. A report cannot be converted to a rule when it does any of the following:

• uses aggregation
• uses greater than or less than comparisons
• filters on log type, or includes more than 10 log types
• has a filter with an empty value
• uses OR groups in Report Builder
• nests conditions deeper than the detection builder allows
• uses Contains or Regex on a field that is not text, such as a timestamp
• uses Contains with an accented capital letter, such as Ü

Note: A Contains filter becomes a case-insensitive match in the rule. Blumira does not copy the time range of the report.

Previewing a custom detection

Blumira requires a successful preview before it saves new or changed detection logic. A preview protects your account from a rule that matches far more activity than you expect.

A preview reports the following:

• the number of matches across a recent window of your logs
• the projected number of matches per day
• whether that projection stays within the limit for your account
• a sample of the events that matched

A preview returns one of three outcomes:

• The projected volume is within the limit, and you can save the rule.
• The projected volume is close to the limit. You can save the rule, but consider whether you want this many findings per day.
• The projected volume exceeds the limit. Narrow your conditions, and then preview again. Blumira does not save a rule in this state.

MSP: Deploying to sub-accounts

If you are an MSP managing customer sub-accounts, the custom detections that you create deploy automatically to your eligible sub-accounts. See Deploying and managing custom detections as an MSP.

Editing a custom detection

After creating and saving a new rule, you can edit the custom detection rule's details and logic. To edit a custom detection rule, do the following:

1. Navigate Detection Rules.
2. In the Rules table, locate a custom detection rule that your organization authored.
3. Click the rule's row, and then click Edit.
4. In the Edit detection window, update any of the following:
   • Name, which is required
   • Description
   • Cooldown (hours), between 1 and 168
   • Category
   • Finding priority
   • Analysis
5. Click Save.

Editing the detection logic

You can also change the conditions of a custom detection rule that your organization authored. A change to the conditions changes how much the rule matches, so Blumira requires a preview before it saves.

To change the conditions of a custom detection rule, do the following:

1. Open the rule in the Edit detection window, as described above.
2. Adjust the rule's conditions.
   Note: Blumira clears the preview whenever you change the conditions. If you edit the conditions after a preview, preview again before you save.

3. Click Preview. Blumira runs your updated conditions against your recent logs and reports the matches it found for the past 7-day period and the projected matches per day.

   Note: If you get zero results, it might be because you selected an incorrect data source. Verify that you have the correct source selected. A custom detection will save even if the results are empty.
4. Review the preview. If the projected volume is too high, tighten your conditions, and then preview again.
5. Click Save.

Note: Blumira applies safety limits to custom detection logic. For example, a condition cannot match every event, and there is a limit on how deeply you can nest conditions. If Blumira blocks a save, adjust the condition that it flags, and then preview again.

Editing a cloned detection

A clone starts with the logic of its source detection. These rules apply when you edit it:

• If the source detection uses log types, every OR branch of your clone must keep at least one log type.
• You cannot exclude a log type or match log types with a pattern.
• A detection can use up to 10 log types.
• The analysis can include only fields that the detection collects.
• Use the log type picker to add or remove log types. If you add conditions, Blumira warns you before you narrow it below the original log types.
• You cannot add log type as a condition. Log type rows inherited from the source are read-only.

Writing the Analysis for a finding

The analysis is the write-up that Blumira shows on every finding from your rule. A clear analysis explains to a responder both what was detected by the rule and the recommended next steps. The analysis cannot be empty, and it is limited to 20,000 characters.

To write or update the analysis for a custom detection rule, do the following:

1. Open the rule in the Edit detection window, as described above.
2. Scroll to the Analysis section.

3. Type your responder-facing summary. 

   Tip: You can apply bold, italics, underline, strikethrough, lists, quotes, code blocks, links, and headings.
4. (Optional) To include a value from the event that triggered the finding, click Insert field, and then select one of the rule's evidence fields. Blumira replaces the placeholder with the real value when a finding fires. If the value is absent from an event, Blumira shows a short fallback note instead of a blank.
5. Click Save.

Blumira blocks the save and explains the problem if a placeholder is incomplete or references a field that the rule does not return.

Enabling and disabling a custom detection

Use the enable and disable control on the rule the same way that you use it for a Blumira-built rule. After you confirm, the confirmation window stays open until Blumira accepts the change. If the change fails, the window shows the reason instead of a generic error.

Blumira does not apply the change immediately. Until it does, the Status column shows “Pending enable” or “Pending disable.” Most changes finish within a few minutes.

Checking the status of a detection rule

On the Detection Rules page, the Status column of the Rules table shows the current state of each rule. To display only the rules with a change in progress, select Pending in the Search preset list.

Deleting a custom detection

Verify the exact rule that you want to remove before you delete it. Blumira cannot recover a deleted custom detection rule. 

To delete a custom detection rule and stop it from generating findings, do the following:

1. Navigate to the Detection Rules page (Settings > Detection Rules).
2. Locate a custom detection rule that your organization authored.
3. Open its action menu, and then click Delete.
4. In the confirmation window, click Confirm.

Limits and guardrails

Blumira applies the following limits to protect the performance and stability of your account:

• Allotment: Your organization can have up to 50 custom detection rules. Blumira checks this limit when you create a rule and explains the limit if you reach it. Modifying Priority or Cooldown in the Details section does not count against this limit.
• Unique names: Each custom detection name must be unique within your organization.
• Cooldown range: A custom detection cooldown must be between 1 hour and 168 hours (7 days).
• Required preview: You must preview a rule successfully before Blumira saves new or changed detection logic.
• Volume ceiling at save: Blumira does not save detection logic that it projects to match too many events per day.
• Nesting depth: You can nest conditions up to four levels deep.

Automatic safety disable

To protect your account from excessive findings, Blumira automatically disables a custom detection rule that matches an unusually high volume of events in a single day. This check applies to rules that already run, and it is separate from the volume ceiling that Blumira applies when you save.

If Blumira disables one of your rules, review and tune its conditions or its cooldown before you enable it again.

What custom detections do not support

Custom detection rules do not currently support the following:

• threshold or count conditions, such as "5 failed logins in 10 minutes"
• more than one data source in a single rule
• raw SQL or a custom query language
• changes to the evidence fields that a rule returns
• custom workflows, because custom detection rules use Blumira's default workflow