From fa83ddb821ea4d05efb09814763ceab429649996 Mon Sep 17 00:00:00 2001 From: jpdjere Date: Tue, 27 Sep 2022 17:59:32 +0200 Subject: [PATCH 1/6] Add Docs for Bulk Update Schedule and Rule Actions --- .../api/rules/rules-api-bulk-actions.asciidoc | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc index e56dd62544..3165ec5231 100644 --- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc +++ b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc @@ -306,6 +306,36 @@ IMPORTANT: Dry run mode is not supported for the `export` bulk action. A `400` e | `delete_index_patterns` | String[] | Delete rules' index patterns | `set_index_patterns` | String[] | Overwrite rules' index patterns | `set_timeline` | { `timeline_id`: String; `timeline_title`: String } | Overwrite rules' Timeline template +| `set_schedule` + +| { `interval`: String; `lookback`: String } +| Overwrite rules' schedule + + +Both `interval` and `lookback` have a format of {integer}{time_unit}, with the accepted time units being `"s"` for +seconds, `"m"` for minutes and `"h"` for hours. The integer must be positive and larger than 0. + +Examples: `"45s"`, `"30m"`, `"6h"` + +| `add_rule_actions` | { + `actions`: <> , + `throttle`: String + } | Add actions to rules +| `set_rule_actions` | { + `actions`: <> , + `throttle`: String + } | Overwrite existing actions to rules + +`throttle` accepts the following values: + +- `"rule"`: Execute actions on each rule execution + +- `"1h"`: Execute actions once per hour + +- `"1d"`: Execute actions once per day + +- `"7d"`: Execute actions once per week + |============================================== <> are shown in order of oldest to newest in the `edit` array payload's property. @@ -688,3 +718,56 @@ Notice that there are no arrays in `attributes.results`. In dry run mode, rule u } } -------------------------------------------------- + + +[[actions-object-schema-update]] +===== `actions` schema + +These fields are required when calling `PUT` to modify the `actions` object: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|action_type_id |String a|The action type used for sending notifications, can +be: + +* `.slack` +* `.email` +* `.pagerduty` +* `.webhook` + +|group |String |Optionally groups actions by use cases. Use `default` for alert +notifications. + +|id |String |The connector ID. + +|params |Object a|Object containing the allowed connector fields, which varies according to the connector type: + +* For Slack: +** `message` (string, required): The notification message. +* For email: +** `to`, `cc`, `bcc` (string): Email addresses to which the notifications are +sent. At least one field must have a value. +** `subject` (string, optional): Email subject line. +** `message` (string, required): Email body text. +* For Webhook: +** `body` (string, required): JSON payload. +* For PagerDuty: +** `severity` (string, required): Severity of on the alert notification, can +be: `Critical`, `Error`, `Warning` or `Info`. +** `eventAction` (string, required): Event https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[action type], which can be `trigger`, +`resolve`, or `acknowledge`. +** `dedupKey` (string, optional): Groups alert notifications with the same +PagerDuty alert. +** `timestamp` (DateTime, optional): https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format timestamp]. +** `component` (string, optional): Source machine component responsible for the +event, for example `security-solution`. +** `group` (string, optional): Enables logical grouping of service components. +** `source` (string, optional): The affected system. Defaults to the {kib} +saved object ID of the action. +** `summary` (string, options): Summary of the event. Defaults to +`No summary provided`. Maximum length is 1024 characters. +** `class` (string, optional): Value indicating the class/type of the event. + +|============================================== From faee8feec7ed33a6be8502d59f04875c47ab5b2a Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Tue, 27 Sep 2022 15:21:38 -0400 Subject: [PATCH 2/6] Fix CI build checks - Add discrete tag to include section on same page of HTML output - Rename section anchor so it's a unique value --- docs/detections/api/rules/rules-api-bulk-actions.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc index 3165ec5231..21313b1fde 100644 --- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc +++ b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc @@ -719,8 +719,8 @@ Notice that there are no arrays in `attributes.results`. In dry run mode, rule u } -------------------------------------------------- - -[[actions-object-schema-update]] +[discrete] +[[actions-object-schema-bulk]] ===== `actions` schema These fields are required when calling `PUT` to modify the `actions` object: From f3bc0ada53b3f460012c2b58c3f377f154551dac Mon Sep 17 00:00:00 2001 From: jpdjere Date: Wed, 28 Sep 2022 14:52:42 +0200 Subject: [PATCH 3/6] Refactor throttle schema --- .../api/rules/rules-api-bulk-actions.asciidoc | 39 ++++++++++++------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc index 21313b1fde..6ccdd25e4e 100644 --- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc +++ b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc @@ -311,6 +311,11 @@ IMPORTANT: Dry run mode is not supported for the `export` bulk action. A `400` e | { `interval`: String; `lookback`: String } | Overwrite rules' schedule +`interval`: Frequency of rule execution. For example, `"1h"` means the rule runs every hour. + +`lookback`: Additional look-back time that the rule analyzes. For example, `"10m"` means the rule analyzes the last 10 minutes of data in addition to the frequency interval. + +If `interval` is set to `"5m"` and `lookback` to `"1m"`, then the rule runs every 5 minutes but analyzes the documents added to indices during the last 6 minutes. Both `interval` and `lookback` have a format of {integer}{time_unit}, with the accepted time units being `"s"` for seconds, `"m"` for minutes and `"h"` for hours. The integer must be positive and larger than 0. @@ -318,23 +323,14 @@ seconds, `"m"` for minutes and `"h"` for hours. The integer must be positive and Examples: `"45s"`, `"30m"`, `"6h"` | `add_rule_actions` | { - `actions`: <> , - `throttle`: String + `actions`: <> , + `throttle`: <> } | Add actions to rules | `set_rule_actions` | { - `actions`: <> , - `throttle`: String + `actions`: <> , + `throttle`: <> } | Overwrite existing actions to rules -`throttle` accepts the following values: - -- `"rule"`: Execute actions on each rule execution - -- `"1h"`: Execute actions once per hour - -- `"1d"`: Execute actions once per day - -- `"7d"`: Execute actions once per week |============================================== @@ -771,3 +767,20 @@ saved object ID of the action. ** `class` (string, optional): Value indicating the class/type of the event. |============================================== + +--- + +[discrete] +[[throttle-schema-bulk]] +===== `throttle` schema + + +`throttle` defines the maximum interval in which a rules `actions` are executed. It accepts the following values: + +- `"rule"`: Execute actions on each rule execution + +- `"1h"`: Execute actions once per hour + +- `"1d"`: Execute actions once per day + +- `"7d"`: Execute actions once per week \ No newline at end of file From 35e5ed43b013edbbc9482f66491c962840c99b98 Mon Sep 17 00:00:00 2001 From: jpdjere Date: Thu, 29 Sep 2022 15:20:43 +0200 Subject: [PATCH 4/6] Reorganized structure of page --- .../api/rules/rules-api-bulk-actions.asciidoc | 144 +++++++++--------- 1 file changed, 72 insertions(+), 72 deletions(-) diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc index 6ccdd25e4e..faf05244b5 100644 --- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc +++ b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc @@ -329,13 +329,84 @@ Examples: `"45s"`, `"30m"`, `"6h"` | `set_rule_actions` | { `actions`: <> , `throttle`: <> - } | Overwrite existing actions to rules + } | Overwrite rules' existing actions |============================================== <> are shown in order of oldest to newest in the `edit` array payload's property. + +[discrete] +[[actions-object-schema-bulk]] +===== `actions` schema + +These fields are required when calling `PUT` to modify the `actions` object: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|action_type_id |String a|The action type used for sending notifications, can +be: + +* `.slack` +* `.email` +* `.pagerduty` +* `.webhook` + +|group |String |Optionally groups actions by use cases. Use `default` for alert +notifications. + +|id |String |The connector ID. + +|params |Object a|Object containing the allowed connector fields, which varies according to the connector type: + +* For Slack: +** `message` (string, required): The notification message. +* For email: +** `to`, `cc`, `bcc` (string): Email addresses to which the notifications are +sent. At least one field must have a value. +** `subject` (string, optional): Email subject line. +** `message` (string, required): Email body text. +* For Webhook: +** `body` (string, required): JSON payload. +* For PagerDuty: +** `severity` (string, required): Severity of on the alert notification, can +be: `Critical`, `Error`, `Warning` or `Info`. +** `eventAction` (string, required): Event https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[action type], which can be `trigger`, +`resolve`, or `acknowledge`. +** `dedupKey` (string, optional): Groups alert notifications with the same +PagerDuty alert. +** `timestamp` (DateTime, optional): https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format timestamp]. +** `component` (string, optional): Source machine component responsible for the +event, for example `security-solution`. +** `group` (string, optional): Enables logical grouping of service components. +** `source` (string, optional): The affected system. Defaults to the {kib} +saved object ID of the action. +** `summary` (string, options): Summary of the event. Defaults to +`No summary provided`. Maximum length is 1024 characters. +** `class` (string, optional): Value indicating the class/type of the event. + +|============================================== + +--- + +[discrete] +[[throttle-schema-bulk]] +===== `throttle` schema + + +`throttle` defines the maximum interval in which a rules `actions` are executed. It accepts the following values: + +- `"rule"`: Execute actions on each rule execution + +- `"1h"`: Execute actions once per hour + +- `"1d"`: Execute actions once per day + +- `"7d"`: Execute actions once per week + [discrete] ===== Example requests @@ -713,74 +784,3 @@ Notice that there are no arrays in `attributes.results`. In dry run mode, rule u } } } --------------------------------------------------- - -[discrete] -[[actions-object-schema-bulk]] -===== `actions` schema - -These fields are required when calling `PUT` to modify the `actions` object: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|action_type_id |String a|The action type used for sending notifications, can -be: - -* `.slack` -* `.email` -* `.pagerduty` -* `.webhook` - -|group |String |Optionally groups actions by use cases. Use `default` for alert -notifications. - -|id |String |The connector ID. - -|params |Object a|Object containing the allowed connector fields, which varies according to the connector type: - -* For Slack: -** `message` (string, required): The notification message. -* For email: -** `to`, `cc`, `bcc` (string): Email addresses to which the notifications are -sent. At least one field must have a value. -** `subject` (string, optional): Email subject line. -** `message` (string, required): Email body text. -* For Webhook: -** `body` (string, required): JSON payload. -* For PagerDuty: -** `severity` (string, required): Severity of on the alert notification, can -be: `Critical`, `Error`, `Warning` or `Info`. -** `eventAction` (string, required): Event https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[action type], which can be `trigger`, -`resolve`, or `acknowledge`. -** `dedupKey` (string, optional): Groups alert notifications with the same -PagerDuty alert. -** `timestamp` (DateTime, optional): https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format timestamp]. -** `component` (string, optional): Source machine component responsible for the -event, for example `security-solution`. -** `group` (string, optional): Enables logical grouping of service components. -** `source` (string, optional): The affected system. Defaults to the {kib} -saved object ID of the action. -** `summary` (string, options): Summary of the event. Defaults to -`No summary provided`. Maximum length is 1024 characters. -** `class` (string, optional): Value indicating the class/type of the event. - -|============================================== - ---- - -[discrete] -[[throttle-schema-bulk]] -===== `throttle` schema - - -`throttle` defines the maximum interval in which a rules `actions` are executed. It accepts the following values: - -- `"rule"`: Execute actions on each rule execution - -- `"1h"`: Execute actions once per hour - -- `"1d"`: Execute actions once per day - -- `"7d"`: Execute actions once per week \ No newline at end of file From 6a99fdfb35e50079804c67788c06b0236fe419ac Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Fri, 30 Sep 2022 11:43:43 -0400 Subject: [PATCH 5/6] Fix build End of block line probably got deleted accidentally --- docs/detections/api/rules/rules-api-bulk-actions.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc index faf05244b5..5c3fe55217 100644 --- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc +++ b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc @@ -784,3 +784,4 @@ Notice that there are no arrays in `attributes.results`. In dry run mode, rule u } } } +-------------------------------------------------- From 8c280381393084022036a3241ff3d7282c8f09a0 Mon Sep 17 00:00:00 2001 From: jpdjere Date: Fri, 30 Sep 2022 18:18:57 +0200 Subject: [PATCH 6/6] Address comments by security-docs team --- .../api/rules/rules-api-bulk-actions.asciidoc | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc index faf05244b5..e68207924e 100644 --- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc +++ b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc @@ -315,12 +315,9 @@ IMPORTANT: Dry run mode is not supported for the `export` bulk action. A `400` e `lookback`: Additional look-back time that the rule analyzes. For example, `"10m"` means the rule analyzes the last 10 minutes of data in addition to the frequency interval. -If `interval` is set to `"5m"` and `lookback` to `"1m"`, then the rule runs every 5 minutes but analyzes the documents added to indices during the last 6 minutes. +If `interval` is set to `"10m"` and `lookback` to `"1m"`, then the rule runs every 5 minutes but analyzes the documents added to indices during the last 11 minutes. -Both `interval` and `lookback` have a format of {integer}{time_unit}, with the accepted time units being `"s"` for -seconds, `"m"` for minutes and `"h"` for hours. The integer must be positive and larger than 0. - -Examples: `"45s"`, `"30m"`, `"6h"` +Both `interval` and `lookback` have a format of `"{integer}{time_unit}"`, where accepted time units are `s` for seconds, `m` for minutes, and `h` for hours. The integer must be positive and larger than 0. Examples: `"45s"`, `"30m"`, `"6h"` | `add_rule_actions` | { `actions`: <> , @@ -390,14 +387,12 @@ saved object ID of the action. |============================================== ---- - [discrete] [[throttle-schema-bulk]] ===== `throttle` schema -`throttle` defines the maximum interval in which a rules `actions` are executed. It accepts the following values: +`throttle` defines the maximum interval in which a rule's actions are executed. It accepts the following values: - `"rule"`: Execute actions on each rule execution