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:

Console supports only Elasticsearch APIs. Console doesn’t allow interactions with Kibana APIs. You must use curl or another HTTP tool instead. For more information, refer to Run Elasticsearch API requests.

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

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, in-progress or closed.

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