From e06688db223953079d28fae9ff9e25368c398a9d 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/3] 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 ce8223f069..2daa183c30 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 77dd784fc9..f6cdc9151c 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. +==== +>>>>>>> 783ce5a (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 ef1428e223..546f150671 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: You need at least `Read` privileges for the `Action and Connectors` feature to import rules with actions. If you're importing rules without actions, `Action and Connectors` feature privileges are not required. 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 2b66a945c1..d49213da14 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 45fb524bfd..7bff59e76c 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 79b38bc963fcd7061d3fe7e3bc3065c04fa4a337 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic Date: Wed, 1 Nov 2023 18:29:32 +0000 Subject: [PATCH 2/3] 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 f6cdc9151c..65663d2671 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. ==== ->>>>>>> 783ce5a (Updates warning about editing rules using API authentication (#4110)) Creates a new detection rule. From fc0f8a7de4cde4a597d4374bad2bf2034f5eb400 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic Date: Wed, 1 Nov 2023 18:58:46 +0000 Subject: [PATCH 3/3] Removes frontmatter --- docs/detections/api/rules/rules-api-create.asciidoc | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 65663d2671..5405b03e63 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -1,11 +1,6 @@ [[rules-api-create]] === Create rule -: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.