From e61f9c0fada79a29b3dbea1a523cd90394fbeea0 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Wed, 1 Nov 2023 19:23:04 +0000 Subject: [PATCH] [8.2] Updates warning about editing rules using API authentication (backport #4110) (#4159) * 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 # docs/detections/api/rules/rules-api-import.asciidoc * Resolves conflict * Removes frontmatter --------- Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> Co-authored-by: natasha-moore-elastic --- .../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, 55 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 f2449d462a..e9a191fd7b 100644 --- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc +++ b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc @@ -14,7 +14,12 @@ NOTE: Console supports only {es} APIs and doesn't allow interactions with {kib} 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. @@ -147,7 +152,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. @@ -230,6 +240,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 81c439dd70..f24bc1766b 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -1,7 +1,12 @@ [[rules-api-create]] === Create 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. +==== 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 11ae47c919..4302fc2e01 100644 --- a/docs/detections/api/rules/rules-api-import.asciidoc +++ b/docs/detections/api/rules/rules-api-import.asciidoc @@ -6,6 +6,13 @@ Imports rules from an `.ndjson` file. The following configuration items are also * Actions * Exception lists +[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: Console supports {es} APIs only. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests]. Please also note this API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only. 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 488bcfc1ab..66412ca958 100644 --- a/docs/detections/api/rules/rules-api-overview.asciidoc +++ b/docs/detections/api/rules/rules-api-overview.asciidoc @@ -33,6 +33,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 1395dd4345..a3da2f12c5 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.