This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.

« Privileges endpoint Prebuilt rules »

› › ›

Signals endpoint

Signals endpoint

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

Aggregates and returns alerts.

Request URL

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

Request body

A query DSL that determines which results are returned.

Example request

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

200: Indicates a successful call.

Response payload

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

Sets the status of one or more alert.

Request URL

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

Request body

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

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

200: Indicates a successful call.

Response payload

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

Add and remove alert tags.

Request URL

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

Request body

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

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

200: Indicates a successful call.

Response payload

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

Allows you to assign and unassign users from alerts.

Request URL

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

Request body

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

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

200: Indicates a successful call.

Response payload

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": []
}

« Privileges endpoint Prebuilt rules »