Writing Detection Rules
Last updated
Was this helpful?
Last updated
Was this helpful?
Each detection rule should have its own YAML file. The file should validate against our Schema. Detection rules will not sync if there are errors parsing or validating the YAML.
The file name should end with .yaml or .yml extension. Files with other extensions will be ignored.
The file should have # schema: https://scanner.dev/schema/scanner-detection-rule.v1.json as its first line. This is how we determine whether to a YAML file is a detection rule. YAML files without this comment will be ignored.
The schema for Scanner detection rules is at .
The schema contains information on the properties, including descriptions, requirements, and valid values. This can be used as a reference to write your detection rules and to validate your YAML documents.
A detection rule YAML consists of:
name - detection rule name
description - description of detection rule
enabled - whether the detection rule is enabled
severity - severity of the detection rule. Scanner uses standards for severity tags. Refer to the for more details.
query_text - the query for the detection rule
tags- associated tags for the detection rule. See , below.
time_range_s - the lookback period (in seconds). Must be minute granularity (for example, 60 seconds is valid, but 30 seconds is not).
run_frequency_s - how frequently to run the detection rule (in seconds). Must be minute granularity and <= time_range_s.
event_sink_keys - keys for event sinks to send detection events to. See , below.
alert_template- custom detection alert formatting. See below.
tests - a list of test cases and expected results to apply to this detection rule. See , below.
Below is an example YAML for a detection rule. It looks for updates to AWS SecurityHub findings, which may indicate evasion of security measures.
It is configured to run every 60 seconds and look for possible threat activity in the last 5 minutes of logs. It will trigger alerts with High severity level and send them to the alert event sinks that are associated with the key high_severity_alerts.
To include an index specifier in your query text, you must use the full index specifier format, which is @index={ UUID | "alias" }. While @index=alias works on Scanner web and API, this format cannot be used for detection rules because aliases can change.
To get the full index specifier format, tab-to-complete an index specifier in the Scanner search box and copy-paste it into your detection rule file.
Below is a valid index specifier:
Below are examples of invalid index specifiers. These will result in QueryParseErrors.
Using index rather than @index will search for a column called index rather than filter a Scanner index.
Tags are specified as an array in YAML. Each tag must begin with an ASCII letter, and contain only ASCII alphanumeric characters, ., -, or _.
Scanner has default MITRE tags that you can use or you can create your own. See MITRE Tags for the full list of default tags.
Below is an example of a detection rule's tags. This should be in the same file as your detection rule.
Event sink keys can just be specified as an array in YAML. Each event sink key must begin with an ASCII letter, and contain only ASCII alphanumeric characters, -, or _.
Below is an example of a detection rule's event sink keys. This should be in the same file as your detection rule.
You can customize detection alerts by providing an alert_template. The alert_template has two optional objects: info and actions. Both accept arrays of items with label and value fields.
actions will appear as buttons in Slack and as links in Markdown. The values in the actions section should be URLs. If the value is an invalid URL or not a URL, the key/value will appear as text in the alert, rather than as a button or link.
Note: info and actions also accept pairs of strings, but this format is deprecated. We recommend migrating to the label and value format.
Below is an example of an alert template. This should be in the same file as your detection rule.
You can specify tests in your YAML file to run against the detection rule.
A detection rule test consists of:
name - test name
now_timestamp - timestamp to start the test (optional)
dataset_inline - a list of JSON log events for the test
expected_detection_result - whether the given dataset triggers a detection event
If now_timestampis not provided, Scanner will use the timestamp of the latest log event as the now_timestamp. In both cases, the timestamp is rounded to the next run_frequency_s. For example, if run_frequency_sis 60 seconds and now_timestampis 2024-07-05T10:09:34.123Z, the timestamp will be rounded up to 2024-07-05T10:10:00.000Z(the next minute).
Detection rules will not sync if there are failing tests.
Test datasets are a list of JSON log events. There are a few ways to write test datasets:
You can export results from Scanner as JSON lines and use the results as a test dataset. To export results, run a query in Scanner and click the arrow next to Run and select JSON Lines under Export Results.
You can copy-paste raw_events from Scanner search results. The copy-pasted result is not guaranteed to be valid JSON because values may not be properly escaped.
You can write your own JSON log events. A valid JSON log event must contain a timestamp in RFC 3339 format. It can contain any number of key/value pairs. An example log event:
Below is an example of a detection rule test. This should be in the same file as your detection rule.
While working on your detection rules, it can be valuable to test them as-is without needing to push to Github and sync with Scanner. We provide tools to do so:
Scanner provides a Python CLI and public API endpoints that can be used to validate the rule files, and also to run the provided tests. For more information:
You can specify keys that identify which event sinks a detection rule should log events to. You can assign one or more actual event sinks to each key in the settings for the sync source; see .
See for more information on the info and actions sections, as well as information on templating values.
A JSON schema that describes detection rules can be found at , which can be used to validate the YAML files directly.