> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wirespeed.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Detections

> Write your own custom detections

## Custom Detections

You can use [advanced queries](/events/advanced-queries) to create custom detections for your environment. Wirespeed highly recommends researching solutions that can be implemented in your source detection systems first, as properly configuring your posture can prevent the need for custom detections. To write a custom detection, create an [advanced query](/events/advanced-queries), select the 3-dot menu and select "Create Custom Detection".

### How it works

1. An advanced query is constructed with the [appropriate filters](/events/custom-detections/#filtering-by-time) and [columns](/events/custom-detections/#return-data)
2. The query is run every 15 minutes
3. Each row returned from the query is [processed](/verdicts) as a detection
4. [Columns](/events/custom-detections/#return-data) are extracted from the query and used to automatically associate users and endpoints from your environment to the detection
5. Detections will be automatically processed and escalated as cases if needed 🎉

### Requirements

#### Return data

For Wirespeed to be able to automatically process your detections, you must return relevant data for us to process. You may return one or more of the following columns to be extracted from your detection:

* `time`
* `severity_id` (OCSF values: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `99`)
* `src_endpoint`
* `dst_endpoint`
* `actor.user`
* `device`
* `http_request`
* `user.email_addr`
* `user.uid`
* `observables`

The above columns don't *need* to be returned. In that case, the detection will likely skip most of the automated [verdicting](/verdicts/introduction) and immediately escalate to your team.

Each row returned from your query will be processed as a detection. If you return multiple rows, each row will be processed as a separate detection. Any detections returning >100 rows will trigger an error.

If you want to provide dynamic information in the detection title like an email address, you can provide an optional `name` column that will be used as the detection name. E.g. `SELECT 'Suspicious login' as name, user.email_addr, time from authentication_events where status = 'Failure';`. Otherwise the custom detection name will be used.

#### Filtering by time

Custom detections run once every 15 minutes. Since these detections will be running repeatedly, you **must** have a time filter on your query. Wirespeed automatically provides the `startTime` and `endTime` variables for you, which you can use in your query.

```sql theme={null}
SELECT * FROM events
WHERE time >= {startTime: DateTime64}
AND time < {endTime: DateTime64}
AND status = 'Success'
```

#### Variables

You can use the following variables in your query:

* `startTime` - The start time of the query window
* `endTime` - The end time of the query window