Signals endpoint
editSignals endpoint
editThe signals endpoint is for retrieving, aggregating, and updating detection alerts. For detailed information on how to retrieve and aggregate results from the indices, see:
The Kibana Console supports only Elasticsearch APIs. You cannot interact with the Kibana APIs with the Console and must use curl
or another HTTP tool instead. For more information, refer to Console.
Get alerts
editAggregates and returns alerts.
Request URL
editPOST <kibana host>:<port>/api/detection_engine/signals/search
Request body
editA query DSL that determines which results are returned.
Example request
editGets 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
editA 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
editSets the status of one or more alert.
Request URL
editPOST <kibana host>:<port>/api/detection_engine/signals/status
Request body
editA 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 requests
editCloses 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
editA 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": [] }