The SIEM app is now a part of the Elastic Security solution. Click here to view the current documentation.
IMPORTANT: No additional bug fixes or documentation updates will be released for this version.

› › ›

Signals endpoint

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Signals endpoint

edit

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 signals

edit

Aggregates and returns signals.

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 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 code

edit

200: Indicates a successful call.

Response payload

edit

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 status

edit

Sets the status of one or more signals.

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 rule IDs.	Yes, when the `query` field is not used.
`query`	Query DSL	Query that determines which signals are updated.	Yes, when the `signal_ids` field is not used.
`status`	String	The new status, which can be `open` or `closed`.	Yes.

Example requests

edit

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 code

edit

200: Indicates a successful call.

Response payload

edit

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

« Privileges endpoint Prebuilt rules »