From 62026a8a52ed4186a5928f919dce8c7365e8cf6d 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 1/2] 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> (cherry picked from commit 783ce5abd7439f2453d64edb221d89aaf2f2ebd0) # Conflicts: # docs/detections/api/rules/rules-api-create.asciidoc --- .../api/rules/rules-api-bulk-actions.asciidoc | 21 +++++++++++++++++-- .../api/rules/rules-api-create.asciidoc | 14 +++++++++++++ .../api/rules/rules-api-import.asciidoc | 7 ++++++- .../api/rules/rules-api-overview.asciidoc | 17 +++++++++++++++ .../api/rules/rules-api-update.asciidoc | 7 ++++++- 5 files changed, 62 insertions(+), 4 deletions(-) diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc index 43e29035ac..f4bbb33283 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 572aed55fb..59ef73389a 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -1,7 +1,21 @@ [[rules-api-create]] === Create rule +<<<<<<< HEAD WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only. +======= +:frontmatter-description: Create a new detection rule. +:frontmatter-tags-products: [security, alerting] +:frontmatter-tags-content-type: [reference] +:frontmatter-tags-user-goals: [manage] + +[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. +==== +>>>>>>> 783ce5ab (Updates warning about editing rules using API authentication (#4110)) 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 edf6f30c25..ebafbae7ff 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 621c6a9bdc..e6d3f7f807 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 0b2b47d266..6be8206757 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. From 9b5811657067424af168bc2ecf085c7f8ab5b62f Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic Date: Wed, 1 Nov 2023 18:23:04 +0000 Subject: [PATCH 2/2] Resolves conflict --- docs/detections/api/rules/rules-api-create.asciidoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 59ef73389a..a432630abc 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -1,9 +1,6 @@ [[rules-api-create]] === Create rule -<<<<<<< HEAD -WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only. -======= :frontmatter-description: Create a new detection rule. :frontmatter-tags-products: [security, alerting] :frontmatter-tags-content-type: [reference] @@ -15,7 +12,6 @@ When used with {kibana-ref}/api-keys.html[API key] authentication, the user's ke 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. ==== ->>>>>>> 783ce5ab (Updates warning about editing rules using API authentication (#4110)) Creates a new detection rule.