From 8104e2709ebe53885eb47fe70b19a09106e7a52f Mon Sep 17 00:00:00 2001 From: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Tue, 28 Mar 2023 13:01:32 -0400 Subject: [PATCH] Action connectors can be imported/exported with rules (#3021) Co-authored-by: Joe Peeples (cherry picked from commit e79d88298dcc1d23dbfb2cc4d17c23e699ff36a3) --- docs/detections/api/rules/rules-api-export.asciidoc | 4 +++- docs/detections/api/rules/rules-api-import.asciidoc | 8 ++++++-- docs/detections/rules-ui-manage.asciidoc | 11 +++++++---- docs/getting-started/detections-req.asciidoc | 2 +- 4 files changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/detections/api/rules/rules-api-export.asciidoc b/docs/detections/api/rules/rules-api-export.asciidoc index 971459a2a4..5acef3e019 100644 --- a/docs/detections/api/rules/rules-api-export.asciidoc +++ b/docs/detections/api/rules/rules-api-export.asciidoc @@ -10,7 +10,9 @@ You cannot export prebuilt rules, but they are available at https://github.com/e [IMPORTANT] ================= -Although detection rule actions are included in the exported file, the connectors used by the actions are not included. Use the {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI in Kibana (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors _before_ you export and import the detection rules. +Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) _is not_ included. You must re-add missing connector details after importing detection rules. + +You can use {kib}'s {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors before importing detection rules. Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the <> UI (*Manage* -> *Rules* -> *Import value lists*) to export and import value lists separately. ================= diff --git a/docs/detections/api/rules/rules-api-import.asciidoc b/docs/detections/api/rules/rules-api-import.asciidoc index e063fbe320..edf6f30c25 100644 --- a/docs/detections/api/rules/rules-api-import.asciidoc +++ b/docs/detections/api/rules/rules-api-import.asciidoc @@ -8,11 +8,13 @@ Imports rules from an `.ndjson` file. The following configuration items are 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. +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. [IMPORTANT] ================= -Although detection rule actions are included in the exported file, the connectors used by the actions are not included. Use the {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI in Kibana (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors _before_ you export and import the detection rules. +Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) _is not_ included. You must re-add missing connector details after importing detection rules. + +You can use {kib}'s {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors before importing detection rules. Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the <> UI (*Manage* -> *Rules* -> *Import value lists*) to export and import value lists separately. ================= @@ -48,6 +50,8 @@ curl -X POST "/api/detection_engine/rules/_import" |`overwrite_exceptions` |Boolean |Determines whether existing exception lists with the same `list_id` are overwritten. Both the exception list container and its items are overwritten. |No, defaults to `false`. +|`overwrite_action_connectors` |Boolean |Determines whether existing actions with the same +`kibana.alert.rule.actions.id` are overwritten. |No, defaults to `false`. |============================================== ===== Example request diff --git a/docs/detections/rules-ui-manage.asciidoc b/docs/detections/rules-ui-manage.asciidoc index 16665ac297..6a27974999 100644 --- a/docs/detections/rules-ui-manage.asciidoc +++ b/docs/detections/rules-ui-manage.asciidoc @@ -172,13 +172,15 @@ You cannot export Elastic prebuilt rules, but you can duplicate a prebuilt rule, If you try to export with both prebuilt and custom rules selected, only the custom rules are exported. ==== -The `.ndjson` file also includes any actions and exception lists related to the exported rules. However, other configuration items require additional handling when exporting and importing rules: +The `.ndjson` file also includes any actions, connectors, and exception lists related to the exported rules. However, other configuration items require additional handling when exporting and importing rules: - *Data views*: For rules that use a {kib} data view as a data source, the exported file contains the associated `data_view_id`, but does _not_ include any other data view configuration. To export/import between {kib} spaces, first use the {kibana-ref}/managing-saved-objects.html#managing-saved-objects-share-to-space[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) to share the data view with the destination space. + To import into a different {stack} deployment, the destination cluster must include a data view with a matching data view ID (configured in the {kibana-ref}/data-views.html[data view's advanced settings]). Alternatively, after importing, you can manually reconfigure the rule to use an appropriate data view in the destination system. -- *Actions and connectors*: Rule actions are included in the exported file, but the connectors used by the actions are _not_ included. Use {kib}'s {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) to export and import any necessary connectors _before_ you export and import the detection rules. +- *Actions and connectors*: Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) _is not_ included. You must re-add missing connector details after importing detection rules. ++ +TIP: You can also use {kib}'s {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) to export and import necessary connectors before importing detection rules. - *Value lists*: Any value lists used for rule exceptions are _not_ included in rule exports or imports. Use the <> UI (*Manage* -> *Rules* -> *Import value lists*) to export and import value lists separately. @@ -190,7 +192,7 @@ To export and import detection rules: .. Select *Bulk actions* -> *Export*, then save the exported file. . To import rules: + -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. +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. .. Click *Import rules*. .. Drag and drop the file that contains the detection rules. @@ -198,8 +200,9 @@ NOTE: You need at least `Read` privileges for the `Action and Connectors` featur NOTE: Imported rules must be in an `.ndjson` file. .. (Optional) Select *Overwrite existing detection rules with conflicting "rule_id"* to update existing rules if they match the `rule_id` value of any rules in the import file. Configuration data included with the rules, such as actions, is also overwritten. .. (Optional) Select *Overwrite existing exception lists with conflicting "list_id"* to replace existing exception lists with exception lists from the import file if they have a matching `list_id` value. +.. (Optional) Select *Overwrite existing connectors with conflicting action "id"* to update existing connectors if they match the `action id` value of any rule actions in the import file. Configuration data included with the actions is also overwritten. .. Click *Import rule*. - +.. (Optional) If a connector is missing sensitive information after the import, a warning displays and you're prompted to fix the connector. In the warning, click *Go to connector*. On the Connectors page, find the connector that needs to be updated, click *Fix*, then add the necessary details. [float] [[enable-detection-rules]] diff --git a/docs/getting-started/detections-req.asciidoc b/docs/getting-started/detections-req.asciidoc index 3d21c37ec1..0dfe6bf066 100644 --- a/docs/getting-started/detections-req.asciidoc +++ b/docs/getting-started/detections-req.asciidoc @@ -108,7 +108,7 @@ a| {kib} space `All` privileges for the `Security` feature (refer to * To provide full access to rule actions and connectors, give your role `All` privileges. With `Read` privileges, you can edit rule actions, but will have limited capabilities to manage connectors. For example, `Read` privileges allow you to add or remove an existing connector from a rule, but does not allow you to create a new connector. -* To import rules with actions and connectors, your role needs at least `Read` privileges. To import rules without actions or connectors, your role does not require `Action and Connectors` feature privileges. +* 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. |Manage alerts