Rules

A rule defines what pattern to search for, how frequently to run the query, and which alerts to trigger when matches are found. Each rule is stored as a .toml file in the rules/ subdirectory of a ruleset.

Configuration Options

Field	Type	Required	Description
`id`	UUID	Yes	A universally unique identifier for the rule
`name`	String	Yes	Human-readable name for the rule
`description`	String	No	Optional description explaining what the rule detects
`query`	Search Query	Yes	Crystalline search pipeline defining what to match
`interval`	Duration	Yes	How often the rule should execute
`window`	Duration	No	Lookback window for data analysis (defaults to interval)
`ingest_window`	Duration	No	Time range for ingesting historical data (defaults to interval)
`alert`	Array	Yes	List of alert IDs to trigger on matches

Example Rule

# Detects any access to the secret.html page
id = "5dee2818-5ff5-49f6-a1e9-f895786d2770"
name = "Secret Page Accessed"
description = "Detects any access to the secret.html page on the nginx webserver."

query = '''
select nginx
| match request=/secret\.html/
| fields _time request remote_addr http_user_agent
'''

[window]
minutes = 30

[ingest_window]
seconds = 10

[[alert]]
id = "summary"

[[alert]]
id = "webhook"

Interval Configuration

The interval parameter determines how often the rule executes. It uses a duration format with these units:

[interval]
seconds = 5   # Run every 5 seconds

Supported time units:

seconds - Seconds
minutes - Minutes
hours - Hours
days - Days

For example, a 5-minute interval would be:

[interval]
minutes = 5

Window Configuration

`window` (Analysis Window)

Defines the lookback period for analyzing data within each interval. If not specified, it defaults to the interval duration.

[interval]
minutes = 5

[window]
minutes = 2   # Analyze last 2 minutes of the 5-minute interval

This is useful when you want to analyze only recent data at the end of an interval.

`ingest_window` (Ingestion Window)

Controls how much historical data is ingested into buckets during rule execution. This affects bucket performance and memory usage.

[interval]
minutes = 5

[ingest_window]
seconds = 10  # Ingest data from last 10 seconds only

When omitted, the ingestion window equals the interval duration. Shorter ingest windows improve performance by limiting bucket scope.

Alert References

Rules reference alerts defined in the corresponding alerts.toml file using their id:

[[alert]]
id = "summary_alert"    # Must match an alert ID in alerts.toml

[[alert]]
id = "webhook"          # Another alert definition

Multiple alerts can be attached to a single rule by adding multiple [[alert]] blocks. Each alert will be triggered when the rule matches events.

Keyboard shortcuts