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