Creating Custom Detection Rules

Custom detection rules let you define exactly what Atatus Cloud SIEM should look for in your security events and how it should respond. This guide walks through creating a rule from start to finish, and how to manage existing rules. If you are new to detection rules, read Detection Rules and Signals Overview first.

Prerequisites

A user with permission to manage SIEM detection rules.
At least one data source sending security events (an integration, Linux audit logs, Kubernetes audit logs, or file integrity monitoring).

Start a new rule

Go to Security → Detection Rules.
Click New Rule.

The rule builder is organized as a five-step form. Each step expands and collapses, and the footer shows which steps still need attention before you can save. Two toggles in the header control whether the rule runs and whether it alerts:

Toggle	Description
Enabled	When off, the rule does not evaluate events at all.
Notify	When off, the signal is still recorded in the signals list, but no Slack, Teams, Email, or PagerDuty alert is dispatched.

Step 1: Select a detection method

Choose how the rule identifies threats in your data. See Detection methods for guidance on each option.

Method	Description
Threshold	Trigger when event count exceeds a defined threshold within a time window.
Anomaly Detection	Use machine learning to detect statistical deviations from baseline behavior.
New Value	Trigger when a new unique value appears for a given field.
Impossible Travel	Detect logins from geographically impossible locations within a short timeframe.
Static Match	Match events against a fixed set of conditions without dynamic analysis.

Step 2: Define detection queries

This step describes what to look for. Start with the rule’s general settings:

Field	Required	Description
Rule Name	Yes	A descriptive name, for example `Multiple Failed Login Attempts`.
Description	No	What this rule detects. Shown on the rule detail page.
Tags	No	Labels on the rule itself, used to filter the rules list. Use `key:value` pairs, for example `scope:fim` or `category:authentication`. These are separate from the signal tags in Step 4.
Data Sources	Yes	Pick the canonical rule-library source. Deployment aliases (for example `fim`, `aws_eks`) match the same source, so choose the canonical one. The selected source also scopes field auto-complete in your queries.
Evaluation Window	Yes	The time window in seconds (1 to 86400, i.e. one second to one day) over which events are aggregated.
Keep Alive	No	How long, in seconds (0 to 86400), to keep a signal alive while its condition stays true.

Add one or more queries

Each rule has at least one query. A query filters and aggregates events:

Field	Description
Query name	An identifier you reference from your case conditions, for example `failed_logins`.
Filter	The Atatus filter expression that selects events. See Filter Query Syntax.
Aggregation	How matched events are summarized: Count, Sum, Average, or Cardinality.
Group by	Fields to group results by, for example `sourceIP` and `hostname`. Each unique combination is evaluated independently.
Distinct fields	Shown only when the aggregation is Cardinality. The field whose unique values are counted, for example `userName`.

Click Add query to add more queries. You can then combine them in your case conditions.

Step 3: Set rule cases

Cases turn query results into a signal. Each case is a boolean condition over your query names, evaluated top to bottom. The first matching case wins and sets the signal’s severity.

Field	Required	Description
Case name	No	A short label, for example `high-volume failure`. Supports templates such as `%{sourceIP}` to include matched values.
Severity	Yes	One of Critical, High, Medium, Low, or Info.
Condition	Yes	A boolean expression over your query names, for example `failed_logins > 10`.
Notification target	No	A per-case destination, for example `#security-alerts`.

Conditions support comparison and logical operators (>, >=, <, <=, ==, !=, &&, ||) over your query names. For example:

failed_logins >= 10 || (failed_logins > 5 && hostname == "prod")

Click Add case to add more cases (for example, a Critical case for very high volumes and a High case for lower ones).

Step 4: Say what’s happening

This step composes the notification body and the tags applied to the signals this rule generates.

Field	Description
Notification template	A Markdown message sent with the alert. Use the toolbar to insert `@here` mentions, `{{variable_name}}` substitutions, and `@on-call` references.
Include triggering group-by values in notification title	When enabled, the values that triggered the signal (for example the source IP) are added to the alert title.
Tag resulting signals with	Labels applied to the signals this rule fires (distinct from the rule tags in Step 2). Useful for filtering the signals list.
Teams	Select up to five teams to route the signal to.

A useful notification template states the goal and the response steps, for example:

### Goal
Detect repeated failed logins that may indicate a brute-force attempt.

### Triage and response
1. Investigate the source IP and affected host.
2. Check whether the account is locked or compromised.
3. Block the IP or rotate credentials if confirmed.

Step 5: Create a suppression

Suppression reduces noise by muting recurring or expected signals. This step is optional.

Field	Description
Enable suppression for this rule	Turns suppression on. The remaining fields are disabled until this is enabled.
Name	A name for the suppression, for example `Mute weekend cron noise`.
Description	Why this suppression exists.
Suppression query	A filter describing which signals to suppress, for example `eventOutcome:success`. Use Refresh preview to see how many signals in the last 24 hours would be suppressed, along with sample matches.
Suppress by attributes	Optionally suppress based on one or more attribute keys, for example `sourceIP`.

Test the rule

Before saving, click Test rule in the footer to validate the rule’s configuration against recent data. The footer also lists any incomplete steps; once everything is valid it shows Ready to save. When you are satisfied, click Save Rule.

A complete example

The following describes an SSH brute-force rule end to end:

Step	Setting	Value
1	Detection method	Threshold
2	Rule Name	`SSH Brute Force Attempt`
2	Data Sources	`runtime-security-agent`
2	Evaluation Window	`300` (5 minutes)
2	Query name	`ssh_attempts`
2	Filter	`source:runtime-security-agent AND auditdMessageType:USER_AUTH AND auditdResult:fail`
2	Aggregation	Count
2	Group by	`sourceIP`, `hostname`
3	Case name	`SSH brute force from %{sourceIP} on %{hostname}`
3	Severity	High
3	Condition	`ssh_attempts >= 10`
5	Suppression	Enabled, grouped by `sourceIP` and `hostname`

This rule fires a High severity signal whenever a single source IP produces 10 or more failed SSH authentications on a host within any 5-minute window.

Manage existing rules

From the Detection Rules list you can manage both built-in and custom rules:

Enable or disable: Toggle a rule on or off without deleting it. This works for both built-in and custom rules.
Override a built-in rule: Built-in rules are read-only, but you can override settings such as severity and notification routing for your account.
Clone: Copy any rule (built-in or custom) into a new, fully editable custom rule. The copy’s name is suffixed with (copy).
Edit: Open a custom rule back in the five-step builder to change it.
Import and export: When editing a custom rule, export it to JSON or import a rule definition. Bulk import is also available for onboarding many rules at once.
Delete: Remove a custom rule. Any overrides you made on it are removed as well.

Next steps

Filter Query Syntax: the full filter DSL for your rule queries.
Investigating Signals: triage the signals your rules generate.

​Prerequisites

​Start a new rule

​Step 1: Select a detection method

​Step 2: Define detection queries

​Add one or more queries

​Step 3: Set rule cases

​Step 4: Say what’s happening

​Step 5: Create a suppression

​Test the rule

​A complete example

​Manage existing rules

​Next steps