458 lines
14 KiB
Markdown
458 lines
14 KiB
Markdown
|
---
|
||
|
|
layout: default
|
||
|
|
title: Detector APIs
|
||
|
|
parent: API tools
|
||
|
|
nav_order: 35
|
||
|
|
---
|
||
|
|
|
||
|
|
# 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.
|
||
|
|
|
||
|
|
```json
|
||
|
|
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`<br> `period` | Object | the frequency at which the detector runs in repetition.
|
||
|
|
`schedule`<br> `period`<br> `interval` | Integer | The duration of the period expressed as a number.
|
||
|
|
`schedule`<br> `period`<br> `unit` | String | The unit of measure for the interval.
|
||
|
|
`inputs` | Object | In process
|
||
|
|
`inputs`<br> `detector_inputs` | Object | In process
|
||
|
|
`inputs`<br> `detector_inputs`<br> `description` | String | In process
|
||
|
|
`inputs`<br> `detector_inputs`<br> `custom_rules` | Object | In process
|
||
|
|
`inputs`<br> `detector_inputs`<br> `custom_rules`<br> `id` | String | In process
|
||
|
|
`inputs`<br> `detector_inputs`<br> `indices` | String | In process
|
||
|
|
`inputs`<br> `detector_inputs`<br> `pre_packaged_rules` | Object | In process
|
||
|
|
`inputs`<br> `detector_inputs`<br> `pre_packaged_rules`<br> `id` | String | In process
|
||
|
|
`triggers` | Object | In process
|
||
|
|
`triggers`<br> `ids` | String | In process
|
||
|
|
`triggers`<br> `types` | String | In process
|
||
|
|
`triggers`<br> `tags` | String | In process
|
||
|
|
`triggers`<br> `id` | String | In process
|
||
|
|
`triggers`<br> `sev_levels` | String | In process
|
||
|
|
`triggers`<br> `name` | String | In process
|
||
|
|
`triggers`<br> `severity` | Integer | In process
|
||
|
|
`triggers`<br> `actions` | Integer | In process
|
||
|
|
`triggers`<br> `actions`<br> `id` | Integer | In process
|
||
|
|
`triggers`<br> `actions`<br> `destination_id` | Integer | In process
|
||
|
|
`triggers`<br> `actions`<br> `subject_template` | Object | In process
|
||
|
|
`triggers`<br> `actions`<br> `subject_template`<br> `source` | String | In process
|
||
|
|
`triggers`<br> `actions`<br> `subject_template`<br> `lang` | String | In process
|
||
|
|
`triggers`<br> `actions`<br> `name` | String | In process
|
||
|
|
`triggers`<br> `actions`<br> `throttle_enabled` | Boolean | In process
|
||
|
|
`triggers`<br> `actions`<br> `message_template` | String | In process
|
||
|
|
`triggers`<br> `actions`<br> `message_template`<br> `source` | String | In process
|
||
|
|
`triggers`<br> `actions`<br> `message_template`<br> `lang` | String | In process
|
||
|
|
`triggers`<br> `actions`<br> `throttle` | Object | In process
|
||
|
|
`triggers`<br> `actions`<br> `throttle`<br> `unit` | String | In process
|
||
|
|
`triggers`<br> `actions`<br> `throttle`<br> `value` | Integer | In process
|
||
|
|
|
||
|
|
### Sample request
|
||
|
|
|
||
|
|
```json
|
||
|
|
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: {{ctx.trigger.name}}",
|
||
|
|
"lang": "mustache"
|
||
|
|
},
|
||
|
|
"name": "hello_world",
|
||
|
|
"throttle_enabled": false,
|
||
|
|
"message_template": {
|
||
|
|
"source": "Detector {{ctx.detector.name}} just entered alert status. Please investigate the issue." +
|
||
|
|
"- Trigger: {{ctx.trigger.name}}" +
|
||
|
|
"- Severity: {{ctx.trigger.severity}}",
|
||
|
|
"lang": "mustache"
|
||
|
|
},
|
||
|
|
"throttle": {
|
||
|
|
"unit": "MINUTES",
|
||
|
|
"value": 108
|
||
|
|
}
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"id": "8qhrBoQBYK1JzUUDzH-N",
|
||
|
|
"sev_levels": [],
|
||
|
|
"name": "test-trigger"
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"name": "nbReFCjlfn"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### Sample response
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"_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: {{ctx.trigger.name}}",
|
||
|
|
"lang": "mustache"
|
||
|
|
},
|
||
|
|
"throttle_enabled": false,
|
||
|
|
"subject_template": {
|
||
|
|
"source": "Detector {{ctx.detector.name}} just entered alert status. Please investigate the issue." +
|
||
|
|
"- Trigger: {{ctx.trigger.name}}" +
|
||
|
|
"- Severity: {{ctx.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.
|
||
|
|
|
||
|
|
```json
|
||
|
|
PUT /_plugins/_security_analytics/detectors/<detector_Id>
|
||
|
|
```
|
||
|
|
|
||
|
|
### Sample request
|
||
|
|
|
||
|
|
```json
|
||
|
|
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
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"_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
|
||
|
|
|
||
|
|
```json
|
||
|
|
DELETE /_plugins/_security_analytics/detectors/J1RX1IMByX0LvTiGTddR
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
## Get Detector
|
||
|
|
|
||
|
|
The Get detector API retrieves the detector details.
|
||
|
|
|
||
|
|
### Sample request
|
||
|
|
|
||
|
|
```json
|
||
|
|
GET /_plugins/_security_analytics/detectors/MFRg1IMByX0LvTiGHtcN
|
||
|
|
```
|
||
|
|
|
||
|
|
### Sample response
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"_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
|
||
|
|
|
||
|
|
```json
|
||
|
|
POST /_plugins/_security_analytics/detectors/_search
|
||
|
|
|
||
|
|
Body:
|
||
|
|
{
|
||
|
|
"query": {
|
||
|
|
"match": {
|
||
|
|
"_id": "MFRg1IMByX0LvTiGHtcN"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### Sample response
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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"
|
||
|
|
]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|