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