New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« Privileges endpoint Prebuilt rules »
Elastic Docs ›Elastic Security Solution [8.17] ›Elastic Security APIs ›Detections API

Signals endpoint

edit

Signals endpoint

edit

New API Reference

For the most up-to-date API details, refer to detections APIs.

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
            }
          }
        }
      ]
    }
  }
}
Copy as curlTry in Elastic 

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
            }
          }
        }
      ]
    }
  }
}
Copy as curl 

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"
}
Copy as curl 

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"
}
Copy as curl 

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"
  ]
}
Copy as curlTry in Elastic 

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"
  ]
}
Copy as curl 

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": []
}
« Privileges endpoint Prebuilt rules »