IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› › ›

Signals endpoint

edit

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

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

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.

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

« Privileges endpoint Prebuilt rules »