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

Name	Type	Description
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	See Time range and run frequency	Lookback period (in seconds)
run_frequency_s required	See Time range and run frequency	How frequently to run the detection rule (in seconds)
enabled required	boolean	Whether the detection rule is enabled
severity required	See Detection severity	The severity of the detection
query_text required	string	Query for the detection rule
event_sink_ids required	list of strings	Event sinks to send event alerts to
sync_key	string	Sync key, used by automatic detection rule syncers

Example

curl $API_BASE/v1/detection_rule \
-H "Authorization: Bearer $SCANNER_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "name": "Errors",
    "description": "Errors in application logs",
    "time_range_s": 300,
    "run_frequency_s": 300,
    "enabled": true,
    "severity": "Informational",
    "query_text": "error | count | where @q.count > 100",
    "event_sink_ids": []
}'

Response

Returns the newly created detection rule.

{
  "detection_rule": {
    "id": "d87284f8-b0f3-4464-9ba9-258c0e585d09",
    "sync_key": null,
    "prepared_query_id": "b8aa9bb6-de1e-4ef8-82bb-29974a1e4ff2",
    "query_text": "error | count | where @q.count > 100",
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "time_range_s": 300,
    "run_frequency_s": 300,
    "author_user_id": null,
    "name": "Errors",
    "description": "Errors in application logs",
    "enabled": true,
    "severity": "Informational",
    "created_at": "2024-05-09T01:07:24Z",
    "updated_at": "2024-05-09T01:07:24Z",
    "event_sink_ids": [],
    "last_alerted_at": null
  }
}

List detection rules

GET /v1/detection_rule

List all detection rules for a tenant.

Body

Name	Type	Description
tenant_id required	string	Unique identifier for the tenant

Example

curl $API_BASE/v1/detection_rule \
-H "Authorization: Bearer $SCANNER_API_KEY" \
-H "Content-Type: application/json" \
-X GET \
-d '{ "tenant_id": "00000000-0000-0000-0000-000000000001" }'

Response

Returns a list of detection rule summaries. The detection rule summary object is the same as the detection rule object, but it does not include event_sink_ids.

{
  "detection_rules": [
    {
      "id": "d87284f8-b0f3-4464-9ba9-258c0e585d09",
      "sync_key": null,
      "prepared_query_id": "b8aa9bb6-de1e-4ef8-82bb-29974a1e4ff2",
      "query_text": "error | count | where @q.count > 100",
      "tenant_id": "00000000-0000-0000-0000-000000000000",
      "time_range_s": 300,
      "run_frequency_s": 300,
      "author_user_id": null,
      "name": "Errors",
      "description": "Errors in application logs",
      "enabled": true,
      "severity": "Informational",
      "created_at": "2024-05-09T01:07:24Z",
      "updated_at": "2024-05-09T01:07:24Z",
      "last_alerted_at": null
    }
  ]
}

Get a detection rule

GET /v1/detection_rule/{id}

Get the detection rule with the given id.

Example

curl $API_BASE/v1/detection_rule/d87284f8-b0f3-4464-9ba9-258c0e585d09 \
-H "Authorization: Bearer $SCANNER_API_KEY" \
-H "Content-Type: application/json" \
-X GET

Response

Returns the detection rule.

{
  "detection_rule": {
    "id": "d87284f8-b0f3-4464-9ba9-258c0e585d09",
    "sync_key": null,
    "prepared_query_id": "b8aa9bb6-de1e-4ef8-82bb-29974a1e4ff2",
    "query_text": "error | count | where @q.count > 100",
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "time_range_s": 300,
    "run_frequency_s": 300,
    "author_user_id": null,
    "name": "Errors",
    "description": "Errors in application logs",
    "enabled": true,
    "severity": "Informational",
    "created_at": "2024-05-09T01:07:24Z",
    "updated_at": "2024-05-09T01:07:24Z",
    "event_sink_ids": [],
    "last_alerted_at": null
  }
}

Update a detection rule

PUT /v1/detection_rule/{id}

Update the detection rule with the given id.

Body

Name	Type	Description
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	See Time range and run frequency	Update the lookback period of the detection rule
run_frequency_s	See Time range and run frequency	Update the how frequently the detection rule is run
enabled	boolean	Enable or disable the detection rule
severity	See Detection severity	Update the severity of the detection rule
query_text	string	Update the query for the detection rule
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

Example

curl $API_BASE/v1/detection_rule/d87284f8-b0f3-4464-9ba9-258c0e585d09 \
-H "Authorization: Bearer $SCANNER_API_KEY" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
    "id": "d87284f8-b0f3-4464-9ba9-258c0e585d09",
    "description": "Detect errors in application logs"
}'

Response

Returns the updated detection rule.

{
  "detection_rule": {
    "id": "d87284f8-b0f3-4464-9ba9-258c0e585d09",
    "sync_key": null,
    "prepared_query_id": "b8aa9bb6-de1e-4ef8-82bb-29974a1e4ff2",
    "query_text": "error | count | where @q.count > 100",
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "time_range_s": 300,
    "run_frequency_s": 300,
    "author_user_id": null,
    "name": "Errors",
    "description": "Detect errors in application logs",
    "enabled": true,
    "severity": "Informational",
    "created_at": "2024-05-09T01:07:24Z",
    "updated_at": "2024-05-09T01:07:24Z",
    "event_sink_ids": [],
    "last_alerted_at": null
  }
}

Delete a detection rule

DELETE /v1/detection_rule/{id}

Delete the detection rule with the given id.

Example

curl $API_BASE/v1/detection_rule/123e4567-e89b-12d3-a456-426614174000 \
-H "Authorization: Bearer $SCANNER_API_KEY" \
-H "Content-Type: application/json" \
-X DELETE

Response

Returns the id and tenant_id for the deleted detection rule.

{
  "id": "d87284f8-b0f3-4464-9ba9-258c0e585d09",
  "tenant_id": "00000000-0000-0000-0000-000000000000"
}

Time range and run frequency

time_range_s is the lookback period for the detection rule and run_frequency_s is how often the detection rule is run. Valid values for time_range_s and run_frequency_s are:

• 60 (1 minute)

• 300 (5 minutes)

• 900 (15 minutes)

• 3600 (1 hour)

• 21600 (6 hours)

• 86400 (24 hours)

run_frequency_s is at most two levels below time_range_s. For example, if time_range_s is 300, valid values for run_frequency_s are 60, 300, and 900.

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.

"severity": "Critical"