Automation - DFIRe documentation

Overview

An automation rule has three parts: a trigger (something that happens to a case), optional filters (conditions the case must match), and one or more actions (what DFIRe does). When a case opens or changes, every enabled rule whose trigger and filters match the case runs its actions.

A typical use is keeping the right responders on a case without anyone remembering to add them. For example, inviting the on-call network engineer to the Slack channel of every case in the Product Security project, or assigning a team lead automatically based on the playbook. Because Slack invites work for people who don't have a DFIRe account, you can pull external responders into the conversation as soon as a case is created.

Rules are managed under Settings → Automation. Creating and editing rules requires the automation-rule permissions, which can be granted to any role in the Role Editor without any other administrative access. Investigators and view-only users do not hold them by default.

How a rule is built

The rule editor reads top to bottom as a sentence, Trigger when … Only if the case matches … Then do this …. And shows a one-line preview of the rule as you build it.

Open Settings → Automation and click Add rule
Give the rule a name. Use the Enabled switch to turn a rule off without deleting it.
Choose one or more triggers
The rule runs when any of its triggers occurs. See Triggers.
Narrow with filters (optional)
Limit the rule to cases matching a mode, criticality, playbook, or project. Leave a filter on Any to match all. See Filters.
Add one or more actions
Choose what happens when the rule matches. See Actions.
Save the rule

Execution order

Rules run in the order they appear on the Automation settings page, top to bottom. Drag a rule by its handle to change its position; the number next to each rule is its place in the sequence. A new rule joins the end of the list.

When several rules match the same case change, they run one after another in this order, so a later rule can override what an earlier one did. This makes default-and-exception setups predictable: put a rule that assigns your default case lead first, and a rule that assigns a different lead to critical cases after it. For a critical case both run, and the later rule's lead wins. A single case edit runs all its matching rules as one sequence. That holds even when the edit changes several things at once, such as criticality and project in the same save.

Triggers

A trigger is the case event that starts the rule. Select one or more:

Trigger	Fires when
Case opened	A case is created. Covers both investigations and incidents. Narrow to one with the Case mode filter.
Escalated to incident	An investigation is escalated to incident mode.
Criticality escalated	A case's criticality is raised (for example, medium to high). A change to or from undetermined does not count.
Criticality downgraded	A case's criticality is lowered. A change to or from undetermined does not count.
Playbook changed	A case's playbook is changed. Filters match the new playbook.
Project changed	A case is moved to a different project. Filters match the new project.

Filters

Filters restrict which cases a rule applies to. A rule matches only when the case satisfies every filter you set; within a single filter, matching any of the chosen values is enough. Each filter defaults to Any, meaning it places no restriction.

Filter	Matches on
Case mode is	Investigation or incident
Criticality is	Critical, high, medium, low, info, or undetermined
Playbook is	One or more playbooks (case types)
Project is	One or more projects

Filters describe the case's state after the change. Combinations that can never occur for the chosen triggers are greyed out. For example, with Criticality escalated selected, the info level is unavailable, because escalation can never leave a case at the lowest level. Undetermined is unavailable with both criticality triggers and with Escalated to incident. A change to or from it is neither a raise nor a drop, and an incident always has a severity.

Actions

Actions are what the rule does when it matches. A rule can carry several, and runs them in the order they are listed. They are additive and safe to repeat. Inviting someone already in a channel, or adding someone already on the team, does nothing.

Action	Effect
Invite Slack user to case channel	Adds a Slack user to the case's Slack channel. Works for people without a DFIRe account.
Remove Slack user from case channel	Removes a Slack user from the case's Slack channel.
Add user to case team	Adds a DFIRe user to the case team as lead, investigator, or viewer.
Remove user from case team	Removes a named DFIRe user from the case team (and from the Slack channel).
Add group to case team	Adds the members of a role group to the case team as investigators or viewers. See Adding and removing a group.
Remove group from case team	Removes every member of a role group from the case team (and from the Slack channel).
Fire a webhook	Emits an Automation Rule Triggered webhook event tagged with a trigger tag. See Firing a webhook.

Identifying a Slack user

For the Slack actions, enter an email address or a Slack member ID and click Resolve. DFIRe looks the user up through your Slack integration and confirms the match by showing their full name, @username, and member ID. Slack provides no lookup by username, so a plain handle on its own cannot be resolved.

Adding to the case team

Choose a role for each user you add. Lead, investigator, or viewer. Adding a user as lead makes them the case lead, replacing the current one. A rule can set only one lead, and a given user can appear in only one team action per rule (you cannot, for example, both add and remove the same person).

Removing from the case team

Removal targets specific users you name in the rule, and removes them regardless of how they joined the case. Removing a team member also removes them from the case's Slack channel.

Adding and removing a group

The group actions use the role groups under Settings → Access Roles. Any role group works, including one that grants no permissions.

Add group to case team adds each active member as an investigator or a viewer. A member whose role cannot edit evidence joins as a viewer. A member who is already on the team keeps their role. A group cannot be the lead. To set a lead, add a user as lead in the same rule.
Remove group from case team removes every member of the group, deactivated accounts included. If the lead is a member, the case has no lead until another action sets one.

A rule reads the group's members when it runs. A user who joins the group later does not join the cases the rule has already run on. Each group can appear in only one group action per rule. If you delete a group, its action stays in the rule and fails on every run until you choose another group.

A case team can follow the case's project. Give each project a rule with the triggers Case opened and Project changed and a filter for that project. List its actions in this order: remove the groups of the other projects, add the project's group, then add the project's lead.

Firing a webhook

The Fire a webhook action does not send a request itself. It emits an Automation Rule Triggered event carrying a trigger tag you choose. To deliver it, create an outgoing webhook subscribed to that event and set its trigger-tag filter to the same tag. Delivery, signing, and retries are handled entirely by the webhook.

Because a webhook matches on the tag regardless of where it came from, the same tag can drive one webhook from both a runbook step and an automation rule. For example, tag both a runbook step and an automation with notify_ciso. Subscribe one webhook to both the runbook-step and automation events with that tag, and either source pages the same destination.

See Webhooks for configuring the receiving webhook, its payload, and authentication.

Run history

Each rule keeps a record of its recent runs, shown by expanding the rule. A run lists the triggering event, the case it ran on, and the outcome of each action, success, partial, or failed, with the reason for anything that did not complete. Slack invites and team changes are also recorded in the audit log, attributed to the system.

Access control

Creating, editing, and deleting automation rules requires the automation-rule permissions. A role can be given them on their own, without any other administrative access, so automation can be delegated to whoever runs it. Investigators and view-only users do not hold them by default and cannot see or change rules. Rule changes are recorded in the audit log with the administrator who made them as the author.

The team actions are the exception. Saving a rule that adds or removes case-team members or groups also requires core.edit_all_cases. Such a rule changes case access on every case it matches. Rules that invite Slack users to the case channel, remove them from it, or fire webhooks need the automation-rule permissions alone.

The Slack actions can change case teams too. Auto-add investigators under Settings → Slack Integration is on by default. While it is on, a linked DFIRe user who joins the channel of an open case joins its team. A team member other than the lead who leaves the channel leaves the team. See Channel and team membership. The automation-rule permissions are not escalation-sensitive, so a delegated administrator can grant them.