# Detection Rules ## What is a detection rule? A detection rule is a query that runs continuously on new logs as they arrive in Scanner. When Scanner indexes a new log file in S3, it runs each detection rule query on the data in the file. Behind the scenes, Scanner builds up a cache of query results for each detection rule, and the cached results are split into 1 minute time bins. > **How it works:** For technical details on how Scanner's detection engine achieves fast, cost-effective detection at scale using time-based rollup trees, see [Detection Rule Engine](https://docs.scanner.dev/scanner/what-and-why/how-it-works/detection-rule-engine). ## What is a detection event? Whenever a detection rule query yields any hits, a detection event is created. This event is added to the `_detections` index in Scanner, so you can search through all detection events, compute statistical aggregations on them, and more. You can also configure a detection rule to send the detection event to an Event Sink, allowing you to send notifications to other tools like Slack or Tines. ## Viewing detection rules Visit the **Detections** tab in Scanner to view all of your detection rules.

The **Search Detections** button allows you to view all detection events that have been added to the `_detections` index. You can filter the list of detection rules by status, severity, and tags or search for detection rules by name, tags, or severity. You can also create new detection rules or edit existing rules from this page. ## Creating or editing a detection rule Select **New > Create New Rule** to create a new rule, or select an existing rule to edit it. You must specify a **Name** for the detection rule, and optionally specify a **Description**.

The **Detection** **Query** is the query that runs on all new log files indexed by Scanner. If this query has *any* results, then the detection rule is triggered, and a detection event is created.

When a detection rule is triggered, it will always add a detection event to the `_detections` index, which is a special index you can query. Before creating a detection rule, develop and test your query in the Search interface: 1. **Test in Search first** - Run your query to verify it returns expected results 2. **Refine with aggregations** - Use `stats`, `groupbycount`, and `where` to identify patterns 3. **Shape the output** - Use `rename` to match field names expected by webhooks or external systems 4. **Use `table` for webhooks** - Select only the fields your webhook endpoint needs 5. **Add thresholds** - Use `where` to filter for values above/below thresholds Once your query works as expected in Search, convert it to a detection rule in the Detections tab as described above. ## Searching through detection events In the main **Detections** tab, you can click **Search Detections** to open up the special `_detections` index and begin querying all past detection events. You can also query the `_detections` index directly from the **Search** tab by adding `@index=_detections` to your query.

The `_detections` index is a special index where all detection events are written. You can query them the same way you query other log events, which allows you to perform powerful investigations. ## Adding tags Optionally, you can add tags to a detection rule. Tags can be used to classify and search for detection rules. Tags are included in detection events and can be searched in the `_detections`index. Scanner has default MITRE tags that you can use or you can create your own. See [mitre-tags](https://docs.scanner.dev/scanner/using-scanner-complete-feature-reference/detections-and-alerting/detection-rules/mitre-tags "mention") for the full list of default tags.

## Configuring a detection rule to push to an event sink Optionally, you can configure the detection rule to send any triggered detection events to an [Event Sink](https://docs.scanner.dev/scanner/using-scanner-complete-feature-reference/detections-and-alerting/event-sinks). For example, in this screenshot, we configure the detection rule to send events to a Slack event sink. To set up an event sink, see [#create-a-new-event-sink](https://docs.scanner.dev/scanner/developer-tools/api/event-sinks#create-a-new-event-sink "mention").

Configure detection rule to send events to an event sink

## Deduplicating detection events Deduplication for detection events can be activated by setting the `Use for deduplication` checkbox under the `...` menu in the **Format Alert** section:

Then, once you've set one or more fields to be deduplication keys, Scanner will deduplicate detection events that have the same values for those fields. E.g. if you have a detection rule that detects failed login attempts, you can set the `email` field to be used for deduplication; then, Scanner will send at most one detection event per `email` value per deduplication time window. By default, the deduplication time window is set to the time range of the detection rule. However, it can be separately-configured in the **Deduplication Window** field in the **Format Alert** section.