Link Search Menu Expand Document Documentation Menu

Detector APIs

The following APIs can be used for a number of tasks related to detectors, from creating detectors to updating and searching for detectors.

Create Detector

Creates a new detector.

POST _plugins/_security_analytics/detectors

Parameters

You can specify the following parameters when creating a detector.

Parameter Type Description
enabled Boolean Enables the ability to add detectors through the API.
type String The type is specified as “detector”.
name String Name of the detector.
detector_type Object The log type that defines the detector.
schedule Object the schedule that determines how often the detector runs.
schedule
    period
Object the frequency at which the detector runs in repetition.
schedule
    period
        interval
Integer The duration of the period expressed as a number.
schedule
    period
        unit
String The unit of measure for the interval.
inputs Object In process
inputs
    detector_inputs
Object In process
inputs
    detector_inputs
        description
String In process
inputs
    detector_inputs
        custom_rules
Object In process
inputs
    detector_inputs
        custom_rules
            id
String In process
inputs
    detector_inputs
        indices
String In process
inputs
    detector_inputs
        pre_packaged_rules
Object In process
inputs
    detector_inputs
        pre_packaged_rules
            id
String In process
triggers Object In process
triggers
    ids
String In process
triggers
    types
String In process
triggers
    tags
String In process
triggers
    id
String In process
triggers
    sev_levels
String In process
triggers
    name
String In process
triggers
    severity
Integer In process
triggers
    actions
Integer In process
triggers
    actions
        id
Integer In process
triggers
    actions
        destination_id
Integer In process
triggers
    actions
        subject_template
Object In process
triggers
    actions
        subject_template
            source
String In process
triggers
    actions
        subject_template
            lang
String In process
triggers
    actions
        name
String In process
triggers
    actions
        throttle_enabled
Boolean In process
triggers
    actions
        message_template
String In process
triggers
    actions
        message_template
            source
String In process
triggers
    actions
        message_template
            lang
String In process
triggers
    actions
        throttle
Object In process
triggers
    actions
        throttle
            unit
String In process
triggers
    actions
        throttle
            value
Integer In process

Sample request

POST _plugins/_security_analytics/detectors
{
  "enabled": true,
  "schedule": {
    "period": {
      "interval": 1,
      "unit": "MINUTES"
    }
  },
  "detector_type": "WINDOWS",
  "type": "detector",
  "inputs": [
    {
      "detector_input": {
        "description": "windows detector for security analytics",
        "custom_rules": [
          {
            "id": "bc2RB4QBrbtylUb_1Pbm"
          }
        ],
        "indices": [
          "windows"
        ],
        "pre_packaged_rules": [
          {
            "id": "06724a9a-52fc-11ed-bdc3-0242ac120002"
          }
        ]
      }
    }
  ],
  "triggers": [
    {
      "ids": [
        "06724a9a-52fc-11ed-bdc3-0242ac120002"
      ],
      "types": [],
      "tags": [
        "attack.defense_evasion"
      ],
      "severity": "1",
      "actions": [{
          "id": "hVTLkZYzlA",
          "destination_id": "6r8ZBoQBKW_6dKriacQb",
          "subject_template": {
            "source": "Trigger: ",
            "lang": "mustache"
          },
          "name": "hello_world",
          "throttle_enabled": false,
          "message_template": {
            "source": "Detector  just entered alert status. Please investigate the issue." +
						"- Trigger: " +
						"- Severity: ",
            "lang": "mustache"
          },
          "throttle": {
            "unit": "MINUTES",
            "value": 108
          }
        }
      ],
      "id": "8qhrBoQBYK1JzUUDzH-N",
      "sev_levels": [],
      "name": "test-trigger"
    }
  ],
  "name": "nbReFCjlfn"
}

Sample response

{
    "_id": "dc2VB4QBrbtylUb_Hfa3",
    "_version": 1,
    "detector": {
        "name": "nbReFCjlfn",
        "detector_type": "windows",
        "enabled": true,
        "schedule": {
            "period": {
                "interval": 1,
                "unit": "MINUTES"
            }
        },
        "inputs": [
            {
                "detector_input": {
                    "description": "windows detector for security analytics",
                    "indices": [
                        "windows"
                    ],
                    "custom_rules": [
                        {
                            "id": "bc2RB4QBrbtylUb_1Pbm"
                        }
                    ],
                    "pre_packaged_rules": [
                        {
                            "id": "06724a9a-52fc-11ed-bdc3-0242ac120002"
                        }
                    ]
                }
            }
        ],
        "triggers": [
            {
                "id": "8qhrBoQBYK1JzUUDzH-N",
                "name": "test-trigger",
                "severity": "1",
                "types": [],
                "ids": [
                    "06724a9a-52fc-11ed-bdc3-0242ac120002"
                ],
                "sev_levels": [],
                "tags": [
                    "attack.defense_evasion"
                ],
                "actions": [
                    {
                        "id": "hVTLkZYzlA",
                        "name": "hello_world",
                        "destination_id": "6r8ZBoQBKW_6dKriacQb",
                        "message_template": {
                            "source": "Trigger: ",
                            "lang": "mustache"
                        },
                        "throttle_enabled": false,
                        "subject_template": {
                            "source": "Detector  just entered alert status. Please investigate the issue." +
										"- Trigger: " +
										"- Severity: ",
                            "lang": "mustache"
                        },
                        "throttle": {
                            "value": 108,
                            "unit": "MINUTES"
                        }
                    }
                ]
            }
        ],
        "last_update_time": "2022-10-24T01:22:03.738379671Z",
        "enabled_time": "2022-10-24T01:22:03.738376103Z"
    }
}

Update Detector

The Update detector API is used for updating a detector.

PUT /_plugins/_security_analytics/detectors/<detector_Id>

Sample request

PUT /_plugins/_security_analytics/detectors/J1RX1IMByX0LvTiGTddR
{
  "type": "detector",
  "detector_type": "windows",
  "name": "windows_detector",
  "enabled": true,
  "createdBy": "chip",
  "schedule": {
    "period": {
      "interval": 1,
      "unit": "MINUTES"
    }
  },
  "inputs": [
    {
      "input": {
        "description": "windows detector for security analytics",
        "indices": [
          "windows"
        ],
        "rules": [
          {
            "id": "46"
          }
        ]
      }
    }
  ],
  "triggers": [
    {
      "sev_levels": [],
      "tags": [],
      "actions": [],
      "types": [
        "windows"
      ],
      "name": "test-trigger",
      "id": "fyAy1IMBK2A1DZyOuW_b"
    }
  ]
}

Sample response

{
    "_id": "J1RX1IMByX0LvTiGTddR",
    "_version": 1,
    "detector": {
        "name": "windows_detector",
        "detector_type": "windows",
        "enabled": true,
        "schedule": {
            "period": {
                "interval": 1,
                "unit": "MINUTES"
            }
        },
        "inputs": [
            {
                "detector_input": {
                    "description": "windows detector for security analytics",
                    "indices": [
                        "windows"
                    ],
                    "rules": [
                        {
                            "id": "LFRY1IMByX0LvTiGZtfh"
                        }
                    ]
                }
            }
        ],
        "triggers": [],
        "last_update_time": "2022-10-14T02:36:32.909581688Z",
        "enabled_time": "2022-10-14T02:33:34.197Z"
    }
}

Delete Detector

This API is used for deleting a detector.

Sample request

DELETE /_plugins/_security_analytics/detectors/J1RX1IMByX0LvTiGTddR

Get Detector

The Get detector API retrieves the detector details.

Sample request

GET /_plugins/_security_analytics/detectors/MFRg1IMByX0LvTiGHtcN

Sample response

{
    "_id": "MFRg1IMByX0LvTiGHtcN",
    "_version": 1,
    "detector": {
        "name": "windows_detector",
        "detector_type": "windows",
        "enabled": true,
        "schedule": {
            "period": {
                "interval": 1,
                "unit": "MINUTES"
            }
        },
        "inputs": [
            {
                "detector_input": {
                    "description": "windows detector for security analytics",
                    "indices": [
                        "windows"
                    ],
                    "rules": []
                }
            }
        ],
        "last_update_time": "2022-10-14T02:43:11.693Z",
        "enabled_time": "2022-10-14T02:43:11.693Z"
    }
}

Search Detector

The Search detector API searches for detector matches by detector ID.

Sample request

POST /_plugins/_security_analytics/detectors/_search

Body:
{
    "query": {
        "match": {
            "_id": "MFRg1IMByX0LvTiGHtcN"
        }
    }
}

Sample response

{
    "took": 2,
    "timed_out": false,
    "_shards": {
        "total": 1,
        "successful": 1,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 1,
            "relation": "eq"
        },
        "max_score": 1.0,
        "hits": [
            {
                "_index": ".opensearch-detectors-config",
                "_id": "MFRg1IMByX0LvTiGHtcN",
                "_version": 1,
                "_seq_no": 6,
                "_primary_term": 1,
                "_score": 1.0,
                "_source": {
                    "type": "detector",
                    "name": "windows_detector",
                    "detector_type": "WINDOWS",
                    "enabled": true,
                    "enabled_time": 1665715391693,
                    "schedule": {
                        "period": {
                            "interval": 1,
                            "unit": "MINUTES"
                        }
                    },
                    "inputs": [
                        {
                            "detector_input": {
                                "description": "windows detector for security analytics",
                                "indices": [
                                    "windows"
                                ],
                                "rules": []
                            }
                        }
                    ],
                    "triggers": [
                        {
                            "id": "fyAy1IMBK2A1DZyOuW_b",
                            "name": "test-trigger",
                            "types": [
                                "windows"
                            ],
                            "sev_levels": [],
                            "tags": [],
                            "actions": []
                        }
                    ],
                    "last_update_time": 1665715391693,
                    "monitor_id": [
                        "LlRf1IMByX0LvTiGzdeX"
                    ]
                }
            }
        ]
    }
}