From 783ce5abd7439f2453d64edb221d89aaf2f2ebd0 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> Date: Wed, 1 Nov 2023 17:32:56 +0000 Subject: [PATCH] Updates warning about editing rules using API authentication (#4110) * Updates warning about editing rules using API authentication * Apply suggestions from TW review Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> * Applies TW feedback * Updates notes to address both scenarios * Removes extra period --------- Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> --- .../api/rules/rules-api-bulk-actions.asciidoc | 21 +++++++++++++++++-- .../api/rules/rules-api-create.asciidoc | 7 ++++++- .../api/rules/rules-api-import.asciidoc | 7 ++++++- .../api/rules/rules-api-overview.asciidoc | 17 +++++++++++++++ .../api/rules/rules-api-update.asciidoc | 7 ++++++- 5 files changed, 54 insertions(+), 5 deletions(-) diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc index f0c1a30be8..9c918318d0 100644 --- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc +++ b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc @@ -12,7 +12,12 @@ You can bulk create, update, and delete rules. IMPORTANT: This API has been deprecated since version 8.2, and is scheduled for end of life in Q4 2023. Please use the <> instead. -WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only. +[WARNING] +==== +When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. + +If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. +==== Creates new rules. @@ -145,7 +150,12 @@ A JSON array containing the deleted rules. IMPORTANT: This API has been deprecated since version 8.2, and is scheduled for end of life in Q4 2023. Please use the <> instead. -WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only. +[WARNING] +==== +When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. + +If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. +==== Updates multiple rules. @@ -228,6 +238,13 @@ A JSON array containing the updated rules. [[bulk-actions-rules-api-action]] ==== Bulk action +[WARNING] +==== +When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. + +If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. +==== + Applies a bulk action to multiple rules. The bulk action is applied to all rules that match the filter or to the list of rules by their IDs. [discrete] diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 71ade8249b..3603168eb6 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -6,7 +6,12 @@ :frontmatter-tags-content-type: [reference] :frontmatter-tags-user-goals: [manage] -WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only. +[WARNING] +==== +When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. + +If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. +==== Creates a new detection rule. diff --git a/docs/detections/api/rules/rules-api-import.asciidoc b/docs/detections/api/rules/rules-api-import.asciidoc index f65d1229c7..5f73a62bf3 100644 --- a/docs/detections/api/rules/rules-api-import.asciidoc +++ b/docs/detections/api/rules/rules-api-import.asciidoc @@ -6,7 +6,12 @@ Imports rules from an `.ndjson` file. The following configuration items are also * Actions * Exception lists -NOTE: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only. +[WARNING] +==== +When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. + +If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. +==== NOTE: To import rules with actions, you need at least `Read` privileges for the `Action and Connectors` feature. To overwrite or add new connectors, you need `All` privileges for the `Actions and Connectors` feature. To import rules without actions, you don't need `Actions and Connectors` privileges. Refer to <> for more information. diff --git a/docs/detections/api/rules/rules-api-overview.asciidoc b/docs/detections/api/rules/rules-api-overview.asciidoc index dda0c67c76..eebf54add1 100644 --- a/docs/detections/api/rules/rules-api-overview.asciidoc +++ b/docs/detections/api/rules/rules-api-overview.asciidoc @@ -31,6 +31,23 @@ the status of Elastic <> TIP: You can view and download a Detections API Postman collection https://github.com/elastic/examples/tree/master/Security%20Analytics/SIEM-examples/Detections-API[here]. +[float] +=== Authentication +This API supports both key- and token-based authentication. + +To use key-based authentication, create an {kibana-ref}/api-keys.html[API key], then specify the key in the header of your API calls. + +To use token-based authentication, provide a username and password; this automatically creates an API key that matches the current user's privileges. + +In both cases, the API key is subsequently used for authorization when the rule runs. + +[WARNING] +==== +If the API key has different privileges than the key that created or most recently updated the rule, the rule behavior might change. + +If the key that created the rule gets deleted, or the user that created the rule becomes inactive, the rule will stop running. +==== + [float] === Kibana role requirements diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index 8c9cb35bb6..b6b9129cc2 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -1,7 +1,12 @@ [[rules-api-update]] === Update rule -WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only. +[WARNING] +==== +When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. + +If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. +==== Updates an existing detection rule.