Automatic Investigations
tenant settings investigations automation
Automatic Investigations in Secureworks® Taegis™ XDR can be set up to monitor newly-created alerts and create a new investigation from alerts that meet the criteria, or likewise append newly-created alerts to existing investigations that match specified attributes.
Important
Only newly-created alerts will invoke Automatic Investigations rules. Alert updates, such as severity changes, do not trigger Automatic Investigations rules at this time.
Automatic Investigations
Rules may be defined at either the partner level and applied to all child tenants or by individual tenants. Rules define a Query Language alert query over the incoming alerts stream and set of Group By definitions that group alerts together into investigations by attributes—for example, entities or the title—of the alerts.
Working with Automatic Investigation Templates ⫘
Create an Automatic Investigation Template ⫘
- From the Taegis Menu, select Investigations → Auto Investigations. The Automatic Investigations page displays.
- Select the Templates tab.
Automatic Investigation Templates
- From the Actions pull-down menu on the right, select Create New Template. The Create New Investigation Template dialog displays.
Create New Template
- Enter a Template Title.
- Enter an Investigation Title that will be assigned to investigations created from this template.
- Select the Priority Level for investigations created from this template.
Investigation Priority
- Select the Investigation Type.
- (Optional) Give the template a description. This is to help you and others using the template to know what the template is for.
- Select Submit to close out the dialog and save the template. It now lists on the templates tab.
- Follow the steps in the next section to edit the template to add values, edit the title and key findings scripts, and add tags.
Edit Automatic Investigation Templates ⫘
- From the Taegis Menu, select Investigations → Auto Investigations.
- The Automatic Investigations page displays. Select the Templates tab to display the currently available templates.
Automatic Investigation Templates
- Select the template you want to edit from the cards or list. The template editor displays.
Template Editor
- Make the edits you need, then choose Save.
Important
- You cannot set the Assignee of automatic investigations to Secureworks, only to the tenant or a registered tenant user. For assistance with an investigation created by customer-created auto investigation rules, request help through chat or
@secureworks
in an investigation comment. - Email notifications are only sent for investigations opened with the Status set to Awaiting Action.
Tip
You can edit values in the template that aren’t available in the template creation dialog, such as add tags or scripting.
Share Automatic Investigation Templates ⫘
To share an automatic investigation template with another user within the tenant, select the Copy share link icon for a direct URL.
Share Automatic Investigation Template
Working with the Auto Investigation Rule Builder ⫘
Create an Automatic Investigation Rule ⫘
- From the Taegis Menu, select Investigations → Auto Investigations.
- The Automatic Investigations page displays. Select New Rule from the top right-hand corner.
- The Rule Builder panel displays.
Auto Investigation Rule Builder Details
Define the Rule Details ⫘
-
Enter a Rule Title that describes the purpose of the rule.
-
Select a rule state. Choose from:
- Enabled—Creates a new investigation or appends alerts to an existing investigation
- Append—Appends alerts to an existing investigation only, but doesn’t create an investigation
- Test—In a future release, this state will generate logs only for verification purposes, but is currently not functioning
- Disabled—The rule doesn’t do anything
-
Select a template from the Investigation Template pull-down menu.
-
Optionally, provide a description.
-
Set the Rule Evaluation Order. For more information, see Rule Order.
-
Add any tags to the rule, then select Continue.
Determine the Rule Criteria ⫘
-
Add a XDR Query Language statement that filters for the alerts you want the rule to apply to. For more on XDR’s Query Language, see Advanced Search Query Language.
-
If you want the user to be able to append Alerts to investigations created by this rule, add a XDR Query Language statement to find the alerts you want to append. For more on XDR’s Query Language, see Advanced Search Query Language.
-
(Optional) Select Ignore Alert Prioritization to make the rule ignore an alert’s Threat Score and execute the rule regardless of whether the system automatically deprioritized the alert in question. This option is off by default.
Configure Alert Grouping ⫘
- Using Common Expression Language (CEL), define if alerts should be appended to an existing investigation and which investigation alerts should be appended to. For more information, see Group By.
Note
This field is mandatory to create the Auto Investigation rule. You must specify at least one alert attribute.
Edit Automatic Investigation Rules ⫘
To edit a rule, select the Edit Rule pencil icon from the Actions column for the desired rule. Edit the details, rule criteria, or alert grouping criteria and then select Submit to save.
Auto Investigation Rule Actions
Export and Import Automatic Investigation Rules ⫘
-
To export a rule, select the Export Rule icon from the Actions column for the desired rule. The rule configuration exports in YAML format.
-
To import a rule configuration in YAML format, select + Import from above the table and choose the file.
Delete Automatic Investigation Rules ⫘
To delete a configured rule, select the Delete Rule icon from the Actions column for the desired rule and confirm your action by selecting Delete.
Rule Evaluation ⫘
The following are taken into account when rules are evaluated:
- Only medium and higher severity alerts trigger Auto Investigation rules; low and informational alerts are excluded from triggering rules.
- Newly-created alerts are evaluated against the set of rules defined at the child tenant level first followed by the MSSP partner level in the order which they are defined.
- Rule evaluation stops on the first match. To match a rule, the alert must match both the rule query as well as contain the specified grouping attributes.
- When a rule is matched, all of the resulting values returned by the Group By clause are used to look up existing investigations that have at least the specified group count of matching attributes.
- If a match is found, the alert is appended to the investigation and if specified in the rule, a comment is generated and added to the investigation.
- If no match is found, depending on the state of the rule, a new investigation is created. When a new investigation is created, the system performs an alert search over recent alerts that match the rule query and appends any with matching Group By attributes to the new investigation.
- When an investigation is manually created, the system evaluates the genesis alerts associated with the newly-created investigation and matches against any defined rules.
- If a rule matches and the investigation is created by a user that is a member of the tenant that defined the rule, the system performs the same alert search as defined above for additional matching alerts that are auto-appended to the investigation.
Rule Monitoring and Testing ⫘
Rules can be put into a test status in which rules are evaluated but not actually appended to investigations. Metrics are collected and logs generated as though the action was actually performed.
Rule Processing ⫘
Important
Rules defined at the child tenant level are executed first before MSSP partner rules; use caution if you are a ManagedXDR customer or have services provided by a Secureworks MSSP partner.
Rule Order ⫘
Rules are processed in the order defined by the order value on the rule—lower value is processed first. Rule processing stops after the first match. Tenant rules are processed before partner rules.
Group By ⫘
The Group By values on a rule determine if an alert should be appended to an existing investigation using Common Expression Language (CEL). When a rule is matched, group_by
criteria are evaluated. If an existing open investigation is found matching any of the results returned by the group_by
expressions, the alert is added to the existing investigation rather than creating a new one.
Each expression may return either a single result or a list. If more than one expression is defined, the entire set of results is combined into one flattened OR
list.
For example, the following returns a list of usernames identified as entities associated with the alert. If an existing open investigation contains an alert with any one of the resulting usernames, the alert would be added to the existing investigation.
group_by:
- "${alertUsernames(alert)}"
To enforce that all of the usernames within the alert must match, the list of usernames needs to be converted into a single string value. This can be done using the join macro:
group_by:
- "${join(alertUsernames(alert))}"
In a more complex example, the following returns a list of IPs identified as entities associated with the alert that do not match the specified addresses (127.0.0.1
or 0.0.0.0
). If an existing open investigation contains an alert with any one of the resulting IPs, the alert would be added to the existing investigation.
group_by:
- "${alertIPs(alert).filter(e, !(e in ['127.0.0.1', '0.0.0.0']))}"
The following example defines a single group_by
clause that joins multiple alert attributes into a single value for the group_by
clause. All of these attributes must then match an existing open investigation before the alert would be appended:
group_by:
- "${join(alertHostnames(alert).filter(e, e != 'localhost')+alertSensorIds(alert))}
By default, any rule can append to any open investigation if the group_by
values match. You may add the name of the rule to the group_by
value to ensure that only this rule can append to investigations created by itself:
group_by:
- "${alertHostnames(alert).map(h, h + 'The Name of This Rule')}"
Note
Group By matches are not rule-specific. This means any rule can append to any investigation if the Group By values match.
Each distinct row in the Group By list can result in a match. The matches are evaluated using an OR
condition. To match with an AND
condition, one must define a single row. In some cases, it may be possible to use the Group By count to result in an AND condition.
Adding Alerts ⫘
Rules are evaluated against the alerts associated with an investigation when that investigation is created or alerts are added to the investigation. If a rule matches an alert that is associated with the investigation, then additional alerts may be added to the investigation as defined by the append filter on the rule.
Notes ⫘
- Only the first 100 alerts associated with the investigation are evaluated.
- If a rule has no append filter, then the rule filter is used to search for related alerts to append.
- The following criteria are always appended to the query before execution and cannot be overridden. In order to be appended to the investigation, alerts must meet these criteria:
- Alert severity of 0.6 and above
- Alert status of OPEN (alert must not be associated with another investigation already)
- Earliest/latest timestamp of +/- 4 hours from alert created at timestamp
- Up to 100 alerts can be automatically appended.
- Alerts that are automatically appended are used for future evaluation of alerts (Group By matches).
Alert Processing ⫘
Medium and higher severity alerts are processed in a sequential fashion as they are created or published. For each alert, the rules are evaluated and an investigation is either created or appended to for the first rule that matches the alert. The filter
on the rule is used to match the alert, but note that alerts are also evaluated against the append_filter
and can be appended to an investigation if both the append_filter
and group_by
criteria match the alert.
Rules that have an append state or an append_filter
defined continue to be evaluated in order until both the filter or append_filter
and group_by
match. If an alert matches the filter, but the group_by
doesn’t, then the alert is evaluated against the next rule in the ordered list of rules.