UTMSTACK logoUTMSTACK logo
Detection EngineeringAlerting Rules

Alerting Rules

Alerting rules describe the threats UTMStack looks for. When an event matches a rule, the engine raises an alert. On Configure > Alerting Rules you browse the 721 shipped rules, switch rules on or off for your tenant, write and import your own, export rules and test them.

Before you start

  • The Configure section of the menu is shown to administrators only.

  • Viewing and exporting rules needs the permission eventprocessing.read.

  • Creating, importing, editing, deleting, switching on or off and testing need eventprocessing.write. Of the built-in roles, only Administrator has it. See Roles and Permissions.

The rule list

The page is titled Alerting Rules: "Correlation rules that turn events into alerts. Toggle, tune or author your own." It loads 50 rules at a time as you scroll.

The Alerting Rules page with the search box, the data type, category, adversary, state and owner filters, the Import, Export All, Test and New rule buttons, and the rule table
ControlWhat it does
Search rules…Searches the list.
Category, adversary, state, owner and data type filtersNarrow the list. State is Active or Inactive; owner is System (shipped) or Custom (yours).
TestTests a sample log against every deployed rule. See Testing Pipelines and Rules.
ImportAdds rules from YAML files.
Export AllDownloads the rules as a zip file. When you tick rows, it becomes Export (N).
New ruleOpens the editor for a new custom rule.

Columns:

ColumnMeaning
RuleThe rule name. A lock marks shipped rules.
Data typesThe kinds of events the rule examines.
CategoryUsually the MITRE ATT&CK tactic (MITRE ATT&CK is a public catalogue of attacker behaviour), for example Credential Access.
TechniqueUsually the MITRE ATT&CK technique, for example T1110 - Brute Force.
AdversaryWhich side of the event is treated as the attacker: Origin or Target.
ImpactThe highest of the rule's three impact values (0 to 3).
ActiveSwitch that turns the rule on or off for your tenant.

Switch a rule on or off

Use the Active switch in the rule's row. The change applies to your tenant only and reaches the engine within about a minute. It works for shipped and custom rules.

This is also how you turn a rule back on after the rule flood guard switched it off. Fix the cause first, or the guard switches it off again. See Rule Flood Guard.

Read a rule

Click a rule to open its panel. It shows:

  • Description

  • Details: Category, Technique, Adversary, Impact (C·I·A), Data types and Updated

  • Condition (CEL), drawn as a tree of conditions joined by AND or OR

  • Correlation steps: the history searches, if any

  • Correlation: Group by and Deduplicate by, if the rule has them

The Visual tab does not list the rule's references: click Code to read them in the rule's YAML. The panel does not show the rule's file name; Export (1) from the list gives you the file.

The panel of a shipped rule in the Visual tab, with Export, the Active switch, Description, Details and the Condition (CEL) shown as a list of conditions

Visual and Code tabs switch between the form and the rule's YAML. The Code tab of a shipped rule is read-only.

167 of the shipped rules are written with the older key afterEvents for their correlation steps. The engine runs these steps, but the panel and the Code tab do not show them. To read such a rule exactly as it is stored, tick it in the list and click Export (1).

Shipped rules cannot be edited or deleted. Custom rules have Edit and Delete buttons.

Create a rule

  1. 1

    Open the editor

    Click New rule. The editor has a Visual tab and a Code tab. They stay in step: a change in one shows in the other. To start from a complete rule, click Code and paste it; Rule Examples has rules to copy.

    The New rule panel in the Visual tab: Metadata with Name, Category, Technique, Adversary, Data types, Confidentiality, Integrity, Availability, Description and Active, then Condition (CEL) and Correlation steps, with Test and Save at the bottom
  2. 2

    Fill in the details

    FieldDescription
    NameThe alert name. Required. Use a name no other rule has: de-duplication, grouping, tagging rules and the flood guard all work by rule name.
    Category, TechniqueFree text. Shipped rules use MITRE ATT&CK names.
    AdversaryOrigin or Target: the side of the event that is the attacker.
    Data typesThe data types the rule examines. Required.
    Confidentiality, Integrity, AvailabilityImpact values from 0 to 3. The highest one sets the alert severity.
    DescriptionWhat the rule detects and what the analyst should do next.
    ActiveWhether the rule is switched on when you save.
  3. 3

    Write the condition

    The condition decides which events match. Required. The Condition (CEL) box has its own Visual and Code switch: Code shows the condition as text.

    In Visual, choose Match all or Match any "of these conditions:", then add conditions. Each condition has a field, a function and an optional Negate. The functions are:

    LabelFunction
    existsexists
    equalsequals
    equals (no case)equalsIgnoreCase
    containscontains
    is one ofoneOf
    contains allcontainsAll
    starts with, ends withstartsWith, endsWith
    matches regexregexMatch
    <, ≤, >, ≥lessThan, lessOrEqual, greaterThan, greaterOrEqual
    in CIDRinCIDR
    hour is, minute is, day of week isisHour, isMinute, isDayOfWeek
    is weekend, is workdayisWeekend, isWorkDay
    time betweenisBetweenTime

    For anything the builder cannot draw, such as nested brackets or a mix of "and" and "or", write the condition in Code. The builder then shows: "This condition uses advanced CEL — edit it in Code, or rebuild it visually." See Condition Functions Reference.

  4. 4

    Add correlation steps (optional)

    A correlation step makes the rule count earlier stored events before it raises an alert, for example "10 failed logins from the same address in the last 15 minutes". Click Add correlation step (a new step starts with Within 2m, Count 1 and Index pattern v11-log-*) and fill in:

    • Within: the time window, written like 15m, 1h or 24h.

    • Count: how many matching stored events are needed.

    • Conditions: which stored events count. Each has a field, an operator (equals (term), not equals (term), matches (text) or not matches (text)) and a value. A value such as {{.origin.ip}} copies the field from the event being checked.

    See Rule File Format for how the count works.

  5. 5

    Add de-duplication or grouping

    Fill in Deduplicate by or Group by with alert fields such as adversary.ip, adversary.user, target.host or dataSource. Without them, every matching event raises a new alert. See How Alerts Are Created.

  6. 6

    Test and save

    Click Test to try the rule on a sample log, then Save. The page confirms "Rule created".

The Index pattern box

Each correlation step in the editor also has an Index pattern box, filled in with v11-log-*. It is left over from UTMStack v11, and the v12 engine ignores its value. However, the editor keeps a correlation step only while this box has text:

  • Leave the value in place.

  • If you clear the box, the step is removed when you save, test or export the rule, and the rule then raises an alert for every event that matches its condition.

Or groups

Add Or group adds alternative conditions to a correlation step. When you save, each Or group takes the Within and Count of its step; it cannot have its own. If you need alternatives with their own window or count, write the rule as a file and import it.

What saving checks

Saving checks that the rule has a name, at least one data type and a condition, that each Within is a valid duration, and that each operator is one of the four above. It does not check that the condition is valid, that impact values are between 0 and 3, or the adversary value. A rule with a broken condition is saved as active and never matches. Test every rule before you save it.

Your rule is saved as rules/user/<tenant id>/<name in lower case with dashes>-<tenant id>.yaml, with your tenant id inside, so it runs only on your tenant's events.

UTMStack writes the file itself from the rule's fields, the same way for Save and Import: comments are removed, the keys are put in a fixed order, and keys that UTMStack v12 does not use, such as id or afterEvents, are dropped. Keep your own commented copy of a rule if you need the comments.

Import rules

Use Import to add rules written as files. Import keeps the file's correlation steps exactly as written, so it is the best way to add counting rules and rules with Or groups.

  1. 1

    Prepare the files

    One rule per .yaml or .yml file, in the format described in Rule File Format. Write correlation steps under correlation. Files that use the older key afterEvents are accepted, but their correlation steps are lost: rename the key to correlation before you import.

  2. 2

    Import

    Click Import and choose one or more files.

  3. 3

    Check the results

    Import results lists each file as Approved or Rejected, with the reason. Approved rules become active custom rules of your tenant. A file is rejected when it has no name, no data types or no condition, when a duration or operator is invalid, or when you already have a custom rule with the same name.

Do not edit an imported counting rule in the editor. Its correlation steps have no index pattern, so the editor removes them when you save. To change such a rule, delete it and import the corrected file. If the rule was switched off when you deleted it, check that the new one is Active after the import.

Customize a shipped rule

Shipped rules are read-only. To change one (see Tuning Rules and Reducing False Positives for when this is the right tool, and Shipped and Custom Rules and Pipelines for what happens to your copy on updates):

  1. Tick the rule in the list and click Export (1). You get a zip file with the rule file.

  2. Edit the file. Give the rule a new name. If it uses afterEvents, rename that key to correlation.

  3. Import the file.

  4. Switch the shipped rule off with its Active switch.

Export rules

  • Export All downloads every rule you can see as a zip file of the stored rule files. Tick rows to export only those (Export (N)).

  • The Export button in a rule's panel downloads one YAML file built from the editor's view of the rule. It leaves out correlation steps that have no index pattern, which includes the steps of every shipped rule. Use Export (1) from the list when you need the exact file.

Apply a rule to all tenants

On a multi-tenant installation, the instance operator also sees Apply to all tenants in the rule panel. In UTMStack v12.0.2 it works for switching a shipped rule on or off in the selected tenants. Creating or changing a custom rule in other tenants does not work from this button, and deleting or switching a custom rule reaches only your own tenant, because each tenant's custom rule is a separate file.

To give several tenants the same custom rule, enter each tenant and import the rule file there (see Import rules), or use the Rules and Pipelines API. See Apply to All Tenants for what each button does.

Audit

Creating, importing, updating, deleting and switching rules on or off are recorded in the audit log. See App Audit Logs.