IMPORTANT: No additional bug fixes or documentation updates will be released for this version.
Signals endpointedit
The signals endpoint is for retrieving, aggregating, and updating signals. For detailed information on how to retrieve and aggregate results from the indices, see:
Get signalsedit
Aggregates and returns signals.
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 signals with a risk score equal to or greater than 70. It also returns the timestamps of the oldest and newest signals 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 } } } ] } }, "size": 0 }
Response codeedit
-
200
- Indicates a successful call.
Response payloadedit
A JSON object with the aggregated values and requested signals.
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 signal statusedit
Sets the status of one or more signals.
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 rule IDs. |
Yes, when the |
|
Query DSL |
Query that determines which signals are updated. |
Yes, when the |
|
String |
The new status, which can be |
Yes. |
Example requestsedit
Closes signal with signal IDs:
POST api/detection_engine/signals/status { "signal_ids": [ "694156bbe6a487e06d049bd6019bd49fec4172cfb33f5d81c3b4a977f0026fba", "f4d1c62c4e8946c835cb497329127803c09b955de49a8fa186be3899522667b0" ], "status": "closed" }
Closes signals 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 signals.
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": [] }