Signals endpointedit
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 alertsedit
Aggregates and returns alerts.
Request URLedit
POST <kibana host>:<port>/api/detection_engine/signals/search
Request bodyedit
A query DSL that determines which results are returned.
Example requestedit
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 codeedit
-
200 - Indicates a successful call.
Response payloadedit
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 statusedit
Sets the status of one or more alert.
Request URLedit
POST <kibana host>:<port>/api/detection_engine/signals/status
Request bodyedit
A JSON object with either a query or signals_id field:
| Name | Type | Description | Required |
|---|---|---|---|
|
String[] |
Array of alert IDs. |
Yes, when the |
|
Query DSL |
Query that determines which alerts are updated. |
Yes, when
the |
|
String |
The new status, which can be |
Yes. |
Example requestsedit
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 codeedit
-
200 - Indicates a successful call.
Response payloadedit
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 tagsedit
Add and remove alert tags.
Request URLedit
POST <kibana host>:<port>/api/detection_engine/signals/tags
Request bodyedit
A JSON object with the tags and ids fields:
| Name | Type | Description | Required |
|---|---|---|---|
|
Object |
Object containing alert tags. Alert tags are the words and phrases that help categorize alerts. Properties of the
You cannot add and remove the same alert tag. |
No |
|
String[] |
Array of alert IDs. |
Yes |
Example requestsedit
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 codeedit
-
200 - Indicates a successful call.
Response payloadedit
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 alertsedit
Allows you to assign and unassign users from alerts.
Request URLedit
POST <kibana host>:<port>/api/detection_engine/signals/assignees
Request bodyedit
A JSON object with the assignees and ids fields:
| Name | Type | Description | Required |
|---|---|---|---|
|
Object[] |
An array of unique identifiers (UIDs) for user profiles. Properties of the
You cannot add and remove the same assignee. |
Yes |
|
String[] |
An array of alert IDs. |
Yes |
Example requestedit
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 codeedit
-
200 - Indicates a successful call.
Response payloadedit
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": []
}