Detection Rules
A detection rule is a query that runs continuously on new logs as they arrive in Scanner. You can create create, read, update, and delete detection rules with the Scanner API.
Create a new detection rule
POST /v1/detection_rule
Create a new detection rule with the specified data.
If the detection rule is active, it will be immediately scheduled for backfill and execution.
Body
tenant_id required
string
Unique identifier for the tenant
name required
string
Name of the detection rule
description required
string
Description of the detection rule
time_range_s required
number
Lookback period (in seconds). Must be minute granuarlity (for example, 60 seconds is valid, but 30 seconds is not).
run_frequency_s required
number
How frequently to run the detection rule (in seconds). Must be minute granularity and <= time_range_s.
enabled_state_override required
"Active", "Staging", or "Paused"
Whether the detection rule runs and sends events to event sinks
query_text required
string
Query for the detection rule
event_sink_ids required
list of strings
Event sinks to send event alerts to
alert_per_row
boolean
If true, emit one detection alert per row of the query's results table instead of a single alert containing the whole (truncated) table. Defaults to false.
tags
list of strings
Associated tags for the detection rule. Scanner has default MITRE Tags that you can use or you can create your own.
sync_key
string
Sync key, used by automatic detection rule syncers
Example
Response
Returns the newly created detection rule.
List detection rules
GET /v1/detection_rule
List all detection rules for a tenant.
Query parameters
tenant_id required
string
Unique identifier for the tenant
pagination[page_size]
number
Maximum number of results to return in a page. Defaults to 50
pagination[page_token]
string
Cursor for pagination. list_detection_rulesreturns next_page_token to be used for this field. If the field is not specified, paging will start at the beginning of the list.
Example
Response
Returns a list of detection rule summaries and pagination information. The detection rule summary object is the same as the detection rule object, but it does not include event_sink_ids. The pagination information includes the next_page_tokento use as the pagination cursor. next_page_tokenis null if there are no more remaining pages.
Get a detection rule
GET /v1/detection_rule/{id}
Get the detection rule with the given id.
Example
Response
Returns the detection rule.
Update a detection rule
PUT /v1/detection_rule/{id}
Update the detection rule with the given id. If the rule is synced from GitHub (in which case detection_rule_sync_id will be non-null), then enable_override is the only field that can be updated.
Body
id required
string
Unique identifier for the detection rule
name
string
Update the name of the detection rule
description
string
Update the description of the detection rule
time_range_s
number
Update the lookback period (in seconds) of the detection rule. Must be minute granularity (for example, 60 seconds is valid, but 30 seconds is not).
run_frequency_s
number
Update the how frequently the detection rule is run (in seconds). Must be minute granularity and <= time_range_s.
alert_per_row
boolean
If true, emit one detection alert per row of the query's results table instead of a single alert containing the whole (truncated) table.
enabled_state_override
"Active", "Staging", "Paused", or null
Enable, enable without sending events, or disable the detection. Overrides enabled_state_synced for synced detection rules if non-null.
query_text
string
Update the query for the detection rule
tags
list of strings
Update the tags for the detection rule. Scanner has default MITRE Tags that you can use or you can create your own.
event_sink_ids
list of strings
Update the event sinks for the detection rule
sync_key
string
Update the sync key for the detection rule
alert_template
object or null
Update the alert template. Set to null to remove. See Alert template below.
Example
Response
Returns the updated detection rule.
Delete a detection rule
DELETE /v1/detection_rule/{id}
Delete the detection rule with the given id.
Example
Response
Returns the id and tenant_id for the deleted detection rule.
Alert template
You can customize detection alert formatting by providing an alert_template object with the following fields:
info
array
Key-value fields displayed in the alert
actions
array
Buttons (Slack) or links (Markdown) shown in the alert
info items appear as key-value information in the alert. Each item has:
label
string
Display label for this field
value
string
Value to display. Supports {{field_name}} template syntax to reference fields from query results.
use_for_dedup
boolean
If true, this field's value is used as a deduplication key. When multiple alerts share the same dedup key values, they are grouped together so you receive a single notification rather than repeated alerts for the same underlying issue. Defaults to false.
actions items appear as buttons in Slack and links in Markdown. Each item has:
label
string
Button or link text
value
string
URL for the action. If the value is not a valid URL, it will appear as text instead of a button or link. Supports {{field_name}} template syntax.
See Detection Alert Formatting for more details on templating.
Example
Detection severity
We use the OCSF schema for detection severity:
Unknown
Information
Low
Medium
High
Critical
Fatal
Other
The detection severity must be one of these string values, e.g.
Last updated
Was this helpful?