Signals endpoint

edit

The signals endpoint is for retrieving, aggregating, and updating detection alerts. For detailed information on how to retrieve and aggregate results from the indices, see:

Get alerts

edit

Aggregates and returns alerts.

Request URL

edit

POST <kibana host>:<port>/api/detection_engine/signals/search

Request body

edit

A query DSL that determines which results are returned.

Example request
edit

Gets aggregated results of all open alerts with a risk score equal to or greater than 70. It also returns the timestamps of the oldest and newest alerts that meet the query’s criteria.

POST api/detection_engine/signals/search
{
  "aggs": {
    "latest": {
      "max": {
        "field": "@timestamp"
      }
    },
    "oldest": {
      "min": {
        "field": "@timestamp"
      }
    }
  },
  "query": {
    "bool": {
      "filter": [
        {
          "match": {
            "signal.status": "open"
          }
        },
        {
          "range": {
            "signal.rule.risk_score": {
              "gte": 70
            }
          }
        }
      ]
    }
  }
}

Gets all in-progress alerts with a risk score equal to or greater than 70.

POST api/detection_engine/signals/search
{
  "query": {
    "bool": {
      "filter": [
        {
          "match": {
            "signal.status": "in-progress"
          }
        },
        {
          "range": {
            "signal.rule.risk_score": {
              "gte": 70
            }
          }
        }
      ]
    }
  }
}

Response code

edit
200
Indicates a successful call.
Response payload
edit

A JSON object with the aggregated values and requested alerts.

Example response:

{
  "took": 3,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 8794,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "oldest": {
      "value": 1576601119930,
      "value_as_string": "2019-12-17T16:45:19.930Z"
    },
    "latest": {
      "value": 1576634706400,
      "value_as_string": "2019-12-18T02:05:06.400Z"
    }
  }
}

Set alert status

edit

Sets the status of one or more alert.

Request URL

edit

POST <kibana host>:<port>/api/detection_engine/signals/status

Request body

edit

A JSON object with either a query or signals_id field:

Name Type Description Required

signal_ids

String[]

Array of alert IDs.

Yes, when the query field is not used.

query

Query DSL

Query that determines which alerts are updated.

Yes, when the signal_ids field is not used.

status

String

The new status, which can be open, acknowledged, or closed.

Yes.

Example requests
edit

Closes alerts with signal_ids:

POST api/detection_engine/signals/status
{
  "signal_ids": [
    "694156bbe6a487e06d049bd6019bd49fec4172cfb33f5d81c3b4a977f0026fba",
    "f4d1c62c4e8946c835cb497329127803c09b955de49a8fa186be3899522667b0"
  ],
  "status": "closed"
}

Closes alerts that are over a month old and have a risk score less than or equal to 20:

POST api/detection_engine/signals/status
{
  "query": {
    "bool": {
      "filter": [
        {
          "range": {
            "signal.rule.risk_score": {
              "lte": 20
            }
          }
        },
        {
          "range": {
            "@timestamp": {
              "lte": "now-M"
            }
          }
        }
      ]
    }
  },
  "status": "closed"
}

Response code

edit
200
Indicates a successful call.
Response payload
edit

A JSON object containing the number of updated alerts.

Example response:

{
  "took": 9594,
  "timed_out": false,
  "total": 8794,
  "updated": 8794,
  "deleted": 0,
  "batches": 9,
  "version_conflicts": 0,
  "noops": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "throttled_millis": 0,
  "requests_per_second": -1,
  "throttled_until_millis": 0,
  "failures": []
}

Apply alert tags

edit

Add and remove alert tags.

Request URL

edit

POST <kibana host>:<port>/api/detection_engine/signals/tags

Request body

edit

A JSON object with the tags and ids fields:

Name Type Description Required

tags

Object

Object containing alert tags. Alert tags are the words and phrases that help categorize alerts.

Properties of the tags object:

  • tags_to_add: (Required, string[]) Array of tags you want to add.
  • tags_to_remove: (Required, string[]) Array of tags you want to remove.

You cannot add and remove the same alert tag.

No

ids

String[]

Array of alert IDs.

Yes

Example requests
edit

Adds and remove tags to alerts:

POST api/detection_engine/signals/tags
{
  "tags": {
    "tags_to_add": ["False Positive"],
    "tags_to_remove": ["Further Investigation Required"]
  },
  "ids": [
    "694156bbe6a487e06d049bd6019bd49fec4172cfb33f5d81c3b4a977f0026fba",
    "f4d1c62c4e8946c835cb497329127803c09b955de49a8fa186be3899522667b0"
  ]
}

Response code

edit
200
Indicates a successful call.
Response payload
edit

A JSON object containing alerts with newly added or removed alert tags.

Example response:

{
    "took": 699,
    "errors": false,
    "items": [
        {
            "update": {
                "_index": ".internal.alerts-security.alerts-default-000001",
                "_id": "694156bbe6a487e06d049bd6019bd49fec4172cfb33f5d81c3b4a977f0026fba",
                "_version": 2,
                "result": "updated",
                "_shards": {
                    "total": 1,
                    "successful": 1,
                    "failed": 0
                },
                "_seq_no": 137,
                "_primary_term": 1,
                "status": 200
            }
        },
        {
            "update": {
                "_index": ".internal.alerts-security.alerts-default-000001",
                "_id": "f4d1c62c4e8946c835cb497329127803c09b955de49a8fa186be3899522667b0",
                "_version": 2,
                "result": "updated",
                "_shards": {
                    "total": 1,
                    "successful": 1,
                    "failed": 0
                },
                "_seq_no": 138,
                "_primary_term": 1,
                "status": 200
            }
        }
    ]
}

Assign or unassign users from alerts

edit

Allows you to assign and unassign users from alerts.

Request URL

edit

POST <kibana host>:<port>/api/detection_engine/signals/assignees

Request body

edit

A JSON object with the assignees and ids fields:

Name Type Description Required

assignees

Object[]

An array of unique identifiers (UIDs) for user profiles. Properties of the assignees object:

  • add: (Required, string[]) An array of assignees you want to add.
  • remove: (Required, string[]) An array of assignees you want to unassign.

You cannot add and remove the same assignee.

Yes

ids

String[]

An array of alert IDs.

Yes

Example request
edit

Assigns and unassigns users to alerts:

POST api/detection_engine/signals/assignees

{
  "assignees": {
    "add": ["u_o4kzon2tUP0u189YjKVT0rTR_HBOED3JmyLLE6MrulY_0"],
    "remove": ["u_P4HW8xg4_xRVI7Oa-i6Ys1Gxe7k3jqZteAeZe6ZctEc_0"]
  },
  "ids": [
    "854f5eceeec1b4cd5495ad18c4259d6e5631a6677bc10c033edb318397d45459",
    "00968e97805854d0aa356968cad971d5184cdf91ebd458720c5b4099f4a5229a"
  ]
}

Response code

edit
200
Indicates a successful call.
Response payload
edit

A JSON object containing the number of updated alerts.

Example response:

{
  "took": 67,
  "timed_out": false,
  "total": 2,
  "updated": 2,
  "deleted": 0,
  "batches": 1,
  "version_conflicts": 0,
  "noops": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "throttled_millis": 0,
  "requests_per_second": -1,
  "throttled_until_millis": 0,
  "failures": []
}