Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Docs for Bulk Update Schedule and Rule Actions #2506

Merged
96 changes: 96 additions & 0 deletions docs/detections/api/rules/rules-api-bulk-actions.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -306,6 +306,32 @@ 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

`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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Modified this example to be consistent with the previous two examples for interval and lookback:

Suggested change
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"`
banderror marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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`: <<actions-object-schema-bulk, actions[]>> ,
`throttle`: <<throttle-schema-bulk, throttle>>
} | Add actions to rules
| `set_rule_actions` | {
`actions`: <<actions-object-schema-bulk, actions[]>> ,
`throttle`: <<throttle-schema-bulk, throttle>>
} | Overwrite existing actions to rules
banderror marked this conversation as resolved.
Show resolved Hide resolved


|==============================================

<<bulk-edit-object-schema, Actions>> are shown in order of oldest to newest in the `edit` array payload's property.
Expand Down Expand Up @@ -688,3 +714,73 @@ Notice that there are no arrays in `attributes.results`. In dry run mode, rule u
}
}
--------------------------------------------------

[discrete]
[[actions-object-schema-bulk]]
===== `actions` schema
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this section going to be deleted?

Copy link
Contributor Author

@jpdjere jpdjere Sep 28, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it shouldn't. See Joe's comment above: I would have liked to extract the actions schema to its own page and link to it from both this page and from this page, but he mentioned that he'd rather not do these refactoring before the docs are migrated, soon.

And I think the actions schema should be in this page, otherwise it's confusing to understand what it means in the context of this API request.

Copy link
Contributor

@banderror banderror Sep 29, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. The reason I asked is that when I was reviewing this PR links to the actions schema were pointing to the rule creation endpoint. Now when they send the user to this section it LGTM 👍

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I'd probably do is I'd lift "actions schema" and "throttle schema" up, because right now the page structure is:

  1. "BulkEditAction object" - its schema
  2. Examples
  3. "actions schema"
  4. "throttle schema"

I'd keep examples after all schemas

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense, reorganized page


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