[Security Solution][Detections]Adds dry_run mode description to _bulk…

…_action API (#2210)

Adds dry_run mode description to _bulk_action API

Preview [here](https://security-docs_2210.docs-preview.app.elstc.co/guide/en/security/master/bulk-actions-rules-api.html). 

- issue elastic/kibana#125512
- PR elastic/kibana#134664

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

@@ -235,6 +235,17 @@ Applies a bulk action to multiple rules. The bulk action is applied to all rules
 
 `POST  <kibana host>:<port>/api/detection_engine/rules/_bulk_action`
 
+[discrete]
+===== URL query parameters
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`dry_run` |Boolean | Enables <<bulk-actions-rules-api-dry-run, dry run mode>> for the request call.
+|No
+|==============================================
+
 [discrete]
 ===== Request body
 
@@ -265,6 +276,15 @@ to apply.
 Yes, if action is `edit`.
 |==============================================
 
+[[bulk-actions-rules-api-dry-run]]
+[discrete]
+==== Dry run mode
+Enable dry run mode to verify that bulk actions can be applied to specified rules. Certain rules, such as prebuilt Elastic rules, can't be edited and will return errors in the request response. Error details will contain an explanation, the rule name and/or ID, and additional troubleshooting information. 
+
+To enable dry run mode on a request, add the query parameter `dry_run=true` to the end of the request URL. Rules specified in the request will be temporarily updated. These updates won't be written to {es}.
+
+
+IMPORTANT: Dry run mode is not supported for the `export` bulk action. A `400` error will be returned in the request response.
 
 [[bulk-edit-object-schema]]
 [discrete]
@@ -581,3 +601,84 @@ If processing of any rule fails, a partial error outputs the ID and/or name of t
 --------------------------------------------------
 
 <1> dev:[] `execution_summary` is under development and its schema may change.
+
+*Example 3, Dry run*
+
+The following request will validate that the `add_index_patterns` bulk action can be successfully applied to three rules. Each rule (specified by its rule ID) is different: one is a prebuilt Elastic rule, another is a custom machine learning rule, and another is a custom query rule. Because dry run mode is enabled, changes to these rules will not be permanent or saved to {es}.
+
+
+[source,console]
+--------------------------------------------------
+POST api/detection_engine/rules/_bulk_action?dry_run=true
+{
+    "action": "edit",
+    "edit": [
+        {
+            "value": [
+                "test-*"
+            ],
+            "type": "add_index_patterns"
+        }
+    ],
+    "ids": ["81aa0480-06af-11ed-94fb-dd1a0597d8d2", "dc015d10-0831-11ed-ac8b-05a222bd8d4a", "de8f5af0-0831-11ed-ac8b-05a222bd8d4a"]
+}
+--------------------------------------------------
+
+[discrete]
+===== Response code
+
+`500`::
+    Indicates a partial bulk action failure.
+
+[discrete]
+===== Response payload
+
+The `attributes.errors` section of the response shows that two rules failed to update and one succeeded. The same results would be returned if you ran the request without dry run mode enabled.
+Notice that there are no arrays in `attributes.results`. In dry run mode, rule updates are not applied and saved to {es}, so the endpoint wouldn't return results for rules that have been `updated`, `created`, or `deleted`.
+
+[discrete]
+===== Response body
+
+[source,json]
+--------------------------------------------------
+{
+    "message": "Bulk edit partially failed",
+    "status_code": 500,
+    "attributes": {
+        "errors": [
+            {
+                "message": "Elastic rule can't be edited",
+                "status_code": 500,
+                "err_code": "IMMUTABLE",
+                "rules": [
+                    {
+                        "id": "81aa0480-06af-11ed-94fb-dd1a0597d8d2",
+                        "name": "Unusual AWS Command for a User"
+                    }
+                ]
+            },
+            {
+                "message": "Machine learning rule doesn't have index patterns",
+                "status_code": 500,
+                "err_code": "MACHINE_LEARNING_INDEX_PATTERN",
+                "rules": [
+                    {
+                        "id": "dc015d10-0831-11ed-ac8b-05a222bd8d4a",
+                        "name": "Suspicious Powershell Script [Duplicate]"
+                    }
+                ]
+            }
+        ],
+        "results": {
+            "updated": [],
+            "created": [],
+            "deleted": []
+        },
+        "summary": {
+            "failed": 2,
+            "succeeded": 1,
+            "total": 3
+        }
+    }
+}
+--------------------------------------------------