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

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 required

boolean

Whether the detection rule is enabled

severity required

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

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

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",
    "tags": ["scanner.error"],
    "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",
    "detection_rule_sync_id": null,
    "query_text": "error | count | where @q.count > 100",
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "time_range_s": 300,
    "run_frequency_s": 300,
    "debounce": true,
    "author_user_id": null,
    "name": "Errors",
    "description": "Errors in application logs",
    "enabled": true,
    "enabled_override": null,
    "severity": "Informational",
    "alert_template": null,
    "tags":["scanner.error"],
    "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.

Query parameters

Name
Type
Description

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

curl -G $API_BASE/v1/detection_rule \
--data-urlencode "tenant_id=00000000-0000-0000-0000-000000000001" \
--data-urlencode "pagination[page_size]=5" \
--data-urlencode "pagination[page_token]=1" \
-H "Authorization: Bearer $SCANNER_API_KEY" \
-H "Content-Type: application/json"

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.

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

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

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.

enabled

boolean

Enable or disable the detection rule

enabled_override

boolean or null

Enable or disable a synced detection rule, overrides enabled if non-null (can only be used on synced detection rules, where detection_rule_sync_id is non-null).

severity

Update the severity of the detection rule

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

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",
    "detection_rule_sync_id": null,
    "query_text": "error | count | where @q.count > 100",
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "time_range_s": 300,
    "run_frequency_s": 300,
    "debounce": true,
    "author_user_id": null,
    "name": "Errors",
    "description": "Detect errors in application logs",
    "enabled": true,
    "enabled_override": null,
    "severity": "Informational",
    "alert_template": null,
    "tags":["scanner.error"],
    "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"
}

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"

Last updated

Was this helpful?