From 87337711129d8117e3d0328d36ea8cc5fc2bea52 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 ff9de357b1..a8b4d07a07 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 c42d753089..18758b451e 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 e063fbe320..500b843f54 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 128ed67279..5c960507ca 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 b75216c68295e030042ca7d1b08fc7006c4ae080 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic Date: Wed, 1 Nov 2023 18:28:14 +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 18758b451e..bbe7ebbfeb 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. From 807526376ce9d2e92c07370756c8bbc9ffe9e52e Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic Date: Wed, 1 Nov 2023 18:58:02 +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 bbe7ebbfeb..360161ecd4 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.