Alerts

Alerts define what happens when a rule matches events. They specify the action taken after a rule identifies matching data. Multiple alerts can be attached to a single rule.

Configuration Options

All alerts are defined in a single alerts.toml file within the ruleset directory. Each alert must have a unique id that is referenced by rules.

Field	Type	Description
`id`	String	Unique identifier for this alert (referenced by rules)
`type`	Enum	The type of alert: `stdout`, `summarise`, or `http`

Alert Types

stdout

Writes matching events to standard output. Useful for debugging or simple logging.

[[alert]]
id = "debug_alert"
type = "stdout"

Configuration:

id - Identifier used by rules to reference this alert

The stdout alert outputs formatted event data directly to the console with minimal overhead.

summarise

Writes matching events to another index for later analysis.

[[alert]]
id = "summary_alert"
type = "summarise"
index = "security_events"

Configuration:

id - Identifier used by rules to reference this alert
index - Name of the target index where events are stored

Events written via summarise alerts maintain the original structure and can be queried later using Crystalline search commands.

http

Sends HTTP requests to a configured endpoint when matches occur. Supports custom templates, authentication headers, and retry logic.

[[alert]]
id = "webhook"
type = "http"
url = "https://api.example.com/alerts"
method = "POST"
timeout = 10
attempts = 3
concurrent = 2

headers = {
    Content-Type = "application/json",
    Authorization = "Bearer secret_token"
}

template = '''{
    "rule_id": "{{ rule.id }}",
    "rule_title": "{{ rule.title }}",
    "event_data": {{ event | json_encode() }}
}'''

The URL and header fields can also include template variables to include dynamic values:

url = "https://api.example.com/alerts/{{ rule.id }}"

headers = {
    Content-Type = "application/json",
    X-User-Id = "{{ event.user_id }}",
    X-Rule-Id = "{{ rule.id }}"
}

Configuration:

Parameter	Type	Default	Description
`url`	String	Required	The HTTP endpoint URL to send alerts to (supports templating)
`method`	Enum	POST	HTTP method (`GET`, `POST`, `PUT`, `DELETE`, etc.)
`timeout`	Integer	30	Timeout in seconds for each request
`attempts`	Integer	1	Number of retries on failure
`concurrent`	Integer	2	Maximum concurrent requests
`headers`	Map	`{}`	HTTP headers (supports templating)
`template`	String	Optional	template for request body

Template Variables

The HTTP alert supports Tera templating with the following variables:

Rule Object

{{ rule.id }} - UUID of the triggering rule
{{ rule.title }} - Human-readable name of the rule
{{ rule.description }} - Rule description (if defined)

Event Object

{{ event._time }} - Timestamp of the matched event
{{ event.<field> }} - Any field from the matched event

Example with nested data:

{
  "rule": {
    "id": "5dee2818-5ff5-49f6-a1e9-f895786d2770",
    "title": "Failed Login Attempt"
  },
  "event": {
    "_time": "2024-01-15T10:30:00Z",
    "username": "admin",
    "source_ip": "192.168.1.100"
  }
}

Alert Example

Here’s a complete example showing all three alert types:

# Debug output for development
[[alert]]
id = "debug"
type = "stdout"

# Store events for later analysis  
[[alert]]
id = "summary"
type = "summarise"
index = "web_alerts"

# Send webhook notifications
[[alert]]
id = "notification"
type = "http"
url = "https://hooks.example.com/crystalline"
method = "POST"
timeout = 15
attempts = 3
concurrent = 2

headers = {
    Content-Type = "application/json"
}

template = '''
{
  "alert": {
    "rule_id": {{ rule.id | json_encode() }},
    "timestamp": "{{ event._time }}",
    "severity": "high"
  }
}
'''

This single ruleset can simultaneously log to console, store in an index, and send webhooks when triggered.

Keyboard shortcuts